Cursor Agent Pipeline: Come Configurare i Worktree, Scrivere Istruzioni Efficaci e Misurare il ROI Reale

I due articoli precedenti su Cursor hanno stabilito l'architettura e l'economia. L'articolo su Cursor 3.0 ha spiegato perché gli agenti paralleli nei worktree sono l'unità produttiva di lavoro. L'articolo su Composer 2.5 ha spiegato che la generazione nel tier Standard è ora abbastanza economica da eseguire dieci candidati per meno di un dollaro. Questo articolo è la parte mancante: come configurare concretamente una pipeline che cattura quel valore senza collassare sotto il proprio peso di revisione.

Il failure mode principale nei workflow agentici non è la qualità della generazione — è la capacità di revisione. Ricerche indipendenti mostrano che le pull request scritte da agenti AI attendono 4,6 volte più a lungo per essere revisionate rispetto a quelle scritte da esseri umani (DX Research, 2026). Quel divario esiste perché l'output degli agenti arriva più velocemente di quanto i revisori riescano a elaborarlo, perché le superfici dei diff sono spesso più grandi di quanto dovrebbero essere, e perché i revisori non si fidano dell'output che non hanno supervisionato. Una pipeline ben progettata affronta tutti e tre. Una mal progettata li peggiora tutti.

Ciò che segue è una guida pratica alla configurazione: il sistema di istruzioni a due livelli che plasma il comportamento degli agenti, la configurazione dei worktree che isola il lavoro parallelo, l'economia della scelta di quanti candidati eseguire, il ciclo che seleziona il vincitore, e il framework di misurazione che ti dice se tutto ciò sta funzionando.

Prima di scrivere una sola regola

Ogni sistema di istruzioni per agenti amplifica ciò che la codebase già ha. Se la tua suite di test è scarsa, gli agenti produrranno codice non testato e non avranno modo di verificarlo. Se la tua pipeline CI è lenta, il gate tra generazione e revisione crea un collo di bottiglia che si moltiplica con N candidati. Se le definizioni dei task sono vaghe, anche gli agenti ben istruiti produrranno diff difficili da circoscrivere e ancor più difficili da revisionare.

Tre prerequisiti prima di configurare qualsiasi istruzione per agenti:

Il sistema di istruzioni a due livelli

Cursor supporta due meccanismi di istruzioni complementari. Usarli entrambi correttamente è la singola modifica di configurazione con il maggiore impatto.

AGENTS.md è uno standard aperto (Linux Foundation, adottato da oltre 60.000 repository) letto nativamente da Cursor, Codex, GitHub Copilot, Gemini CLI, Aider, Windsurf e Zed (AGENTS.md, 2026). Va posizionato nella root del progetto e nelle sottodirectory dove si applicano regole diverse. È puro Markdown — nessuna sintassi speciale. L'agente legge il file più vicino nell'albero delle directory; i file più specifici sovrascrivono quelli meno specifici.

I file .cursor/rules/*.mdc forniscono override scoped specifici di Cursor. Ogni file .mdc ha un blocco di frontmatter YAML che controlla quando la regola si attiva: sempre, quando vengono trovati glob di file specifici, quando l'agente decide che è rilevante in base a una descrizione, o solo quando viene invocata manualmente con @nome-regola (Cursor, 2026c).

Scrivere istruzioni che cambiano il comportamento

L'errore più comune nelle istruzioni per agenti è scrivere principi invece di comportamenti. "Scrivi codice pulito e ben testato" non cambia nulla. "Crea un file __tests__/[NomeClasse].test.ts corrispondente per ogni nuova classe che crei, con almeno un test happy-path e uno error-case" cambia ciò che viene committato.

Tre tecniche che rendono efficaci le istruzioni:

Sii specifico sulle zone vietate. Nomina le directory esatte e i pattern di file che gli agenti non devono toccare senza approvazione umana. Le proibizioni vaghe ("non toccare i file sensibili") vengono ignorate. I percorsi espliciti ("non modificare mai i file in /src/auth/, /infra/, o qualsiasi file che corrisponda a *.env*") vengono rispettati.

Codifica la tua architettura nelle istruzioni. Di' all'agente quale package gestisce quale concern, qual è il comando del tuo test runner, dove risiedono i tipi, quale pattern di state management usi. Questo è contesto che l'agente non può inferire dal codice da solo, e impedisce la categoria più comune di allucinazione: codice dall'aspetto plausibile che viola le tue convenzioni effettive.

Usa il Plan Mode prima di ogni task non banale. Premi Shift+Tab nell'input dell'agente per passare al Plan Mode. L'agente produce un piano scritto — file da toccare, approccio, rischi potenziali — prima di scrivere una sola riga di codice. Revisiona il piano, correggilo se necessario, poi approvalo. Una revisione del piano di due minuti elimina la classe di failure degli agenti più costosa: l'esecuzione corretta dell'approccio sbagliato (Cursor, 2026a).

# AGENTS.md — Project Instructions

## Architecture overview
This is a TypeScript monorepo with three packages:
- `packages/api`    — Express REST API, PostgreSQL via Prisma ORM
- `packages/worker` — Background job processor (BullMQ + Redis)
- `packages/web`    — Next.js 15 frontend

## Running tests
- Unit tests:        npm run test           (Vitest, runs in ~90s)
- Integration tests: npm run test:integration (requires Docker, ~8 min)
- Do NOT write integration tests unless explicitly asked

## Forbidden zones — STOP and ask a human before touching any of these
- /packages/api/src/auth/          — authentication and session management
- /.github/workflows/              — CI/CD pipeline configuration
- /packages/api/prisma/schema.prisma — database schema (requires migration)
- Any file whose name contains SECRET, KEY, TOKEN, or CERT

## Routing rules for model selection
- Standard tier: test generation, scaffolding, doc updates, mechanical refactors
- Fast tier:     multi-file features with a clear spec
- Human only:    anything touching /packages/api/src/auth/ or /infra/

## Code conventions
- TypeScript strict mode — no `any`, use `unknown` and narrow
- Co-locate types with their implementation (not in a /types folder)
- Every async function needs explicit error handling
- Mock all external dependencies in unit tests — never hit real infrastructure

---
description: Testing and interface requirements for API service classes
globs: ["packages/api/src/services/**/*.ts"]
alwaysApply: false
---

When creating or modifying a service class:
1. Create `__tests__/[ServiceName].test.ts` if it does not exist
2. Test every public method: at least one happy-path and one error case
3. Export `interface I[ServiceName]` alongside the class
4. Mock Prisma with `vi.mock('@/lib/prisma')` — never import the real client in tests

Setup dei worktree per la generazione parallela

Cursor 3 crea e gestisce i git worktree automaticamente quando esegui agenti in Worktree Mode. Ogni agente ottiene la propria directory e il proprio branch, condividendo la stessa history git e l'object store del tuo checkout principale. L'isolamento è completo: un agente nel worktree 3 non può vedere le modifiche non committate nel worktree 1 (Cursor, 2026b).

Il limite superiore è 8 agenti paralleli per repository. In pratica, il limite produttivo è più basso — è la tua capacità di revisione, non il cap della piattaforma, a vincolare quanti candidati dovresti generare.

Per passare un progetto esistente al Worktree Mode, apri le Impostazioni di Cursor e abilitalo nella sezione Agents. Cursor creerà una directory .cursor/worktrees/ e gestirà i branch automaticamente. Per i team che preferiscono il controllo esplicito, puoi configurare i worktree manualmente e aprire ciascuno in una finestra Cursor separata:

#!/bin/bash
# setup-agent-worktrees.sh
# Usage: ./setup-agent-worktrees.sh feat/checkout-validation 3

TASK_BRANCH="${1:-feat/agent-task}"
N="${2:-3}"
REPO_NAME=$(basename "$(pwd)")

echo "Creating $N worktrees for task: $TASK_BRANCH"

for i in $(seq 1 "$N"); do
  BRANCH="${TASK_BRANCH}-candidate-${i}"
  DIR="../${REPO_NAME}-agent-${i}"

  git worktree add "$DIR" -b "$BRANCH"
  echo "  ✓ Worktree $i: $DIR (branch: $BRANCH)"
done

echo ""
echo "Open each in a separate Cursor window:"
for i in $(seq 1 "$N"); do
  echo "  cursor \"../${REPO_NAME}-agent-${i}\""
done

echo ""
echo "Cleanup when done:"
echo "  git worktree prune"

Ogni finestra di Cursor esegue il proprio agente in modo indipendente. Quando un agente termina, revisioni il diff nel branch di quella finestra direttamente. La vista diff integrata di Cursor mostra esattamente cosa è cambiato; l'isolamento del worktree garantisce che tu stia guardando solo il lavoro di quell'agente, non una fusione di diversi.

Scegliere N — quanti agenti eseguire in parallelo

L'economia è semplice. Ai prezzi del tier Standard, dieci candidati Composer 2.5 costano meno di $1,00. Il vincolo dei costi è irrilevante per la maggior parte dei task. Il vincolo rilevante è ciò che accade dopo la generazione.

Se il tuo gate CI elimina il 60% dei candidati — una cifra realistica per task con una buona copertura dei test — cinque agenti generano all'incirca due candidati che raggiungono la fase di revisione. Due candidati che superano i test e rientrano nel limite del diff sono genuinamente comparabili; scegliere tra loro richiede minuti, non ore. Questo è il punto operativo produttivo.

Tre segnali che indicano di ridurre N:

• La coda di revisione cresce più velocemente di quanto venga smaltita
• Gli agenti producono diff simili con variazioni minori (bassa diversità = basso valore di N)
• Il tempo di esecuzione della CI è abbastanza lento da creare ritardi di accodamento anziché risparmiare tempo

Tre segnali che indicano che N è troppo basso:

• La CI elimina costantemente tutti i candidati (il task necessita di una migliore decomposizione, oppure N=1 era destinato a fallire)
• La revisione rileva che tutti i candidati passati hanno lo stesso difetto (hai bisogno di maggiore diversità nell'inizializzazione degli agenti — usa prompt iniziali diversi o file di contesto diversi)
• La generazione finisce più velocemente di quanto la CI riesca a elaborarla (esegui più candidati, il collo di bottiglia non è ancora la revisione)

Il ciclo di selezione

Una volta ottenuti N candidati che superano la CI, è necessario un passo di selezione. La tentazione è di scegliere manualmente — leggere ogni diff, scegliere il preferito. Per N piccoli (2–3), va bene. Per N più grandi, o come processo ripetibile, un agente conductor è più affidabile.

Il pattern conductor: dai a un agente Composer Fast (o Claude Opus 4.7 per task ad alto rischio) tutti i diff passati e chiedigli di classificarli secondo criteri espliciti. L'agente non genera nuovo codice — valuta i diff esistenti.

You are a code review conductor. Below are N diffs that all pass the CI gate
for task: [TASK DESCRIPTION].

Rank them against these criteria, in order of priority:
1. Smallest diff surface that fully satisfies the acceptance criteria
2. No new external dependencies introduced
3. Highest test coverage delta (new tests cover the new code)
4. No changes to files outside the stated scope

For each diff, provide:
- A score 1–10 against each criterion
- One sentence identifying the main risk
- A PASS or REJECT recommendation

Return a ranked list with the top candidate clearly identified.
Do not generate new code or suggest modifications — evaluate only what exists.

Misurare il ROI reale

La cosa più onesta che i dati dicono sul ROI degli agenti di coding AI: il marketing dei vendor fissa le aspettative a un miglioramento della produttività di 3–10×; la maggior parte delle organizzazioni atterra nell'intervallo del 5–15% di guadagno di throughput (DX Research, 2026). Si tratta di un ritorno reale, ma non è il numero che compare nei case study. Pianifica per l'intervallo realistico.

Cosa misurare, e come:

Monitora questi dati settimanalmente, non giornalmente. Le medie settimanali attenuano il rumore della variazione dei singoli task. La metrica che indica più direttamente se la pipeline è sana è il review time per agent PR: se cresce mese dopo mese, stai generando più velocemente di quanto riesci a revisionare, e la risposta è ridurre N o investire nel gate CI, non generare di più.

Sei failure mode da evitare

Conclusione

La pipeline descritta qui non è una scorciatoia verso una produttività 10× — i dati sono chiari sul fatto che tali guadagni siano eccezionali piuttosto che tipici. È una metodologia per catturare il reale miglioramento del throughput del 5–15% che i workflow agentici ben configurati consegnano, senza accumulare il debito di revisione e i fallimenti di fiducia che quelli mal configurati creano.

L'ordine conta: prima i prerequisiti, poi le istruzioni, poi i worktree, poi N, poi la selezione, poi la misurazione. Ogni team che salta alla configurazione dei worktree senza i prerequisiti finisce con una generazione veloce e una pipeline di revisione rotta. Ogni team che salta la misurazione finisce per non riuscire a stabilire se l'investimento vale la pena di continuare.

Gli agenti sono ora infrastruttura, non una funzionalità. Trattali come tratti la CI: configurali con cura, misurarli continuamente, e ottimizza la pipeline quando le metriche ti dicono che qualcosa non va.