What Is AGENTS.md (and Why Does Your Agent Ignore Your Rules)?

Quick answer
AGENTS.md is a convention, not a standard: a markdown file at the repository root that agents read for project-specific instructions.
It is plain markdown with no required schema. Its value is that it travels with the repository, so every session starts with the same context.
Agents ignore it for three reasons: the instructions conflict with a system prompt, they are too vague to act on, or the file is so long that the relevant rule is lost.
Keep it short, imperative, and specific — build commands, test commands, conventions, and hard constraints. Link to detailed docs instead of pasting them.
Some tools read a differently named file, or look in several locations. Check which file your agent actually loads before debugging the rules themselves.

What is AGENTS.md?

AGENTS.md is a markdown file placed at the root of a repository that tells an AI coding agent how the project should be worked on. It grew as a shared convention across tools rather than as a formal specification: the idea is that instead of repeating your conventions in every prompt, you write them once in the repository and the agent reads them at the start of a session. Because it is a normal file, it is versioned with the code and reviewed like anything else.

The contents are ordinary instructions. Build and test commands, the package manager to use, directory layout, naming conventions, patterns to follow and patterns to avoid, and any hard constraints such as ‘do not modify the generated client’ or ‘never commit directly to main’. Nothing about the format is magical; what makes it work is that it is stable across sessions and visible to everyone working in the repository.

Why does the agent ignore my rules?

The first cause is precedence. A coding tool typically combines a system prompt, the project file, and the current conversation, and the system prompt usually wins where they conflict. If your file says ‘always write tests first’ and the tool’s built-in behaviour is to implement and then offer tests, you may see the built-in behaviour. Restating the rule as a concrete action sometimes helps; trying to override a tool’s core design generally does not.

The second cause is vagueness. ‘Write clean, maintainable code’ is not an instruction an agent can follow or fail to follow; ‘run pnpm test before proposing a change’ is. The third is length. A file of several hundred lines dilutes the rules that matter, because attention is spread across irrelevant sections and the agent may summarise or skip parts. Files that work in practice are short and mostly made of commands and hard constraints.

What belongs in the file

Write the things you would tell a competent contractor on their first day, and nothing else. The commands to install, build, test, and lint — exactly as they are run, including the package manager. The layout of the repository, with one sentence per top-level directory. The conventions that are not discoverable from the code, such as preferring a particular error type, a specific logging library, or a migration tool. And the constraints, which are the most valuable part: files or directories not to edit, branches not to touch, commands that must never be run.

Deliberately leave out anything the agent can discover by reading the code, and anything that belongs in a spec rather than a standing rule. Long architectural explanations belong in a separate document that you link. A good target is a screen or two of text; if it is longer, the rules that matter are competing with the rules that do not.

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test` (never `npm test`)
- Lint + types: `pnpm lint && pnpm typecheck`

## Layout
- `src/api` — HTTP handlers, one file per route
- `src/db` — schema and migrations (Drizzle)
- `src/lib` — shared helpers, no side effects at import

## Conventions
- Errors: throw `AppError` from `src/lib/errors.ts`, never raw `Error`
- Every handler validates input with the zod schema next to it
- Never use `SELECT *`; list columns explicitly

## Do not
- Edit `src/generated/` — it is regenerated from the OpenAPI spec
- Commit directly to `main`
- Add a dependency without updating `pnpm-lock.yaml`

How to tell whether it is working

Test the file rather than trusting it. Add one unambiguous rule with a visible consequence — say, that all new endpoints must include an integration test in a specific directory — and check whether the next agent session follows it. If it does not, the rule is being overridden, misread, or buried. Deleting everything unrelated and re-testing distinguishes the three: an overridden rule still fails in a short file, while a buried one starts passing.

Treat the file as code. When an agent repeatedly does the wrong thing, add a specific rule; when a rule stops being relevant, remove it. A file that only ever grows becomes the reason the important rules are skipped, which is the opposite of its purpose.

Where this bites vibecoders
The instinct is to write the largest possible rules file, on the theory that more context means better behaviour. It is one of the clearest cases where more is worse: attention spent on a section about commit message style is attention not spent on the rule forbidding edits to generated code. Start with commands and hard constraints, verify one rule at a time, and grow the file only in response to a mistake it would have prevented.

Where AI coding assistants get this wrong

Writing a rules file of hundreds of lines where the important constraints are lost.
Phrasing rules as aspirations (“write good code”) rather than checkable actions.
Putting architecture essays in the rules file instead of linking to a spec.
Assuming a rule will override the tool’s built-in system prompt.
Never verifying that a rule actually changed the agent’s behaviour.
Documenting conventions merely because they exist, including ones the agent already follows.

Checklist

Confirm which file and path your agent actually reads.
List the exact install, build, test, and lint commands.
Give a one-line description of each top-level directory.
State the constraints: files not to edit, branches not to touch.
Delete anything the agent can infer from the code.
Verify one new rule per session and add rules only in response to real mistakes.

FAQ

Is AGENTS.md an official standard?

It is a convention that several coding tools support, not a formal specification with an owner. Different tools may read a differently named file or search several locations, so the practical step is to check your tool’s documentation for which project files it loads and in what order.

Should I put my whole architecture doc in AGENTS.md?

No. Long documents dilute the instructions that must not be missed, and agents handle them less reliably than short, specific rules. Keep the file to commands, layout, conventions, and hard constraints, and link to detailed documents for the reasoning behind them.

Why does the agent still do something my rules forbid?

Usually precedence or ambiguity. A built-in system prompt can outrank a project file, and a rule that is not a checkable action is easy to satisfy inconsistently. Rewrite the rule as a concrete behaviour, and if the tool’s default still wins, enforce it with a lint rule, a test, or a pre-commit hook rather than in prose.

Does a rules file help with a small project?

Less so, and it is worth keeping it minimal. The value comes from consistency across sessions and across people, which matters most where there are conventions a newcomer cannot infer. On a single-file script, the commands and one or two constraints are usually the entire useful content.