Claude Code, No-Plan Execution e Trust without Verify

Per sua natura, che è poi anche la natura degli Agenti AI, Claude Code opera in modo del tutto autonomo, Quindi legge i file, compila i piani, effettua le modifiche e interrompe la propria sessione di lavoro solo quando, secondo i suoi parametri interni, quest'ultimo sembra completato. Se lo sviluppatore non impone esplicitamente dei binari di verifica e dei test all'agente, si ritroverà obbligato ad assumere il ruolo di controllore manuale per ogni singola riga di codice prodotta. Una situazione che, se non corretta, cancella di fatto i vantaggi dell'automazione e porta con sé delle regressioni spesso impercettibili ma catastrofiche in seno alla codebase.

Claude Code e No-Plan Execution

Parliamo ora dell'avvio dello sviluppo "a caldo", senza pianificazione. Permettere a Claude di modificare file e lanciare comandi senza aver prima analizzato la struttura di un problema produce del codice caotico o delle modifiche impattanti su file spesso non coinvolti, o coinvolti solo marginalmente, in un progetto.

Un errore dovuto allo "sviluppo impulsivo" potrebbe sintetizzarsi in questo modo:

# L'agente inizierà a modificare arbitrariamente file di routing e middleware
"Integra il supporto di Google OAuth 2.0 nel nostro server Express"

I questo caso, un utilizzo della modalità plan in modo preventivo potrebbe essere la scelta giusta. Si può attivare la modalità plan tramite Shift+Tab o attraverso il terminale con l'istruzione

claude --permission-mode plan

In questo stato, gli strumenti di scrittura del filesystem sono bloccati fisicamente e ciò costringe Claude a esplorare e produrre esclusivamente un piano in formato markdown.

Rivediamo quindi il nostro prompt:

# Claude opera in ambiente di sola lettura controllata
"Voglio integrare Google OAuth 2.0. Quali file devono essere modificati? Qual è il flusso di callback? Elabora un piano dettagliato."

Una volta approvato il piano, che si può anche modificare direttamente nel proprio editor con Ctrl+G, si torna in modalità di default e si ordina l'implementazione.

File CLAUDE.md inesistente o sovraccarico

Senza istruzioni relative al contesto, Claude ricomincia da zero a ogni avvio. Al contrario, inserire troppe informazioni porta l'agente a ignorare le regole che hanno priorità sulle altre.

È bene ricordare che uno scaffold rapido, accompagnato a delle regole sintetiche, genera un file base con /init, lo mantiene sotto le 200 righe e include solo le convenzioni che l'agente non può desumere da solo dal codice:

# CLAUDE.md - Convenzioni di Progetto
## Comandi per Build & Test
- Compilazione: npm run build
- Esecuzione test singolo: npm run test -- <file_path>
- Linter: npm run lint
## Stile del Codice
- Usa solo TypeScript ES modules (import/export), mai CommonJS (require)
- Esigi sempre la definizione esplicita dei tipi di ritorno nei metodi pubblici
- Tutte le query SQL devono utilizzare il wrapper transazionale: db.transaction()

Trust without Verify

Accettare ciecamente l'affermazione di successo di Claude senza testarne la correttezza a livello formale è un buon modo per complicarsi la vita e il lavoro. Si pensi per esempio ad un prompt privo di criteri di convalida accurati come il seguente:

"Scrivi una funzione per convalidare le email e salvala in utility"

Ecco invece un prompt basato sul test-driven development che prevede una fase di esecuzione verificata:

"Implementa la funzione validateEmail in @src/utils/validators.ts.
Casi di test attesi: 'user@example.com' -> true, 'invalid' -> false, 'user@.com' -> false.
Scrivi i test unitari associati, esegui il test runner del progetto e mostrami l'output completo come prova del superamento.

Da non dimenticare poi i sistemi di controllo automatico in .claude/settings.json. È infatti sempre buona norma utilizzare dei ganci, o hooks, per automatizzare la convalida a ogni modifica o prima di terminare una sessione di sviluppo:

{
 "hooks": {
 "PreToolUse": "npm run lint",
 "PostToolUse": "npm run test"
 }
}