AGENTS.md: the cross-tool agent instructions file

# AGENTS.md

Instructions for any coding agent working on Project Name (a single,
predictable place for the things it needs) the
things a new human contributor would be told on their first day, written down
once instead of repeated in every prompt.

## Project overview

What this repository contains, what it is for, and the constraint that matters
most. Keep it to a paragraph.

## Setup

```sh
npm install
cp .env.example .env
npm run db:migrate
```

Node 20 or later. The `.env` defaults point at local services; nothing here
talks to production.

## Commands

| Command | What it does |
| :--- | :--- |
| `npm run dev` | Dev server on port 3000 with hot reload |
| `npm test` | Full test suite: must pass before committing |
| `npm run lint` | Lint and format check |
| `npm run build` | Production build into `dist/` |

## Code style

- TypeScript, strict mode, no implicit `any`.
- Two-space indent, single quotes, semicolons. Prettier decides; do not argue
  with it in review.
- Named exports. Default exports only where a framework demands one.
- Match the surrounding file's idiom over any rule in this list.

## Testing

Run `npm test` before every commit. New behavior needs a test; a bug fix needs
a test that fails without the fix. Do not mark a task complete with failing
tests, say what is failing instead.

## Pull requests

- One logical change per PR.
- Imperative title: `Add retry to the export queue`.
- The body explains why the change is needed and what you considered instead.
- Never commit secrets, `.env` files, or anything under `tmp/`.

## Boundaries

- Do not modify `db/migrations/` without asking: migrations are irreversible
  in production.
- Do not add dependencies without asking.
- `src/vendor/` is generated. Edit the generator, not the output.

## Where to ask

Open a draft PR with your question in the description, or ask in `#project-dev`.

AGENTS.md is a Markdown file in the root of a repository that describes how to work in it: how to set it up, which commands to run, what the conventions are, and what an agent must not touch.

What makes it worth knowing about is not the format (it is ordinary Markdown with no required structure) but the agreement. It emerged as a vendor-neutral convention so that a repository does not accumulate one instructions file per tool. That is why searches for it grew so sharply through the year: it is the answer to having four of these files.

Why a shared file instead of one each

Coding agents each arrived with their own convention: a CLAUDE.md, a .cursorrules, a .github/copilot-instructions.md - and all of them said roughly the same things. Repositories ended up with several files that drifted apart, and the one a human had open was rarely the one the tool was reading.

AGENTS.md is the convergence on one. Tools that support it read it directly; tools that do not can be pointed at it in a single line from their own file:

See AGENTS.md: it is the source of truth for this repository.

That one line is worth more than a second copy of the content, because a copy has to be maintained and a pointer does not.

The test for what goes in

Would you say it to a competent new contributor on their first morning? Setup steps, the command that must pass before committing, the conventions that come up in review, the two directories not to touch. That is the file.

What fails the test: anything the code already states, anything true of software in general (“write clean code”), and anything that describes the project’s history rather than its rules.

Commands in a table

A table forces a description next to every command, which is the part that actually gets used. A bare list of commands makes the reader guess which one is the gate.

Style rules, then the escape hatch

List the conventions that come up in review (indentation, quoting, export style) and then add the line that keeps them from doing damage:

- Match the surrounding file's idiom over any rule in this list.

Without it, a style list becomes a mandate to reformat files that were fine, and the diff fills with churn nobody asked for.

Boundaries are the highest-value section

State the limits explicitly, with the reason attached:

- Do not modify db/migrations/ without asking: migrations are
  irreversible in production.
- Do not add dependencies without asking.
- src/vendor/ is generated. Edit the generator, not the output.

The reason matters as much as the rule. A boundary with an explanation generalises to the situation you did not think of; a bare prohibition does not.

One file, or one file and a pointer

If the project also has a CLAUDE.md, keep the content in one place and make the other a two-line pointer. Two maintained copies diverge quickly, and the failure is silent: both files look authoritative, and nothing indicates which one was updated last.