Guide OpenCode Agents : 7 vérifications pour Subagents et AGENTS.md

Réponse courte : utilisez AGENTS.md pour les règles du dépôt et OpenCode agents pour un spécialiste nommé avec prompt, modèle, outils et limites propres.

AGENTS.md garde les règles durables du dépôt : commandes de test, style, dossiers générés et avertissements. L'agent décrit le comportement d'un rôle précis.

Mélanger ces couches crée des consignes dupliquées et difficiles à corriger.

Un subagent est utile quand il isole une vraie préoccupation : explorer un grand dossier, relire un diff sensible ou étudier une API.

Définissez un contrat de sortie avec références de fichiers, plan de patch ou liste de risques.

Le modèle doit suivre le risque. Revue, architecture et migration demandent plus de raisonnement; résumé et notes peuvent être plus légers.

Réduisez outils et chemins autorisés pour limiter les changements accidentels.

La configuration partagée doit être lisible dans Git, mais les secrets restent dans des variables d'environnement ou le flux du fournisseur.

Des noms stables comme reviewer ou docs-editor rendent journaux et prompts plus clairs.

Commencez par une inspection sans écriture. Vérifiez le périmètre, le ton et le format de sortie.

Autorisez ensuite une petite modification et examinez le diff.

1. Nommer le rôleUtilisez reviewer, planner ou docs-editor.
2. Définir la sortiePrécisez le résultat et les interdits.
3. Choisir le modèleAlignez raisonnement et coût sur le risque.
4. Limiter les outilsCommencez par le minimum.
5. Valider sans écritureDemandez inspection ou revue.
6. Lire un diffÉlargissez seulement après un changement propre.
7. Documenter la règleExpliquez quand utiliser l'agent.

Trop d'agents provoquent de la confusion. Commencez par un rôle qui résout un besoin répété.

Ne dupliquez pas les mêmes règles dans AGENTS.md et dans l'agent.

MCP, hooks et skills peuvent renforcer un rôle, mais augmentent aussi le risque.

Validez une couche à la fois : prompt, outil, puis écriture.

Avant de le proposer à l'équipe, conservez un exemple de tâche réussie : objectif, fichiers lus, commandes lancées, résultat et diff relu. Cette trace transforme le rôle en comportement vérifiable plutôt qu'en simple intention.

Ajoutez aussi une règle d'arrêt. Si l'agent manque de contexte, il doit demander le fichier ou la commande précise au lieu de deviner. S'il voit des secrets, de la production ou des droits d'écriture larges, il doit s'arrêter et lister les risques. Cette limite protège le dépôt sans ralentir les tâches ordinaires.

Pour une petite équipe, commencez avec deux rôles au maximum : reviewer et docs-editor. Le premier protège les changements de code; le second maintient README, guides et notes de migration. Ajoutez ensuite research agent ou migration-checker seulement si le besoin se répète.

Choisissez des noms qui décrivent le travail attendu. reviewer, docs-editor, release-checker ou migration-planner restent lisibles dans les journaux, les prompts et les revues de diff. Un nom amusant peut sembler pratique au début, mais il rend plus difficile de comprendre pourquoi l'agent a été appelé.

Gardez une progression claire des permissions. Un agent sans écriture peut analyser un dossier et produire un rapport; un agent capable d'éditer doit avoir un périmètre plus étroit, une commande de vérification connue et un format de sortie qui liste les fichiers modifiés. Cette séparation réduit les corrections surprises.

Révisez la configuration lorsque le projet change de framework, de commande de build ou de fournisseur de modèle. Une règle sûre en janvier peut devenir fausse après une migration. Notez la date du dernier essai réussi et supprimez les rôles qui ne correspondent plus au flux réel.

{
  "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 configuration partagée doit être lisible dans Git, mais les secrets restent dans des variables d'environnement ou le flux du fournisseur.