Come organizzare il contesto per agenti AI di coding
Spec, AGENTS.md, skill, script e subagent senza riempire la chat
Un agente di coding lavora meglio quando non deve ricostruire ogni volta cosa vuoi. Il contesto va distribuito: le decisioni di prodotto in una spec, le regole ricorrenti in AGENTS.md, i workflow ripetibili in skill, le procedure consolidate in script e le esplorazioni rumorose in subagent o chat separate. Così puoi ripartire da sessioni pulite senza perdere memoria utile e senza usare sempre il modello più potente.
Risposta breve
Per organizzare il contesto di un agente AI di coding, non mettere tutto nella chat. Usa una spec per requisiti e criteri di successo, AGENTS.md per regole stabili del repository, skill per workflow ripetibili, script per passaggi meccanici e subagent o chat separate per esplorazioni isolate. La chat principale deve contenere decisioni, non rumore.
- Spec driven development: salva obiettivo, vincoli e verifiche in file, così puoi ripartire da una chat pulita.
- AGENTS.md: utile per norme sempre vere, ma da tenere sintetico perché viene letto all'inizio del lavoro.
- Skill: utile quando ripeti lo stesso flusso e vuoi istruzioni caricate solo quando servono.
- Script: utile quando il comportamento è stabile e non serve più ragionarlo in linguaggio naturale.
- Subagent: utile per audit, ricerca, test e log analysis che sporcherebbero la conversazione principale.
Confronto rapido
| Criterio | Dove mettere il contesto | Quando conviene |
|---|---|---|
| Spec | Requisiti, non-obiettivi, criteri di successo, file interessati e comandi di verifica | Quando il task dura più di una sessione o coinvolge decisioni di prodotto che non vuoi perdere |
| AGENTS.md | Regole operative stabili: test da lanciare, stile del repo, limiti, fonti di verità | Quando ripeti le stesse istruzioni in quasi ogni task dello stesso repository |
| Skill | Workflow riusabile con istruzioni, riferimenti e script opzionali caricati al bisogno | Quando il flusso si ripete, ma non deve entrare sempre nel contesto iniziale |
| Script | Passaggi meccanici, controlli, generatori e verifiche che non richiedono giudizio ogni volta | Quando una skill o una procedura è ormai consolidata e vuoi ridurre token e variabilità |
| Subagent o chat separata | Esplorazione, audit, test, log, confronto alternative e lavoro read-only parallelo | Quando l'output intermedio sarebbe utile, ma non vuoi sporcare la conversazione principale |
Workflow consigliati
Questi esempi mostrano come spostare contesto dalla chat a supporti più adatti. Il risparmio nasce da meno ripetizione, meno esplorazione e meno retry.
Feature nuova
Spec sintetica più file rilevanti · Piano, patch e test
Beneficio
Meno esplorazione
Errore da evitare
Prompt vago che fa leggere mezzo repo
Prima scrivi una spec. Poi apri una sessione pulita e chiedi all'agente di implementare solo quella.
Routine ripetuta
Nome skill e file necessari · Output nel formato atteso
Beneficio
Istruzioni caricate solo quando servono
Errore da evitare
Ripetere ogni volta la checklist nella chat
Se scrivi lo stesso prompt tre volte, probabilmente è candidato a skill. Se è stabile, valuta uno script.
Audit su PR
Diff, test e criteri · Sintesi dei rischi
Beneficio
Main thread pulito
Errore da evitare
Raw log e note di esplorazione nella chat principale
Manda subagent separati su sicurezza, test e regressioni, poi riporta solo sintesi e file da cambiare.
Perché il prompt vago costa caro
Un prompt vago obbliga l'agente a scoprire cosa intendi. In un repository reale questo significa leggere file, cercare pattern, interpretare test, formulare ipotesi e spesso correggersi. Prima ancora di scrivere codice, hai già consumato contesto e token.
- Sostituisci 'sistema questa parte' con obiettivo, file, vincoli e output atteso.
- Dai il comando di verifica: test, typecheck, build o scenario manuale.
- Se non sai ancora cosa vuoi, chiedi una fase di analisi limitata e non una patch completa.
Usa spec driven development per ripartire pulito
La spec è il ponte tra memoria umana e memoria dell'agente. Se requisiti, decisioni e criteri di successo vivono in un file, puoi chiudere una chat rumorosa e ripartire da quel file. Questo riduce dipendenza dalla cronologia e rende il lavoro più verificabile.
- Scrivi problema, obiettivo, non-obiettivi, vincoli e definizione di done.
- Aggiorna la spec quando cambia una decisione, invece di lasciarla sepolta in chat.
- Usa la spec come input iniziale di una sessione pulita prima dell'implementazione.
Metti in AGENTS.md solo ciò che vale sempre
AGENTS.md è potente perché Codex lo legge prima di lavorare e costruisce una catena di istruzioni dal livello globale al repository. Proprio per questo va usato con parsimonia: ogni regola inutile entra nel contesto iniziale e compete con il task corrente.
- Metti comandi standard, source of truth, regole editoriali e vincoli che valgono quasi sempre.
- Non metterci la storia completa del prodotto, decisioni temporanee o checklist rare.
- Se una regola vale solo per una cartella, usa un file più vicino a quella cartella invece di gonfiare il root.
Trasforma flussi ripetitivi in skill
Una skill è adatta quando ripeti un flusso, ma non vuoi caricare tutte le istruzioni in ogni sessione. La documentazione Codex descrive le skill come pacchetti con istruzioni, risorse e script opzionali, caricati per progressive disclosure: prima nome e descrizione, poi il file completo solo quando serve.
- Crea una skill quando hai trigger chiaro, passaggi ricorrenti e output verificabile.
- Tieni la descrizione precisa: deve dire quando usare e quando non usare la skill.
- Sposta esempi lunghi e riferimenti in file collegati, così il contesto si apre solo al bisogno.
Quando una skill diventa script
Se un passaggio non richiede più interpretazione, spesso non dovrebbe restare prompt. Uno script costa meno in token, è più ripetibile e produce output più facile da verificare. La skill può spiegare quando lanciare lo script e come interpretarne il risultato.
- Script per validazioni, generazione dati, controlli SEO, trasformazioni meccaniche e report ripetibili.
- Prompt per decisioni, trade-off, sintesi e casi in cui serve giudizio.
- Skill come orchestrazione leggera: istruzioni più comandi già pronti.
Isola rumore con subagent o chat separate
Subagent e chat separate servono quando un lavoro produce molto output intermedio. Codex spiega che spostare esplorazioni, test, log e analisi in agenti specializzati aiuta a tenere la conversazione principale focalizzata su requisiti, decisioni e risultati finali.
- Usa subagent per task read-heavy: audit, ricerca, confronto alternative, test e log analysis.
- Chiedi sintesi, non raw output: file coinvolti, rischi, evidenze e raccomandazione.
- Evita subagent write-heavy in parallelo sullo stesso codice se può creare conflitti.
Non usare sempre il modello più potente
Il contesto non va solo organizzato: va anche assegnato al modello giusto. Molti task possono essere delegati a modelli inferiori o agenti specializzati: estrarre file rilevanti, riassumere log, controllare copy, cercare duplicati, verificare link. Il modello migliore va riservato a decisioni e patch ad alto rischio.
- Modello economico per triage, estrazione, controllo formato e riassunti intermedi.
- Modello forte per progettazione, refactor, bug ambigui e review finale.
- Main agent come integratore: decide cosa tenere, cosa scartare e cosa implementare.
Checklist prima di avviare l'agente
Prima di chiedere a un agente di lavorare, controlla dove vive ogni pezzo di contesto. Se tutto è nella chat, stai costruendo debito di contesto. Se tutto è in AGENTS.md, stai pagando un costo fisso. La soluzione sana è distribuire il contesto per stabilità e frequenza d'uso.
- Obiettivo e criteri di successo sono in una spec o nel prompt iniziale?
- Le regole ricorrenti sono in AGENTS.md e sono davvero ricorrenti?
- Il flusso è abbastanza ripetitivo da meritare una skill?
- Il passaggio è abbastanza meccanico da meritare uno script?
- L'esplorazione può stare in un subagent o chat separata?
- Il modello scelto è proporzionato al rischio del task?
Domande frequenti
AGENTS.md sostituisce una spec?
No. AGENTS.md contiene regole ricorrenti del progetto. La spec contiene requisiti e decisioni di un task specifico. Mischiarli rende le istruzioni persistenti troppo lunghe.
Quando devo creare una skill?
Quando ripeti lo stesso workflow con trigger chiaro, passaggi simili e output verificabile. Se lo usi una sola volta, basta un prompt o una spec.
Quando devo usare uno script invece di una skill?
Usa uno script quando il passaggio è meccanico e stabile: validare, trasformare, generare o controllare. Usa una skill quando serve guidare un comportamento con giudizio.
I subagent fanno risparmiare token?
Non sempre. Possono consumare più token in totale, ma tengono pulito il contesto principale e permettono di usare modelli o istruzioni diverse per lavori separati.
Meglio chat lunga o chat pulita?
Chat lunga se il contesto è ancora utile e ordinato. Chat pulita se hai molte ipotesi superate, log, output intermedi o cambi di direzione. La chat pulita funziona solo se porti con te una spec aggiornata.