How to give the agent your project's instructions (AGENTS.md)

 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
39
40
41
42
43
44
45
46
47
48
49
50
51
52

# How to give the agent your project's instructions (`AGENTS.md`)

This guide shows how to make mm follow the rules of the project it works in — how to build and test, what not to touch — without editing the agent's configuration. It assumes you already run `mm` in a project directory, or from an editor that opens one.

## Steps

1. Write an `AGENTS.md` at the root of the project — plain Markdown, no required section:

   ```markdown
   # Build and test
   - Tests run with `make check`, never with `go test` directly.

   # Conventions
   - Never edit files under `vendor/`.
   - Commit messages start with the ticket number.
   ```

2. Start mm **from that directory** (or open the project in your editor). The banner names the file and its size:

   ```
   mm … | yolo: on | agents.md: /home/me/project/AGENTS.md (~50 tokens)
   ```

   No configuration is needed: `agentsMd.enabled` is `true` by default.

3. Ask as usual. The file is part of the system prompt of the conversation; the model follows it unless you ask otherwise in the chat.

4. After editing `AGENTS.md`, type `/new` (or start a new session in the editor): the next conversation reads the new version. The current one keeps the version it started with.

## Variants

- **The file lives elsewhere in the project**: `agentsMd: {path: docs/AGENTS.md}`. A relative path is relative to the project directory, so one configuration serves every project.
- **Turn it off for one agent**: `agentsMd: {enabled: false}` in that agent's file. For an agent called by another one (`ask_agent`, `/ask`, `mm --ask`), only the called agent's own setting counts.
- **A long file on a small model**: the banner warns when the file takes 20 % of the context window or more. Shorten it, or set `agentsMd: {maxChars: 8000}` — above the limit, the file is not read at all (the banner says `skipped (too long)`); it is never cut in the middle.
- **In an editor (ACP)**: each session reads the `AGENTS.md` of the project it was opened in; the banner, printed before any session exists, shows `agents.md: <session cwd>/AGENTS.md`.
- **A JSON agent** (`structuredOutput`) never reads the file; the banner shows `agents.md: ignored (structured output)`.

## Check what the model received

Turn the trace on and read the system message of the first request:

```bash
AGENT_TRACE=true mm agent.yaml -p "How do I run the tests here?"
jq -r '.messages[0].content' .mm/traces/*-0001.request.json
```

The file appears after the `system` prompt, under `PROJECT INSTRUCTIONS (from <path>)`. See [How to see the JSON sent to the model](inspect-model-traffic.md).

## See also

- [`agentsMd` reference](../reference/configuration.md#agentsmd-keys) — the keys, what is and is not read
- [Project instructions — explanation](../explanation/project-instructions.md) — why it joins the prompt this way, and when it is read