Comment Écrire des Fichiers AGENTS.md pour les Équipes de Développement d'API

Les agents de codage lisent votre dépôt avant d'écrire du code, et le premier fichier qu'ils lisent est AGENTS.md. C'est la convention ouverte sur laquelle Codex CLI, Cursor, Aider, OpenHands et une liste croissante d'autres outils se sont mis d'accord afin qu'un seul fichier de contexte fonctionne avec tous les agents. Pour les équipes de développement d'API, ce fichier fait la différence entre un agent qui exécute les bons tests sur un serveur local réel et un autre qui hallucine des points de terminaison et livre un client défectueux.

Ce guide couvre ce qu'est AGENTS.md, pourquoi les équipes API devraient le traiter comme du code de production, les sections importantes pour les dépôts "OpenAPI-first", des exemples concrets, et comment le maintenir à jour à mesure que l'API évolue. Nous l'associons à Apidog à la fin afin que le flux de test de contrat de l'agent reste ancré dans une spécification réelle.

En bref

• AGENTS.md est un simple fichier Markdown à la racine du dépôt qui indique aux agents de codage comment naviguer, construire, tester et livrer du code dans votre projet.
• La convention est ouverte et supportée par Codex CLI, Cursor, OpenHands, Aider, Claude Code et d'autres outils d'agents.
• Pour les équipes API, les sections les plus rentables sont les commandes de compilation, le chemin de la spécification OpenAPI, les points de terminaison du serveur de maquette, les commandes de test de contrat, la configuration d'authentification et les zones "ne pas toucher".
• Gardez-le court. De 200 à 400 lignes, c'est amplement suffisant. Plus long, l'agent ignorera les parties importantes.
• Associez-le à une collection Apidog pour que l'agent dispose à la fois du contexte (AGENTS.md) et d'un contrat exécutable (la spécification OpenAPI).

Ce qu'est réellement AGENTS.md

AGENTS.md est un fichier Markdown que vous commitez à la racine d'un dépôt. Les agents de codage le recherchent lors du premier contact avec la base de code et traitent son contenu comme le briefing faisant autorité sur le fonctionnement du projet. La convention a commencé au sein de Codex CLI d'OpenAI et a été publiée en tant que standard ouvert afin que d'autres outils puissent lire le même fichier. À partir de cette année, Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody et plusieurs agents plus petits le lisent tous.

Trois choses le rendent utile :

1. Un fichier, tous les agents. Vous écrivez le contexte une fois et chaque agent de la boîte à outils de l'équipe le récupère. Pas de dérive de configuration par outil.
2. Markdown simple. Pas de DSL, pas de schéma, pas d'étape de compilation. Les ingénieurs l'éditent comme n'importe quel autre document.
3. Vit à côté du code qu'il décrit. Lorsque le script de compilation change, le fichier change dans la même PR. Le diff rend le changement visible pour les relecteurs et pour l'agent.

Le cousin le plus proche est CLAUDE.md, que Claude Code d'Anthropic lit. Les deux formats se chevauchent fortement ; de nombreux projets conservent un AGENTS.md lié symboliquement à CLAUDE.md afin que les deux outils fonctionnent sans configuration supplémentaire. L'équipe Codex et Anthropic se sont publiquement alignées sur le maintien de la compatibilité des formats à l'avenir.

Pourquoi les équipes de développement d'API en ont plus besoin que la plupart

Les équipes API se trouvent à une intersection délicate : le code est petit, les contrats sont grands, et les conséquences de toute erreur sont visibles par chaque client en aval. Un agent qui ne sait pas que la spécification se trouve à openapi.yaml réécrira les types à partir de la forme de réponse qu'il se souvient des données d'entraînement. Un agent qui ne connaît pas la commande de test de contrat commettra du code qui compile mais brise le pipeline du SDK client.

Un AGENTS.md bien écrit pour un dépôt API fait quatre choses :

• Établit la spécification comme source de vérité. Chaque changement commence et se termine par le schéma OpenAPI ou GraphQL. L'agent apprend à mettre à jour la spécification en premier, puis à régénérer les types.
• Nomme les serveurs locaux. Les agents qui démarrent un serveur de maquette local ou un serveur réel choisissent la bonne URL pour les tests, et non un extrait de Stack Overflow.
• Liste les commandes de test par intention. "Exécuter les tests unitaires" n'est pas la même chose que "exécuter les tests de contrat" ou "exécuter les tests d'intégration sur l'environnement de staging".
• Signale les chemins interdits. Le code SDK généré, les wrappers clients tiers et les fichiers de migration semblent souvent éditables, mais ne le sont pas.

Lorsque le fichier fait ces quatre choses, la sortie de l'agent cesse de ressembler à un développeur junior qui a sauté le README et commence à ressembler à un coéquipier.

La structure qui fonctionne pour les dépôts API

AGENTS.md n'a pas de schéma requis. La communauté s'est accordée sur quelques sections qui apparaissent dans presque tous les fichiers bien réglés. Pour une équipe API, l'ordre ci-dessous est un excellent défaut.

1. Résumé du projet (3-5 lignes)

Indiquez ce que fait l'API, qui sont les consommateurs, et quel langage et framework le serveur utilise. Restez factuel.

# Projet : API de paiements

Service de paiement interne pour la gamme de produits Acme. Les clients sont
mobiles, web et backends partenaires. Le serveur est Go 1.23 sur Echo, Postgres
17 pour le stockage, et une couche d'idempotence basée sur Redis.

Ce bloc indique à l'agent quel langage utiliser par défaut, quels idiomes suivre et quels clients sont affectés si vous livrez une forme de réponse incorrecte.

2. Commandes de démarrage rapide

Cinq à dix commandes que l'agent exécutera constamment. Incluez toujours la commande, ne renvoyez jamais à un wiki.

## Commandes

| Intention | Commande |
|--------|---------|
| Installer dépendances | `make deps` |
| Exécuter serveur localement | `make dev` (écoute 127.0.0.1:8080) |
| Exécuter tests unitaires | `make test` |
| Exécuter tests de contrat sur maquette locale | `make contract` |
| Lint | `make lint` |
| Régénérer clients depuis spécification | `make codegen` |
| Appliquer migrations | `make migrate` |

Si une commande a besoin d'une variable d'environnement pour fonctionner, placez le nom de la variable d'environnement à côté. Les agents sont bons pour exporter des variables ; ils sont mauvais pour deviner.

3. La section de spécification OpenAPI / GraphQL

C'est la section la plus précieuse d'un dépôt API. Indiquez à l'agent où se trouve la spécification, comment la spécification est liée au code généré et dans quelle direction les modifications circulent.

## Source de vérité

- La spécification se trouve à `apis/payments/openapi.yaml`.
- Les clients générés se trouvent dans `gen/clients/{go,ts,python}` et NE DOIVENT PAS être édités manuellement.
- Le pipeline de génération est `make codegen`. Exécutez-le après chaque modification de spécification
  et commitez les clients régénérés dans la même PR.
- Les modifications de spécification suivent le flux : spécification -> `make codegen` -> mises à jour des gestionnaires de serveur ->
  tests de contrat -> livraison.

Ce bloc seul élimine une catégorie de bugs où les agents éditent le client généré pour "corriger" une incompatibilité de type, la prochaine exécution de codegen efface le changement, et la build se brise mystérieusement deux jours plus tard.

4. Serveur de maquette et câblage Apidog

Si vous utilisez des serveurs de maquette (et vous devriez), nommez-les. Listez les URL, la spécification qu'ils lisent et comment les démarrer.

## Serveurs locaux

- Serveur réel : `make dev` -> `http://127.0.0.1:8080`
- Serveur de maquette Apidog : `make mock` -> `http://127.0.0.1:4010`
- La maquette lit le même `openapi.yaml` et rejoue les exemples sauvegardés
  de la collection Apidog à `apis/payments/apidog/`.

C'est là qu'Apidog prend sa place dans le fichier. Le serveur de maquette, la spécification et les exemples de requêtes enregistrés forment un contrat que l'agent peut exécuter sans brûler d'appels sur le backend réel. Associez-le au guide de test d'API sans Postman pour le workflow sous-jacent.

5. Authentification et secrets

Indiquez à l'agent comment l'API s'authentifie et quelles variables d'environnement contiennent quoi. Ne mettez jamais de vrais secrets dans le fichier.

## Authentification

- La production utilise des identifiants client OAuth 2 émis par Auth0.
- Le développement local utilise un jeton de développement statique ; exportez `DEV_TOKEN` depuis `.env.local`.
- La collection Apidog utilise les mêmes noms de variables d'environnement pour que la maquette et le
  client réel se comportent de manière identique.
- Les jetons NE DOIVENT PAS être commités ; `.env.local` est dans `.gitignore`.

6. Stratégie de test

Classez les couches de test. Les agents les exécuteront dans l'ordre que vous indiquez.

## Tests

1. `make test` pour les tests unitaires. Rapides, exécutés à chaque changement.
2. `make contract` pour les tests de contrat OpenAPI sur la maquette. Exécutés avant
   toute fusion de modification de spécification.
3. `make integration` pour les tests de bout en bout sur un serveur local avec une
   base de données Postgres réelle. Exécutés avant la fusion vers la branche principale.
4. Les tests de charge de staging s'exécutent toutes les nuits via GitHub Actions ; ce n'est pas une commande locale.

7. Liste "Ne pas toucher"

Le code généré, les dépendances vendues et les migrations appartiennent presque toujours ici.

## Ne pas éditer manuellement

- `gen/**` (régénéré par `make codegen`)
- `vendor/**` (géré par `go mod vendor`)
- `migrations/*.up.sql` au-delà de la première migration non appliquée
- `apis/payments/openapi.yaml` noms de champs de schéma sans approbation du propriétaire

8. Style maison

Trois à cinq règles. Plus, et l'agent choisira la mauvaise.

## Conventions

- Les erreurs renvoient des problèmes JSON RFC 7807 ; jamais de chaînes brutes.
- Utilisez snake_case en JSON, camelCase en Go, PascalCase dans les clients TS.
  Le codegen gère le mappage.
- Les clés d'idempotence sont requises sur tous les points de terminaison POST qui créent des ressources.
- Les nouveaux points de terminaison nécessitent un test de contrat qui exerce à la fois les chemins 200 et 4xx.

Exemple concret : un fichier de 90 lignes qui fait le travail

La tentation est d'écrire 800 lignes. Résistez. Le fichier ci-dessous couvre un service API réel en 90 lignes de Markdown et est suffisant pour que tout agent majeur travaille productivement.

# Projet : API de paiements

Service de paiement interne pour la gamme de produits Acme. Go 1.23, Echo,
Postgres 17, Redis pour l'idempotence. Les consommateurs sont mobiles, web,
et backends partenaires.

## Commandes

| Intention | Commande |
|--------|---------|
| Installer | `make deps` |
| Exécuter serveur | `make dev` |
| Tests unitaires | `make test` |
| Tests de contrat | `make contract` |
| Lint | `make lint` |
| Régénérer clients | `make codegen` |
| Migrer DB | `make migrate` |

## Source de vérité

- Spécification : `apis/payments/openapi.yaml`
- Clients générés : `gen/clients/{go,ts,python}` (ne pas éditer)
- Flux d'édition : spécification -> `make codegen` -> gestionnaire -> tests de contrat -> livraison

## Serveurs locaux

- Serveur réel : `make dev` (`http://127.0.0.1:8080`)
- Maquette Apidog : `make mock` (`http://127.0.0.1:4010`)
- Collection Apidog : `apis/payments/apidog/`

## Authentification

- Production : Identifiants client Auth0 OAuth 2.
- Développement local : `DEV_TOKEN` statique depuis `.env.local`.

## Ordre des tests

1. `make test`
2. `make contract`
3. `make integration`

## Ne pas éditer manuellement

- `gen/**`, `vendor/**`
- Migrations appliquées dans `migrations/`
- Noms de champs de spécification sans approbation du propriétaire

## Conventions

- Problèmes JSON RFC 7807 pour les erreurs
- JSON en snake_case, codegen gère le mappage linguistique
- Clés d'idempotence requises sur les créations POST
- Chaque nouveau point de terminaison livré avec un test de contrat

C'est suffisant. N'ajoutez des sections que lorsqu'un agent fait deux fois la même mauvaise chose.

Maintenir le fichier à jour

Un fichier AGENTS.md obsolète est pire qu'aucun fichier du tout. L'agent y croira et expédiera du code basé sur une commande de compilation qui ne fonctionne plus.

Trois habitudes le maintiennent à jour :

1. Traitez-le comme du code de production. Les modifications passent par la même révision que toute autre PR. Les réviseurs vérifient que les listes de commandes correspondent au Makefile réel.
2. Intégrez-le à l'intégration continue. Un court script qui analyse le tableau de commandes et exécute chaque commande sur un nouveau checkout détecte rapidement la dérive. La plupart des équipes écrivent cela en 30 lignes de Bash.
3. Mettez-le à jour dans la même PR. Lorsque vous ajoutez une nouvelle commande de test, ne promettez pas de mettre à jour AGENTS.md plus tard. Mettez-le à jour maintenant. Le coût est de deux minutes ; le coût de l'omission est de deux semaines de confusion de l'agent.

Apidog comme contrat d'exécution pour votre AGENTS.md

AGENTS.md donne le contexte à l'agent. La spécification OpenAPI lui donne le contrat. Apidog relie les deux : il lit la spécification, exécute une maquette locale à l'URL indiquée dans AGENTS.md, rejoue les exemples de requêtes enregistrés pour les tests, et permet à l'agent de voir les réponses réelles sans brûler de crédits sur le backend en direct.

Le modèle qui fonctionne :

• Commitez apis/<service>/openapi.yaml et apis/<service>/apidog/ (la collection exportée).
• Listez l'URL de la maquette et la commande make mock dans AGENTS.md.
• Les agents exécutent make contract pour des tests rapides sur des exemples enregistrés.
• Lorsque la spécification change, l'agent régénère les clients, exécute la suite de contrats, et seulement ensuite touche le serveur réel.

Pour une exploration plus approfondie du workflow de maquette Apidog avec une API réelle, le guide de l'API DeepSeek V4 couvre le même modèle appliqué à une API de modèle au lieu d'une API de service.

Erreurs courantes commises par les équipes API

Après avoir examiné des dizaines de ces fichiers, les mêmes cinq problèmes apparaissent :

1. Lien au lieu de liste. "Voir le wiki pour les commandes de construction." L'agent ne navigue pas sur le wiki. Insérez les commandes directement.
2. Prose marketing. "Notre plateforme API de classe mondiale permet..." L'agent n'a pas besoin d'un argumentaire de vente. Énoncez les faits.
3. Commandes obsolètes. Une commande qui a cassé en mars est toujours dans le fichier en avril. Intégrez l'intégration continue pour le détecter.
4. Absence de la section de spécification. Le bloc le plus utile. Incluez-le toujours.
5. Pas de liste "ne pas toucher". L'agent édite le code généré. La prochaine exécution de codegen efface l'édition. La build échoue. Répétez.

Si vous souhaitez une base de départ, copiez l'exemple ci-dessus dans votre dépôt, modifiez le résumé du projet et ajustez le tableau de commandes. Vous pouvez livrer un fichier utilisable en 20 minutes.

FAQ

Est-ce que AGENTS.md est la même chose que CLAUDE.md ?Les formats sont compatibles. La plupart des équipes en gardent un comme source de vérité et lient symboliquement l'autre. Anthropic et OpenAI se sont publiquement alignés sur le maintien de l'interopérabilité des conventions.

Où dois-je placer le fichier ?Toujours à la racine du dépôt. Certains agents lisent également des fichiers AGENTS.md imbriqués dans des sous-répertoires, ce qui est utile pour les monorepos. Commencez par un fichier racine et n'ajoutez des fichiers de sous-répertoire que si un seul fichier racine devient trop long.

Quelle doit être sa longueur ?200 à 400 lignes est l'idéal. Au-delà, les agents commencent à sauter des sections. Si vous avez besoin de plus de détails, renvoyez à un document séparé avec un résumé d'une ligne intégré.

Dois-je inclure des exemples de code ?Des courts, oui. Des longs, non. Réservez les exemples complets aux tests ; les agents lisent aussi les tests. Le guide gratuit GPT-5.5 Codex explique comment Codex utilise spécifiquement les tests d'exemple comme signal additionnel.

L'agent relit-il le fichier à chaque tour ?La plupart des agents le lisent au début de la session et le mettent en cache. Certains le relisent après de grands changements de fichiers. Si vous effectuez une modification majeure, redémarrer la session de l'agent est le mouvement le plus sûr.

Comment puis-je tester que mon fichier fonctionne ?Exécutez une nouvelle session d'agent sans autre contexte, donnez-lui une petite tâche ("ajouter une réponse 422 à POST /payments") et observez ce qu'il fait. S'il lit la spécification, exécute make codegen et écrit un test de contrat, le fichier fait son travail.