AGENTS.md et CLAUDE.md pour une base de connaissances

AGENTS.md et CLAUDE.md sont des fichiers markdown simples que les agents de code lisent avant de travailler dans un dossier. Dans une base de connaissances, c’est là que vous dites aux agents comment vos notes sont organisées et quelles règles chaque document doit suivre. Aucun des deux fichiers n’a de champs obligatoires ni de schéma : vous écrivez des instructions en markdown ordinaire.

Ce guide couvre d’abord l’installation manuelle. À côté de chaque partie, vous verrez ce qui change avec Knowtarium, notre base de connaissances chiffrée de bout en bout que les personnes et les agents écrivent ensemble, et les conventions qu’il transmet à chaque agent que vous connectez.

AGENTS.md

AGENTS.md est un format ouvert pour guider les agents de code, géré par l’Agentic AI Foundation sous l’égide de la Linux Foundation. De nombreux agents de code le lisent, dont OpenAI Codex et Cursor. Vous le placez à la racine de votre dossier, et vous pouvez en ajouter d’autres dans des sous-dossiers : l’AGENTS.md le plus proche du fichier modifié l’emporte, et ce que vous tapez dans le chat prime sur tous.

CLAUDE.md

CLAUDE.md est la version de Claude Code. D’après la documentation d’Anthropic, Claude Code le lit à plusieurs endroits, du plus large au plus précis :

Les organisations peuvent aussi déployer un CLAUDE.md géré. Les fichiers ne s’écrasent pas les uns les autres : Claude Code les met bout à bout, de la racine du système de fichiers jusqu’à l’endroit où vous l’avez lancé, si bien que les instructions les plus précises viennent en dernier. Les fichiers des sous-dossiers se chargent quand Claude lit un fichier de ce sous-dossier. Un CLAUDE.md peut intégrer d’autres fichiers avec @path/to/file, jusqu’à quatre niveaux de profondeur. Anthropic recommande de garder chaque fichier sous les 200 lignes.

Dans Knowtarium

Knowtarium ajoute des garde-fous qu’un fichier d’instructions ne peut pas offrir. Quoi qu’un agent fasse de vos règles, chaque changement qu’il fait est signé et peut être annulé en un clic, il ne supprime des documents que si vous lui en avez donné la permission, et il ne peut rien marquer comme vérifié par une personne. Dans les dossiers où vous activez la relecture, ses changements attendent sous forme de diffs jusqu’à ce que vous les approuviez.

(s’ouvre en grand dans un nouvel onglet) (s’ouvre en grand dans un nouvel onglet)

Si vous utilisez plusieurs agents, écrivez vos règles une seule fois dans AGENTS.md. Les versions récentes de Claude Code lisent AGENTS.md d’elles-mêmes quand il n’y a ni CLAUDE.md ni CLAUDE.local.md dans le dossier ou au-dessus (à partir de la v2.1.277). Si vous voulez aussi des instructions propres à Claude, ou si vous avez une version plus ancienne, créez à côté un CLAUDE.md qui l’importe :

@AGENTS.md
 
## Claude Code
 
- Travaille en mode plan pour tout changement qui touche plus de trois documents.

Claude lit d’abord l’AGENTS.md importé, puis les lignes qui suivent. Tous les autres agents lisent AGENTS.md directement : les règles ne divergent donc jamais.

La plupart des exemples d’AGENTS.md sont écrits pour du code : commandes de build, tests, style. Une base de connaissances a besoin d’autres règles. Voici celles qui comptent le plus quand des agents écrivent une grande partie de vos notes.

L’organisation des dossiers

Dites à quoi sert chaque dossier de premier niveau et où vont les nouveaux documents. Sans cela, les agents inventent des dossiers, et deux agents rangent le même genre de note à deux endroits.

Les noms

Une notion par fichier, un seul schéma de nommage. Des noms datés pour les décisions et les réunions font que le dossier se trie tout seul.

Les liens

Choisissez un style de lien et dites-le. Les liens markdown standard marchent dans tous les outils ; les [[wikilinks]] seulement dans certains. Dites aux agents de mettre à jour les liens quand ils déplacent un fichier, et qu’un lien vers un document que personne n’a encore écrit est permis.

Un frontmatter pour la provenance et la fraîcheur

C’est la règle que la plupart des modèles oublient, et celle qui permet de vérifier plus tard une base de connaissances écrite par des agents. Exigez que chaque document dise qui l’a écrit et quand il se périme. L’Open Knowledge Format, une spécification ouverte publiée par Google Cloud, vous donne les noms de champs : type (le seul obligatoire), generated, verified, status, stale_after et sources. Utiliser un format publié signifie que tout outil qui lit OKF comprend vos notes.

La citation des sources

Exigez une source pour chaque chiffre, date, nom et citation, citée à côté de l’affirmation. Le guide pour faire citer leurs sources aux agents va plus loin.

Ce que les agents ne doivent jamais faire

Écrivez les lignes rouges sous forme de règles « Jamais » : ne jamais marquer quelque chose comme vérifié par une personne, ne jamais supprimer, ne jamais écraser la modification d’une personne. La documentation d’Anthropic note que des instructions précises et concises sont suivies plus régulièrement que des instructions générales.

Comment noter une vérification

Quand un agent confirme un document, il doit le dire d’une façon fixe : sa propre entrée dans verified, avec un horodatage. N’importe qui peut alors distinguer la vérification d’un agent de celle d’une personne.

Dans Knowtarium

Dans les dossiers où la relecture est activée, Knowtarium transforme ces entrées en niveau de confiance. L’entrée d’un agent rend un document machine-confirmed, la vôtre le rend human-reviewed, et les deux après le dernier changement le rendent fully verified. Quand vous y approuvez le changement d’un agent, l’application écrit votre entrée pour vous.

(s’ouvre en grand dans un nouvel onglet) (s’ouvre en grand dans un nouvel onglet)

Copiez ceci dans AGENTS.md à la racine de votre dossier de notes, puis adaptez la liste des dossiers aux vôtres. Il reste largement sous la limite de 200 lignes recommandée par Anthropic.

---
type: Instructions
title: Règles pour les agents
---
 
# Base de connaissances : règles pour les agents
 
Ce dossier est une base de connaissances que des personnes et des agents écrivent ensemble.
Chaque fichier est du markdown simple avec un frontmatter YAML (OKF v0.2).
Lis ce fichier en entier avant de changer quoi que ce soit.
 
## Organisation
 
- Le index.md de chaque dossier liste ce que contient le dossier. Lis-le en premier.
- log.md note ce qui a changé, le plus récent en premier. Ajoute une ligne à chaque session.
- company/     mission, glossaire, notre façon de travailler
- customers/   segments, interviews/ (un fichier par entretien)
- metrics/     un fichier par indicateur ; computations/ pour les requêtes approuvées
- decisions/   un fichier par décision, nommé YYYY-MM-DD-short-title.md
- references/  copies des sources que tu cites (PDF, CSV, pages enregistrées)
- Ne crée jamais de nouveau dossier de premier niveau. Demande d’abord.
 
## Trouver les choses
 
- Pars du index.md racine et suis les liens. Ne lis pas tous les fichiers.
- Cherche avant d’écrire. Si un document existe sur le sujet, mets-le à jour.
 
## Noms
 
- Une notion par fichier. Les noms de fichiers sont en minuscules-avec-tirets.md.
- index.md et log.md sont réservés. Ne les utilise jamais pour un document.
 
## Liens
 
- Utilise des liens markdown standard, jamais des [[wikilinks]].
- Fais les liens depuis la racine du paquet : [Churn](/metrics/churn.md).
- Un lien vers un document qui n’existe pas encore, c’est permis. Ne crée pas
  un fichier vide juste pour réparer le lien.
- Quand tu renommes ou déplaces un fichier, mets à jour tous les liens qui y mènent.
 
## Frontmatter
 
Chaque document commence par un frontmatter. Garde les clés que tu ne connais pas
exactement telles quelles.
 
```yaml
---
type: Metric                # obligatoire : Metric, Decision, Interview, ...
title: Churn
description: Une phrase, utilisée dans index.md et dans la recherche.
status: stable              # draft | stable | deprecated
generated: { by: <ton-nom>/<version>, at: <heure UTC, ISO 8601> }
stale_after: <heure UTC>    # à partir de quand on ne peut plus le citer sans risque
sources:
  - id: billing-export
    resource: /references/billing-2026-09.csv
    title: Export de facturation, septembre 2026
---
```
 
- Signe dans `generated` chaque document que tu écris ou modifies.
  Mets à jour `generated.at` à chaque changement significatif.
- Renseigne `stale_after` : 90 jours pour les indicateurs, 1 an pour les décisions.
- Les nouveaux documents commencent en `status: draft`.
 
## Sources
 
- Chaque chiffre, date, nom et citation a besoin d’une source.
- Ajoute la source à `sources` avec un `id` court et stable, puis cite-la
  après l’affirmation par une note de bas de page : Le churn est tombé à 2,4 %.[^billing-export]
- Ne cite qu’une source que tu as ouverte pendant cette session. N’invente jamais d’URL.
- Si tu ne trouves pas de source, écris l’affirmation sous
  « ## Open questions » au lieu de la présenter comme un fait.
 
## Vérifier la modification d’une personne
 
- Lis le changement, puis chaque document qui pointe vers lui ou partage
  une source avec lui.
- Si tout concorde encore, ajoute-toi à `verified` :
  - { by: <ton-nom>/<version>, at: <heure UTC> }
- Si quelque chose ne concorde plus, propose la correction. Ne l’applique pas en silence.
 
## Jamais
 
- N’ajoute jamais d’entrée `human:` à `verified`. Seule une personne le fait.
- Ne supprime ni ne réordonne jamais les entrées `verified` de quelqu’un d’autre.
- Ne supprime jamais un document. Mets `status: deprecated` et explique pourquoi.
- N’écrase jamais la modification d’une personne. Si tu n’es pas d’accord, dis-le et arrête-toi.
- Ne modifie jamais les fichiers de references/. Ce sont les preuves.
 
## Quand tu as fini
 
- Ajoute une entrée datée à log.md.
- Liste tous les fichiers que tu as créés, modifiés, déplacés ou dépréciés.

Remplacez les durées de conservation sous Frontmatter par les vôtres. OKF compte chaque fichier .md comme un document, sauf index.md et log.md : le modèle commence donc par son propre frontmatter et un type pour que le paquet reste valide. L’exemple de bloc de frontmatter à l’intérieur est là pour que les agents le copient.

Certaines règles ne comptent qu’à un endroit. Avec AGENTS.md, mettez un deuxième fichier dans ce dossier, comme metrics/AGENTS.md ; les agents utilisent le plus proche. Claude Code a aussi des règles limitées à certains chemins : des fichiers markdown dans .claude/rules/ avec un champ paths, chargés seulement quand Claude lit un fichier correspondant.

---
paths:
  - "metrics/**/*.md"
---
 
# Indicateurs
 
- Chaque indicateur pointe vers la requête qui le calcule dans metrics/computations/.
- Ne change jamais un chiffre sans nouvelle entrée de source.

Cela garde le fichier racine court. La documentation d’Anthropic prévient que des fichiers d’instructions plus longs consomment plus de contexte et sont moins bien suivis.

Dans Claude Code, lancez /context et regardez sous Memory files pour confirmer que votre fichier est chargé. Avec n’importe quel agent, commencez une session en lui demandant de reformuler les règles pour écrire un nouveau document. S’il n’y arrive pas, le fichier n’est pas lu ou il est trop long.

Vérifiez ensuite le résultat, pas la promesse. Deux grep repèrent les écarts les plus courants :

# documents sans type : le seul champ OKF obligatoire
$ grep -rL "^type:" --include="*.md" . | grep -v -e "/index.md$" -e "/log.md$"
 
# wikilinks qui se sont glissés
$ grep -rn "\[\[" --include="*.md" .

Quand la même erreur revient deux fois, ajoutez une règle pour elle. C’est aussi le conseil d’Anthropic pour CLAUDE.md : écrivez ce que vous auriez sinon à expliquer de nouveau.

Knowtarium inclut un skill de conventions que chaque agent que vous connectez reçoit avec ses outils (Claude Code, Codex, Cursor, Claude Desktop et d’autres) : vous n’avez pas à écrire les conventions d’une base de connaissances Knowtarium dans chaque fichier d’instructions.

Ce qu’il enseigne

• Lire d’abord l’index propre à l’espace de travail. Quand il a un index.md, le lire et suivre ses liens au lieu de charger chaque document.
• Lire avant d’écrire. Les titres et les descriptions avant les documents entiers, et chaque changement indique la version sur laquelle il s’appuie : un agent ne peut donc pas écraser une modification qu’il n’a pas lue.
• Savoir comment un changement arrive. Dans la plupart des dossiers, un changement est enregistré aussitôt et peut être annulé, donc mieux vaut être prudent ; dans les dossiers où la relecture est activée, il attend une approbation. Dans les deux cas, dire à la personne lequel des deux.
• Vérifier après la modification d’une personne. Dans les dossiers où la relecture est activée, lire les documents liés, enregistrer la vérification si tout concorde encore, et signaler un conflit si quelque chose ne concorde plus.

Comment il s’articule avec votre AGENTS.md

Dans Knowtarium, votre AGENTS.md est l’ensemble d’instructions du dossier : écrivez-le dans l’application, et les agents le reçoivent avec chaque note qu’ils y écrivent.

Certaines règles ne dépendent pas de la lecture d’un fichier. Dans Knowtarium, chaque changement d’un agent est signé avec sa propre clé, les agents ne suppriment des documents que si vous leur en avez donné la permission, ils ne peuvent rien marquer comme vérifié par une personne, et dans les dossiers où la relecture est activée, ils ne peuvent pas passer outre votre relecture. Un agent n’atteint que l’espace de travail et les dossiers auxquels vous l’avez connecté. L’application n’appelle aucune IA elle-même : quand vous voulez faire vérifier vos modifications, vous le demandez à votre agent, et il suit le skill.

Les agents se connectent via MCP avec npx knowtarium connect, avec le plugin Knowtarium dans Claude Code et Codex (il inclut le skill), avec l’extension dans Claude Desktop, ou en un clic pour Cursor et VS Code. Les connecteurs pour les applications de chat comme claude.ai et ChatGPT viendront plus tard. Voir comment les agents travaillent avec Knowtarium.