Usare Claude per documentazione tecnica e commenti al codice

La documentazione è il debito tecnico più tollerato che esista: tutti sanno che manca, nessuno trova il tempo di scriverla, e il costo si paga a ogni nuovo sviluppatore che entra nel progetto. Usare Claude per la documentazione tecnica è uno dei casi in cui l'AI rende di più in rapporto allo sforzo, perché il materiale di partenza, il codice, esiste già. In questo articolo raccontiamo come lo facciamo noi, con i prompt che funzionano e i limiti da tenere presenti.

Perché la documentazione è il compito ideale per un modello AI

Scrivere documentazione richiede due capacità: leggere codice e spiegare in linguaggio chiaro. Sono esattamente i punti di forza di un modello come Claude. A differenza della generazione di codice nuovo, dove l'AI può imboccare strade sbagliate, qui il perimetro è definito: il codice è la fonte, il compito è descriverlo.

I formati su cui otteniamo i risultati migliori:

• README di progetto: struttura, requisiti, installazione, comandi principali;
• commenti e docstring: descrizione di funzioni e classi, parametri, valori di ritorno, casi limite;
• documentazione di API: endpoint, formati di richiesta e risposta, codici d'errore;
• guide di onboarding: come è organizzato il repository, dove vivono le cose, come si avvia l'ambiente locale;
• spiegazioni di codice ereditato: quando prendiamo in mano un progetto scritto da altri, farci spiegare i moduli principali accorcia di molto la fase di ambientamento.

I prompt che funzionano (e perché)

La differenza tra documentazione utile e prosa generica sta nelle istruzioni. Tre regole che applichiamo sempre.

Definisci il lettore. "Documenta questa funzione" produce una parafrasi del codice. "Documenta questa funzione per uno sviluppatore che deve integrarla senza leggerne l'implementazione" produce quello che serve: cosa fa, cosa si aspetta, cosa restituisce, quando fallisce.

Imponi un formato. Chiedi la struttura esatta: sezioni del README, standard delle docstring del linguaggio, tabella per i parametri. Il formato costante rende la documentazione consultabile, e permette di rigenerarla senza stravolgere tutto a ogni modifica.

Chiedi di documentare il perché, non solo il cosa. Il commento "incrementa il contatore" sopra una riga che incrementa un contatore è rumore. Chiedi esplicitamente di segnalare le decisioni non ovvie: perché esiste quel controllo, cosa succederebbe rimuovendo quella condizione. E chiedi al modello di dichiarare quando un'intenzione non è deducibile dal codice, invece di inventarla: è il punto dove altrimenti nascono le allucinazioni.

Claude Code: documentare il repository, non lo snippet

Il salto di qualità arriva quando il modello vede il progetto intero invece del singolo file incollato in chat. Claude Code, lo strumento di coding agentico di Anthropic, lavora direttamente sul repository: si usa da terminale, come app desktop per Mac e Windows, dal browser su claude.ai/code o dentro gli IDE con le estensioni per VS Code e JetBrains.

Per la documentazione questo cambia il risultato: può leggere le dipendenze reali tra i moduli, verificare come una funzione viene usata nel resto del codice e aggiornare i file di documentazione direttamente nel progetto. Nei nostri flussi lo usiamo per generare la prima stesura dei README e per mantenere allineati i commenti dopo interventi estesi di refactoring, con la revisione di uno sviluppatore prima del commit. La famiglia di modelli attuale copre esigenze diverse: i modelli più capaci per l'analisi di codice complesso, i più leggeri per compiti ripetitivi su grandi volumi di file.

I limiti da conoscere prima di fidarsi

L'entusiasmo va calibrato su tre limiti concreti.

Primo: il modello documenta ciò che il codice fa, non ciò che dovrebbe fare. Se c'è un bug, la documentazione generata descriverà il comportamento sbagliato con tono sicuro. La revisione umana resta un passaggio del flusso, non un optional.

Secondo: il contesto di business non è nel codice. Il motivo per cui una regola calcola l'IVA in un certo modo o esclude certi clienti sta nella testa di chi ha preso la decisione. Quel sapere va aggiunto a mano, ed è la parte di documentazione che vale di più.

Terzo: la documentazione generata invecchia come quella scritta a mano. Senza un processo che la aggiorni quando il codice cambia, dopo sei mesi mente. La soluzione è organizzativa: rigenerare e rivedere la documentazione fa parte della chiusura di ogni intervento importante, non è un progetto annuale.

Un partner che il codice lo documenta (e lo scrive)

Sviluppiamo software su misura con un principio semplice: il cliente deve ricevere codice comprensibile e documentato, non una scatola nera. Usiamo l'AI dove accelera il lavoro e la revisione umana dove serve giudizio. Se hai un progetto da sviluppare, o un software ereditato che nessuno sa più toccare, prenota una call gratuita: lo analizziamo e ti diciamo come rimetterlo in ordine.