AGENTS.md ou HUMAN.md : quelles différences ?

Ce qu'est AGENTS.md

AGENTS.md est un fichier Markdown simple situé à 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, sous l'égide 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 et demande de l'aide si son hypothèse est incorrecte. Un agent ne peut pas poser de question. Il devine, exécute npm test sur un projet qui utilise pnpm test, lit l'erreur, puis essaie autre chose. Chacune de ces tentatives consomme des tokens que vous payez. Écrire la commande réelle 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 headings 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 chemin que tous les outils recherchent 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 associé au fichier en cours de modification 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

Cette imbrication est utile, car c’est le seul moyen d’énoncer une règle vraie dans un dossier et fausse dans le dossier 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 toutes les tâches sans rapport et n’apporte rien.

Ce qui doit figurer dans un fichier AGENTS.md

Notez 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 à copier-coller dans un terminal. Ajoutez la commande qui permet d’exécuter un seul test. Un agent qui sait uniquement 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 par défaut 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.

Donnez suffisamment de détails pour qu’une affirmation puisse être vérifiée. « Utilisez une indentation de 2 espaces » est une instruction 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 le vérifier. Il en va de même pour les emplacements : « Les gestionnaires d’API se trouvent dans src/api/handlers/ » est plus utile que « Organisez correctement les fichiers ».

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 » évite une erreur précise. Comme la cause est indiquée, l’agent peut en déduire le cas équivalent que vous n’avez pas explicitement décrit.

Ce qui ne doit jamais y figurer

Ne mettez jamais de secret dans ces fichiers. Le fichier est enregistré dans git, chargé dans le contexte au début de chaque session et envoyé à un fournisseur de modèles à chaque requête. Une clé d’API dans un fichier AGENTS.md se retrouve dans l’historique de votre dépôt et dans les journaux d’un tiers. Indiquez où se trouve 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 règle générale est expliquée dans ne pas laisser les identifiants à la portée d’un agent.

N’incluez rien que l’agent peut déduire en examinant les fichiers. Une liste de répertoires copiée, une copie de votre liste de dépendances ou une présentation de l’architecture qui répète les noms des dossiers deviennent obsolètes dès la semaine suivant leur rédaction et consomment du contexte à chaque session entre-temps. Conservez les pièges et leurs raisons. Supprimez l’inventaire.

CLAUDE.md est l’équivalent de la même approche pour Claude Code

Claude Code lit CLAUDE.md et ne lit pas AGENTS.md automatiquement. Un fichier de projet se trouve dans ./CLAUDE.md ou ./.claude/CLAUDE.md. Les préférences personnelles pour chaque projet se placent dans ~/.claude/CLAUDE.md. Une organisation peut déployer un fichier à l’échelle de 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 de l’emplacement depuis lequel vous avez lancé la session est donc lu en dernier.

Si votre dépôt contient déjà un fichier AGENTS.md, ne gérez pas une deuxième copie. Importez-le, puis ajoutez uniquement les éléments spécifiques à 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 n’apparaît pas dans cette liste, le fichier n’a jamais été chargé et son contenu n’a donc pas été appliqué. Pour générer une première version au lieu d’en écrire une vous-même, exécutez /init. La commande lit le code source et produit un fichier de départ. 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 la fenêtre de contexte et réduisent le respect des instructions. Si vous voulez voir ce qui utilise également cet espace, ce qui remplit réellement la fenêtre de contexte d’un agent l’explique en détail.

Un point mérite d’être souligné. Un fichier AGENTS.md contient des consignes, pas un système d’autorisation. Son contenu est fourni comme contexte ordinaire. Le modèle le lit et s’y conforme généralement, mais rien ne bloque une action qui le contredit. Pour une règle qui doit être respectée à chaque fois, comme « ne jamais effectuer de push vers main », utilisez un hook ou un paramètre d’autorisation. Ces mécanismes s’exécutent sous forme de code et ne dépendent pas de la décision du modèle de respecter la règle.

Outils qui créent ces fichiers pour vous

Deux projets présents dans la liste des tendances GitHub le 30 juillet 2026 montrent la direction 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 aucun package ni runtime. Vous copiez le contenu de son fichier AGENTS.md dans votre propre fichier AGENTS.md à la racine, et 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 de modifier quoi que ce soit, puis met à jour la documentation concernée une fois la modification appliquée. Le principe est le suivant : la documentation qu'un agent maintient automatiquement pendant son travail reste conforme à la réalité, contrairement à celle qu'une personne met à jour manuellement.

HUMAN.md : le même principe appliqué à vous

Intuition-Lab/personal-model (1,260 étoiles en juillet 2026) applique ce principe à 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 rédigez : « un modèle vivant de ce qui compte actuellement, de votre façon de prendre des 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 vous avoir demandé l’autorisation macOS et expose le résultat aux agents via MCP (model context protocol). La procédure d’installation courte :

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

Vous n’avez besoin d’aucun de ces éléments pour obtenir l’essentiel du bénéfice. Un HUMAN.md rédigé manuellement 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 voulez pas rouvrir, ainsi que le niveau de détail que vous souhaitez recevoir. 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 personnel, donc une donnée sensible. Ne le placez pas dans un dépôt public. Mettez-le dans ~/.claude/CLAUDE.md, ou dans un fichier CLAUDE.local.md ignoré par git à la racine du projet ; il sera chargé en même temps que le fichier versionné et traité de la même manière.

Un 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 si vous ne pouvez pas les maintenir à 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.

Écrivez-le, puis corrigez-le directement sur place. Le signal indiquant qu’il faut ajouter une ligne est que vous avez saisi deux fois la même correction dans le chat. Cette seule règle permet de conserver un fichier utile et l’empêche de devenir un document que personne ne lit, y compris les machines. Une fois stabilisé, il accompagne le repository. C’est particulièrement important lorsque l’agent s’exécute ailleurs que sur votre laptop : exécuter un coding agent sur votre propre serveur décrit cette configuration.

FAQ

Le fichier AGENTS.md est-il identique au fichier 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 fichier CLAUDE.md, soit avec ln -s AGENTS.md CLAUDE.md. Deux copies complètes gérées séparément divergeront en moins d’un mois.

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

Non. Son 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 suivies, et deux fichiers donnant des indications opposées laissent l’agent en choisir une arbitrairement. Pour une règle qui doit toujours être respectée, utilisez un hook ou une règle d’autorisation. Le client les applique quel que soit le choix du modèle.

Faut-il valider AGENTS.md dans git ?

Oui, pour tout ce qui est vrai du projet : commandes de build, organisation, conventions. C’est le rôle de ce fichier, car les agents de vos coéquipiers démarrent ainsi avec le même contexte que le vôtre. Les éléments personnels ou propres à une machine doivent figurer dans un fichier distinct ignoré par git. Les identifiants ne doivent figurer dans aucun des deux fichiers.

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 remises en question à chaque session. Aucun outil n’est nécessaire pour commencer : vingt lignes rédigées manuellement dans votre fichier d’instructions utilisateur vous apportent déjà l’essentiel de la valeur. Traitez ce fichier comme des données personnelles et ne l’incluez dans aucun dépôt que vous publiez.