Faire comprendre votre projet à l'IA : contexte et fichiers de règles

La leçon 5 du module 05 l'a montré : le modèle lui-même ne se souvient de rien, chaque conversation repart de zéro. C'est pareil pour les outils de programmation IA. Hier, vous avez passé une demi-heure à lui expliquer « nos tests se lancent avec make test, pas directement avec pytest », et aujourd'hui, dans une nouvelle conversation, il lance de nouveau directement pytest.

La solution : écrire ces « choses à réexpliquer à chaque fois » dans un fichier que l'outil charge automatiquement dans son contexte à chaque démarrage. Cette leçon explique comment l'écrire.

Comment s'appellent ces fichiers

Chaque outil lit un fichier différent. En septembre 2026, selon leur documentation officielle :

AGENTS.md est un format ouvert, aujourd'hui maintenu par l'Agentic AI Foundation, sous l'égide de la Linux Foundation ; son site (agents.md) liste plus de vingt outils qui le prennent en charge. Son positionnement est simple : le README est écrit pour les humains, AGENTS.md pour les outils de programmation IA.

La documentation de Claude Code indique explicitement qu'il lit CLAUDE.md et non AGENTS.md. Si votre projet a déjà un AGENTS.md, la documentation officielle recommande de créer un CLAUDE.md contenant une ligne @AGENTS.md pour l'inclure : les deux types d'outils lisent ainsi le même contenu, sans avoir à maintenir deux fichiers :

@AGENTS.md

## 只对 Claude Code 生效的补充
改动 src/billing/ 下的代码之前，先进入计划模式。

Noms de fichiers et règles changent avec les versions ; jetez un œil à la documentation récente de votre outil avant de vous en servir. La manière d'écrire présentée ci-dessous vaut pour tous les fichiers de ce type.

Où les placer, et lequel prime

On peut généralement placer ces fichiers à plusieurs niveaux :

• Personnel, global : par exemple ~/.codex/AGENTS.md ou ~/.claude/CLAUDE.md, pour vos préférences personnelles dans tous vos projets.
• Racine du projet : commité dans git, partagé par toute l'équipe.
• Sous-dossiers : dans un grand dépôt, un sous-projet peut avoir le sien, qui ne s'applique qu'aux fichiers de ce dossier.

Quand plusieurs fichiers coexistent, la règle générale est : plus il est proche du fichier en cours de travail, plus il prime. Le site d'AGENTS.md le dit ainsi : « The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything » ; autrement dit, le fichier le plus proche du fichier modifié s'applique, et ce que vous dites directement dans la conversation a la priorité la plus haute. Codex et Claude Code concatènent les fichiers de chaque niveau, de la racine au dossier courant ; plus un fichier est proche du dossier courant, plus il vient tard, et le contenu qui suit l'emporte naturellement sur celui qui précède.

Ce qu'il faut écrire

Une question pour trancher : faut-il réexpliquer cela à l'IA à chaque fois ?

Ce qui mérite d'y figurer, en général :

Comment construire, tester et vérifier. C'est le point le plus important. Quand l'IA a modifié du code, elle doit pouvoir vérifier elle-même. Écrivez les commandes précises :

## 命令
- 安装依赖：`uv sync`
- 运行全部测试：`uv run pytest -q`
- 只跑一个文件：`uv run pytest tests/test_retrieval.py -q`
- 代码检查：`uv run ruff check .`

La structure du projet. Quel code se trouve dans quel dossier, où est le point d'entrée. Seulement ce que l'IA ne peut pas deviner à partir des noms de fichiers.

Les règles propres à ce projet. Ce qui s'écarte des pratiques habituelles mérite le plus d'y figurer :

## 约定
- 所有调用大模型的代码都通过 `llm.py` 里的函数，不要直接 new 一个 OpenAI 客户端。
- 价格表在 `llm.PRICES`，改价格只改这一处。
- 用户能看到的文字一律用中文。

Les pièges déjà rencontrés. Une erreur que l'IA a commise une fois, notez-la pour qu'elle ne recommence pas :

## 注意
- 检索器里调用本地模型必须持有 `_MODEL_LOCK`，多线程同时调用会互相争抢到几乎卡死。
- `data/httpx-docs/` 是第三方文档的副本，不要修改里面的文件。

Ce qu'il ne faut pas écrire

• Ce que l'IA apprend elle-même en lisant le code. Quels fichiers se trouvent dans le dossier, quelles dépendances sont utilisées : elle le voit elle-même. L'écrire ne fait que gaspiller du contexte.
• Les principes vagues. « Écrire du code de qualité », « faire attention à la sécurité » ne contiennent rien de vérifiable ; autant ne rien écrire.
• Les longues procédures. Un long processus nécessaire seulement pour un type de tâche n'a pas sa place dans un fichier lu à chaque fois. Certains outils ont des mécanismes dédiés, chargés à la demande (comme les skills de Claude Code ou les règles conditionnelles de Cursor).
• Les secrets. Clés, mots de passe, adresses internes : jamais. Ce fichier est commité dans git et entre dans le contexte du modèle.

La documentation de Claude Code recommande de limiter un CLAUDE.md à 200 lignes. La raison est simple : ce fichier est lu en entier dans le contexte à chaque fois ; plus il est long, plus il prend de place, et plus il y a de règles, plus le modèle a du mal à toutes les respecter.

Du concret, pour être respecté

Deux façons d'écrire, comparées :

Les formulations concrètes ont un point commun : elles sont vérifiables. Si l'IA l'a fait ou non, vous le voyez tout de suite. Avec une formulation vague, l'IA croit l'avoir déjà fait.

Les règles ne doivent pas se contredire. Si le fichier racine dit « indentation de 2 espaces » et celui d'un sous-dossier « 4 espaces », le modèle risque d'en choisir une au hasard. Relisez régulièrement ces fichiers, et supprimez ce qui est périmé ou contradictoire.

Un fichier de règles est du contexte, pas une contrainte

Ce point est très important, et le plus souvent mal compris.

La documentation officielle de Claude Code le dit clairement : CLAUDE.md est transmis au modèle comme contexte ; le modèle s'efforce de le respecter, mais le respect strict n'est pas garanti. Ce n'est pas une règle appliquée de force. Si vous écrivez dans le fichier « ne modifie pas le fichier .env », le modèle obéira la plupart du temps, mais il y aura toujours des exceptions.

L'expérience de la leçon 8 du module 05 offre une bonne comparaison : des règles de sécurité parfaitement claires dans le prompt, le modèle le plus fort les a quand même enfreintes 4 fois sur 5. Fichiers de règles et prompts sont au fond la même chose.

Ce qui est vraiment interdit doit donc être limité par les mécanismes contraignants de l'outil, et non écrit dans un fichier de règles en espérant la bonne volonté du modèle :

• Les réglages d'autorisation : la plupart des outils permettent de configurer quelles commandes et quels fichiers demandent votre confirmation, lesquels sont interdits. Claude Code, par exemple, accepte des règles d'interdiction dans ses réglages ; Codex propose un bac à sable en lecture seule ou limité à l'écriture dans l'espace de travail.
• Les hooks : certains outils exécutent automatiquement vos scripts à des moments précis, par exemple formater après chaque modification de fichier, ou vérifier avant chaque commande qu'elle n'est pas dangereuse. Un hook est exécuté par le programme, sans dépendre du jugement du modèle.
• git et la revue de code : toutes les modifications de l'IA passent par un commit git, que vous relisez avant de fusionner. C'est le dernier contrôle, et le plus fiable.

En une phrase : le fichier de règles dit à l'IA « comment mieux faire », les mécanismes contraignants garantissent « ce qui ne doit jamais arriver ».

Partir d'un fichier vide

N'écrivez pas d'emblée un gros fichier de règles exhaustif. Mieux vaut :

1. Générer un premier jet avec la commande d'initialisation de l'outil. Claude Code et Codex ont tous deux une commande /init, qui analyse votre projet et écrit les informations de base comme les commandes de build et la structure des dossiers.
2. Supprimer ce que l'IA apprend en lisant le code, et ajouter ce qu'elle ignore : conventions d'équipe, pièges déjà rencontrés.
3. Ensuite, chaque fois que l'IA commet la même erreur une deuxième fois, ou que vous vous surprenez à réexpliquer la même chose dans la conversation, ajouter une ligne au fichier.

Un fichier de règles, comme un jeu d'évaluation, grandit peu à peu avec l'usage.

Exercices

1. Écrivez un AGENTS.md (ou CLAUDE.md) pour l'un de vos projets, en 50 lignes au plus. Relisez-le ensuite avec la section « Ce qu'il ne faut pas écrire » de cette leçon et supprimez ce qui doit l'être.
2. Trouvez une règle que vous voulez voir strictement respectée par l'IA (par exemple « ne jamais modifier le dossier migrations »), et cherchez si votre outil de programmation IA permet d'en faire une limite contraignante, plutôt que de l'écrire seulement dans le fichier de règles.
3. Écrivez un AGENTS.md pour RepoBot v4 de ce cours. Réfléchissez : qu'est-ce qu'un outil de programmation IA qui ouvre ce projet pour la première fois a le plus besoin de savoir ?

Auto-test

1. Le projet a déjà un AGENTS.md. Comment faire lire le même contenu à Claude Code ?

Claude Code lit CLAUDE.md, pas AGENTS.md. Selon la documentation officielle, on crée un CLAUDE.md contenant une ligne @AGENTS.md pour l'inclure, sous laquelle on peut ajouter du contenu propre à Claude Code ; si aucun contenu supplémentaire n'est nécessaire, on peut aussi créer un lien symbolique vers AGENTS.md.

2. Le fichier de règles dit « ne modifie pas le fichier .env ». Est-ce une garantie que l'IA ne le modifiera pas ?

Non. Le fichier de règles est transmis au modèle comme contexte ; il s'efforce de le respecter, sans garantie. Ce qui est vraiment interdit doit être limité par des mécanismes contraignants comme les réglages d'autorisation et les hooks, et chaque modification doit être relue via git.

3. Qu'est-ce qui mérite le plus de figurer dans un fichier de règles, et qu'est-ce qui doit le moins y figurer ?

Le plus utile : les informations que l'IA ne peut pas deviner et dont elle a besoin à chaque fois, comme la façon de construire et de tester (commandes précises), les conventions propres au projet et les pièges déjà rencontrés. À éviter absolument : ce que l'IA apprend en lisant le code, les principes vagues invérifiables, et toute clé ou mot de passe.