Consignes du projet (`AGENTS.md`) — explication

De quoi s'agit-il ?

La configuration d'un agent dit ce qu'est l'agent : son nom, ses outils, sa façon de modifier les fichiers. Elle ne peut pas dire comment chaque projet où il travaille se compile, se teste ou s'organise — un même agent.yaml sert pour beaucoup de projets. AGENTS.md (https://agents.md) est la convention que partagent les agents de code pour cela : un simple fichier Markdown à la racine d'un dépôt, écrit pour les agents. mm le lit dans le répertoire où travaille une conversation et l'ajoute au prompt système (ticket 81).

Pourquoi il est ajouté au prompt système

Le fichier suit le prompt system de la configuration, sous un titre qui nomme son origine — PROJECT INSTRUCTIONS (from <chemin>) — et ne le remplace jamais : les deux répondent à des questions différentes, et l'agent a besoin des deux. Le titre indique au modèle que ces règles viennent du projet, pas de son rôle, ce qui l'aide quand elles divergent (un agent à qui l'on demande de répondre en anglais, un projet dont les commentaires sont en français).

Un premier message utilisateur (« voici les consignes du projet ») a été écarté : les petits modèles locaux accordent plus de poids au message système, et certains templates de chat (Gemma, Mistral) refusent deux tours utilisateur d'affilée. Le même mécanisme porte déjà le paragraphe OUTPUT FORMAT de structuredOutput.

Pourquoi il est lu par conversation, pas par question

Le fichier est lu quand une conversation commence — au démarrage, sur /new, sur /resume, pour une session d'éditeur nouvelle ou rechargée — et plus jusqu'à la suivante. Le relire avant chaque question prendrait une modification plus tôt en compte, mais un message système qui change en cours de conversation oblige le serveur à relire tout l'historique : llama.cpp garde en cache le début du prompt déjà traité, et le message système en est la première partie (le même cache que le ticket 53 protège en gardant les outils dans un ordre stable). Sur une longue conversation locale, ce sont des minutes par question. Une version par conversation garde le cache ; /new est le moyen de prendre une modification en compte.

/resume suit la règle que mm appliquait déjà au prompt system : une conversation reprise continue sous le prompt actuel de l'agent, elle reçoit donc aussi le fichier actuel. Une session reprise est de toute façon relue en entier par le serveur, cela ne coûte rien.

Pourquoi le répertoire de travail, et lui seul

Le répertoire de travail, c'est le projet : le répertoire où tourne mm, ou le cwd qu'un éditeur donne à chaque session. Chaque session ACP lit donc le fichier de son propre projet, et un agentsMd.path relatif est résolu là, jamais à côté du fichier de configuration — sinon un même agent.yaml lirait le même fichier dans tous les projets.

La convention autorise aussi des fichiers imbriqués dans un monorepo, le plus proche l'emportant. mm ne remonte pas jusqu'à la racine du dépôt et ne concatène pas de fichiers : un fichier, un endroit, un comportement prévisible.

Pourquoi un avertissement plutôt qu'une coupe

Le message système part avec chaque requête et occupe la fenêtre de contexte pendant toute la conversation. Quelques pages d'AGENTS.md ne sont rien pour un modèle cloud, et la moitié de la fenêtre d'un modèle 4B servi avec 16k tokens. mm le mesure — la même estimation que la compression du contexte, les caractères divisés par 3,5 — et avertit à partir de 20 % d'une fenêtre connue. Il ne le coupe pas : une troncature garde le début et laisse tomber la fin en silence, qui peut contenir la seule règle qui comptait, pendant que le modèle croit avoir tout lu. agentsMd.maxChars existe pour qui veut une limite ferme ; au-delà, le fichier est laissé de côté en entier et la bannière le dit — un fichier absent est un état que l'utilisateur voit, un fichier à moitié lu ne l'est pas.

Les agents qui ne le lisent pas

Les agents JSON (structuredOutput) : des consignes en prose (« termine chaque réponse par une signature ») contrediraient la contrainte JSON, et une signature ajoutée au JSON casserait tout script qui le lit. La bannière mentionne le fichier ignoré de façon neutre, puisque c'est voulu.
Les agents appelés par un autre (/ask, ask_agent, mm --ask) : ils tournent comme leur propre processus mm avec leur propre configuration, et ne lisent le fichier du répertoire de travail qu'on leur donne que si leur propre agentsMd.enabled le dit. Un relecteur sans outils peut le désactiver ; un assistant de code le garde et suit les mêmes règles que l'agent qui l'a appelé.

Liens avec le reste

Sortie structurée — l'autre paragraphe que mm ajoute au prompt système.
Interroger un autre agent — le répertoire de travail que reçoit un agent interrogé.
Comment donner à l'agent les consignes de votre projet et la référence de agentsMd.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


# Consignes du projet (`AGENTS.md`) — explication

## De quoi s'agit-il ?

La configuration d'un agent dit ce qu'est l'agent : son nom, ses outils, sa façon de modifier les fichiers. Elle ne peut pas dire comment chaque projet où il travaille se compile, se teste ou s'organise — un même `agent.yaml` sert pour beaucoup de projets. `AGENTS.md` (https://agents.md) est la convention que partagent les agents de code pour cela : un simple fichier Markdown à la racine d'un dépôt, écrit pour les agents. mm le lit dans le répertoire où travaille une conversation et l'ajoute au prompt système (ticket 81).

## Pourquoi il est ajouté au prompt système

Le fichier suit le prompt `system` de la configuration, sous un titre qui nomme son origine — `PROJECT INSTRUCTIONS (from <chemin>)` — et ne le remplace jamais : les deux répondent à des questions différentes, et l'agent a besoin des deux. Le titre indique au modèle que ces règles viennent du projet, pas de son rôle, ce qui l'aide quand elles divergent (un agent à qui l'on demande de répondre en anglais, un projet dont les commentaires sont en français).

Un premier message utilisateur (« voici les consignes du projet ») a été écarté : les petits modèles locaux accordent plus de poids au message système, et certains templates de chat (Gemma, Mistral) refusent deux tours utilisateur d'affilée. Le même mécanisme porte déjà le paragraphe `OUTPUT FORMAT` de `structuredOutput`.

## Pourquoi il est lu par conversation, pas par question

Le fichier est lu quand une conversation commence — au démarrage, sur `/new`, sur `/resume`, pour une session d'éditeur nouvelle ou rechargée — et plus jusqu'à la suivante. Le relire avant chaque question prendrait une modification plus tôt en compte, mais un message système qui change en cours de conversation oblige le serveur à relire tout l'historique : llama.cpp garde en cache le début du prompt déjà traité, et le message système en est la première partie (le même cache que le ticket 53 protège en gardant les outils dans un ordre stable). Sur une longue conversation locale, ce sont des minutes par question. Une version par conversation garde le cache ; `/new` est le moyen de prendre une modification en compte.

`/resume` suit la règle que mm appliquait déjà au prompt `system` : une conversation reprise continue sous le prompt actuel de l'agent, elle reçoit donc aussi le fichier actuel. Une session reprise est de toute façon relue en entier par le serveur, cela ne coûte rien.

## Pourquoi le répertoire de travail, et lui seul

Le répertoire de travail, c'est le projet : le répertoire où tourne `mm`, ou le `cwd` qu'un éditeur donne à chaque session. Chaque session ACP lit donc le fichier de son propre projet, et un `agentsMd.path` relatif est résolu là, jamais à côté du fichier de configuration — sinon un même `agent.yaml` lirait le même fichier dans tous les projets.

La convention autorise aussi des fichiers imbriqués dans un monorepo, le plus proche l'emportant. mm ne remonte pas jusqu'à la racine du dépôt et ne concatène pas de fichiers : un fichier, un endroit, un comportement prévisible.

## Pourquoi un avertissement plutôt qu'une coupe

Le message système part avec chaque requête et occupe la fenêtre de contexte pendant toute la conversation. Quelques pages d'`AGENTS.md` ne sont rien pour un modèle cloud, et la moitié de la fenêtre d'un modèle 4B servi avec 16k tokens. mm le mesure — la même estimation que la compression du contexte, les caractères divisés par 3,5 — et avertit à partir de 20 % d'une fenêtre connue. Il ne le coupe pas : une troncature garde le début et laisse tomber la fin en silence, qui peut contenir la seule règle qui comptait, pendant que le modèle croit avoir tout lu. `agentsMd.maxChars` existe pour qui veut une limite ferme ; au-delà, le fichier est laissé de côté en entier et la bannière le dit — un fichier absent est un état que l'utilisateur voit, un fichier à moitié lu ne l'est pas.

## Les agents qui ne le lisent pas

- **Les agents JSON** (`structuredOutput`) : des consignes en prose (« termine chaque réponse par une signature ») contrediraient la contrainte JSON, et une signature ajoutée au JSON casserait tout script qui le lit. La bannière mentionne le fichier ignoré de façon neutre, puisque c'est voulu.
- **Les agents appelés par un autre** (`/ask`, `ask_agent`, `mm --ask`) : ils tournent comme leur propre processus `mm` avec leur propre configuration, et ne lisent le fichier du répertoire de travail qu'on leur donne que si leur propre `agentsMd.enabled` le dit. Un relecteur sans outils peut le désactiver ; un assistant de code le garde et suit les mêmes règles que l'agent qui l'a appelé.

## Liens avec le reste

- [Sortie structurée](structured-output.md) — l'autre paragraphe que mm ajoute au prompt système.
- [Interroger un autre agent](asking-another-agent.md) — le répertoire de travail que reçoit un agent interrogé.
- [Comment donner à l'agent les consignes de votre projet](../how-to/give-project-instructions.md) et la [référence de `agentsMd`](../reference/configuration.md#clés-de-agentsmd).

Consignes du projet (AGENTS.md) — explication