Un’architettura non documentata è una conoscenza che vive nella testa di due persone. Su un progetto Claude il problema si sdoppia, perché la documentazione ha due lettori con esigenze opposte: i colleghi che manterranno il sistema, e l’agente stesso, che quel testo lo carica a ogni sessione e lo paga in token.

La documentazione che l’agente legge da solo

Claude Code ha tre superfici documentali, con regole diverse.

CLAUDE.md è il contratto sempre presente. Vive su quattro livelli — policy gestita dall’organizzazione, utente, progetto, locale — e i file trovati vengono concatenati nel contesto invece di sovrascriversi a vicenda. Il livello di policy sta in percorsi di sistema e “Managed policy CLAUDE.md files cannot be excluded”. Il vincolo di forma è duro: “target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” Un architetto che ci riversa dentro l’intero documento di design ottiene meno aderenza, non più.

.claude/rules/ è il posto di ciò che vale solo per una parte del codice: una regola con frontmatter paths entra in contesto quando Claude tocca i file corrispondenti.

Le Skill sono il posto delle procedure. La guida di authoring impone l’ordine di lavoro — “Create evaluations BEFORE writing extensive documentation” — e la forma: SKILL.md sotto le 500 righe, riferimenti a un solo livello di profondità, descrizione in terza persona che dica sia che cosa fa sia quando usarla.

E la distinzione che serve davanti al comitato di governance: “Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer.”

Discovery e design: definire «fatto» prima di costruire

Il ciclo AI-native descritto da Anthropic ha sei fasi — Plan, Design, Build, Test, Deploy, Maintain — e una diagnosi che riorienta il lavoro dell’architetto: “Code is no longer the bottleneck — the human-speed steps around it are.” Il collo di bottiglia si sposta su intento, revisione e approvazione, e “Humans remain accountable for every decision that requires judgment.”

Il modo documentato di rendere verificabile un obiettivo è la rubrica. Nella Managed Agents API “An outcome tells the session what the end result should look like and how to measure its quality”, e il grader gira in una finestra di contesto separata per non farsi influenzare dalle scelte implementative dell’agente. La regola di scrittura vale ben oltre quell’API: criteri come “The CSV contains a price column with numeric values” invece di “The data looks good”, perché “vague criteria produce noisy evaluations”.

Il limite dichiarato: la documentazione ammessa non descrive un metodo di discovery con gli stakeholder. Sostiene la parte verificabile — rubriche, criteri di uscita, eval — mentre il discovery va condotto con i metodi della tua organizzazione, senza far passare una prassi generica per prescrizione Anthropic.

L’handoff è un pacchetto, non una riunione

Il playbook indica come veicoli gli artefatti versionati (intento, specifica, piano, diff) come traccia di audit, le Skill come conoscenza istituzionale codificata e gli hook come cancelli di approvazione deterministici. In Claude Code quel pacchetto si distribuisce come plugin, che raccoglie skill, agenti, hook e server MCP in un oggetto versionato, pubblicabile da un marketplace ospitato in un repository privato per restare interno al team.

mio-plugin/
├── .claude-plugin/plugin.json   manifesto: nome, descrizione, versione
├── skills/                      procedure caricate su richiesta
├── agents/                      sotto-agenti dedicati
├── hooks/hooks.json             cancelli deterministici
└── .mcp.json                    server MCP dell'integrazione

Consegnare questo invece di un documento significa che chi riceve ottiene la guida operativa e l’attrezzatura nello stesso artefatto, con una versione da citare quando qualcosa cambia.

Monitoraggio e iterazione

Un agente in produzione si osserva come un servizio. L’Agent SDK esporta OpenTelemetry e risponde alle quattro domande che la pagina elenca: quali tool ha chiamato, quanto è durata ogni richiesta al modello, quanti token sono stati spesi, dove si è rotto. Gli span sono claude_code.interaction, claude_code.llm_request, claude_code.tool e claude_code.hook; quando l’agente delega, gli span del sotto-agente si annidano sotto quelli del padre, così l’intera catena appare come una traccia sola.

Due dettagli da portare a una revisione di sicurezza. Il contenuto non viene registrato per default: “Telemetry is structural by default”, e prompt, argomenti dei tool e corpi delle richieste si abilitano solo con variabili dedicate. E l’esportazione fallisce in silenzio se il collector non risponde, quindi «abbiamo l’osservabilità» va verificato guardando arrivare i dati, non guardando la configurazione.

L’iterazione, infine, non si governa a calendario ma per fiducia guadagnata: l’autonomia si concede in proporzione all’affidabilità dimostrata e si allarga per tipo di attività, dopo successi ripetuti.