Maintenir AGENTS.md
AGENTS.md est la documentation canonique destinée aux agents. Gardez-la minimale — les agents sont capables et n'ont pas besoin d'être guidés pas à pas. Visez moins de 60 lignes ; ne dépassez jamais 100. La qualité de suivi des instructions se dégrade à mesure que la longueur du document augmente.
Quand l'utiliser
- L'utilisateur demande de créer, mettre à jour ou auditer
AGENTS.mdouCLAUDE.md. - Le projet nécessite des instructions concises et à haute valeur pour l'agent, dérivées de la chaîne d'outils et de la structure du dépôt.
- La documentation existante de l'agent est trop longue, dupliquée ou s'éloigne des conventions réelles du projet.
Configuration du fichier
- Créez
AGENTS.mdà la racine du projet - Créez un lien symbolique :
ln -s AGENTS.md CLAUDE.md
Avant d'écrire
Analysez le projet pour comprendre ce qui doit figurer dans le fichier :
- Gestionnaire de paquets — Vérifiez les fichiers de verrouillage (
pnpm-lock.yaml,yarn.lock,package-lock.json,uv.lock,poetry.lock) - Configurations du linter/formateur — Cherchez
.eslintrc,biome.json,ruff.toml,.prettierrc, etc. (ne les dupliquez pas dans AGENTS.md) - Commandes CI/build — Vérifiez le
Makefile, les scriptspackage.json, les configurations CI pour les commandes canoniques - Indicateurs de monorepo — Vérifiez
pnpm-workspace.yaml,nx.json, Cargo workspace, ou les fichierspackage.jsonde sous-répertoires - Conventions existantes — Vérifiez les fichiers CONTRIBUTING.md, docs/, ou les motifs README existants
Règles d'écriture
- En-têtes + puces — Pas de paragraphes
- Blocs de code — Pour les commandes et les modèles
- Référencez, n'intégrez pas — Renvoyez aux docs existantes : « Voir
CONTRIBUTING.mdpour l'installation » ou « Suivez les motifs danssrc/api/routes/» - Pas de remplissage — Pas d'introductions, de conclusions ou de formules de politesse
- Faites confiance aux capacités — Omettez le contexte évident
- Préférez les commandes par fichier — Commandes de test/lint/vérification de type par fichier plutôt que des builds projet entier
- Ne dupliquez pas les linters — Le style de code vit dans les configurations de linter, pas dans AGENTS.md
Sections obligatoires
Gestionnaire de paquets
Quel outil et les commandes clés uniquement :
## Gestionnaire de paquets
Utilisez **pnpm** : `pnpm install`, `pnpm dev`, `pnpm test`
Commandes par fichier
Les commandes par fichier sont plus rapides et moins coûteuses que les builds projet entier. Incluez-les toujours lorsqu'elles sont disponibles :
## Commandes par fichier
| Tâche | Commande |
|------|---------|
| Vérification de type | `pnpm tsc --noEmit chemin/vers/fichier.ts` |
| Lint | `pnpm eslint chemin/vers/fichier.ts` |
| Test | `pnpm jest chemin/vers/fichier.test.ts` |
Attribution des commits
Incluez toujours cette section. Les agents doivent utiliser leur propre identité :
## Attribution des commits
Les commits IA DOIVENT inclure :
Co-Authored-By: (nom du modèle d'agent et ligne d'attribution)
Exemple : `Co-Authored-By: Claude Sonnet 4 <[email protected]>`
Conventions clés
Motifs spécifiques au projet que les agents doivent suivre. Restez bref.
Sections optionnelles
Ajoutez uniquement si vraiment nécessaire :
- Motifs de routes API (montrez un modèle, pas une explication)
- Commandes CLI (format tableau)
- Conventions de nommage des fichiers
- Indications sur la structure du projet (pointez vers les fichiers critiques, signalez le code hérité à éviter)
- Surcharges monorepo (les fichiers
AGENTS.mdde sous-répertoire remplacent la racine)
Anti-modèles
Omettez :
- « Bienvenue... » ou « Ce document explique... »
- « Vous devriez... » ou « N'oubliez pas de... »
- Les règles de linter/formateur déjà dans les fichiers de configuration (
.eslintrc,biome.json,ruff.toml) - La liste des compétences ou plugins installés (les agents les découvrent automatiquement)
- Les commandes de build projet entier complètes lorsque des alternatives par fichier existent
- Les instructions évidentes (« exécuter les tests », « écrire du code propre »)
- Les explications de pourquoi (dites simplement quoi)
- Les longs paragraphes en prose
Exemple de structure
# Instructions de l'agent
## Gestionnaire de paquets
Utilisez **pnpm** : `pnpm install`, `pnpm dev`
## Attribution des commits
Les commits IA DOIVENT inclure :
Co-Authored-By: (nom du modèle d'agent et ligne d'attribution)
## Commandes par fichier
| Tâche | Commande |
|------|---------|
| Vérification de type | `pnpm tsc --noEmit chemin/vers/fichier.ts` |
| Lint | `pnpm eslint chemin/vers/fichier.ts` |
| Test | `pnpm jest chemin/vers/fichier.test.ts` |
## Routes API
[Bloc de code modèle]
## CLI
| Commande | Description |
|---------|-------------|
| `pnpm cli sync` | Synchroniser les données |
Limitations
- Utilisez cette compétence uniquement lorsque la tâche correspond clairement au périmètre décrit ci-dessus.
- Ne traitez pas la sortie comme un substitut à une validation, un test ou une revue d'expert spécifique à l'environnement.
- Arrêtez-vous et demandez des clarifications si les entrées requises, les autorisations, les limites de sécurité ou les critères de succès sont absents.