AGENTS.md et HUMAN.md : guide pratique

Ce qu’est AGENTS.md

AGENTS.md est un fichier Markdown standard placé à la racine d’un dépôt. Il indique à un agent de programmation comment travailler sur ce projet. Le site officiel le décrit comme « un README pour les agents : un emplacement dédié et prévisible où fournir le contexte et les instructions nécessaires pour aider les agents de programmation IA à travailler sur votre projet ». Le format est géré par l’Agentic AI Foundation au sein de la Linux Foundation. Plus de vingt agents le lisent, notamment Codex, Cursor, Jules, Devin et GitHub Copilot (en juillet 2026).

Cette convention répond à un besoin pratique. Une nouvelle personne dans votre équipe lit le README, devine la commande de build, puis demande de l’aide si son hypothèse est incorrecte. Un agent ne peut pas poser cette question. Il devine, exécute npm test sur un projet qui utilise pnpm test, lit l’échec, puis essaie autre chose. Chacune de ces tentatives consomme des tokens que vous payez. Écrire la commande correcte une seule fois élimine toute cette catégorie d’erreurs.

Aucun champ n’est obligatoire. Le site l’indique clairement : « AGENTS.md est simplement du Markdown standard. Utilisez les titres de votre choix ; l’agent analyse simplement le texte que vous lui fournissez. » C’est toute la spécification. La valeur ne vient pas du format. Elle vient du fait que le fichier se trouve à un emplacement que chaque outil consulte déjà.

Emplacement du fichier et fichier prioritaire

Placez le premier fichier à la racine du dépôt. Dans un monorepo, vous pouvez en ajouter d’autres dans chaque sous-projet. La règle est simple : « les agents lisent automatiquement le fichier le plus proche dans l’arborescence ; le fichier le plus proche est donc prioritaire ». En cas de conflit entre deux fichiers, le fichier correspondant au fichier modifié est prioritaire. Tout ce que vous saisissez dans le chat est prioritaire sur les deux.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

La hiérarchie des fichiers est utile, car c’est le seul moyen d’énoncer une règle vraie dans un dossier et fausse dans le suivant. Une règle comme « chaque endpoint valide ses entrées » doit se trouver à côté des endpoints. Dans un fichier racine, elle est chargée pour chaque tâche sans rapport et n’apporte rien. Si votre fichier racine contient déjà une section par service, la séparation en fichiers imbriqués est la solution. Elle indique quelles règles déplacer vers les niveaux inférieurs et lesquelles conserver à la racine.

Ce qui doit figurer dans AGENTS.md

Indiquez ce qu’un agent ne peut pas déduire en lisant le code. Commencez par les commandes exactes de build, de test et de lint, sous la forme à coller dans un terminal. Ajoutez la commande qui permet d’exécuter un test unique. Un agent qui sait seulement lancer toute la suite la lancera quarante fois. Indiquez les conventions qui diffèrent des valeurs par défaut des outils. L’agent connaît déjà ces valeurs et doit uniquement connaître vos écarts. Ajoutez le format des messages de commit et les règles applicables aux pull requests, si vous en avez.

Les consignes doivent être suffisamment concrètes pour qu’une affirmation puisse être vérifiée. « Utilisez une indentation de 2 espaces » est une consigne exploitable, car il est possible de vérifier si elle a été respectée. « Formatez correctement le code » ne l’est pas, car rien ne permet de la vérifier. Il en va de même pour les emplacements : « Les gestionnaires d’API se trouvent dans src/api/handlers/ » est préférable à « Gardez les fichiers organisés ».

Les règles négatives sont également utiles. « Ne modifiez jamais les fichiers sous dist/, ils sont générés par npm run build » empêche une erreur précise. Comme la cause est indiquée, l’agent peut en déduire les cas équivalents que vous n’avez pas explicitement mentionnés. Une règle sur la portée des modifications a aussi sa place ici. Un agent laissé à sa propre appréciation réécrira davantage que nécessaire : une compétence largement copiée se contente d’insister sur la plus petite modification qui fonctionne.

Ce qui ne doit jamais y figurer

Ne mettez jamais de secret dans ces fichiers. Le fichier est commit dans git, chargé dans le contexte au début de chaque session et envoyé à un fournisseur de modèles à chaque requête. Une clé API présente dans un AGENTS.md se retrouve dans l’historique de votre dépôt et dans les journaux d’un tiers. Référencez le secret au lieu de le copier : « le mot de passe de la base de données se trouve dans .env, qui est ignoré par git ; demandez avant de le lire ». La discipline plus générale est présentée dans garder les identifiants hors de portée d’un agent.

N’incluez rien que l’agent peut déduire en examinant le projet. Une liste de répertoires copiée-collée, une copie de votre liste de dépendances ou une vue d’ensemble de l’architecture qui répète les noms des dossiers : tout devient obsolète dès la semaine suivant sa rédaction et consomme du contexte à chaque session entre-temps. Conservez les pièges et leurs raisons. Supprimez l’inventaire. Il est utile de séparer les raisons, car un agent qui ne voit pas pourquoi une structure inhabituelle existe la refactorisera discrètement. C’est notamment le cas lorsqu’il faut conserver un DESIGN.md à côté de celui-ci.

CLAUDE.md est l’équivalent de cette approche pour Claude Code

Claude Code lit CLAUDE.md et ne lit pas AGENTS.md de lui-même. Un fichier de projet se trouve dans ./CLAUDE.md ou ./.claude/CLAUDE.md. Les préférences personnelles applicables à chaque projet vont dans ~/.claude/CLAUDE.md. Une organisation peut aussi déployer un fichier valable pour toute la machine dans /etc/claude-code/CLAUDE.md sous Linux. Les fichiers détectés sont concaténés depuis la racine du système de fichiers jusqu’à votre répertoire de travail. Le fichier le plus proche du répertoire depuis lequel vous avez lancé la session est donc lu en dernier. Chaque session lancée dans ce répertoire charge la même pile de fichiers. Vous pouvez ainsi exécuter deux sessions côte à côte sur une même machine, et ces sessions peuvent se transmettre des tâches pendant leur exécution.

Si votre dépôt contient déjà un fichier AGENTS.md, ne conservez pas une seconde copie. Importez-le, puis ajoutez uniquement les éléments propres à Claude :

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Un lien symbolique convient si vous n’avez rien d’autre à ajouter :

ln -s AGENTS.md CLAUDE.md

La commande n’affiche rien en cas de réussite. Lors de votre prochaine session, exécutez /context et vérifiez que CLAUDE.md apparaît sous Fichiers de mémoire. S’il manque dans cette liste, le fichier n’a jamais été chargé et son contenu n’a donc pas été appliqué. Pour générer un premier brouillon au lieu d’en rédiger un vous-même, exécutez /init. La commande lit le code source et produit un fichier initial. Si un fichier CLAUDE.md existe déjà, elle suggère des améliorations au lieu de l’écraser.

Limitez chaque fichier à environ 200 lignes. Les fichiers plus longs consomment davantage de fenêtre de contexte et le respect des instructions diminue. Pour voir ce qui occupe aussi cet espace, cet aperçu du contenu réel de la fenêtre de contexte d’un agent détaille le sujet.

Un point mérite d’être souligné. Un fichier AGENTS.md fournit des consignes, mais ne constitue pas un système de permissions. Son contenu est transmis comme un contexte ordinaire. Le modèle le lit et s’y conforme généralement, mais rien ne bloque une action qui le contredit. Lorsqu’une règle que vous avez écrite est ignorée discrètement et que vous ne comprenez pas pourquoi, examinez les raisons pour lesquelles une instruction est ignorée avant de reformuler le texte une troisième fois. Pour une règle qui doit être respectée à chaque exécution, comme « ne poussez jamais vers main », utilisez un hook ou un paramètre de permission. Ces mécanismes s’exécutent comme du code et ne dépendent pas de la décision du modèle d’obéir.

Outils qui créent ces fichiers pour vous

Deux projets présents dans la liste des tendances GitHub le 30 juillet 2026 montrent l’orientation que prend cette convention.

agent0ai/dox (1,368 étoiles en juillet 2026) est un framework qui maintient à jour une arborescence de fichiers AGENTS.md. Il ne fournit ni package ni runtime. Vous copiez le contenu de son fichier AGENTS.md dans votre propre fichier AGENTS.md racine : c’est l’installation. Pour un projet existant, indiquez à votre agent :

Initialize DOX tree for this project now.

L’agent crée ensuite les fichiers AGENTS.md enfants et leurs index, parcourt cette arborescence avant toute modification, puis met à jour la documentation concernée une fois la modification appliquée. L’idée est que la documentation qu’un agent maintient au fil de son travail reste exacte, contrairement à celle qu’une personne met à jour manuellement.

HUMAN.md, la même approche appliquée à vous

Intuition-Lab/personal-model (1,260 stars en juillet 2026) applique ce modèle à une personne plutôt qu’à un dépôt. Le projet présente votre HUMAN.md comme le résultat du système, et non comme un fichier que vous saisissez : « un modèle vivant de ce qui compte maintenant, de la manière dont vous prenez habituellement vos décisions et de la direction que prend votre attention ». Il s’exécute localement sur macOS 13 ou version ultérieure, capture l’activité après que vous avez accordé l’autorisation à macOS, puis expose le résultat aux agents via MCP (model context protocol). L’installation minimale :

uv tool install personal-model
persome onboard
persome model open --after 30

Vous n’avez besoin de rien de tout cela pour obtenir l’essentiel du bénéfice. Un HUMAN.md rédigé à la main tient en une vingtaine de lignes : votre rôle, votre fuseau horaire, la stack que vous utilisez réellement, les décisions que vous avez déjà prises et que vous ne souhaitez pas rouvrir, ainsi que le niveau de détail que vous attendez en retour. Il évite les mêmes explications répétées qu’un fichier de projet, mais à un niveau supérieur.

Une précaution s’impose. Un HUMAN.md est par définition un profil de personne, donc une donnée sensible. Ne le placez pas dans un dépôt public. Mettez-le dans ~/.claude/CLAUDE.md, ou dans un CLAUDE.local.md ignoré par git à la racine du projet. Ce fichier est chargé avec le fichier versionné et traité de la même manière.

Modèle de départ à copier

Ce modèle est volontairement court. Supprimez les sections qui ne s’appliquent pas et évitez d’en ajouter que vous ne pourrez pas tenir à jour.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Rédigez-le, puis corrigez-le directement. Ajoutez une ligne uniquement lorsque vous avez saisi deux fois la même correction dans le chat. Cette règle suffit à conserver un fichier utile et empêche le fichier de devenir un document que personne ne lit, y compris les machines. Une fois stabilisé, il reste avec le dépôt. C’est particulièrement important lorsque l’agent s’exécute ailleurs que sur votre ordinateur portable : exécuter un agent de programmation sur votre propre serveur explique cette configuration.

FAQ

AGENTS.md est-il le même fichier que CLAUDE.md ?

Il s’agit de la même idée, sous deux noms de fichier. Claude Code lit CLAUDE.md et ignore AGENTS.md, sauf si vous les reliez. Conservez un seul fichier comme source de référence et liez l’autre à celui-ci, soit avec une ligne contenant @AGENTS.md au début de votre CLAUDE.md, soit avec ln -s AGENTS.md CLAUDE.md. Deux copies complètes gérées séparément finiront par diverger en moins d’un mois.

La rédaction d’un fichier AGENTS.md garantit-elle que l’agent le respecte ?

Non. Le contenu est fourni comme contexte. Le modèle le lit et s’y conforme généralement, mais rien n’empêche une action qui le contredit. Les instructions vagues sont les moins bien respectées. Deux fichiers donnant des consignes opposées laissent l’agent en choisir un de manière arbitraire. Pour une règle qui doit toujours être respectée, utilisez un hook ou une règle d’autorisation. Le client les applique quelle que soit la décision du modèle.

Faut-il ajouter AGENTS.md au dépôt git ?

Oui, pour tout ce qui est vrai du projet : commandes de build, arborescence et conventions. C’est précisément le rôle de ce fichier : les agents de vos coéquipiers démarrent ainsi avec le même contexte que le vôtre. Tout ce qui est personnel ou propre à une machine doit être placé dans un fichier gitignored distinct. Les identifiants ne doivent figurer dans aucun des deux.

Qu’est-ce que HUMAN.md et en ai-je besoin ?

HUMAN.md est un profil lisible par une machine, qui décrit une personne plutôt qu’un projet. Il contient votre rôle, vos contraintes et les décisions déjà prises, afin qu’elles ne soient pas rouvertes à chaque session. Vous n’avez besoin d’aucun outil pour commencer : vingt lignes rédigées manuellement dans votre fichier d’instructions utilisateur vous apportent déjà l’essentiel. Traitez ce fichier comme une donnée personnelle et ne le placez dans aucun dépôt que vous publiez.