Fissi il terminale. Sai cosa costruire. Ma le mani non si muovono. Il workflow che usi da anni, quello che hai nel sangue, sembra sbagliato. Non rotto, esattamente. Solo… la forma giusta per un lavoro che non esiste più.

Porto questa sensazione con me da mesi. Gli agenti AI scrivono codice più veloce di quanto riesca a revisionarlo. Il gap tra “so cosa costruire” e “è costruito” si è ridotto a minuti. E la consapevolezza crescente che il processo che avevo raffinato in un decennio era stato progettato per un mondo che è già andato avanti.

Quindi sto provando qualcosa di diverso. Da questa settimana, giro un nuovo workflow. Non perché ho letto un manifesto. Perché il vecchio ha smesso di calzare.

La Cosa che Nessuno Ti Dice

L’AI non ha reso il coding più veloce. Questa è la storia in superficie. Quello che ha fatto davvero è spostare dove si svolge il lavoro reale.

Il vecchio modello: pensi, scrivi, il tool cattura i typo, fai ship. Il progresso misurato in keystroke. La qualità misurata in test coverage. La mano umana su ogni riga.

Quel modello assumeva che il bottleneck fosse la velocità di digitazione. Non lo era. Non è mai stato il typing. Era il giudizio: cosa costruire, come strutturarlo, quando fermarsi. Il typing era solo l’artefatto.

Ora un agente gestisce l’artefatto. E se il tuo workflow è ancora organizzato intorno all’artefatto, stai ottimizzando la cosa sbagliata.

Il Lineare è una Bugia

Plan. Build. Test. Ship. Quattro box. Frecce pulite. Ogni tool di project management lo disegna così. Ogni sprint retrospective lo assume.

È sempre stata una semplificazione.

Il lavoro reale è disordinato. Scopri a metà build che il piano si basava su un’assunzione sbagliata. I test rivelano requisiti di cui non avevi parlato. Lo ship porta a galla problemi che nessuno aveva previsto. Il processo “lineare” era in realtà una serie di correzioni travestite da progresso.

Il nuovo workflow abbandona le finzioni. Non ci sono fasi. Ci sono modalità. Plan mode. Build mode. Validate mode. Passi tra loro in base a quello che il lavoro richiede. A volte sei in plan mode per un’ora. A volte per 30 secondi tra due cicli di build.

Due regole sono non negoziabili: l’acceptance test deve essere rosso prima che Build inizi, e non fare mai ship senza un green gate. Tutto il resto è flessibile.

Il Loop

L’ho capito prima di capire il software. Non avevo ancora le parole per dirlo.

Da bambino, avrò avuto otto o nove anni, mia mamma mi mandava a fare la spesa. Erano gli anni Ottanta in Italia, quando i bambini attraversavano ancora la città da soli e nessuno chiamava la polizia. Mi dava una lista lunga, io camminavo fino al grande negozio dall’altro lato del quartiere, e tornavo quaranta minuti dopo con metà della roba sbagliata e qualcosa che mancava. Troppe cose da ricordare. Troppo tempo tra la partenza e il ritorno. Nessuna possibilità di correggere il tiro.

Così abbiamo cambiato il sistema. Lista più corta. Negozio più vicino. Più viaggi. Ogni viaggio era abbastanza piccolo da farlo bene, e se sbagliavo qualcosa, la correzione era una passeggiata di cinque minuti, non una spedizione di quaranta.

Non ci voleva più tempo in totale. Falliva solo in piccolo.

È questa l’idea alla base del workflow, distillata in una corsa al supermercato. Loop piccoli. Feedback veloce. Fallisci in piccolo, correggi veloce, vai avanti.

   ┌────────────┐
   │   Define   │
   └─────┬──────┘
         │
   ┌─────▼──────┐   ┌──────┐   ┌──────────┐
   │    Plan    │   │ Build │◄─▶│ Validate │─┐
   │  (x2 ops)  │   └──▲───┘   └────┬─────┘ │
   └─────┬──────┘      │             │       │
         │          RED GATE      GREEN GATE │
   ┌─────▼──────┐      │             │       │
   │  Red Gate  │──────┘        ┌────▼────┐  │
   │ (acceptance│               │  Ship   │  │
   │  must fail)│               └─────────┘  │
   └────────────┘                            │
         ▲                                   │
         └───────────────────────────────────┘

Define una volta. Ship una volta. Tutto nel mezzo è un loop: chiarisci cosa vuoi, produci cambiamenti, verifica che siano reali. Aggiusta. Ripeti. La dimensione di ogni ciclo dipende da quanto ti fidi di quello che stai costruendo. Alta fiducia, loop grandi. Alta incertezza, loop piccoli.

Il Brief

Ogni pezzo di lavoro inizia con due file, non uno.

specs.md è il cosa e il perché. L’obiettivo. Il contesto. I criteri di accettazione. I vincoli. Cosa significa “fatto” in una frase. Cosa è in scope. Cosa non lo è. Un log continuo di decisioni e correzioni di rotta. Non è un prompt (quelli sono usa e getta) e non è una spec tradizionale (quelle sono rigide). È un brief vivente. Scrivi quello che sai, lasci spazi per quello che non sai ancora, e lo aggiorni mentre il lavoro ti insegna le cose.

plan.md è il come. Ma Plan ha due compiti, non uno.

Primo: la strategia di implementazione. L’agente legge le specs, propone un approccio, lo divide in chunk piccoli. Ogni chunk è un passo concreto che può eseguire e validare in modo indipendente. Il piano evolve: se un chunk rivela che il passo successivo dovrebbe essere diverso, aggiorni il piano, non forzi l’originale.

Secondo: la specifica dell’acceptance test. Prima che venga scritta una singola riga di implementazione, l’agente scrive un test automatizzato che esercita il sistema dall’esterno, contro i criteri di accettazione in specs.md. Non un unit test. L’intero percorso: l’input entra, l’output atteso esce. Questo test fallirà. È quello che deve fare. Quel fallimento è la prova che il target è reale.

La separazione conta. Le specs sono tue. Catturano intento e contesto che sopravvivono a qualsiasi tentativo di implementazione. Il piano è la proposta dell’agente su come arrivarci. Se il piano va storto, lo butti e ne scrivi uno nuovo. Le specs restano.

Entrambi i file vivono in Mindforge , il mio vault Obsidian. Non in una chat window. Non incollati in un prompt. In un vault a cui l’agente ha accesso diretto al filesystem. Penso a Mindforge come al Context Engine: un unico posto dove il pensiero umano e l’esecuzione dell’agente si incontrano. L’agente lo legge prima di ogni sessione. Ci scrive durante il lavoro. Nessun contesto va perso tra sessioni, tra task, o tra tool.

Il log dentro specs.md è la memoria a lungo termine del progetto. “Abbiamo provato X. X ha fallito per Y. Siamo passati a Z.” Senza di esso, il ragionamento dietro ogni decisione evapora nel momento in cui chiudi l’editor. Ti ritrovi con codice che funziona e nessuno ricorda perché è fatto in quel modo. I prompt sono usa e getta. Il log no.

Mi sono bruciato abbastanza volte per il contesto mancante. Il log resta.

Il Red Gate

L’acceptance test è scritto. Ora lo esegui.

Se fallisce: bene. Quella è la condizione di ingresso per Build. Hai un target. L’agente sa cosa significa “fatto” senza doverlo chiedere.

Se passa: fermati. C’è qualcosa che non va. O il test non testa davvero la cosa giusta, o la feature esiste già, o hai frainteso i requisiti. Tutti e tre i casi richiedono risoluzione prima di scrivere una singola riga di implementazione.

Questo gate non è opzionale. L’agente non può procedere a Build senza un test confermato rosso. Nessuna eccezione, nessuna scorciatoia.

Ho fatto ship di cose che “sembravano fatte” senza questo tipo di ancoraggio. Pensi che il lavoro sia completo. L’edge case emerge alle 23. Lo risali fino a un requisito che nessuno aveva scritto, un test che nessuno aveva eseguito, un’assunzione che nessuno aveva messo in discussione. Il red gate è come si previene questo.

Rosso non è un fallimento. Rosso è la prova che hai definito correttamente il target.

Il Setup

Il protocollo è tool-agnostic. Quello che richiede è un agente capace di operazioni autonome sul filesystem: leggere specs, scrivere codice, eseguire comandi, auto-validarsi, e venire da te solo quando è bloccato. Qualsiasi agente con accesso al filesystem e un terminale va bene. Il workflow non si preoccupa di quale usi.

Detto questo: io uso Claude Code, il CLI agent di Anthropic. Non perché sia l’unica opzione, ma perché si adatta a questo workflow meglio delle alternative che ho provato. È veloce. Gestisce bene i loop autonomi: legge le specs, costruisce, si auto-controlla, corregge, ripete. Resta nel terminale dove lavoro, legge e scrive file direttamente, e non ha bisogno che tenga d’occhio una chat window. Quando il workflow richiede un agente che può andare avanti da solo e tornare con risultati, velocità e autonomia contano più di qualsiasi altra cosa. Se usi un agente diverso, il loop è lo stesso. I tool sono tuoi da scegliere.

Sto configurando un profilo agente dedicato: un agente profilato che chiamo “the coder.” Un file CLAUDE.md gli dà contesto persistente sul workflow, le regole di ingaggio, e la struttura del progetto. Sa come lavoro prima che io scriva una singola parola. In più, uno skill dedicato (slash command) per ogni modalità del loop: /start per avviare un nuovo task, /plan per entrare in planning mode, /build per delegare l’implementazione, /validate per eseguire il checklist, /ship per chiudere. Ogni skill codifica le regole per quella modalità così l’agente si comporta in modo coerente senza che io ripeta le istruzioni ogni sessione.

Lasciare la Tastiera

Questa è la parte difficile. Quella che non sembra giusta, anche quando funziona.

L’agente legge le specs. Propone un approccio. Discuti, fai domande, aggiusti. Poi l’agente prende il controllo. Costruisce. Esegue i check dopo ogni chunk: compilazione, unit test, linting. Se qualcosa si rompe, lo corregge e ri-controlla. Fino a tre tentativi prima di portare il problema a te. Quando tutti i chunk sono completi, esegue l’acceptance test. Se il Green Gate è su, scala a Ship. Altrimenti torna a Plan.

Non guardi ogni riga. Non interrompi a metà del lavoro.

Quando torna, presenta quello che ha costruito: cosa ha passato, cosa ha fallito, cosa ha corretto lungo la strada. Poi rivedi. Non il codice riga per riga (il linter e i test gestiscono quello). Rivedi quello che gli agenti mancano sistematicamente: fit architetturale, security blind spot, trappole di performance, edge case che non ha considerato, astrazioni premature.

Se qualcosa è sbagliato, descrivi il problema. L’agente rientra nel suo loop. Di solito uno o due giri.

Diventa più facile con la pratica.

Cosa Diventi

Smetti di essere la persona che scrive il codice. Diventi la persona che decide quale codice debba esistere.

System designer. Valutatore di rischi. Quello che dice “questo non appartiene qui” o “cosa succede quando questo fallisce alle 3 di notte senza dati?”

È un tipo diverso di stanchezza. Meno fisica. Più cognitiva. Stai scambiando la fatica dei tasti con la fatica delle decisioni. Certi giorni è un buono scambio. Certi giorni no.

Ma anche l’output è diverso. Quando funziona, l’agente produce codice pulito, testato, coerente a un ritmo che non riesco a eguagliare. E il mio lavoro diventa assicurarmi che quel ritmo non superi la mia comprensione.

Fidati, ma Verifica Tutto

Il codice generato dall’AI gira. Passa i test. Sembra corretto. La tentazione è di fidarsi perché è veloce e sicuro. Ma quella sicurezza viene dai dati di training, non dalla comprensione del tuo sistema.

“Ha girato” non è “è corretto.” L’ho imparato nel modo difficile.

La validazione non è un passo alla fine. È una modalità in cui rimani. I check automatizzati girano dopo ogni chunk: compilazione, test, linting, type checking. La revisione umana cattura il resto. Questa soluzione appartiene qui a lungo termine? Ha introdotto un buco di sicurezza sottile? Sta risolvendo un problema che abbiamo davvero?

Ma il segnale primario è il Green Gate: l’acceptance test che hai scritto prima che Build inizi, ora verde. È l’unico check che conferma che il sistema fa quello che doveva fare, dall’esterno, contro i requisiti reali. Tutto il resto è evidenza di supporto.

Nessun green gate, nessuno ship. Non negoziabile.

Se non riesci a rispondere a quelle domande, non fai ship. Punto.

Ship Pulito

Quando il loop finisce, fare ship è un atto deliberato. Non “l’agente ha smesso di produrre codice,” ma “ho deciso che questo lavoro è adatto a esistere.”

Git history pulita. PR description che spiega cosa, perché, e come. Ticket aggiornato. Tempo registrato. E una breve retrospettiva: cosa ha fatto bene l’agente, dove ha avuto difficoltà, cosa cambierei la prossima volta.

Chiudi il contesto. Ricomincia da zero.

Quando il Loop Si Rompe

Certi giorni salti il planning del tutto. Fix banale. Solo build e validate.

Certi giorni rimani in plan mode per ore perché il problema è profondo e una mossa sbagliata si propaga.

Certi giorni l’agente gira in tondo. Tre tentativi, quattro, cinque. È bloccato. Uccidi il contesto. Rileggi le specs con occhi freschi. Inizia un nuovo loop da zero. Nessun sunk cost. Nessuna sentimentalità.

Certi giorni avvii un secondo agente per rivedere il lavoro del primo. Occhi freschi, nessun bias da sunk cost. È la code review più economica che avrai mai.

Il processo è uno strumento. Nel momento in cui diventa una religione, smette di funzionare.

Su Cosa Scommetto

  • Pochi errori grandi contano più di tante piccole vittorie
  • La recuperabilità conta più della perfezione
  • L’attenzione umana dovrebbe andare dove ha la leva più alta
  • Imparare a lavorare con l’AI vale più di imparare a lavorare più veloce senza di essa

Cosa Potrebbe Andare Male

Tanto.

Non è un framework per principianti. Se non hai le basi di ingegneria per valutare quello che l’agente produce, farai ship di codice sbagliato con alta fiducia. L’agente non lo segnalerà. Non sa quello che non sa.

Non è una garanzia di risultati migliori. È una scommessa che un workflow progettato intorno ai punti di forza reali dell’AI (esecuzione veloce, iterazione instancabile) e ai suoi punti deboli (nessun giudizio reale, nessun contesto oltre a quello che gli dai) supererà il vecchio modo.

Ed è un esperimento. Sto tracciando dove gli agenti falliscono, dove sono ancora io il bottleneck, dove il loop si rompe. Se qualcosa non funziona, lo cambio. Il workflow è soggetto alla stessa regola che impone: itera o scarta.

Inizia Ora

Questa settimana. Ogni task. Nuovo protocollo.

Riporterò cosa si rompe.

Apri il terminale, scrivi il primo specs.md, e avvii il loop. Questo è non testato. Ma anche il vecchio non funzionava, quindi eccoci qui.