Prompt pattern per coding agent

Perche promptare un coding agent e diverso

Un chatbot risponde una volta; un coding agent lavora in un ciclo, legge il tuo repository, modifica file, esegue i tuoi test e reagisce ai risultati. Questo cambia cosa deve realizzare un buon prompt. Non chiedi uno snippet, briefi un compagno di squadra che esegue vere azioni nella tua codebase, quindi il prompt deve portare l'intenzione (cosa vuoi e perche), i vincoli (il tuo stack, le tue convenzioni e cosa non deve toccare) e una definizione di "finito" contro cui l'agente puo verificarsi. La leva piu grande e togliere del tutto le regole permanenti dal prompt: scrivi il tuo stack, le tue convenzioni e il tuo quality gate in un CLAUDE.md o AGENTS.md, cosi ogni prompt parte dalle tue regole e il prompt stesso porta solo il compito. I pattern qui sotto presuppongono questa fondazione e si concentrano sulla missione per compito.

• L'agente agisce: modifica file ed esegue comandi, quindi un'intenzione vaga diventa cattivi cambiamenti, non solo una brutta frase.
• Le regole permanenti vanno in CLAUDE.md o AGENTS.md, non in ogni prompt; vedi Come usare Claude Code.
• Un buon prompt per compito porta intenzione, vincoli e una definizione verificabile di "finito".
• Il contesto e finito: un prompt mirato lascia all'agente spazio per leggere codice e riflettere. Vedi il glossario sul context window.

Pattern 1: ruolo e spec

Il punto di partenza piu affidabile e nominare il ruolo che l'agente deve adottare, poi specificare il compito come una spec ristretta e testabile piuttosto che un desiderio. Una spec nomina l'obiettivo, i vincoli, i file o la zona nello scope e i criteri di accettazione che decidono quando e finito. "Migliora il login" e un desiderio; la versione qui sotto e una spec. La riga di ruolo focalizza il modello (un senior engineer rivede diversamente da un tutor), e i criteri di accettazione danno all'agente qualcosa di concreto da verificare, il che gli impedisce di gridare vittoria troppo presto. Tieni la spec sull'essenziale: sovraspecificare ogni riga toglie all'agente la capacita di prendere buone decisioni locali.

Role: act as a senior backend engineer on this codebase.

Goal: add rate limiting to the public /api/contact endpoint.

Constraints:
- Use the existing Convex rate-limit helper; do not add a new dependency.
- Limit to 5 requests per minute per IP. Return 429 with a clear JSON body.
- Touch only the contact route and its test; leave other endpoints alone.

Done when:
- A new test proves the 6th request in a minute gets a 429.
- `bun run lint && bun run typecheck && bun run test` all pass.

Plan first (do not edit yet), show me the plan, and wait for my go-ahead.

Pattern 2: mostra un esempio (few-shot)

I modelli fanno corrispondere pattern, quindi il modo piu rapido di ottenere un output nella forma voluta e mostrarne uno. Se hai bisogno di un nuovo file, componente, test o migrazione che deve assomigliare a cio che esiste gia, mostra all'agente un esempio esistente e chiedigli di seguire la stessa struttura: "Scrivi il nuovo endpoint esattamente come src/api/users.ts, con il suo file di test." Questo pattern few-shot funziona perche la tua codebase e la migliore guida di stile che hai, e batte descrivere le tue convenzioni in prosa. Per un output su cui non puoi puntare, dai un piccolissimo esempio inline del formato atteso (una riga di log di esempio, una forma JSON, uno stile di messaggio di commit), cosi l'agente ha un target da far corrispondere.

• Punta su un file esistente: "Segui la struttura di src/api/users.ts e il suo test."
• La tua codebase e la tua guida di stile; un esempio batte un paragrafo di convenzioni.
• Per i nuovi formati, inserisci inline un piccolissimo campione dell'output esatto (una riga di log, una forma JSON).
• Un esempio affilato in genere supera diverse istruzioni vaghe.

Pattern 3: scomponi il grande lavoro in passi

Le grandi richieste vaghe sono dove gli agenti derivano: di fronte a "costruisci il dashboard", prendono cento decisioni che avresti preso tu altrimenti e seppelliscono gli errori in un enorme diff. La soluzione e la decomposizione. O scomponi tu stesso il lavoro in una sequenza di piccoli compiti rivedibili separatamente, oppure chiedi all'agente di proporre prima un piano e lo approvi prima che venga scritto codice. Il piano-prima e l'abitudine piu potente con i coding agent: una direzione sbagliata catturata nel piano non costa nulla, mentre lo stesso errore dopo un diff di mille righe costa vero tempo. In Claude Code, e la modalita plan (Shift+Tab); in ogni agente, puoi semplicemente istruire "plan first, do not edit, show me the steps". Poi implementi un passo, rivedi, e passi al successivo.

• Dividi un grande compito in piccoli passi rivedibili separatamente piuttosto che un mega-prompt.
• Chiedi un piano prima delle modifiche; correggere un piano e gratuito, un enorme diff no.
• Implementa un passo, rivedi il diff, poi continua; mantieni ogni cambiamento leggibilmente piccolo.
• Passi piu piccoli mantengono anche pulita la context window, cosi l'agente resta affilato sul compito.

Pattern 4: costruisci una verification loop

Il tratto distintivo di un coding agent e che puo eseguire cose, quindi i migliori prompt gli dicono come verificare il proprio lavoro e continuare finche la verifica non passa. Invece di "correggi il test che fallisce", di' "esegui la suite di test, correggi cio che e rosso, e rilanciala; non fermarti finche non e verde". Invece di fidarti che un cambiamento funzioni, di' all'agente di eseguire il type-checker, il linter e i test e leggere l'output reale piuttosto che supporre. Questo trasforma l'agente da un generatore one-shot in un ciclo chiuso che si ancora a veri risultati. La versione piu forte cuoce il ciclo nel tuo progetto, cosi non e nemmeno un prompt: hook che fanno girare il tuo gate automaticamente (vedi la guida Claude Code Hooks) significano che l'agente e tenuto allo standard, che tu pensi a chiederlo o no.

• Chiedi all'agente di eseguire il gate (tipi, lint, test) e leggere l'output reale, non supporre.
• Fallo iterare: "correggi e rilancia finche la suite non e verde", non una sola esecuzione.
• Per l'UI o il comportamento, fallo lanciare il dev server o un check Playwright, cosi vede il vero risultato.
• Automatizza il ciclo con hook, cosi la verifica arriva ogni volta, non solo quando ci pensi.

Pattern 5: dai all'agente il contesto giusto, non tutto il contesto

Gli agenti falliscono piu spesso per mancanza di contesto che per un modello debole: di fronte a usare una API senza la sua documentazione, indovinano. Quindi porta all'agente cio di cui ha bisogno, consapevolmente. Punta sui file pertinenti, incolla l'errore per intero, collega la documentazione, nomina la funzione esatta. Ma resisti alla trappola opposta di riversare tutto: una context window stipata di venti file e una lunga cronologia degrada la qualita, perche il modello perde il dettaglio importante nel rumore (l'effetto "lost in the middle"). L'arte e la curation: abbastanza contesto per riuscire, abbastanza poco per restare affilato. Questo e il cuore del context engineering, e la nostra guida Context Engineering approfondisce la gestione della window su un compito lungo.

• Nomina i file esatti, incolla l'errore completo e collega la documentazione di cui l'agente ha bisogno.
• Non riversare tutto il repo; il contesto pertinente batte il contesto massimo ogni volta.
• Attento al "lost in the middle": un dettaglio chiave sepolto in un enorme prompt viene ignorato.
• Vedi la guida Context Engineering e il glossario sul context window e sul system prompt.

Gli anti-pattern da evitare

La maggior parte del dolore di prompting viene da una breve lista di errori ricorrenti. Nominarli li rende facili da individuare nelle proprie abitudini. Il rimedio per ognuno e un pattern qui sopra: sii specifico, mostra un esempio, scomponi, verifica e cura il contesto.

• Desideri vaghi: "fai meglio" non da niente da verificare all'agente. Nomina una spec e criteri di accettazione.
• Il mega-prompt: una richiesta enorme che seppellisce cento decisioni in un diff non rivedibile. Scomponi e pianifica prima.
• Fiducia senza verifica: accettare un output che non hai fatto testare all'agente. Costruisci una verification loop.
• Riversamento di contesto: incollare tutto al punto di annegare il segnale. Cura a cio di cui il compito ha bisogno.
• Ridigitare le regole a ogni turno: stack e convenzioni vanno in CLAUDE.md o AGENTS.md, non in ogni prompt.
• La cortesia come istruzione: "per favore prova forse" si legge come opzionale. Sii diretto; i vincoli sono regole, non suggerimenti.

Domande frequenti

Continua a imparare