# AGENTS.md starter

Version: 1.0
Updated: 2026-10-02
Method: https://suhailmohebi.com/notes/the-toolbench/

Purpose: give every coding agent in a repository the same short, testable house rules from one canonical file.

Output: an AGENTS.md of at most ~150 lines with exact commands, workflows, boundaries and a done check, read by each tool natively or through one pointer.

## Use when

Several agents or tools share one repository, an agent repeats a mistake a teammate would not, or tool instruction files have drifted.

## Quick start

1. Copy the skeleton in section 2 to `AGENTS.md` at the repository root and replace every [bracket].
2. Run one representative task three times with and three times without the file (section 3); keep only what changed the result.
3. Point every other tool at this file (section 5). Copy it only for a tool that can neither read nor import it, and regenerate that copy after every edit.

One fact, one owner: a rule restated in several files will eventually be wrong in one of them.

## 1. What belongs

| Put in AGENTS.md | Leave out, or move to a reference file |
|---|---|
| Exact build, test and lint commands | Architecture tours and decision history |
| Numbered workflows for the 2–3 most common tasks | Long lists of “don’t” with no matching “do” |
| One decision table where two patterns compete | Onboarding prose a README already covers |
| A few real code examples of 3–10 lines | Secrets, tokens, hostnames, personal preferences |
| Approval gates and secret handling | One package’s rules: use a nested AGENTS.md |

AGENTS.md is plain Markdown with no required fields; the nearest one to the edited file wins, and an explicit chat instruction overrides it. In Augment Code’s study, 100–150-line files with a few focused reference files did best; architecture sprawl and long warning lists caused over-exploration.

## 2. Copy-ready skeleton

```markdown
# AGENTS.md

[What this repository is, in one line.]
[Who uses its output and where it runs, in one line.]

## Commands
- Install: `[command]`; build: `[command]`
- Test all: `[command]`; one file: `[command with a file placeholder]`
- Lint and format: `[command]`

## Workflow: [common task; copy this section for each of the 2-3 most common tasks]
1. [Step naming the exact file, folder or command]
2. Run `[test command]` and fix failures before reporting.

## Decide before coding
| Question | [Option A] | [Option B] |
|---|---|---|
| [Condition that points to A] | yes | |
| [Condition that points to B] | | yes |

## Conventions
- Don't [anti-pattern]. Do [concrete alternative, with its path].

~~~[language]
[3-10 lines of real code showing the preferred pattern]
~~~

## Boundaries
- New session: read this file and the README, then summarise current state and risky areas before changing files.
- Without asking: read the repository except secret files ([.env*, key paths]), run the commands above, edit [paths].
- Ask first: commit, push, deploy, delete, publish, [add dependencies].
- Never: commit or print secrets; skip or weaken a failing check.
- Secrets: [environment variables or secret store], referred to by name only; also deny reads of secret files in the tool’s permission settings.

## Done means
- [ ] `[lint command]` and `[test command]` pass.
- [ ] [The changed behaviour was observed: page, endpoint or CLI output.]
- [ ] The report states what was not verified.

## Reference files (open only when the task needs them)
- `[docs/agents/topic.md]`: [when to read it, in one line]
```

## 3. Test whether it helps

1. Pick a recent task with a known-good result, such as a reviewed and merged change.
2. From the same base revision, run it three times without AGENTS.md and three times with it; compare every run with the known-good result.

| Run | Right commands | Workflow followed | Files read beyond need | Matches known-good |
|---|---|---|---|---|
| Without (3 runs) |  |  |  |  |
| With (3 runs) |  |  |  |  |

Record counts such as 2/3. Keep what changed the result in most runs and cut the rest; a difference seen in one run only is noise until it repeats. Repeat with a second task shape: one file can help a bug fix and hurt a feature.

## 4. Maintenance triggers

- An agent makes the same mistake twice, or a review catches something the file should have said.
- A command, path, tool, approval rule or preferred pattern in the file changes; stale patterns steer agents backwards.
- Two instruction files contradict each other, or the file passes ~150 lines or ~10–15 references.
- Any large edit: re-run the section 3 test and delete lines that no longer change behaviour.

## 5. One source for every tool

- **Tools that read `AGENTS.md` natively** (the agents.md site lists them, Codex and Cursor among them): nothing to add; confirm in each tool’s docs before adding a pointer.
- **Claude Code** (v2.1.277 or later) reads `AGENTS.md` directly only when no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` exists in the working directory or above it, and some sessions still read `CLAUDE.md` only (older versions, a disabled `agents-md` plugin, or the first session after an upgrade). If you keep a `CLAUDE.md`, or need those sessions covered, start a `CLAUDE.md` with an `@AGENTS.md` line and add Claude-only notes below; `/memory` lists what loaded. Claude Code also imports any `@path` outside backticks at launch, so keep reference paths in backticks.
- **Aider**: add `AGENTS.md` to `read:` in `.aider.conf.yml` (`read: AGENTS.md`, or `read: [AGENTS.md, CONVENTIONS.md]`).
- **Gemini CLI**: add `{ "context": { "fileName": "AGENTS.md" } }` to `.gemini/settings.json`; `["AGENTS.md", "GEMINI.md"]` loads both. Unpaid-tier and Google One users were moved to Antigravity CLI on 2026-06-18; it reads `AGENTS.md` without configuration.
- **A tool that reads only its own filename**: symlink it (`ln -s AGENTS.md [its-filename]`) when every clone is on macOS or Linux; Git on Windows checks a symlink out as a one-line text file unless `core.symlinks` is enabled. Otherwise use the tool’s import syntax, or a copy step you re-run after every edit to `AGENTS.md`.

## Worked example

A filled file for a small TypeScript web app; small projects need fewer lines:

```markdown
# AGENTS.md

Meeting-room booking web app: TypeScript single-page front end built with Vite.
CI deploys `main`; agents work on feature branches only.

## Commands
- Install: `npm ci`; dev server: `npm run dev`; build: `npm run build`
- Test all: `npm test` (`vitest run`); one file: `npm test -- src/lib/api.test.ts`
- Browser tests: `npm run test:e2e`; lint and types: `npm run lint && npm run typecheck`

## Workflow: add an API call
1. Add the function to `src/lib/api.ts` using `apiClient`; test it in `src/lib/api.test.ts`.
2. Call it from the page, handle loading and error states, then run the "Done means" checks.

## Workflow: fix a UI bug
1. Reproduce it in `npm run dev` and write a failing test (see the table below).
2. Fix it, run the "Done means" checks, then check the page at mobile and desktop widths.

## Decide before coding
| Question | Unit test (`*.test.ts`) | Browser test (`e2e/`) |
|---|---|---|
| Pure function or one module? | yes | |
| Needs routing or a real browser? | | yes |

## Conventions
- Don't call `fetch` in components. Do use `apiClient` from `src/lib/api.ts`.
- Don't edit `src/generated/`. Do edit `schema/api.yaml`, then run `npm run generate`.

~~~ts
export function getRoom(id: string) {
  return apiClient.get<Room>("/rooms/" + id);
}
~~~

## Boundaries
- Without asking: read the repository except `.env` files, run the commands above, edit `src/` and `e2e/`.
- Ask first: commit, push, deploy, delete files or branches, add dependencies.
- Never: commit `.env` or print secrets (named in `.env.example`); skip hooks or failing tests.

## Done means
- [ ] `npm test`, `npm run lint` and `npm run typecheck` pass.
- [ ] The changed page or API call was observed in `npm run dev` or `npm run test:e2e`.
- [ ] The report lists anything not verified.

## Reference files (open only when needed)
- `docs/agents/data-model.md`: before changing stored fields.
```

Verdict: keep a section only if the with-and-without runs show it changed behaviour in most of them: the agent used `apiClient`, not `fetch`, wrote the failing test first and stopped before committing.

## Stop if

- The file would need secrets, internal hostnames or personal data to be useful.
- The with-and-without comparison shows no gain, or a regression.
- Two instruction files disagree and nobody can say which is current.
- An irreversible action is guarded only by a line in this file: that is context, not enforcement, so enforce it elsewhere first.

## Sources

- Agentic AI Foundation: AGENTS.md — https://agents.md/ (checked 2026-10-02)
- Anthropic: How Claude remembers your project — https://code.claude.com/docs/en/memory (checked 2026-10-02)
- Augment Code: A good AGENTS.md is a model upgrade — https://www.augmentcode.com/blog/how-to-write-good-agents-dot-md-files (checked 2026-10-02)
- Aider: Specifying coding conventions — https://aider.chat/docs/usage/conventions.html (checked 2026-10-02)
- Gemini CLI: Gemini CLI configuration — https://geminicli.com/docs/reference/configuration/ (checked 2026-10-02)