Préparez votre codebase pour les agents

Voici comment je structure les fichiers liés aux agents IA dans mes projets.

Vous utilisez peut-être plusieurs outils comme Claude Code, OpenCode, Aider, AMP, Cursor, Droid et d’autres—souvent en comparant les modèles et les résultats sur le même codebase.

Chaque outil utilise sa propre convention pour charger les règles, compétences et commandes, ce qui mène à de la duplication si ce n’est pas géré avec soin. L’objectif est de garder le contenu DRY (Don’t Repeat Yourself) : une seule source de vérité pour les instructions des agents.

La Solution

Utilisez un fichier unique AGENTS.md agnostique des outils à la racine du projet + un répertoire agents/ pour le contenu modulaire.

Structure recommandée :

agents/
├── rules/
│   ├── python.md
│   ├── nextjs.md
│   ├── security.md
│   └── ...
├── skills/
│   ├── testing.md
│   ├── infrastructure.md
│   ├── refactoring.md
│   └── ...
├── commands/
│   ├── fix-tests.md
│   ├── fix-linter.md
│   ├── add-feature.md
│   └── ...
└── scripts/
    ├── parse_test_coverage.py
    ├── run_linter_fix.sh
    └── ...

Configurez chaque outil pour charger ou référencer AGENTS.md (et optionnellement les fichiers dans agents/).

AGENTS.md agit comme l’index central :

Instructions obligatoires en haut
Sections pour les règles, compétences, commandes avec des références style @ où c’est supporté
Guide de chargement clair (ex., “Toujours charger rules/python.md pour les fichiers Python”)

Configuration des Outils

Notes de Compatibilité

De nombreux outils supportent les compétences compatibles Claude (format .claude/skills/) :

OpenCode
AMP
Cursor

Cela permet de partager les fichiers de compétences entre eux avec des changements minimes.

Claude Code

Docs : Skills • Changelog
Répertoire : .claude/
État (2026) : Les commandes slash et les compétences sont fusionnées en skills unifiés (v2.1+). Les fichiers de commandes existants restent supportés pour la compatibilité.

Fichiers recommandés :

.claude/skills/my-skill/SKILL.md

---
description: Brief purpose of this skill
user-invocable: true           # optional: show in / menu
---

# My Skill

Follow the relevant instructions in `AGENTS.md` (usually under /skills/ or /commands/).
Load matching content from agents/ when the task matches.

CLAUDE.md (toujours supporté, mais préférez AGENTS.md)

## Mandatory

- **ALWAYS** read and follow `AGENTS.md` at the project root before any action.
- For language-specific rules, load from `agents/rules/`.
- For task patterns, reference `agents/skills/` or `agents/commands/`.

OpenCode

Docs : Rules • Skills • Commands
Répertoire : Racine du projet (pas de dossier .opencode/ obligatoire)

Structure des Fichiers :

opencode.json (optionnel, pour des globs supplémentaires / fichiers distants)

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENTS.md",
    "agents/rules/*.md"
  ]
}

OpenCode préfère AGENTS.md nativement (avec fallback vers CLAUDE.md). Utilisez opencode.json pour inclure plus de fichiers automatiquement.

AMP

Docs : Agent Skills • Custom Commands
Répertoire : .agents/

Structure des Fichiers :

.agents/skills/my-skill/SKILL.md (compatible Claude)

---
description: [your description]
---

# My Skill

Read and follow instructions in `AGENTS.md` — usually under agents/skills/.

.agents/commands/my-command-name.md

---
name: my-command-name
description: [brief description]
---

# My Command

Follow the matching section in `AGENTS.md`.

Aider

Docs : Config Reference
Fichier : .aider.conf.yml (ou ~/.aider.conf.yml)

read:
  - AGENTS.md
  - agents/rules/python.md     # optional: include specific rules

Aider charge automatiquement les fichiers listés dans le contexte.

Droid

Docs : Skills • Custom Slash Commands
Répertoire : .factory/

Structure des Fichiers :

.factory/skills/my-skill/SKILL.md

---
description: [your description]
---

# My Skill

Refer to `AGENTS.md` for detailed instructions (agents/skills/ section).

.factory/commands/my-command-name.md (structure similaire)

Cursor

Docs : Rules • Skills • Commands
Répertoire : .cursor/

Structure des Fichiers :

.cursor/rules/general.mdc (ou .md)

---
description: Core project instructions — always apply
alwaysApply: true
---

## Mandatory Instructions

- **ALWAYS** read `AGENTS.md` at project root.
- Load relevant rules from `agents/rules/` based on file type.
- Use `@agents/skills/...` syntax to reference skills when applicable.

.cursor/skills/my-skill/SKILL.md (compatible Claude)
.cursor/commands/my-command-name.md

Cursor charge automatiquement AGENTS.md quand présent (pas de configuration nécessaire). Les règles avec alwaysApply: true assurent un comportement cohérent.

Antigravity

Docs : Rules & Workflows • Skills
Répertoire : .agent/ (projet) ou global ~/.gemini/

Structure des Fichiers :

.agent/rules/general.md

---
description: Always read this before anything
trigger: always_on
---

## Core Rules

- **ALWAYS** read `AGENTS.md`.
- Reference `agents/` subfolders as needed.

.agent/skills/my-skill/SKILL.md (format standard)

Conseils Rapides

Gardez AGENTS.md < 400–500 lignes pour éviter la pression de contexte.
Utilisez les titres Markdown et les ancres pour faciliter les références.
Pour les équipes : committez agents/ + AGENTS.md dans git ; envisagez des symlinks ou sous-modules pour les règles partagées.
Test : Posez à chaque outil une question simple (“Explique les règles du projet”) et vérifiez que AGENTS.md est référencé.
Sécurité : Ne mettez jamais de secrets dans ces fichiers—utilisez des variables d’environnement ou des vaults sécurisés.

Cette configuration minimise la duplication tout en maximisant la compatibilité entre les outils (état 2026).