03 - Workflow Agentici: Decomporre Problemi per AI
C'e un momento preciso in cui l'AI smette di essere un assistente e diventa un collaboratore: quando smetti di chiederle "scrivi questa funzione" e inizi a chiederle "risolvi questo problema". Quel salto mentale, dalla singola istruzione al task complesso, e il cuore dei workflow agentici. Ed e anche il punto in cui la maggior parte dei developer si blocca, perchè costruire un workflow agentico efficace richiede un cambio di paradigma profondo: non si tratta di prompt più lunghi, ma di architettura.
Nel 2025, il 92% degli sviluppatori americani usa strumenti AI nel proprio lavoro quotidiano (Stack Overflow Developer Survey 2025), ma solo una frazione di questi sfrutta davvero il potenziale dei sistemi agentici. Il problema non e l'accesso alla tecnologia: e la mancanza di pattern architetturali chiari per decomporre problemi complessi in task che un agente AI può risolvere in modo affidabile, verificabile e ripetibile.
In questo articolo costruiremo insieme una comprensione profonda dei workflow agentici: dai pattern fondamentali (Sequential, Parallel, Hierarchical, Iterative) all'implementazione pratica con Claude Code, passando per la gestione del contesto, le metriche di qualità e gli anti-pattern che trasformano un workflow promettente in un sistema inaffidabile. Il tutto con case study reali e codice funzionante.
Cosa Imparerai
- I quattro pattern fondamentali di decomposizione: Sequential, Parallel, Hierarchical, Iterative
- L'architettura di un workflow agentico: Planner, Executor, Reviewer, Memory
- Come strutturare CLAUDE.md per guidare agenti su progetti reali
- Il loop Plan-Execute-Review e i workflow di self-healing
- Tool use e context management per sessioni agentiche lunghe
- Metriche per valutare la qualità di un workflow agentico
- Gli anti-pattern più pericolosi e come evitarli
- Case study: refactoring di una codebase Angular con workflow agentico
Cos'è un Workflow Agentico
Un workflow agentico e una sequenza strutturata di operazioni in cui uno o più agenti AI pianificano, eseguono e verificano azioni per raggiungere un obiettivo complesso. A differenza di una singola chiamata LLM, un workflow agentico ha memoria tra i passi, può usare strumenti (file system, terminale, web, API), può delegare subtask ad agenti specializzati e può adattarsi agli errori senza intervento umano.
La distinzione chiave rispetto al vibe coding "naive" sta nella struttura deliberata. Chiedere a Claude "refactorizza questa codebase" produce risultati mediocri. Costruire un workflow che: (1) analizza la codebase, (2) identifica i componenti da refactorizzare in ordine di priorità, (3) refactorizza un componente alla volta con test di regressione, (4) verifica ogni step prima di procedere, produce risultati professionali. La differenza e la decomposizione.
Definizione Operativa
Un workflow agentico e affidabile quando: ogni step e verificabile indipendentemente, il fallimento di un passo non corrompe l'intero workflow, l'output finale e deterministico rispetto all'input, e un operatore umano può ispezionare e correggere il workflow a qualsiasi checkpoint. Questa definizione viene dal framework Anthropic "Building effective agents" (2024) e rimane la bussola per valutare qualsiasi implementazione.
Problem Decomposition: Il Nucleo del Workflow Agentico
La ricerca TDAG (Task Decomposition and Agent Generation, 2025) ha dimostrato che la qualità della decomposizione e il fattore più predittivo del successo di un sistema multi-agente: una decomposizione sbagliata propaga errori in modo esponenziale attraverso i passi successivi, mentre una decomposizione corretta isola i fallimenti e permette il recovery.
Esistono quattro pattern fondamentali di decomposizione, ciascuno adatto a tipi diversi di problemi:
Pattern 1: Sequential (Catena)
Il pattern più semplice: ogni task dipende dall'output del precedente. Adatto a workflow lineari dove l'ordine e semanticamente significativo (es: analisi -> design -> implementazione -> test).
Pattern Sequential:
[Input]
|
v
[Task A] --> output_A
|
v
[Task B] --> output_B
|
v
[Task C] --> [Output Finale]
Caratteristiche:
- Ogni task riceve output del precedente come contesto
- Fallimento in Task B blocca Task C
- Debugging semplice: errore localizzato al task fallito
- Latenza: somma di tutti i tempi (A + B + C)
Caso d'uso tipico: Pipeline di generazione codice
1. Analisi requisiti
2. Design architetturale
3. Implementazione
4. Test generation
5. DocumentationPattern 2: Parallel (Scatter-Gather)
Più task indipendenti vengono eseguiti simultaneamente da agenti separati, con un aggregatore che raccoglie e sintetizza i risultati. Riduce drasticamente la latenza ma richiede che i subtask siano davvero indipendenti (nessuna condivisione di stato mutabile).
Pattern Parallel (Scatter-Gather):
[Input]
|
[Orchestrator/Splitter]
/ | \
v v v
[Task A] [Task B] [Task C]
out_A out_B out_C
\ | /
v v v
[Aggregator/Merger]
|
[Output Finale]
Caratteristiche:
- Task A, B, C eseguiti in parallelo (via sub-agents)
- Latenza: max(A, B, C) invece di A + B + C
- Fallimento parziale: gestibile se aggregatore e robusto
- Rischio: race condition su risorse condivise
Caso d'uso tipico: Review multi-dimensionale
Agent 1: Security review
Agent 2: Performance analysis
Agent 3: Code style check
Agent 4: Test coverage analysis
Aggregator: Synthesize findingsPattern 3: Hierarchical (Supervisor-Worker)
Un agente supervisore decompone il problema in subtask e delega a worker specializzati. I worker possono a loro volta avere sub-worker. E il pattern più potente per problemi di grandi dimensioni ma anche il più complesso da debuggare. LangGraph ha documentato questo pattern come il più adottato nel 2025 per sistemi enterprise.
Pattern Hierarchical:
[Planner Agent]
"Refactorizza il modulo auth"
/ | \
v v v
[Backend Agent] [Frontend] [Test Agent]
"Refactorizza "Aggiorna "Aggiorna
AuthService" LoginCmp" test suite"
| | |
[sub-tasks] [sub-tasks] [sub-tasks]
| | |
done done done
\ | /
v v v
[Planner: Merge & Verify]
|
[Output Finale]
Livelli tipici in sistemi reali:
L0: Problem Planner (decompone goal globale)
L1: Domain Agents (backend, frontend, infra)
L2: Task Workers (singoli file, funzioni)
L3: Tool Calls (bash, file system, test)Pattern 4: Iterative (ReAct / Reflexion)
L'agente opera in loop: esegue un'azione, osserva il risultato, riflette sullo stato attuale e decide il passo successivo. E il pattern del ReAct framework (Reasoning + Acting) e della sua estensione Reflexion (che aggiunge una critica esplicita). Adatto a problemi esplorativi dove il percorso di soluzione non e noto a priori.
Pattern Iterative (ReAct + Reflexion):
[Goal]
|
v
[Think] <-----------+
| |
v |
[Act / Tool Use] | (se max_iter non
| | raggiunto e goal
v | non soddisfatto)
[Observe] |
| |
v |
[Critique/Reflect]--+
|
(se goal soddisfatto)
|
v
[Output]
Elementi chiave:
- Scratchpad: memoria degli step precedenti
- Stop condition: goal raggiunto O max_iterations
- Critique: valutazione esplicita dell'output parziale
- Tool repertoire: set di tool disponibili all'agente
Caso d'uso: Debugging di un test che fallisce
1. Leggi error message
2. Analizza codice correlato
3. Formula ipotesi
4. Applica fix
5. Esegui test
6. Se fallisce ancora: ritorna a step 2
7. Se passa: scrivi explanationArchitettura di un Workflow Agentico
Indipendentemente dal pattern scelto, un workflow agentico maturo ha quattro componenti fondamentali. Comprenderli e il prerequisito per costruire sistemi robusti in produzione.
1. Planner
Il Planner riceve il goal di alto livello e lo trasforma in un piano strutturato: una sequenza (o DAG) di subtask con dipendenze, assegnazione agli agenti, criteri di successo per ogni passo e stima delle risorse (token budget, tool necessari). Un buon Planner produce piani verificabili: ogni step ha un output atteso ben definito.
2. Executor
L'Executor prende i singoli task dal Planner e li esegue, usando i tool disponibili: file system,
bash, web search, API. Ogni Executor specializzato (backend agent, test agent, doc agent) ha
accesso solo agli strumenti necessari per il suo dominio, seguendo il principio del
least privilege. Claude Code implementa questo attraverso il sistema di
permessi e i custom sub-agents con allowedTools configurabili.
3. Reviewer
Il Reviewer verifica che l'output di ogni Executor soddisfi i criteri di successo definiti dal Planner. Non e un semplice "sembra ok": un Reviewer di qualità esegue test automatici, analisi statica, controlli di regressione. Il Reviewer può approvare (workflow procede), richiedere modifiche (l'Executor ritenta) o escalare all'umano (checkpoint obbligatorio).
4. Memory
La Memory gestisce il contesto attraverso i passi del workflow. Ha due livelli:
- Short-term (in-context): il contenuto della context window corrente, inclusi gli output degli step precedenti. Limitata dai token disponibili.
-
Long-term (external): file di stato (es:
claude-progress.txt), database, git history. Permette di riprendere workflow interrotti tra sessioni diverse.
Il Pattern claude-progress.txt
Anthropic consiglia di usare un file claude-progress.txt nella root del progetto
per la memoria inter-sessione. L'agente inizializzatore scrive lo stato del workflow ad ogni
checkpoint; l'agente successivo legge questo file per capire dove si trova il lavoro e cosa
deve fare. In combinazione con git log, fornisce un contesto completo senza
saturare la context window.
Implementazione Pratica con Claude Code
Claude Code offre tre leve principali per costruire workflow agentici: il file
CLAUDE.md per guidare il comportamento dell'agente, il
Task tool per delegare a sub-agents, e i custom agents
(definiti in .claude/agents/) per specializzazione. Vediamo come combinarli.
Struttura CLAUDE.md per Workflow Agentici
Il file CLAUDE.md e la "costituzione" del tuo progetto per gli agenti AI. Un CLAUDE.md progettato per workflow agentici include non solo le informazioni sul progetto, ma la struttura del workflow stesso: quali agenti esistono, come si coordinano, quali sono i criteri di successo per ogni fase.
# CLAUDE.md - Workflow Agentico per Progetto Angular
## Progetto
Portfolio Angular con SSR, Angular 21, TypeScript strict.
Stack: Angular, Firebase, SCSS.
## Workflow Agentici Disponibili
### Workflow: Feature Development
Usa questo workflow per implementare nuove feature:
**Fase 1 - Planning** (obbligatoria):
- Leggi tutti i file correlati alla feature
- Crea `docs/plans/[feature-name].md` con:
- Componenti da creare/modificare
- Interfacce TypeScript necessarie
- Test da scrivere (TDD: scrivi prima i test)
- Dipendenze e rischi
- NON implementare finchè il piano non e approvato
**Fase 2 - TDD Implementation**:
- Scrivi unit test PRIMA dell'implementazione
- Implementa il minimo necessario per far passare i test
- Poi refactorizza
- Verifica `npm test` passa senza errori
**Fase 3 - Review**:
- Esegui `npm run lint`
- Verifica che build SSR compili: `npm run build`
- Controlla che non ci siano regressioni
### Workflow: Refactoring
Per refactoring di componenti esistenti:
1. Crea branch: `git checkout -b refactor/[nome]`
2. Analizza dipendenze del componente con grep/Glob
3. Refactorizza UN componente alla volta
4. Verifica test dopo ogni componente
5. Commit atomico per ogni componente
### Workflow: Debug
Per bug fixing:
1. Riproduci il bug con un test che fallisce
2. Identifica root cause (NON fixare sintomi)
3. Applica fix minimale
4. Verifica che il test ora passi
5. Controlla regressioni
## Agenti Specializzati
Disponibili in `.claude/agents/`:
- `architect.md`: Per decisioni architetturali
- `security-reviewer.md`: Prima di ogni commit
- `code-reviewer.md`: Dopo ogni implementazione
- `tdd-guide.md`: Per TDD workflow
## Criteri di Successo Globali
- TypeScript strict: zero errori `tsc --noEmit`
- Test coverage: minimo 80%
- Build SSR: `npm run build` deve completare senza errori
- Nessun `any` implicito
- Nessuna mutazione di stato (immutability pattern)
## Gestione Errori
Se un comando fallisce:
1. Leggi l'errore completo
2. NON procedere al passo successivo
3. Identifica e risolvi prima di continuare
4. Se non riesci dopo 2 tentativi: STOP e chiedi chiarimentiPrompt Engineering per Task Decomposition
La qualità della decomposizione dipende direttamente dalla qualità del prompt iniziale. Ecco un template testato per guidare un agente nella decomposizione di task complessi:
# Prompt Template: Task Decomposition
## Contesto
Sei un Planning Agent. Il tuo compito e decomporre il goal seguente
in subtask concreti, verificabili e assegnabili a agenti specializzati.
## Goal
[DESCRIZIONE DEL GOAL]
## Vincoli
- Ogni subtask deve avere: ID, descrizione, input atteso, output atteso,
agente responsabile, criteri di successo (verificabili automaticamente)
- I subtask devono essere ordinati per dipendenze (DAG)
- Nessun subtask deve durare più di [X] minuti / [Y] token
- Definisci i checkpoint obbligatori dove un umano deve approvare
## Output Atteso
Produci un piano strutturato in questo formato JSON:
{
"goal": "descrizione del goal",
"estimated_complexity": "low|medium|high",
"subtasks": [
{
"id": "T001",
"description": "Analizza la struttura del componente AuthService",
"agent": "analyzer",
"inputs": ["src/app/services/auth.service.ts"],
"outputs": ["docs/analysis/auth-service.md"],
"success_criteria": ["file creato", "contiene sezioni: deps, interfaces, methods"],
"depends_on": [],
"estimated_tokens": 8000
},
{
"id": "T002",
"description": "Scrivi test per AuthService",
"agent": "tdd-agent",
"inputs": ["docs/analysis/auth-service.md", "src/app/services/auth.service.ts"],
"outputs": ["src/app/services/auth.service.spec.ts"],
"success_criteria": ["npm test -- --testPathPattern=auth.service passa"],
"depends_on": ["T001"],
"estimated_tokens": 12000
}
],
"checkpoints": ["dopo T001: review del piano", "dopo T003: review implementazione"],
"rollback_strategy": "git stash prima di ogni modifica distruttiva"
}Uso del Task Tool per Sub-Agents
Claude Code espone il Task tool per delegare lavoro a sub-agents. Ogni sub-agent opera in un contesto isolato con la propria context window, il che permette di gestire workflow che superano i limiti di una singola sessione. La ricerca Anthropic (2026 Agentic Coding Trends Report) indica che il pattern più efficace usa Opus per l'orchestrazione e Sonnet per i worker, riducendo i costi del 40-60% mantenendo la qualità.
# Prompt per orchestrare sub-agents con Task tool
Devo refactorizzare il modulo di autenticazione di questa Angular app.
Ho analizzato il codebase e identifico questi task paralleli indipendenti:
**Task 1 - Security Review** (usa Task tool):
Prompt: "Leggi src/app/services/auth.service.ts e tutti i file che lo importano.
Analizza vulnerabilità di sicurezza: token storage, session management,
CSRF protection. Produci un report markdown in docs/security/auth-review.md
con priorità: CRITICAL, HIGH, MEDIUM, LOW."
Tools: Read, Grep, Write
**Task 2 - Test Coverage Analysis** (usa Task tool):
Prompt: "Analizza src/app/services/auth.service.spec.ts vs auth.service.ts.
Identifica funzioni non coperte dai test. Produci lista in docs/analysis/test-gaps.md"
Tools: Read, Glob, Grep, Write
**Task 3 - Dependency Graph** (usa Task tool):
Prompt: "Mappa tutte le dipendenze di AuthService usando grep e glob.
Crea docs/analysis/auth-deps.md con grafo ASCII delle dipendenze."
Tools: Read, Glob, Grep, Write
Esegui i 3 Task in parallelo. Quando tutti completano, leggi i 3 report
e produci docs/plans/auth-refactoring.md con il piano di refactoring
consolidato, ordinato per priorità."Workflow Patterns Avanzati
Plan-Execute-Review Loop
Il loop PER (Plan-Execute-Review) e il pattern più robusto per workflow complessi. Ogni iterazione produce un artefatto verificabile prima di procedere alla successiva. La chiave e che il Review step non e opzionale: e il meccanismo che previene la propagazione degli errori.
Plan-Execute-Review Loop:
ITERAZIONE 1:
Plan: "Analizza AuthService e crea piano di refactoring"
Execute: Agente legge codice, scrive docs/plans/auth.md
Review: Verifica che docs/plans/auth.md esiste e ha sezioni richieste
-> PASS: procedi a iterazione 2
-> FAIL: retry Execute (max 2 volte), poi escalate
ITERAZIONE 2:
Plan: "Scrivi test per AuthService (basati sul piano)"
Execute: Agente scrive auth.service.spec.ts
Review: `npm test -- --testPathPattern=auth` deve passare
-> PASS: procedi a iterazione 3
-> FAIL: agente debug + retry
ITERAZIONE 3:
Plan: "Refactorizza AuthService (TDD: test devono restare verdi)"
Execute: Agente modifica auth.service.ts
Review: `npm test` + `tsc --noEmit` + `npm run lint`
-> PASS: procedi a iterazione 4
-> FAIL: `git checkout src/app/services/auth.service.ts` + retry
ITERAZIONE 4:
Plan: "Aggiorna componenti che usano AuthService"
Execute: Agente aggiorna LoginComponent, ProfileComponent, etc.
Review: `npm run build` (SSR build completa)
-> PASS: workflow completato
-> FAIL: rollback + analisi root cause
Metriche del Loop:
- Tasso di retry per iterazione (ideale: <20%)
- Token consumati per iterazione
- Tempo per iterazione
- Success rate complessivoMulti-Agent Code Review Pipeline
Una pipeline di code review multi-agente e uno dei casi d'uso più maturi per i workflow agentici nel 2025. Ogni agente specializzato porta una prospettiva diversa, e l'aggregazione produce una review più completa di qualsiasi singolo agente.
Pipeline Multi-Agent Code Review:
Input: Pull Request con modifiche al codebase
FASE 1 - Parallel Review (4 agenti in parallelo):
Agent A: Security Reviewer
- Cerca: SQL injection, XSS, CSRF, secrets esposti
- Tool: Read, Grep (pattern: hardcoded secrets, eval, innerHTML)
- Output: security-report.md (CRITICAL/HIGH/MEDIUM/LOW)
Agent B: Performance Analyst
- Cerca: memory leak, N+1 queries, bundle size impact
- Tool: Read, Glob, Bash (npm run analyze)
- Output: performance-report.md
Agent C: Type Safety Checker
- Cerca: any impliciti, type assertion unsafe, null check mancanti
- Tool: Read, Bash (tsc --noEmit --strict)
- Output: types-report.md
Agent D: Test Coverage
- Verifica: nuove funzioni hanno test, edge cases coperti
- Tool: Read, Bash (npm test -- --coverage)
- Output: coverage-report.md
FASE 2 - Synthesis (1 agente):
Input: i 4 report paralleli
Task: Sintetizza in PR-review.md con:
- Issues raggruppate per severita
- Blockers (nessun merge finchè non risolti)
- Suggestions (opzionali ma consigliate)
- Positive findings (cosa e fatto bene)
FASE 3 - Human Checkpoint:
Il developer legge PR-review.md e decide:
- Merge as is (zero blockers)
- Fix blockers e re-run pipeline
- Request clarification on specific issuesSelf-Healing Workflows: Retry e Fallback
I workflow in produzione falliscono. La domanda non e "se" ma "quando" e "come si riprende". Un workflow self-healing implementa strategie di retry con backoff esponenziale, rollback automatico agli ultimi checkpoint validi e fallback a strategie alternative quando il percorso principale fallisce ripetutamente.
Self-Healing Workflow Pattern:
STRATEGIA 1: Retry con Backoff
Tentativi: 1, 2, 3 (max)
Attesa: 0s, 30s, 120s
Condizione retry: errore transitorio (timeout, rate limit)
Condizione NO retry: errore logico (file non trovato, syntax error)
STRATEGIA 2: Checkpoint + Rollback
Prima di ogni modifica distruttiva:
$ git stash push -m "checkpoint-[step-id]-[timestamp]"
Se step fallisce dopo max retry:
$ git stash pop # rollback allo stato precedente
-> Notifica umano con context dell'errore
STRATEGIA 3: Alternative Path
Step principale: Refactorizza con TypeScript strict
Se fallisce 3 volte:
Fallback 1: Refactorizza con TypeScript non-strict + TODO commenti
Se fallisce ancora:
Fallback 2: Documenta il problema invece di risolvere
Escalate: crea docs/issues/[step-id]-blocked.md
STRATEGIA 4: Isolamento Fallimenti
Workflow di 10 step:
Step 1-5: completati con successo
Step 6: fallisce
-> NON annullare step 1-5
-> Salva stato "parzialmente completato"
-> Riprendi da step 6 dopo fix manuale
IMPLEMENTAZIONE in Claude Code:
"Se il comando fallisce, NON procedere al passo successivo.
Prima di ogni modifica ai file, esegui:
git stash push -m 'pre-[descrizione]'
Se dopo 2 tentativi il task non funziona, STOP.
Crea docs/blocked/[task-id].md con:
- Comando che ha fallito
- Output dell'errore completo
- Ipotesi sulla causa
- Cosa e stato completato prima del blocco"Tool Use e Context Management
La gestione del contesto e probabilmente la sfida tecnica più sottile nei workflow agentici. Una context window mal gestita produce risultati degradati, dimenticanze e allucinazioni. Una context window ben gestita permette sessioni agentiche di ore su codebase di migliaia di file.
Token Budget e Prioritizzazione
Claude Code opera con una context window di 200.000 token, ma consumarla tutta in una singola sessione e un anti-pattern. La ricerca Anthropic suggerisce di operare nel range 60-80% della context window massima per mantenere qualità costante. Oltre l'80%, la qualità delle risposte degrada significativamente.
Strategie di Context Management:
1. PROGRESSIVE SUMMARIZATION
Dopo ogni step completato:
"Aggiorna claude-progress.txt con un riassunto conciso di questo step:
- Cosa e stato fatto
- File modificati (lista)
- Test status (pass/fail)
- Prossimo step previsto
MAX 200 parole. Poi usa /compact per comprimere la conversazione."
2. SELECTIVE LOADING
NON leggere tutti i file del progetto all'inizio.
Leggi solo i file rilevanti per il task corrente:
- Usa Glob per identificare file per pattern
- Usa Grep per trovare dipendenze specifiche
- Leggi file solo quando necessario (lazy loading)
3. EXTERNAL STATE
File di stato persistenti (sopravvivono tra sessioni):
- claude-progress.txt: stato workflow corrente
- docs/plans/[feature].md: piano approvato
- docs/analysis/[component].md: analisi completate
Inizio sessione: "Leggi claude-progress.txt e docs/plans/
attivi. Dimmi dove siamo nel workflow e cosa devi fare ora."
4. TOOL CHAINING EFFICIENTE
INSTEAD OF: Read 20 file + analizza tutto
DO THIS:
1. Grep per pattern specifico (trova file rilevanti)
2. Glob per struttura directory
3. Read SOLO i file identificati come rilevanti
4. Elabora
Risparmio tipico: 60-70% token
5. CHECKPOINT COMPACTION
Ogni 5-10 step complessi, usa /compact in Claude Code.
Poi ricarica contesto da claude-progress.txt.
Mantieni la sesione fresca per i task restanti.Gestione dei Tool Calls
Ogni tool call consuma token (sia per il tool use che per la risposta). Una gestione efficiente dei tool call e critica per workflow lunghi. Il principio chiave e batching: aggregare più operazioni nella stessa tool call invece di fare molte chiamate separate.
Anti-Pattern: Tool Call Storm
Un errore comune e chiedere all'agente di leggere i file uno alla volta con loop espliciti.
Questo genera centinaia di tool call e satura rapidamente il context. Invece, usa pattern
come Glob + Grep per identificare i file rilevanti, poi leggi solo quelli.
Claude Code può eseguire multiple tool calls in parallelo quando sono indipendenti: questa
feature riduce la latenza del 40-60% rispetto alle chiamate sequenziali.
Metriche e Valutazione dei Workflow Agentici
"Funziona" non e una metrica. Per valutare e migliorare un workflow agentico, servono metriche quantitative su quattro dimensioni: affidabilità, qualità dell'output, efficienza e sicurezza.
Framework di Metriche per Workflow Agentici:
AFFIDABILITA
- Task Completion Rate (TCR): % task completati senza intervento umano
Target: >85% per workflow di produzione
- Retry Rate: % step che richiedono più di 1 tentativo
Target: <20% per step (>20% indica task mal specificato)
- Escalation Rate: % step escalati a umano
Target: dipende dal rischio del dominio (5-30%)
QUALITA OUTPUT
- Test Pass Rate: % test che passano dopo il workflow
Target: 100% (zero regressioni accettabili)
- Build Success Rate: % build SSR che completano senza errori
Target: 100%
- Code Review Score: punteggio da code-reviewer agent (1-10)
Target: >7 prima di merge
EFFICIENZA
- Token per Task: token consumati / task completato
Baseline: misura nelle prime 10 esecuzioni
- Latenza End-to-End: tempo totale del workflow
Ottimizza con parallelismo quando bottleneck identificato
- Cost per Feature: costo API totale / feature implementata
Target: definito dal business, tipico $0.10 - $2.00
SICUREZZA
- Destructive Operations Count: operazioni che modificano/eliminano dati
Flag ogni operazione con rm, DROP, DELETE, overwrite
- Unauthorized Tool Use: tool calls non consentite dal CLAUDE.md
Target: 0 (monitorato via hooks)
- Secret Exposure: secrets nel codice generato
Verifica automatica con grep patternsAnti-Pattern da Evitare
La letteratura del 2025 sui sistemi agentici ha identificato pattern ricorrenti di fallimento. Conoscerli in anticipo e il modo più efficiente per costruire workflow robusti.
1. Over-Decomposition
Scomporre un task in troppi subtask crea overhead di coordinazione che supera il beneficio. Se un task richiede meno di 5 minuti e 3.000 token, probabilmente non ha senso delegarlo a un sub-agent separato. La ricerca multi-agente mostra che sistemi con più di 5-7 agenti attivi simultaneamente tendono ad avere tassi di errore esponenzialmente più alti (il cosiddetto "17x error trap" documentato da Towards Data Science, 2025).
Over-Decomposition: Esempio
Sbagliato: Creare 15 sub-agent per refactorizzare 15 funzioni in un singolo
file da 200 righe. La overhead di coordinazione (context setup per ogni agente, merge dei
risultati, gestione conflitti) supera il tempo che avrebbe impiegato un singolo agente.
Corretto: Un singolo agente legge il file, identifica le 15 funzioni,
le refactorizza in sequenza con test intermedi. Sub-agents solo per file/moduli realmente
indipendenti e di dimensioni significative.
2. Under-Specification
Task descritti in modo vago producono output imprevedibili. "Migliora il codice" non e un task: e una speranza. Ogni task deve specificare: cosa fare, su quali file, quali vincoli rispettare, come verificare il successo. L'under-specification e la causa numero 1 di workflow che sembrano funzionare ma producono output di scarsa qualità.
3. Context Pollution
Caricare in context window troppo contesto irrilevante (file non necessari, conversazioni precedenti, documentazione verbosa) degrada la qualità delle risposte. Il fenomeno "lost in the middle" - documentato dalla ricerca su LLM nel 2024 - mostra che gli LLM prestano meno attenzione alle informazioni nel mezzo della context window. Tieni il contesto pulito, mirato e strutturato.
4. Missing Rollback Strategy
L'incidente Replit del 2025 - in cui un agente ha eliminato un database di produzione - e l'esempio più citato di workflow senza rollback strategy. Ogni operazione distruttiva (delete, overwrite, DROP) deve avere un meccanismo di undo: git stash, backup, transazioni reversibili. "L'agente sapeva cosa stava facendo" non e una strategia di disaster recovery.
5. No Human-in-the-Loop
I workflow completamente automatizzati senza checkpoint umani sono appropriati solo per task a basso rischio e ben compresi. La ricerca Anthropic (2026 Agentic Coding Trends Report) mostra che gli sviluppatori delegano completamente (0% supervisione) solo il 20% dei task: il restante 80% richiede almeno un checkpoint di revisione. Progetta i workflow con Human-in- the-Loop espliciti per decisioni architetturali, deployment e modifiche ai dati.
6. Agente Senza Memoria Inter-Sessione
Ogni nuova sessione Claude Code parte da zero. Un workflow complesso (5+ ore di lavoro) che
non scrive stato esterno e destinato a perdere progresso. Usa sempre claude-progress.txt,
file di piano in docs/ e commit frequenti come meccanismi di persistenza.
Case Study: Refactoring di una Codebase Angular con Workflow Agentico
Vediamo come questi principi si applicano a un caso reale: il refactoring del modulo blog di un portfolio Angular da un'architettura legacy (componenti grandi, logica nel template, nessun test) a un'architettura moderna (componenti small, servizi separati, 80%+ coverage).
Contesto
- Codebase: Angular 21, SSR, ~3.000 righe nel modulo blog
- Problema: 0% test coverage, componenti da 500+ righe, nessun separation of concerns
- Goal: refactoring completo senza regressioni funzionali
- Vincolo: produzione attiva, zero downtime tollerato
Workflow Progettato
WORKFLOW: Blog Module Refactoring
FASE 0 - Setup (5 min, umano):
$ git checkout -b refactor/blog-module
Crea claude-progress.txt con stato iniziale
Crea docs/plans/blog-refactoring.md (vuoto, agente lo popolera)
FASE 1 - Analysis (agente, ~30 min):
Task: "Analizza il modulo blog completo.
Leggi tutti i file in src/app/articles/ e src/app/services/blog.service.ts.
Crea docs/analysis/blog-module.md con:
- Lista completa componenti e loro dimensioni (righe)
- Dipendenze tra componenti (chi importa chi)
- Logica duplicata identificata
- Violazioni separation of concerns
- Priorità di refactoring (impatto x sforzo)"
Review: Umano legge docs/analysis/blog-module.md e approva il piano
FASE 2 - Test Foundation (agente, ~60 min):
Task: "Scrivi test E2E per le funzionalità critiche del blog
PRIMA di qualsiasi refactoring. Usa Playwright.
Funzionalità da coprire:
- Navigazione alla lista articoli
- Apertura articolo specifico
- Navigazione serie (prev/next)
- Switch lingua IT/EN
I test devono passare sulla versione CORRENTE del codice."
Review: `npm run test:e2e` deve avere 100% dei test E2E verdi
FASE 3 - Service Extraction (agente, ~90 min, iterativo):
Task: "Estrai logica da BlogComponent in servizi separati.
UN servizio alla volta, in questo ordine:
1. BlogFilterService (filtraggio e ricerca articoli)
2. BlogSeriesService (navigazione serie)
3. BlogSEOService (meta tags per articoli)
Per ogni servizio:
a) Crea il file .service.ts con logica estratta
b) Crea il file .service.spec.ts con test unitari
c) Aggiorna BlogComponent per usare il servizio
d) Verifica: npm test passa, npm run build passa
e) Commit: git commit -am 'refactor: extract [ServiceName]'"
Review dopo ogni servizio: E2E test devono restare verdi
FASE 4 - Component Split (agente, ~120 min, iterativo):
Task: "Dividi BlogComponent (attuale 480 righe) in:
- BlogListComponent (lista articoli)
- BlogCardComponent (singola card articolo)
- BlogFilterComponent (filtri e ricerca)
- BlogPaginationComponent (paginazione)
Un componente alla volta. Stesso pattern di FASE 3:
implementa, test, verifica build, commit atomico."
Review: Umano verifica UI visivamente + E2E test
FASE 5 - Coverage Check (agente, ~30 min):
Task: "Verifica che coverage sia >80% per tutti i nuovi file.
Per ogni file sotto soglia, aggiungi test mancanti.
Produci report in docs/analysis/coverage-report.md"
Review: Coverage report + npm test
FASE 6 - Final Review (umano):
- Legge PR diff completo
- Verifica docs/analysis/coverage-report.md
- Merge su master se tutto ok
RISULTATI TIPICI DI QUESTO WORKFLOW:
Coverage: 0% -> 82%
Dimensione componenti: 480 righe -> media 95 righe
Build time: -15% (componenti più piccoli, lazy loading più efficace)
Tempo umano: ~45 min (fase 0 + review + fase 6)
Tempo agente: ~5-6 ore
Costo API stimato: $3-8 (dipende da modello)Lezioni Apprese dal Case Study
Tre insight emersi da questo tipo di workflow su codebase reali:
- I test E2E prima del refactoring sono non negoziabili. Senza una rete di sicurezza funzionale, ogni step del refactoring e un salto nel buio. Il tempo investito nella FASE 2 (test E2E) si ripaga 10x nell'evitare regressioni non rilevate.
-
I commit atomici sono memoria del workflow. Un commit per ogni servizio/componente
refactorizzato rende il rollback chirurgico: se un refactoring introduce un problema, si fa
git revertdi quel singolo commit senza perdere il lavoro precedente. - Il tempo umano cala al 10-15% del totale. Con un workflow ben progettato, il developer passa la maggior parte del tempo a revisionare output e approvare checkpoint, non a scrivere codice. Questo e il vibe coding maturo: non delegare tutto, ma delegare strategicamente mantenendo la supervisione sulle decisioni chiave.
Dato da Tenere a Mente
Il 21% delle startup YC Winter 2025 ha una codebase con oltre il 91% di codice generato da AI. Ma le startup più mature di queste non usano vibe coding "raw": usano workflow agentici strutturati con checkpoint umani, test automatizzati e strategie di rollback. La differenza tra "codice generato" e "software di qualità generato da AI" e esattamente la struttura del workflow.
Il Futuro dei Workflow Agentici
La ricerca nel 2025-2026 indica tre direzioni di evoluzione per i workflow agentici nel contesto dello sviluppo software:
- Dynamic Task Decomposition: Framework come TDAG (2025) spostano la decomposizione da statica (definita dal developer) a dinamica (l'agente decide la struttura del workflow in base al problema). I primi risultati sono promettenti ma richiedono ancora supervisione umana per codebase di produzione.
- Persistent Agent Memory: L'integrazione di vector database con agent frameworks (LangGraph + pgvector, CrewAI + Chroma) permette agli agenti di ricordare pattern tra progetti diversi, accumulando "esperienza" su codebase specifiche.
- Agent Skills come Standard: Anthropic ha introdotto Agent Skills nel 2025: bundle di istruzioni, script e risorse che gli agenti possono caricare dinamicamente. L'idea e che skill come "Angular Expert", "Security Auditor" o "Performance Optimizer" diventino moduli riutilizzabili tra team e organizzazioni.
Conclusioni
I workflow agentici non sono magia: sono architettura. La differenza tra un sistema agentico che funziona e uno che fallisce sta quasi sempre nella qualità della decomposizione, nella chiarezza dei criteri di successo e nella solidita della strategia di recovery dagli errori.
I quattro pattern (Sequential, Parallel, Hierarchical, Iterative) non sono mutuamente esclusivi: i workflow più efficaci li combinano. Un Planner gerarchico può delegare task paralleli, ciascuno dei quali usa un loop iterativo per raggiungere la qualità richiesta. La struttura e sempre al servizio del problema specifico.
Il passo pratico più importante che puoi fare oggi: prendi un task complesso che di solito risolvi in una singola sessione AI e prova a decomporlo in 3-5 subtask verificabili. Definisci i criteri di successo per ciascuno prima di iniziare. Aggiungi un checkpoint umano dopo ogni fase critica. Poi misura: il workflow strutturato produce output migliore? Quasi certamente si. E questo e il punto di partenza per diventare un architect di sistemi agentici.
Serie: Vibe Coding e Sviluppo Agentico
- 01 - Vibe Coding: Il Paradigma che ha Cambiato il 2025
- 02 - Claude Code: Sviluppo Agentico da Terminale
- 03 - Workflow Agentici: Decomporre Problemi per AI (questo articolo)
- 04 - Multi-Agent Coding: LangGraph, CrewAI e AutoGen
- 05 - Testare il Codice Generato da AI
- 06 - Prompt Engineering per IDE e Code Generation
- 07 - Sicurezza nel Vibe Coding: Rischi e Mitigazioni
- 08 - Il Futuro dello Sviluppo Agentico nel 2026
Approfondimenti Correlati
- Claude e il Model Context Protocol (MCP) - Come MCP estende le capacità degli agenti con strumenti esterni
- Sicurezza Web: API e Vulnerabilità - Rischi di sicurezza specifici nei workflow agentici