The Compounding Knowledge Lifecycle — Agent Guide

Punti chiave

1. Scommessa fondante del compound engineering. "ogni unità di lavoro dovrebbe rendere più facile l'unità successiva." Il codice migliora il prodotto, non il processo; ciò che si accumula (compounds) è la conoscenza — ogni problema risolto, concetto nominato e 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 nei wiki perché nessuno li rilegge". Questo sistema chiude il ciclo rendendo il recupero automatico attraverso 5 skill, non una questione di disciplina volontaria.
3. Un learning (solution doc). = 1 file markdown = 1 problema risolto, sotto docs/solutions/<category>/. L'intero 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 area?"), problem_type (l'interruttore di instradamento), applies_when (un test di autoselezione di 3 righe), severity (classificazione quando più elementi corrispondono), date (segnale di obsolescenza).
4. problem_type = 2 binari. 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 gradino sopra: generalizzato da più learning → più leva, più rischio se diventa obsoleto. Nessuno ancora promosso qui (docs/solutions/patterns/critical-patterns.md = uno slot in attesa di essere riempito).
6. Cattura = /ce-compound. , disciplina centrale = tempismo: documentare mentre il contesto è ancora fresco (stessa sessione del fix, mentre i tentativi falliti e il "ah, ECCO perché" sono ancora presenti). Una settimana dopo → degrada in un semplice riassunto.
7. Meccanica. fan-out di subagent (context analyzer = categoria/nome/frontmatter, solution extractor = corpo in prosa problema/investigazione/soluzione/prevenzione, related-docs finder = controllo di deduplicazione); solo l'orchestratore scrive UN documento, i subagent non toccano mai i file tracciati. Altri punti di ingresso: /ce-debug (propone un compound dopo l'analisi della causa radice), /ce-pov ("compound it" → tooling_decision in modalità headless), modalità leggera (piccole lezioni, salta il controllo di deduplicazione).
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. "Accumulare (compounding)" = classi di fallimento vengono eliminate, non solo 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): la cache repo-profile (ri-derivata 1×/commit, condivisa da 9 skill, mai fonte di verità — cancellarla non fa perdere nulla). Regola: la conoscenza che rimpiangeresti → git; ciò che è ri-derivabile → /tmp. I piani non vengono mai modificati dopo l'esecuzione → spiegano comunque il perché mesi dopo.
10. Rilevazione: nulla spinge la conoscenza verso di te. (nessun digest, nessun "leggi il wiki"). 5 skill la tirano (pull) al momento decisionale, 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 (i learning → vincoli e KTD), /ce-brainstorm (delimita l'ambito), /ce-code-review (revisore sempre attivo: verdetto rispettato / violato rispetto al diff reale — "il dente più affilato"; una violazione = un finding 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) L'evidenza presente vince — se un learning contraddice il codice attuale, il conflitto viene segnalato invece di essere respinto (una memoria sicura di sé ma sbagliata è peggio di nessuna); (2) La data è un segnale — ogni learning porta la propria data per valutare se il mondo si è evoluto nel frattempo.
13. Refresh — "una memoria che cresce soltanto finisce per mentire.". 3 controforze a ritmi diversi: tempo di lettura (l'evidenza presente vince, gratuito); tempo di scrittura (quando si aggiunge/modifica una voce di CONCEPTS.md, si ispeziona il suo coherence neighborhood — i termini correlati citati — e si corregge la deriva per cui esiste evidenza; limitato, mai un audit completo su un semplice sospetto); su richiesta (/ce-compound-refresh, una scansione deliberata, NON un follow-up predefinito, eseguita solo in presenza di un motivo, con un suggerimento di ambito — /ce-compound-refresh payments — perché un refresh sull'intero corpus quasi mai è la spesa giusta).
14. Il ciclo completo tramite /ce-explain. (skill consegnata "ieri", tutto realmente accaduto): il brainstorm recupera 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 revisione 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"); il vocabolario compound (Explainer, Check-in → CONCEPTS.md); un residuo → issue #1057 → futuro learning #36. "Nessun passaggio ha richiesto a qualcuno di ricordarsi di consultare la memoria."
15. Perché si accumula (metafora finanziaria). learning = capitale, ogni recupero che cambia una decisione = pagamento di interessi, pattern doc = reinvestimento. Modalità di fallimento evitate: marciume del wiki, linee guida obsolete che uccidono il nuovo lavoro, accumulo non curato, memoria invisibile, decadimento, silos (un unico docs/solutions/ serve 9 skill).
16. Legame diretto con questo repo. la convenzione docs/solutions/ (frontmatter module/tags/problem_type) documentata nel CLAUDE.md del repo 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).