The Compounding Knowledge Lifecycle — Agent Guide

Punti chiave

1. La scommessa del compound engineering. "ogni unità di lavoro dovrebbe rendere più facile la prossima unità." Il codice migliora il prodotto, non il processo; ciò che si accumula in modo composto è la conoscenza — ogni problema risolto, concetto nominato, convenzione documentata in una forma recuperabile nel momento esatto in cui il lavoro futuro ne ha bisogno.
2. Il vero collo di bottiglia = il recupero. , non la scrittura. I postmortem "marciscono nelle wiki perché nessuno li rilegge". Questo sistema chiude il cerchio rendendo il recupero automatico attraverso 5 skill, non una disciplina volontaria.
3. Un learning (solution doc). = 1 file markdown = 1 problema risolto, sotto docs/solutions/<category>/. Tutto il frontmatter serve alla ricerca, non alla narrazione: title (bersaglio grep #1), tags (superficie di sinonimi — grep tags:.*(menu|routing|handoff) senza aprire un file), module/component ("è la mia zona?"), problem_type (l'interruttore di instradamento), applies_when (un test di autoselezione di 3 righe), severity (classifica quando più elementi corrispondono), date (segnale di obsolescenza).
4. problem_type = 2 filoni. bug-track (cosa si è rotto: runtime_error, test_failure, performance_issue, security_issue…) e knowledge-track (cosa è stato deciso/scoperto: architecture_pattern, design_pattern, tooling_decision, convention, workflow_issue, best_practice…). "Un sistema che conserva solo i bug dimentica la parte essenziale di ciò che un team apprende." Censimento vivente: 35 learning, 6 categorie, skill-design in testa (20).
5. Pattern doc. = un livello superiore: generalizzato a partire da più learning → più leva, più rischio se diventa obsoleto. Nessuno ancora promosso a questo livello (docs/solutions/patterns/critical-patterns.md = uno slot in attesa).
6. Cattura = /ce-compound. , disciplina centrale = tempismo: documentare mentre il contesto è ancora fresco (stessa sessione del fix, mentre i tentativi falliti e l'"ah, ECCO perché" sono ancora presenti). Una settimana dopo → degenera in un riassunto.
7. Meccanica. fan-out di subagenti (context analyzer = categoria/nome/frontmatter, solution extractor = corpo in prosa problema/indagine/soluzione/prevenzione, related-docs finder = anti-duplicato); solo l'orchestratore scrive UN documento, i subagenti non toccano mai i file tracciati. Altri punti d'ingresso: /ce-debug (propone un compound dopo la causa radice), /ce-pov ("compound it" → tooling_decision in modalità headless), modalità leggera (piccole lezioni, salta l'anti-duplicato).
8. "La vita di un learning". (esempio canonico): incidente #714 (l'agente si ferma dopo il menu) → causa radice (instradamento per opzione in un file di riferimento non caricato) → fix + /ce-compound → learning post-menu-routing-belongs-inline.md → test di regressione + dottrina in AGENTS.md ("Inline the Trigger, Not the Content"). Un incidente, 4 artefatti durevoli. "Compounding" = le classi di fallimento vengono ritirate, non semplicemente documenti che si accumulano.
9. Mappa della memoria, asse = durabilità. DUREVOLE (git): docs/solutions/ (i 35 learning), CONCEPTS.md (vocabolario/glossario, mai specifiche), STRATEGY.md (direzione/assi), docs/plans/ + brainstorms/ (il PERCHÉ). EFFIMERO (derivato): cache repo-profile (derivata 1×/commit, condivisa da 9 skill, mai fonte di verità — cancellarla non fa perdere nulla). Regola: la conoscenza di cui si avrebbe nostalgia → git; ciò che è ri-derivabile → /tmp. I piani non vengono mai modificati dopo l'esecuzione → spiegano ancora il perché mesi dopo.
10. Rilevamento: nulla ti spinge la conoscenza addosso. (nessun digest, nessun "leggi la wiki"). 5 skill la attingono al momento della decisione, tramite un protocollo condiviso learnings-researcher, grep-first (la memoria è progettata per essere cercata senza essere letta). Imbuto: 35 documenti → grep paralleli sul frontmatter → una manciata di candidati (frontmatter di ~30 righe) → lettura completa dei vincitori → 5 risultati distillati nel contesto del chiamante.
11. Consumatori. /ce-plan (learning → vincoli e KTD), /ce-brainstorm (delimita l'ambito), /ce-code-review (revisore sempre attivo: verdetto seguito / violato rispetto al diff reale — "il dente più affilato"; una violazione = un risultato con file:line, non un suggerimento), /ce-ideate (elimina i vicoli ciechi passati), /ce-debug (fa emergere cause radice note).
12. 2 regole di fiducia. (1) Le prove presenti vincono — se un learning contraddice il codice attuale, il conflitto viene segnalato invece di far fallire il learning (una memoria sbagliata con sicurezza è peggio di nessuna memoria); (2) La data è un segnale — ogni learning porta la sua data per valutare se il mondo è andato avanti.
13. Refresh — "una memoria che cresce soltanto finisce per mentire.". 3 controforze a ritmi diversi: tempo di lettura (le prove presenti vincono, gratuito); tempo di scrittura (quando si aggiunge/modifica una voce in CONCEPTS.md, si ispeziona il suo coherence neighborhood — i termini correlati referenziati — e si corregge la deriva per cui esiste evidenza; limitato, mai un audit completo su un sospetto); su richiesta (/ce-compound-refresh, una passata deliberata, NON un follow-up predefinito, eseguita solo quando c'è un motivo, con un indizio di ambito — /ce-compound-refresh payments — perché un refresh sull'intero corpus quasi mai è la spesa giusta).
14. Il ciclo completo via /ce-explain. (una skill consegnata "ieri", tutto è realmente accaduto): il brainstorm attinge il repo-profile dalla cache; la pianificazione fa emergere 5 learning (3 da applicare obbligatoriamente: instradamento inline del menu [eredità del #714], portabilità di $ARGUMENTS, ancoraggio SKILL_DIR); l'implementazione crea il suo test di regressione speculare; la review verifica il diff rispetto a 8 learning (tutti rispettati) e respinge un fix proposto da un revisore che avrebbe reintrodotto la modalità di fallimento originale ("la memoria non si è limitata a informare il lavoro, lo ha difeso"); vocabolario compound (Explainer, Check-in → CONCEPTS.md); residuo → issue #1057 → futuro learning #36. "Nessuna fase ha richiesto che qualcuno si ricordasse di consultare la memoria."
15. Perché si accumula in modo composto (metafora finanziaria). learning = capitale, ogni recupero che cambia una decisione = pagamento di interessi, pattern doc = reinvestimento. Modalità di fallimento evitate: marcescenza delle wiki, guida obsoleta che uccide il nuovo lavoro, accumulo non curato, memoria invisibile, decadimento, silos (un unico docs/solutions/ serve 9 skill).
16. Legame diretto con questo repository. la convenzione docs/solutions/ (frontmatter module/tags/problem_type) documentata nel CLAUDE.md del repository veille è esattamente questo sistema; le skill compound-engineering:* (ce-compound, ce-plan, ce-code-review, ce-compound-refresh…) sono installate qui. Un candidato naturale per una promozione a livello aziendale (un pattern di capitalizzazione).