Workflow AI Coding: Roadmap Completa per AI Engineer

100K token. Questo è il confine reale tra un coding agent che produce codice di qualità e uno che inizia a prendere decisioni incoerenti. Non importa se il modello ha una context window da 1 milione di token: la smart zone, la finestra cognitiva effettiva di un LLM, resta intorno ai 100K. Tutto quello che viene dopo è zona morta.

Questo dato, confermato da benchmark indipendenti e dall’esperienza quotidiana con i coding agent che implementiamo per i clienti, cambia radicalmente come si deve strutturare il lavoro. Il workflow AI coding nel 2026 non è “apri il terminale e chiedi all’AI di programmare”. È un sistema ingegnerizzato con fasi precise, ruoli definiti e feedback loop continui.

Quella che segue è la roadmap che uso ogni giorno. Cinque fasi, dalla prima idea al codice in produzione, con i tool specifici, le skill da creare e i repo da avere nella propria cassetta degli attrezzi.

Due vincoli strutturali degli LLM che devi conoscere

Prima di qualsiasi workflow, serve capire due limiti cognitivi che condizionano ogni scelta operativa.

Smart zone e dumb zone: ogni token aggiunto alla context window aumenta le relazioni di attenzione in modo quadratico. Come aggiungere una squadra a un campionato di calcio: il numero di partite esplode. Intorno ai 100K token, la qualità dell’output inizia a degradare. L’agente “entra nella dumb zone”: prende scorciatoie, dimentica istruzioni, produce codice che non si integra con il resto.

L’agente è come il protagonista di Memento: ogni volta che cancelli il contesto, torna allo stato iniziale. Non ricorda nulla delle sessioni precedenti. Questo sembra un limite, ma è un vantaggio enorme se lo sfrutti correttamente. Uno stato iniziale pulito è sempre identico, sempre prevedibile, sempre nella smart zone. Il compacting (comprimere la conversazione senza cancellarla) è meno affidabile perché il sedimento residuo degrada la qualità nei cicli successivi.

Implicazione pratica: dimensiona ogni task perché l’agente resti nella smart zone. Se il task è troppo grande, spezzalo. Se la conversazione supera i 60-70K token, cancella e riparti. Questo vincolo è la ragione per cui tutto il workflow che segue è costruito attorno a task piccoli, indipendenti e parallelizzabili.

Fase 1: Alignment Session (il “Grill Me” che cambia tutto)

Il primo errore che vedo ripetere continuamente è passare direttamente dall’idea al codice. “Aggiungi la gamification alla piattaforma” → copia-incolla nel terminale → risultato inutilizzabile. Il problema non è l’AI. È che non avete un design concept condiviso.

Frederick P. Brooks in The Design of Design parla del shared design concept: l’idea condivisa tra tutti i partecipanti a un progetto. Con un coding agent serve la stessa cosa. Non un documento, non un piano: un allineamento cognitivo tra te e l’AI su cosa stiamo costruendo.

Come si ottiene? Con una alignment session strutturata. In pratica: crei una skill (un file Markdown nel tuo repo) che istruisce l’AI a farti domande aggressive, una alla volta, finché non avete raggiunto un’intesa completa sul task. La skill è minima:

• Prompt base: “Intervistami su ogni aspetto di questo piano finché non raggiungiamo un’intesa condivisa. Per ogni domanda fornisci la tua raccomandazione. Una domanda alla volta.”
• Durata tipica: 20-80 domande, 20-60 minuti
• Output: una conversazione che diventa il fondamento per tutto il lavoro successivo

L’alignment session non è specs-to-code. Non stai scrivendo specifiche per poi darle in pasto all’AI ignorando il codice. Stai costruendo un’intesa, e quell’intesa resta nella context window come “gold tokens”: token ad alto valore informativo che guidano tutto quello che segue.

Skill da creare: .claude/skills/grill-me.md nel tuo repo. Non serve un framework esterno. 5-10 righe di Markdown bastano. L’AI fa il resto.

Fase 2: PRD come destination document

Dopo l’alignment session hai 25-30K token di conversazione ad alto valore. Ora serve cristallizzarli in un destination document: un PRD (Product Requirements Document) che descrive dove stai andando, non come ci arrivi.

Il PRD contiene:

• Problem statement: il problema concreto che stai risolvendo
• Soluzione proposta: cosa costruirai
• User stories: 10-20 storie che definiscono il comportamento atteso
• Decisioni di implementazione: scelte tecniche già prese durante l’alignment
• Moduli coinvolti: quali parti della codebase vengono toccate
• Out of scope: cosa NON farai (critico per evitare scope creep)

Un punto controintuitivo: non serve rileggere il PRD. Se l’alignment session è stata fatta bene, hai già un design concept condiviso con l’AI. Il PRD è un artefatto di quel concetto, non un input da validare manualmente. L’AI è eccellente nella summarizzazione: se l’intesa è corretta, il riassunto lo sarà.

Skill da creare: .claude/skills/write-prd.md. Template di PRD con sezioni standard, istruzione per esplorare il repo prima di scrivere, e regola di includere sempre i moduli proposti da modificare. Questo mantiene il codice nel campo visivo fin dalla pianificazione.

Fase 3: Kanban Board con Vertical Slice

Qui succede la magia. Il PRD descrive la destinazione. Ora serve il viaggio: come ci arriviamo senza finire nella dumb zone?

La risposta sono i vertical slice, un concetto che arriva da The Pragmatic Programmer (1999) sotto il nome di traceable bullets. L’idea: invece di implementare per layer orizzontali (prima tutto il database, poi tutto il backend, poi tutto il frontend), ogni task attraversa tutti i layer verticalmente. Un singolo slice produce una funzionalità visibile e testabile end-to-end.

Perché questo è critico per l’AI? Tre ragioni:

• Feedback immediato: l’agente può verificare che tutto funziona dopo ogni slice, non dopo tre fasi orizzontali
• Task contenuti: ogni slice resta nella smart zone (uno slice = una sessione = contesto pulito)
• Parallelizzazione: slice indipendenti possono essere assegnati ad agenti diversi in parallelo

Il Kanban board che generi dal PRD ha relazioni di blocco tra le issue. Se lo slice A deve essere completato prima dello slice B, lo dichiari esplicitamente. Questo trasforma il piano sequenziale in un DAG (directed acyclic graph) parallelizzabile.

Errore tipico da correggere: l’AI tende a proporre slice orizzontali (“prima creiamo il servizio, poi l’API, poi l’UI”). Devi intervenire e dire: “Il primo slice è troppo orizzontale. Voglio schema + servizio + UI minima nel primo slice.” Questa correzione dà all’agente feedback sulla propria architettura fin dalla prima iterazione.

Skill da creare: .claude/skills/prd-to-issues.md. Include l’istruzione esplicita “Usa vertical slice / traceable bullets” e la regola che ogni issue deve produrre qualcosa di visibile e testabile end-to-end.

Fase 4: Implementazione AFK con TDD

Ecco dove l’umano lascia il loop. L’agente prende le issue dal Kanban board e le implementa in autonomia, una per sessione, con contesto pulito ogni volta.

Il pattern si chiama AFK loop (o “Ralph loop” nella community). È uno script bash che:

• Carica tutte le issue del backlog in contesto (come testo, non come link)
• Passa gli ultimi 5 commit per dare senso della direzione del progetto
• Avvia il coding agent con modalità accept-edits (o in Docker sandbox per sicurezza)
• L’agente sceglie la prossima issue secondo priorità definite nel prompt
• Implementa con TDD: red → green → refactor
• Esegue i feedback loop (test, typecheck)
• Committa e passa alla prossima issue (o esce se ha finito)

Perché TDD è non negoziabile: senza test, l’agente codifica alla cieca. Non ha modo di verificare se il suo codice funziona. Il TDD fornisce un feedback loop oggettivo e, dettaglio cruciale, impedisce all’AI di “barare” sui test. Quando scrivi il test prima dell’implementazione, non puoi adattare il test al codice già scritto.

Setup pratico:

• Vitest/Jest: per progetti TypeScript (veloce, watch mode)
• pytest: per progetti Python
• Docker sandbox: per isolare l’agente dal sistema (tool: Sandcastle o container custom)
• Skill TDD: .claude/skills/tdd.md con istruzione “Red Green Refactor: scrivi un test che fallisce, fallo passare, poi refactora”

Fase 5: QA, Review e il pattern Push vs Pull

L’agente ha completato le issue. Ora serve qualità. Due passaggi separati, nessuno opzionale.

Automated review (in contesto pulito): non far fare la review allo stesso agente che ha scritto il codice. Sarebbe come chiedere a uno studente di correggere il proprio compito. Cancella il contesto, avvia un nuovo agente con il diff e le coding standard, e fai valutare il codice nella smart zone. Usa Opus (o il modello più potente disponibile) per la review, anche se hai usato Sonnet per l’implementazione.

QA manuale: qui è dove imponi il tuo gusto. L’AI non ha occhi per il frontend. Non capisce se un’interazione “sembra giusta”. Non sa se il flow è intuitivo per un utente reale. La QA manuale è il momento in cui generi nuove issue per il Kanban board: bug trovati, miglioramenti di UI, edge case scoperti. Queste issue tornano nel loop AFK.

Pattern Push vs Pull per coding standard:

• Pull (implementazione): le coding standard sono disponibili come skill. L’agente le consulta se ha dubbi. Non inquini il prompt con informazioni che potrebbero non servire
• Push (review): le coding standard vengono iniettate direttamente nel contesto del reviewer. L’agente di review riceve sia il codice che le regole da verificare. Nessuna possibilità di ignorarle

Architettura: Deep Module per far lavorare meglio l’AI

Una codebase di file piccoli con molte dipendenze incrociate (shallow module) è un incubo per i coding agent. L’AI deve navigare decine di import, tracciare dipendenze, capire dove testare. Risultato: codice frammentato, test che mockano tutto, e nessun feedback reale.

La soluzione viene da John Ousterhout (A Philosophy of Software Design): deep module. Moduli con un’interfaccia piccola e semplice, ma molta logica interna. Pochi file, molte responsabilità coese, test boundary chiari.

Vantaggi concreti per l’AI:

• Meno file da navigare: l’agente non si perde in un grafo di 200 micro-file
• Test boundary naturali: un test per modulo, che testa il comportamento tramite l’interfaccia pubblica
• Delega dell’implementazione: puoi conoscere solo l’interfaccia di un modulo e delegare tutto l’interno all’AI. Il gray box: sai cosa fa, non come lo fa
• Meno mock: se il modulo è autocontenuto, non servono mock di dipendenze esterne per testarlo

Skill da creare: .claude/skills/improve-architecture.md. Istruzione: “Scansiona la codebase, identifica cluster di file con dipendenze incrociate, proponi come consolidarli in deep module con interfacce pulite e test boundary chiari.”

Questo è forse il singolo miglioramento con il ROI più alto. Una sessione di 30 minuti con questa skill può trasformare una codebase ingovernabile in una dove l’AI produce codice di qualità al primo tentativo.

Parallelizzazione: più agenti sullo stesso progetto

Se il Kanban board ha issue senza relazioni di blocco tra loro, possono essere lavorate in parallelo da agenti indipendenti. Ogni agente opera in un worktree Git separato (un branch isolato), implementa la propria issue, e poi un agente “merger” riunisce i branch risolvendo conflitti.

Il setup con Sandcastle (TypeScript) o script bash equivalenti:

• Planner: legge il backlog, identifica le issue parallelizzabili, assegna i branch
• Implementer (×N): ogni agente prende una issue, crea un worktree, implementa con TDD
• Reviewer: review automatica su ogni branch prima del merge
• Merger: unisce i branch, risolve conflitti di tipo e test, produce il commit finale

Tool e repo per iniziare:

• Sandcastle: libreria TypeScript open source per orchestrazione di loop paralleli con Docker sandbox. Crea worktree, sandboxa in container, esegue prompt e merge
• Claude Code con worktree: il flag isolation: ‘worktree’ nei workflow dinamici crea automaticamente branch isolati per ogni subagent
• Git worktree nativo: git worktree add ../branch-name per setup manuali senza framework
• GitHub Issues + label “afk”: per separare issue automatizzabili da quelle che richiedono decisioni umane

Checklist completa: cosa installare e configurare

La roadmap sintetica per chi vuole partire oggi:

• Coding agent: Claude Code (npm install -g @anthropic-ai/claude-code) o equivalente. Configura la status line per monitorare sempre i token usati
• Framework test veloce: Vitest per TS/JS, pytest per Python. Il tempo di esecuzione dei test è il ceiling della qualità dell’agente
• 4 skill Markdown nel repo: grill-me, write-prd, prd-to-issues, tdd. Ogni skill è 5-15 righe. Nessun framework esterno
• Docker Desktop: per sandbox degli agenti AFK (opzionale ma consigliato per sicurezza)
• Architettura skill: .claude/skills/improve-architecture.md per scansione e consolidamento moduli. Una sessione trasforma la codebase
• Libri da leggere: The Pragmatic Programmer (Hunt/Thomas), A Philosophy of Software Design (Ousterhout), The Design of Design (Brooks). Pre-AI ma perfettamente applicabili come prompt engineering implicito
• CLAUDE.md minimale: non riempirlo di 250K di contesto. Solo le informazioni essenziali. Il system prompt deve restare piccolo per non consumare smart zone
• Monitoring token: controlla sempre quanti token stai usando. Superare i 60-70K è il segnale per cancellare e ripartire

Le domande aperte (e perché non hanno ancora risposta)

Questo workflow funziona bene per sviluppatori singoli o team piccoli. Ma ci sono problemi non risolti che vale la pena menzionare onestamente.

Code review scaling: se deleghi tutta l’implementazione agli agenti, la quantità di codice da rivedere esplode. Non esiste ancora un modo elegante per mantenere PR piccole e self-contained quando l’agente produce 4 issue in un ciclo AFK. È un problema reale e scomodo.

Frontend e gusto: l’AI non ha occhi. Può generare prototipi e varianti da cui scegliere, ma non sa se un’interazione “sembra giusta”. Il frontend resta l’area dove l’intervento umano è più frequente e meno delegabile.

Doc rot: i PRD, una volta implementati, diventano rapidamente obsoleti. Se li tieni nel repo, l’agente potrebbe usarli come riferimento anche quando il codice si è evoluto in direzioni diverse. La soluzione pragmatica: eliminarli dopo l’implementazione, o segnarli come “chiusi” su GitHub Issues.

Il workflow perfetto non esiste. Quello che esiste è un sistema che ti permette di delegare l’implementazione rimanendo in controllo dell’architettura, della qualità e della direzione. Non tutto il controllo: il giusto controllo. Se vuoi vedere come applichiamo questo workflow con i nostri clienti, dai un’occhiata ai casi studio. Per chi vuole costruire questa competenza nel proprio team, il nostro percorso di formazione aziendale copre esattamente questo stack.