Ce qu’un repository doit dire à un agent IA

Un repository « agent-friendly » n’est pas un repository qui contient énormément de documentation. C’est un repository dans lequel un nouvel agent peut répondre rapidement à quelques questions simples : où suis-je, qu’est-ce qui est vrai aujourd’hui, quelles règles dois-je respecter, qu’est-ce qui reste à décider et où dois-je regarder pour cette tâche précise ?

J’ai longtemps eu le réflexe inverse : plus un projet grossissait, plus j’ajoutais du contexte dans un gros fichier racine. C’est rassurant, parce que l’on a l’impression que rien ne peut être oublié. En pratique, on finit surtout par forcer chaque nouvelle session à relire des choix anciens, des idées jamais retenues et des détails qui ne concernent pas la mission du jour.

Le problème n’est donc pas « comment documenter tout le projet ? ». Le problème est : comment transformer le repository en mémoire opérationnelle du projet, capable de grandir sans devenir lui-même une source de confusion ?

Un repository n’est pas forcément un repository de code

Le mot repository fait penser à src/, tests, packages et CI. Pourtant la logique fonctionne tout aussi bien pour un projet de recherche, une formation, un univers narratif, une documentation produit, un audit ou une collection de notes.

Ce qui justifie le repository n’est pas la présence de code. C’est le besoin de conserver :

• un état courant ;
• des décisions ;
• des règles et standards ;
• des contenus ou livrables versionnés ;
• des idées encore incertaines ;
• une file de travail ;
• un historique consultable ;
• des sources de vérité que plusieurs humains ou agents peuvent reprendre.

Un projet documentaire peut donc ressembler à ceci :

repo/
├── AGENTS.md
├── CURRENT.md
├── DECISIONS.md
├── BACKLOG.md
├── README.md
├── docs/
│   ├── standards/
│   └── research/
├── content/
└── sources/

Un projet logiciel peut ajouter :

├── src/
├── tests/
├── scripts/
└── package.json

La couche de continuité reste presque la même. Le code est simplement un type d’artefact supplémentaire.

La structure cible

Pour la majorité de mes projets, je pars aujourd’hui d’une structure proche de celle-ci :

repo/
├── AGENTS.md
├── CURRENT.md
├── DECISIONS.md
├── README.md
├── BACKLOG.md             # ou docs/backlog/ si le volume le justifie
├── docs/
│   ├── product.md
│   ├── design.md
│   ├── engineering.md
│   ├── standards/
│   └── domains/
│       ├── billing.md
│       └── content.md
├── content/               # optionnel
├── sources/               # optionnel
├── src/                   # optionnel
└── ...

Tous ces fichiers ne sont pas obligatoires. La logique importante est la séparation des responsabilités :

• AGENTS.md route ;
• CURRENT.md décrit le présent ;
• DECISIONS.md conserve les arbitrages durables ;
• BACKLOG.md ou docs/backlog/ conserve ce qui mérite encore d’être examiné ou fait ;
• README.md explique le projet à un humain ;
• docs/ porte les contrats et standards qui ont réellement besoin d’une source de vérité ;
• content/, sources/ ou src/ portent les artefacts du projet.

Un petit projet peut très bien commencer avec seulement AGENTS.md, CURRENT.md, README.md et son contenu. Les autres documents apparaissent lorsque le coût de reconstruction devient supérieur au coût de maintenance.

AGENTS.md : le routeur, pas l’encyclopédie

Le rôle d’AGENTS.md est souvent mal compris. Ce fichier ne devrait pas contenir tout ce qu’un agent doit savoir sur le produit. Il doit surtout expliquer comment trouver l’information utile et quelles règles de travail sont incontournables.

J’y mets généralement cinq choses :

1. l’ordre de lecture initial ;
2. la carte des sources de vérité ;
3. les standards transverses à charger selon le type de tâche ;
4. les règles de mise à jour du repository ;
5. la définition minimale de « terminé ».

Un exemple de début peut ressembler à ceci :

1. Lire CURRENT.md pour connaître l’état actif.
2. Lire docs/engineering.md avant toute modification technique.
3. Lire docs/content-standard.md avant toute modification éditoriale.
4. Lire DECISIONS.md seulement si la tâche touche un arbitrage durable.
5. Lire les docs du domaine concerné, pas tout le dossier docs/.

Ce format donne une stratégie de lecture. Il évite la phrase beaucoup plus coûteuse : « Lis tous les fichiers suivants avant de commencer. »

Ce qui ne devrait pas vivre dans AGENTS.md

Je n’y mets pas :

• l’historique détaillé du projet ;
• le backlog complet ;
• toutes les décisions produit ;
• la documentation de chaque module ;
• des résumés recopiés depuis d’autres fichiers ;
• les détails d’une mission temporaire ;
• chaque idée nouvelle découverte pendant le travail.

Si AGENTS.md devient un manuel de plusieurs dizaines de pages, il perd précisément son intérêt : chaque tâche repaie le coût de tout le contexte.

CURRENT.md : la photo du projet aujourd’hui

CURRENT.md répond à une autre question : si je reprends ce projet maintenant, où en est-il réellement ?

J’y garde par exemple :

• l’objectif actif ;
• l’état réellement livré ;
• le gate ou la phase actuelle ;
• les derniers éléments validés ;
• les principaux blockers ;
• la prochaine action recommandée.

Dans un projet sans code, la logique est identique. CURRENT.md peut dire qu’un audit est terminé, qu’un plan de formation est validé, que trois chapitres restent à écrire ou qu’une hypothèse est encore ouverte.

Ce fichier est volontairement mutable. Lorsqu’un chantier est terminé, on ne conserve pas tous ses détails « pour l’historique ». Git fait déjà ce travail.

Une bonne règle est la suivante : CURRENT doit pouvoir être corrigé sans sentiment de perte. Si supprimer une phrase de CURRENT.md fait perdre une décision importante, cette décision n’était probablement pas au bon endroit.

DECISIONS.md : éviter de redécouvrir les mêmes arbitrages

DECISIONS.md conserve les choix que l’on ne veut pas refaire à chaque nouvelle session.

Exemples :

• « La V0 reste local-first tant que l’usage multi-device n’est pas validé. »
• « Le Workbench est séparé de la surface publique. »
• « Ce projet de recherche utilise les sources primaires comme référence ; les synthèses secondaires servent uniquement à l’orientation. »
• « Le cours vise des praticiens débutants ; les détails d’infrastructure avancée restent hors périmètre. »

Une décision utile contient idéalement :

• ce qui a été décidé ;
• pourquoi ;
• ce que cela exclut ou rend inutile ;
• éventuellement la condition qui permettrait de la rouvrir.

Le but n’est pas de produire des ADR formels pour chaque détail. Un simple paragraphe suffit souvent. Ce qui compte est que le futur agent n’ait pas à reconstituer l’arbitrage depuis une conversation ou vingt commits.

Idée, ticket, décision, règle : quatre objets différents

C’est probablement la distinction qui évite le plus de confusion dans un repository qui grandit.

Une idée signifie : « cela pourrait être intéressant ». Elle n’est pas encore une instruction.

Un ticket signifie : « il existe un travail ou une question suffisamment concrète pour être suivi ». Il peut encore être refusé, fusionné ou requalifié.

Une décision signifie : « nous avons arbitré ce point et cette réponse doit survivre à la session ».

Une règle ou un standard signifie : « cette manière de travailler s’applique désormais de façon répétée à une catégorie de tâches ».

Si une idée est ajoutée directement à AGENTS.md, le prochain agent peut la prendre pour une obligation. Si un ticket fermé reste la seule trace d’une décision importante, un autre agent devra rouvrir l’enquête. Si toutes les décisions deviennent des standards, le repo finit sous une gouvernance disproportionnée.

Je cherche donc à faire progresser l’information entre ces états plutôt qu’à tout ranger dans un seul backlog.

Triage des idées et des tickets

Le backlog ne doit pas être une poubelle chronologique où chaque pensée devient éternellement une tâche.

J’utilise une logique proche de :

INBOX → TRIAGED → READY → ACTIVE → DONE
            ↘ PARKED
            ↘ REJECTED

Inbox

Une idée, un bug observé, une question ou une opportunité peut entrer rapidement. À ce stade, on cherche surtout à ne pas perdre le signal.

L’entrée doit toutefois contenir un minimum de contexte :

Titre
Pourquoi cela mérite d’être regardé
Preuve / observation
Zone potentiellement concernée

« Ajouter de l’IA » n’est pas une idée exploitable. « Plusieurs utilisateurs recopient manuellement les mêmes données entre X et Y ; vérifier si une synchronisation ciblée supprime cette étape » est déjà beaucoup plus utile.

Triaged

Le triage décide ce que l’objet est réellement :

• bug confirmé ;
• amélioration ;
• question produit ;
• dette ;
• idée à garder pour plus tard ;
• doublon ;
• non-problème.

Il doit aussi répondre à une question souvent oubliée : est-ce que ce sujet mérite vraiment d’entrer dans la file de travail maintenant ?

Ready

Un ticket devient READY lorsque quelqu’un ou un agent peut raisonnablement l’exécuter sans redécouvrir le problème depuis zéro.

Il possède alors :

• un résultat observable ;
• les contraintes principales ;
• les sources de vérité concernées ;
• des critères d’acceptation ;
• les inconnues qui restent volontairement ouvertes.

Active

Limiter le nombre de sujets actifs évite qu’un repository donne l’impression que tout est prioritaire.

CURRENT.md peut pointer vers le ticket actif ou le gate en cours, sans recopier tout son contenu.

Done, Parked, Rejected

DONE signifie que le résultat est livré ou la question résolue. La connaissance durable doit alors être promue vers la bonne source : décision, standard, contrat, documentation ou contenu.

PARKED signifie que l’idée reste intéressante mais ne mérite pas d’occuper la file active.

REJECTED est parfois important : quelques lignes de raison empêchent de reproposer exactement la même fausse bonne idée trois semaines plus tard.

GitHub Issues ou backlog dans le repository ?

Il n’y a pas une seule bonne réponse. Je choisis selon le rôle du projet.

GitHub Issues fonctionne bien lorsque

• plusieurs personnes collaborent ;
• commentaires, assignation ou labels apportent de la valeur ;
• l’équipe utilise déjà GitHub comme cockpit ;
• les tickets ont une vie opérationnelle indépendante de la documentation.

Un backlog versionné dans le repo fonctionne bien lorsque

• le projet est surtout piloté par son propriétaire et des agents ;
• la reprise doit fonctionner même sans charger un outil externe ;
• les cartes ont besoin d’être reliées étroitement aux documents du repo ;
• le projet est documentaire ou de conception ;
• on veut que les changements de backlog suivent les commits.

Un format léger peut tenir dans BACKLOG.md. Quand le volume augmente :

docs/backlog/
├── README.md
└── cards/
    ├── P-001.md
    ├── P-002.md
    └── P-003.md

La règle importante est de ne pas maintenir le même ticket à la fois dans GitHub Issues, un backlog Markdown et CURRENT.md. Choisir un propriétaire ; les autres surfaces pointent vers lui.

Faire évoluer les règles et standards

Un repository intelligent ne se contente pas de conserver ses règles initiales. Il doit pouvoir apprendre de ses propres problèmes sans transformer chaque incident en procédure éternelle.

Je distingue quatre niveaux.

1. Observation

Un problème apparaît : un agent crée des fichiers v2.css, une note publique redevient trop courte, un type de ticket manque systématiquement de critères d’acceptation.

On capture d’abord l’observation. Il est souvent trop tôt pour créer une règle générale.

2. Décision

On comprend la cause et on choisit une réponse : « l’historique appartient à Git ; les fichiers actifs ne portent pas de suffixe de version ».

Cette décision peut vivre dans DECISIONS.md si le pourquoi doit survivre.

3. Standard

Si la règle concerne une classe entière de travaux futurs, elle possède un propriétaire clair :

docs/standards/engineering.md
docs/standards/content.md
docs/standards/research.md

AGENTS.md ne recopie pas le standard : il explique quand le charger.

4. Garde-fou automatisé

Quand une règle est objective et peu coûteuse à vérifier, le meilleur rappel est parfois un test.

Exemples :

• interdire les feuilles de style nommées v2.css ou fixes.css ;
• vérifier qu’une note publique possède un minimum de structure ;
• s’assurer qu’un schéma respecte certaines contraintes ;
• valider des liens internes ou des métadonnées obligatoires.

L’automatisation ne remplace pas un standard éditorial ou une revue humaine. Elle protège seulement les invariants suffisamment mécaniques.

Le cycle devient donc :

problème observé
→ décision
→ standard si répétable
→ contrôle automatique si vérifiable

C’est beaucoup plus robuste que d’ajouter sans cesse de nouvelles phrases à AGENTS.md.

Comment modifier un standard existant

Une règle durable ne doit pas être traitée comme un texte sacré.

Lorsqu’un standard évolue :

1. identifier la preuve ou la nouvelle contrainte qui justifie le changement ;
2. modifier la source propriétaire ;
3. supprimer ou réécrire l’ancienne règle devenue fausse ;
4. mettre à jour les contrôles automatisés concernés ;
5. conserver le pourquoi dans une décision si le risque de redécouverte est réel ;
6. vérifier que AGENTS.md route toujours vers le bon document.

Je préfère cela à une succession de règles du type : « règle originale, sauf depuis août 2026, sauf dans tel cas ». Le document actif doit expliquer le système actuel. Git garde les anciennes versions.

Quand créer des documents de domaine

La vraie tentation, une fois cette structure comprise, est de créer immédiatement quinze fichiers sous docs/.

Je préfère partir de la question : est-ce que ce domaine possède assez de règles ou de décisions propres pour mériter une source de vérité séparée ?

Un document dédié devient pertinent lorsque plusieurs de ces conditions sont vraies :

• le domaine possède des invariants métier ou éditoriaux ;
• plusieurs artefacts en dépendent ;
• le sujet revient régulièrement dans des tâches différentes ;
• une erreur de compréhension coûte cher ;
• le contexte serait trop volumineux ou trop spécifique pour rester dans un document transversal.

Cela vaut pour du code, mais aussi pour une formation ou un projet de contenu. Une formation complexe peut avoir docs/standards/pedagogy.md. Un travail de recherche peut avoir docs/research-method.md. Un univers narratif peut avoir docs/world-rules.md.

La progressive disclosure en pratique

L’objectif de cette organisation est qu’un agent ne lise pas la même chose pour chaque mission.

Exemple : correction visuelle

Pour une correction responsive :

1. CURRENT.md ;
2. AGENTS.md ;
3. le standard design ;
4. le composant et ses styles.

Pas besoin de charger les décisions de base de données.

Exemple : écrire un nouveau chapitre de formation

1. CURRENT.md ;
2. AGENTS.md ;
3. le standard éditorial/pédagogique ;
4. le plan du cours ;
5. les sources nécessaires au chapitre.

Pas besoin de charger toute l’architecture du site qui publiera la formation.

Exemple : trier de nouvelles idées produit

1. CURRENT.md ;
2. la source propriétaire du backlog ;
3. les décisions produit utiles ;
4. éventuellement les preuves ou retours qui ont créé les idées.

L’objectif n’est pas encore d’ouvrir tous les fichiers d’implémentation. Le triage porte d’abord sur le problème et la priorité.

Le principe le plus important : une vérité, un propriétaire

La structure précédente ne sert à rien si la même information est répétée dans quatre endroits.

Imaginons qu’un projet soit local-first. Si cette règle apparaît dans :

• le README ;
• CURRENT.md ;
• DECISIONS.md ;
• une roadmap ;
• le prompt de chaque agent ;

alors le futur problème n’est plus de trouver l’information. C’est de savoir quelle copie est encore correcte.

J’essaie donc d’identifier le propriétaire de chaque vérité. Les autres documents peuvent pointer vers lui, mais pas maintenir une version parallèle.

Cette même règle s’applique aux idées : une carte backlog n’est pas un contrat produit. Une décision n’est pas automatiquement une tâche. Un standard n’est pas un historique.

Comment terminer une session proprement

La continuité se gagne surtout à la fin de la mission.

Avant de fermer une session, je pose cinq questions :

1. L’état courant a-t-il changé ? Mettre à jour CURRENT.md.
2. Une décision durable a-t-elle été prise ? L’enregistrer dans la bonne source.
3. Une nouvelle idée a-t-elle été découverte ? La capturer dans l’inbox/backlog, pas dans les règles actives.
4. Une règle générale a-t-elle réellement émergé ? Mettre à jour le standard propriétaire, et éventuellement un garde-fou.
5. Une information utile n’existe-t-elle encore que dans la conversation ? La condenser dans le repo.

Ce dernier point est crucial. Une conversation peut être très détaillée, mais si les décisions importantes ne retournent pas dans le repository, la prochaine session recommencera l’enquête.

Trois niveaux de maturité pour faire grandir la structure

Je ne démarre pas un petit repo avec vingt documents.

Niveau 1 — projet simple

repo/
├── AGENTS.md
├── CURRENT.md
├── README.md
└── content-or-src/

Cela suffit tant que les décisions sont peu nombreuses et que la file de travail reste évidente.

Niveau 2 — projet qui commence à durer

repo/
├── AGENTS.md
├── CURRENT.md
├── DECISIONS.md
├── BACKLOG.md
├── README.md
├── docs/
└── content-or-src/

Le projet possède maintenant une mémoire distincte de son état courant.

Niveau 3 — projet avec plusieurs domaines ou agents parallèles

repo/
├── AGENTS.md
├── CURRENT.md
├── DECISIONS.md
├── docs/
│   ├── backlog/
│   ├── standards/
│   ├── domains/
│   └── history/      # seulement si un historique hors Git apporte une vraie valeur
├── content-or-src/
└── tests-or-checks/

À ce niveau, l’objectif n’est toujours pas d’avoir plus de fichiers. L’objectif est que chaque nouvelle complexité obtienne un propriétaire clair.

Les anti-patterns que je rencontre le plus souvent

Le fichier racine géant

Tout est techniquement disponible, mais chaque mission paie le coût total du projet. Le nouvel agent a aussi du mal à distinguer règle actuelle et contexte historique.

La documentation miroir

README, CURRENT, roadmap et backlog répètent les mêmes informations avec quelques jours de décalage. Le problème devient la synchronisation des documents.

Le backlog qui devient une spécification

Une idée non triée finit écrite comme une exigence. Quelques semaines plus tard, un agent l’implémente simplement parce qu’elle est dans le repository.

AGENTS.md utilisé comme journal de corrections

Chaque problème rencontré ajoute une nouvelle règle à la fin du fichier. Au bout de vingt itérations, personne ne sait quelles règles sont générales, anciennes ou contradictoires.

L’historique comme source de vérité

Demander à un agent de relire systématiquement les commits pour comprendre l’état actuel est un signal que le repo ne possède plus de représentation fiable de son présent.

Git est excellent pour répondre à « comment en est-on arrivé là ? ». Il est beaucoup moins efficace pour répondre à « quelle est la règle aujourd’hui ? ».

La gouvernance spéculative

Créer une architecture complète de documentation avant d’avoir des décisions à documenter produit surtout des dossiers vides et des conventions que personne ne maintient.

Le handoff uniquement en conversation

Une mission peut très bien se terminer par un résumé dans le chat. Mais si le repo ne reçoit aucune mise à jour, ce résumé devient une dépendance invisible au prochain agent.

Checklist d’audit

Pour savoir si un repository est réellement reprenable et évolutif, je vérifie :

• Existe-t-il un point d’entrée évident pour un nouvel agent ?
• L’état courant peut-il être compris en quelques minutes ?
• Les décisions durables ont-elles un propriétaire identifiable ?
• Les idées non décidées sont-elles clairement séparées des règles actives ?
• Le backlog possède-t-il un vrai mécanisme de triage ?
• Un ticket READY contient-il assez d’information pour être exécuté sans enquête complète ?
• Les standards sont-ils séparés des décisions qui les ont fait naître ?
• Une règle objective importante peut-elle être protégée par un contrôle automatique ?
• Une tâche ciblée peut-elle éviter de charger la majorité de la documentation ?
• Les mêmes vérités sont-elles recopiées dans plusieurs fichiers ?
• L’historique Git est-il utilisé comme archive plutôt que comme manuel actif ?
• La fin d’une session remet-elle décisions, idées et état au bon endroit ?
• La structure reste-t-elle utilisable même si le projet ne contient aucun code ?

Si la réponse est oui à ces questions, le repo n’est pas seulement plus confortable pour un agent. Il devient un système de continuité du projet.

Ce que cette structure cherche vraiment à optimiser

On parle facilement d’économie de tokens, mais ce n’est pas mon objectif principal. Le vrai bénéfice est la continuité avec discernement.

Un bon repository agent-friendly permet de changer de session, d’outil ou de modèle sans perdre la logique du projet. Mais il permet aussi au projet d’apprendre : une observation peut devenir une idée, une idée un ticket, un ticket une décision, une décision un standard, et un standard suffisamment objectif un contrôle automatique.

C’est cette capacité d’évolution qui compte le plus. Le repository n’est plus seulement l’endroit où l’on stocke les fichiers. Il devient la mémoire structurée de ce que le projet sait, croit encore, a décidé et doit explorer ensuite.