Un bon fichier AGENTS.md répond aux questions que Codex devrait sinon retrouver à chaque tâche. Comment lancer le projet ? Quelles commandes vérifient le changement ? Qu’est-ce qu’il ne faut pas toucher ? Quelques consignes précises sont déjà utiles.
Le piège, c’est d’en faire un deuxième README. L’historique du produit peut rester dans la documentation. Ici, je veux surtout les informations qui changent la façon de travailler dans le dépôt.
Commencer avec les commandes qui existent
Voici une base pour un projet de ce type. Les commandes doivent correspondre aux scripts réellement présents dans package.json. Une commande inventée dans les instructions coûte plus de temps qu’elle n’en fait gagner.
# Travailler dans ce projet
## Stack
React 19, TanStack Start, Tailwind CSS 4, pnpm.
## Vérifier un changement
pnpm build
pnpm typecheck
pnpm test
pnpm format:check
## Garder le périmètre
Réutiliser les composants avant d’en ajouter.
Ne pas modifier les fichiers générés à la main.
Ne pas ajouter de dépendance sans expliquer le besoin.
## Protéger les données
Ne pas lire les fichiers .env sans demande explicite.
Ne pas mettre de secret dans le code client.
Ne pas envoyer de mail réel pendant les tests.
## Livrer
Vérifier le clavier et une largeur mobile.
Indiquer ce qui a été testé et ce qui reste incertain.
Ne pas faire de commit, push ou déploiement sans demande.
Mettre les règles au bon endroit
Codex peut lire des instructions globales et des instructions propres au projet. Des fichiers plus proches du dossier de travail peuvent préciser les règles. Pour éviter les surprises, garde une consigne au niveau où elle s’applique. Une règle sur les e-mails concerne le serveur, pas chaque composant de l’interface.
Si le fichier devient long, remplace les explications détaillées par des chemins vers les documents concernés. « Pour les migrations, lire docs/database.md » est plus facile à maintenir qu’une copie de cette page. Il faut bien sûr que le fichier existe et soit encore à jour.
Écrire des règles que l’on peut vérifier
« Fais du code propre » laisse presque tout ouvert. « Réutilise le composant Button et vérifie le focus au clavier » donne deux actions concrètes. Une bonne consigne précise ce qui compte dans ce dépôt, sans imposer une recette universelle à tous les fichiers.
Après un changement de stack ou de scripts, relis les instructions. Et quand une erreur revient, demande-toi si une phrase précise pourrait l’éviter. Le fichier doit rester utile à la prochaine tâche.
Les consignes ne verrouillent pas les accès
Écrire « ne déploie pas » ne retire pas une permission de déploiement. Les approbations, les droits du compte et l’environnement d’exécution restent nécessaires. AGENTS.md explique le cadre. Il ne remplace pas les contrôles techniques qui le font respecter.
Pour la demande elle-même, je détaille un exemple dans Mieux travailler avec Codex.