Multi-agente, CI/CD e spec-driven 🤖

Fin qui abbiamo parlato di un agente alla volta: un task, una sessione, un risultato. Ma i progetti reali non funzionano così. Hanno bisogno di più agenti che lavorano in parallelo, di pipeline che automatizzano la qualità, e di una specifica che sopravvive al codice. Questa guida è il livello successivo: come orchestrare più agenti, integrarli nelle CI/CD, e usare la specifica come contratto guida.

Il codice muore. La specifica no. Gli agenti che lavorano da una specifica producono codice che può essere rigenerato. Gli agenti che lavorano da un prompt vago producono codice che può essere solo riscritto.

Delegazione multi-agente 🤝

Pattern: Writer/Reviewer

Il pattern più semplice e più efficace. Un agente scrive il codice (sessione A), un altro lo revisiona in un contesto separato (sessione B).

Perché funziona:

• L’agente reviewer non ha il contesto dello scrittore → vede il codice come lo vedrebbe un revisore umano
• Nessun bias di conferma: l’agente che ha scritto il codice non può “vedere” i suoi stessi errori
• La finestra di contesto del reviewer è pulita

Come implementarlo:

    sequenceDiagram
    participant U as Sviluppatore
    participant A1 as Writer Agent
    participant A2 as Reviewer Agent

    U->>A1: Task: implementa [funzionalità]
    A1->>A1: Pianifica e scrive il codice
    A1->>U: Consegna il diff
    U->>A2: Task: revisa questo diff
    A2->>A2: Analizza sicurezza, pattern, coerenza
    A2->>U: Report con findings
    U->>U: Valida e merge
  

Sotto-agenti sequenziali specializzati

L’agente primario (Lead Agent) suddivide il problema e delega le sotto-attività a sotto-agenti isolati.

Esempio pratico:

1. Fase esplorativa: sotto-agente Explore in sola lettura → esplora il repository e produce una mappa
2. Fase di implementazione: Lead Agent riceve la mappa → scrive il codice
3. Fase di verifica: sotto-agente Scout esegue i test e produce un report

Regola chiave: ogni sotto-agente opera in un contesto circoscritto e isolato. Non deve mai caricare l’intero repository nella finestra di contesto.

Esecuzione parallela isolata

Il task viene diviso in moduli indipendenti gestiti da sotto-agenti eseguiti in parallelo su worktree Git distinti o container isolati.

Quando conviene:

• Moduli indipendenti senza dipendenze incrociate
• Generazione di suite di test per moduli isolati
• Refactoring simultaneo di componenti separate

Quando NON conviene:

• Moduli fortemente accoppiati → conflitti di merge
• Task che richiedono visione contestuale unificata
• Operazioni su file interdipendenti

La delega conviene per compiti ad ampia scala ma slegati tra loro. Per moduli accoppiati, la delega parallera è peggio del singolo agente.

Agenti asincroni e CI/CD 🔄

Flusso: issue → PR

Gli agenti cloud possono essere assegnati a issue e lavorare in background:

1. Assegnazione: sviluppatore assegna issue all’agente cloud
2. Esecuzione: l’agente clona il repo, analizza il contesto, implementa
3. Autovalutazione: l’agente esegue build, lint, test prima di notificare
4. Consegna: l’agente apre una PR con resoconto architetturale
5. Review umana: sviluppatore revisiona e fa merge

Integrazione in pipeline CI/CD

Gli agenti vengono invocati in modalità non interattiva all’interno dei workflow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

name: Agentic Quality Check
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  agent-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - name: Agent Security & Quality Check
        run: |
          opencode run "Analizza i test falliti o le violazioni del linter nella PR. Applica correzioni, esegui test, committa se verdi." --auto

Casi d’uso automatizzati:

• Fix automatico di vulnerabilità segnalate da linter
• Aggiornamento automatico dipendenze
• Aggiornamento documentazione tecnica ad ogni commit
• Rigenerazione di snapshot test

Spec-driven development 📋

Il ciclo Specify → Clarify → Plan → Implement

La specifica è il contratto che sopravvive al codice. Il workflow è:

    flowchart LR
    A[Specificare 📝] --> B[Chiarire 💬]
    B --> C[Pianificare 📐]
    C --> D[Implementare ⚙️]
    D --> E[Verificare ✅]
    E --> |Nuovo ciclo| A
  

Fase 1 — Specifica (Umano) L’ingegnere scrive SPEC.md con requisiti, interfacce, vincoli, criteri di accettazione.

Fase 2 — Chiarimento (Agente + Umano) L’agente analizza la specifica e formula domande su ambiguità, casi limite, incoerenze. → Punto di controllo umano 1: lo sviluppatore risponde e affina la specifica.

Fase 3 — Pianificazione (Agente) L’agente trasforma la specifica approvata in un documento esecutivo (PLANS.md): sequenza di file da creare, modificare, rimuovere. → Punto di controllo umano 2: l’utente revisiona e valida il piano. Nessun codice prima dell’approvazione.

Fase 4 — Scomposizione (Agente) L’agente suddivide il piano in sotto-attività atomiche, sequenziali, testabili.

Fase 5 — Implementazione (Agente + CI) L’agente esegue un task alla volta, lancia i test dopo ogni modifica, applica fix. → Punto di controllo umano 3: code review finale e merge.

Il valore della specifica

La specifica non è un documento preliminare. È il contratto vivente del progetto. Codice generato da una specifica chiara può essere rigenerato. Codice generato da un prompt vago può essere solo riscritto.

Cosa mettere in SPEC.md:

• Requisiti funzionali (cosa deve fare il sistema)
• Interfacce API (endpoint, firme, schemi)
• Vincoli di sicurezza
• Criteri di accettazione (test che devono passare)
• Scopo esplicito (cosa NON fa il sistema)

Anti-pattern 🚫

• Delega senza isolamento — più sotto-agenti sullo stesso file = conflitti. Ogni sotto-agente opera su moduli indipendenti.
• Spec-driven senza controllo umano — i punti di controllo non sono opzionali. Senza di essi, l’agente deriva dall’architettura.
• CI/CD agentic senza rollback — ogni fix automatico deve poter essere annullato. Mai delegare deploy o migrazioni di produzione.
• Sotto-agenti con troppo contesto — un sotto-agente che carica l’intero repository non è un sotto-agente: è un agente lento.
• “Risolvere tutto” con un prompt — la delega funziona per task atomici, non per “costruisci un sistema completo”.

Criteri di accettazione 📏

Riferimenti della serie 📚

• The repository is the contract — AGENTS.md come conoscenza condivisa
• Greenfield from specification — il workflow spec-driven in dettaglio
• Multi-agente: come gestire una squadra di AI — il post blog complementare