Documentazione da codebase 📖

La documentazione è la funzione che tutti vorrebbero e nessuno vuole scrivere. Un agente di coding può farlo al posto tuo — ma con una condizione: devi verificare ciò che genera. Una documentazione sbagliata è peggio di nessuna documentazione, perché qualcuno la leggerà e la crederà. E quando la crederà, prenderà decisioni basate su informazioni false.

Generare documentazione è facile. Generare documentazione corretta richiede lo stesso rigore di generare codice.

Quando usare l’agente per questo caso 🎯

• README iniziale — descrizione del progetto, installazione, usage, contribuzione.
• API reference — documentazione delle interfacce esposte, parametri, tipi di ritorno.
• Changelog automatico — riepilogo delle modifiche tra versioni.
• ADR (Architecture Decision Record) — documentazione delle decisioni architetturali e del loro contesto.
• Guide di contribuzione — come contribuire, standard di codifica, processo di review.

Quando NON usare l’agente ⛔

• Il codice è troppo complesso da comprendere — se l’agente non capisce il codice, la documentazione sarà un riassunto di illusioni.
• La documentazione riguarda processi non codificati — workflow manuali, decisioni organizzative, policy aziendali. L’agente non può documentare ciò che non esiste nel codice.
• Devi documentare API instabili — prima stabilizza l’API, poi documentala.

Prompt di apertura 📝

“Genera [tipo di documento] per [modulo/package]. Formato: [README / API reference / changelog / ADR]. Pubblico: [sviluppatori / utenti]. Vincoli: [lingua, stile, doc-as-code]. Cita il codice sorgente come riferimento.”

Esempi concreti:

“Genera un README.md per il modulo src/auth/. Pubblico: sviluppatori interni. Formato: installazione, usage, API pubblica. Vincoli: lingua inglese, stile diretto, esempi di codice funzionanti.”

“Genera un ADR per la scelta di PostgreSQL come database. Contesto: [descrizione]. Decisione: PostgreSQL. Conseguenze: [elenco]. Formato: standard ADR con sezioni Context/Decision/Consequences.”

Setup del contesto 🔧

1. Indica i file sorgente — l’agente deve leggere il codice per documentarlo. Non inventare: estrarre.
2. Definisci il pubblico — sviluppatori interni? utenti finali? devops? Il livello di dettaglio cambia drasticamente.
3. Specificare il formato — README, ADR, API reference, changelog. Ogni formato ha le sue convenzioni.

Ciclo di lavoro 💡

1. Pianifica: definisci cosa documentare e in che formato.
2. Estrai: l’agente legge il codice e genera la documentazione.
3. Verifica coerenza: ogni affermazione deve essere verificabile contro il codice. Se l’agente scrive “l’endpoint accetta un parametro id di tipo string”, verifica che sia davvero così.
4. Aggiorna: la documentazione vive con il codice. Ogni modifica al codice deve aggiornare la doc corrispondente.

La verifica è il passaggio più importante. Un agente può inventare parametri, errori, comportamenti che non esistono. Sempre verificare sul codice reale.

Per la doc-as-code, mantieni la documentazione nel repository insieme al codice: versionata, revisionabile, parte del CI.

Pipeline doc-as-code 🔧

La generazione di documentazione non è un atto singolo: è un processo che va dalla scoperta del codice alla verifica di coerenza.

    flowchart LR
    A[Scan 🔍] --> B[Plan 📋]
    B --> C[Generate ✍️]
    C --> D[Verify ✅]
    D --> |Drift detected| A
  

La fase di Verify è quella che separa la documentazione utile da quella dannosa. Usa tool di drift detection per intercettare quando codice e documentazione divergono.

Drift detection e verifica 📐

Il drift tra documentazione e codice è il nemico silenzioso della doc-as-code. I dati mostrano che:

• Nested README scoperte solo ~40% delle volte dagli agenti
• Documenti in directory speciali (_docs/, docs/) scoperti <10% delle sessioni
• 60-70% dei breaking changes passano la code review senza che la documentazione venga aggiornata

Tool di drift detection

Enforcement hierarchy

La verifica può operare su 3 livelli crescenti di rigidità:

1. Advisory — l’agente segnala ma non blocca
2. PreToolUse hook — blocca modifiche che rompono la coerenza doc-codice
3. CI gate — il build fallisce se doc e codice divergono

Pattern sicuro: “Propose, don’t auto-merge” — mai aggiornare la documentazione direttamente. Genera sempre una PR che un umano revisiona.

ADR: la sezione più preziosa 📋

Gli Architecture Decision Record sono la documentazione più importante che un agente può generare. La sezione chiave è “Alternatives rejected”: documenta non solo cosa hai scelto, ma perché hai scartato le alternative. È la sezione più saltata e la più preziosa.

Y-statement format (compatto e agent-friendly):

“In the context of {situation}, facing {concern}, I decided {decision} to achieve {goal}, accepting {tradeoff}.”

L’ADR può diventare un constraint CI verificabile: anziché documento statico, diventa una regola che l’agente e la pipeline verificano ad ogni build.

Changelog automation 📦

Generare changelog manualmente è noioso e soggetto a errori. L’automazione combina Conventional Commits con AI polish.

Tool landscape

Two-stage workflow

1. Stage 1: Conventional Commits generano il changelog grezzo (release-please o git-cliff)
2. Stage 2: AI polish per leggibilità e coerenza tono

Il changelog non è un dump di commit. È una comunicazione agli utenti. L’AI può trasformare “fix: resolve null pointer in auth handler” in “Fixed authentication crash when user has no profile”.

Criteri di accettazione ✅

• Ogni affermazione verificabile contro il codice sorgente.
• Nessuna API, parametro o comportamento inventato.
• Documentazione versionata con il codice (stesso repo, stesso branch).
• Formato corretto per il tipo scelto (README, ADR, ecc.).

Approfondimenti 📚

• Comprendere una codebase esistente — prima di documentare, capisci cosa c’è.
• Blog: Context engineering — come gestire il contesto per output coerenti.
• Docs: Generative AI per documentazione — tecniche avanzate di generazione documentale.