Guida OpenCode Agents: 7 controlli per Subagents e AGENTS.md

Risposta breve: usa AGENTS.md per le regole del repository e OpenCode agents quando serve uno specialista con prompt, modello, strumenti e limiti propri.

AGENTS.md conserva le regole durevoli del repository: test, stile, cartelle generate e avvisi. L'agent descrive il comportamento di un ruolo specifico.

Mescolare i livelli produce istruzioni duplicate e difficili da correggere.

Un subagent è utile quando separa un problema reale: leggere una grande cartella, rivedere un diff rischioso o studiare una API.

Definisci un contratto di output con file, piano di patch o rischi.

Il modello segue il rischio. Review, architettura e migrazioni richiedono più ragionamento; riassunti e note possono essere più leggeri.

Limita strumenti e percorsi per ridurre modifiche accidentali.

La configurazione condivisa deve essere leggibile in Git, ma i segreti restano in variabili d'ambiente o flussi del provider.

Nomi stabili come reviewer o docs-editor rendono i log chiari.

Inizia con ispezione senza scrittura. Controlla ruolo, ambito e formato.

Poi consenti una piccola modifica e rivedi il diff.

1. Nominare il ruoloUsa reviewer, planner o docs-editor.
2. Definire outputSpiega risultato e divieti.
3. Scegliere modelloAllinea ragionamento e costo al rischio.
4. Limitare strumentiParti dal minimo.
5. Validare senza scritturaChiedi ispezione o review.
6. Rivedere un diffEspandi solo dopo un cambio pulito.
7. Registrare la regolaDocumenta quando usare l'agent.

Troppi agents creano confusione. Parti da un ruolo che risolve un lavoro ripetuto.

Non duplicare regole tra AGENTS.md e agent.

MCP, hooks e skills aumentano valore e rischio.

Verifica un livello alla volta: prompt, strumento, scrittura.

Prima di proporre l'agent al team, conserva un esempio di attività riuscita: obiettivo, file letti, comandi eseguiti, risultato e diff revisionato. Questa prova rende il ruolo verificabile e permette di capire se modifiche future al prompt peggiorano il comportamento.

Aggiungi una regola di arresto. Se manca contesto, l'agent deve chiedere il file o il comando preciso invece di indovinare. Se incontra segreti, produzione o permessi di scrittura troppo ampi, deve fermarsi e restituire i rischi. Così proteggi il repository senza rallentare il lavoro ordinario.

Nei team piccoli, inizia con due ruoli al massimo: reviewer e docs-editor. Il reviewer protegge le modifiche al codice; docs-editor mantiene README, guide e note di migrazione. Aggiungi research agent o migration-checker solo quando il bisogno è ricorrente.

Dopo la prima settimana fai una revisione breve. Controlla quali attività hanno davvero usato l'agent, quali prompt sono stati corretti, se qualche strumento era troppo ampio e se l'output rispetta ancora il contratto. Rimuovi i ruoli inutilizzati invece di accumulare configurazione.

Prepara anche un rollback semplice. Chi lavora nel repository deve sapere come disattivare l'agent, quale file definisce il ruolo, quali variabili d'ambiente sono opzionali e quale commit contiene la versione verificata. Questi dati operativi valgono più di una descrizione lunga ma non provata.

Elimina inoltre un agent quando resta per settimane senza un compito chiaro. Una lista più piccola aiuta gli sviluppatori a scegliere il ruolo giusto e a controllare davvero il risultato.

I nuovi ruoli non dovrebbero essere attivi per impostazione predefinita; diventano pronti solo dopo un esempio verificato.

Scegli nomi che descrivono il lavoro. reviewer, docs-editor, release-checker o migration-planner restano comprensibili nei log e nelle revisioni. Un nome creativo può sembrare comodo, ma rende più difficile capire quale rischio l'agent doveva gestire.

Fai crescere i permessi per gradi. Un agent in sola lettura può analizzare un modulo ampio; un agent con scrittura deve avere directory consentite, comandi di verifica e un output che elenchi file modificati, test eseguiti e ipotesi rimaste aperte.

{
  "agents": {
    "reviewer": {
      "model": "provider/reasoning-model",
      "description": "Review diffs and return concrete findings only",
      "tools": ["read", "grep"]
    },
    "docs-editor": {
      "model": "provider/fast-model",
      "description": "Update documentation after source changes",
      "tools": ["read", "edit"]
    }
  }
}

La configurazione condivisa deve essere leggibile in Git, ma i segreti restano in variabili d'ambiente o flussi del provider.