How to Write an AGENTS.md Rules File That Works

Short answer: a rules file that actually works is short, specific and verifiable. It tells the agent the exact commands to build, test and lint; the conventions it cannot infer from the code; the boundaries it must not cross; and what “done” means. It leaves out anything the agent can learn by reading the repository, and anything vague like “write clean code”. Put it at the repository root as AGENTS.md (or Assumer.md for Assumer, which is compatible with AGENTS.md and CLAUDE.md) and commit it.

What is AGENTS.md?

AGENTS.md is an open, plain-Markdown format for giving coding agents project context. Its site describes it as a “README for agents” and says it is maintained by the Agentic AI Foundation under the Linux Foundation. Many tools read it, including OpenAI Codex, OpenCode, Cursor, Gemini CLI, Aider, Zed and GitHub Copilot’s coding agent, according to the list on agents.md (some need a small configuration change).

There is no required schema. It is just Markdown that gets loaded into the agent’s context at the start of a session.

AGENTS.md vs CLAUDE.md vs Assumer.md

File	Read by	Notes
AGENTS.md	Many agents and editors	Open, tool-neutral convention
CLAUDE.md	Claude Code; also OpenCode and Assumer as a fallback	Claude Code’s native name
Assumer.md	Assumer	Compatible with AGENTS.md and CLAUDE.md
GEMINI.md	Gemini CLI	Gemini’s context file

OpenCode’s rules documentation, for example, loads AGENTS.md from the project and falls back to CLAUDE.md when there is no AGENTS.md. If your team uses several tools, keep one canonical file and avoid maintaining divergent copies.

Why most rules files underperform

Rules files often fail for predictable reasons:

1. Too long. The file is loaded into context every session. Pages of prose dilute the important lines.
2. Too vague. “Follow best practices” gives the agent nothing to act on.
3. Restating the obvious. The agent can see you use TypeScript. It cannot see that pnpm test:unit is the fast test command.
4. Out of date. A command that no longer exists is worse than no command.
5. No definition of done. Without it, the agent stops when the code compiles, not when it works.

What to include

1. Project overview (2 to 4 lines)

What the project is and how it is organised. Enough to orient, no more.

2. Exact commands

Install, dev server, build, test (all and single test), lint, format, typecheck. Copy-paste ready.

3. Conventions the agent cannot infer

Naming rules, error-handling patterns, preferred libraries, where new files go, and patterns you are migrating away from.

4. Boundaries

Files and directories not to touch, commands not to run, secrets handling, and when to ask instead of acting.

5. Definition of done

The checks that must pass before a task is complete.

6. Git and PR conventions

Branch naming, commit message format, and what a pull request description should contain.

The AGENTS.md site recommends a similar set: project overview, build and test commands, code style, testing instructions and security considerations.

A copy-ready template

# AGENTS.md

## Project
Invoice service for the billing platform. Node 22, TypeScript, Fastify, Postgres via Drizzle.
- `src/routes/` HTTP handlers (thin, no business logic)
- `src/services/` business logic
- `src/db/` schema and migrations

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test all: `pnpm test`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`

## Conventions
- Use `Result<T, AppError>` from `src/lib/result.ts`; do not throw in services.
- Money is always integer paise/cents (`amountMinor`), never floats.
- New endpoints need a Zod schema in `src/schemas/`.
- Prefer `date-fns` over `moment` (we are removing `moment`).

## Boundaries
- Never edit files in `src/db/migrations/` that are already merged; create a new migration.
- Do not read or print `.env*` files.
- Ask before adding a new dependency.

## Definition of done
- `pnpm typecheck`, `pnpm lint` and `pnpm test` all pass.
- New logic has tests next to the file (`*.test.ts`).

## Git
- Branch: `feat/<short-name>` or `fix/<short-name>`
- Commits: Conventional Commits (`feat:`, `fix:`, `chore:`)

This is about 40 lines. Every line is either a command the agent will run, a decision it could not make on its own, or a limit it must respect.

Writing rules the agent will actually follow

Be concrete

Weak: “Write good tests.” Strong: “Every new service function needs a test in the same folder covering the success path and at least one error path.”

Explain the reason once

“Money is integer paise, never floats (floating-point rounding caused invoice mismatches).” A short reason helps the agent generalise to cases you did not list.

Use positive instructions with a clear alternative

“Do not use moment” is fine; “Use date-fns instead of moment” is better because it tells the agent what to do.

Prefer verification over trust

Instead of “make sure types are correct”, write “run pnpm typecheck”. Agents with a shell tool can check the rule themselves.

Monorepos and nested rules

According to agents.md, agents read the nearest AGENTS.md in the directory tree, so the closest file takes precedence, and explicit instructions in the chat prompt override the file. A practical layout:

repo/
├── AGENTS.md              # shared: git rules, CI, global boundaries
├── apps/web/AGENTS.md     # Next.js commands, UI conventions
├── apps/api/AGENTS.md     # API commands, DB rules
└── packages/ui/AGENTS.md  # component and story conventions

Keep the root file about the whole repository and push package details down.

Rules files vs skills

A rules file is always loaded. For long, task-specific procedures, such as “how we write a database migration” or “how to cut a release”, use a skill instead. In Assumer, skills are folders with a SKILL.md file that the agent loads only when relevant, which keeps the always-on context small.

<skills folder>/
└── release/
    └── SKILL.md   # step-by-step release procedure

Check the Assumer documentation for the skills folder location your version uses.

Rule of thumb: if it applies to almost every task, put it in the rules file. If it applies to one kind of task, make it a skill.

Using a rules file with Assumer

npm i -g @4born-solutions/assumer
assumer login
cd your-repo
assumer

Assumer reads Assumer.md and is compatible with existing AGENTS.md and CLAUDE.md files, so you do not need to rewrite what you already have. Pair the rules file with per-tool permissions (allow, ask or deny) for the boundaries that must be enforced, not just requested. A rule saying “don’t run destructive commands” is guidance; a permission set to deny is a guarantee.

Maintenance checklist

• Review the file whenever build or test commands change.
• When the agent makes the same mistake twice, add one precise line.
• When a line has not mattered in months, delete it.
• Review rules changes in pull requests like code.

FAQ

What is an AGENTS.md file?

AGENTS.md is a plain Markdown file in your repository that gives AI coding agents the project context they need, such as build and test commands, code style and conventions. It is often described as a README for agents.

What is the difference between AGENTS.md, CLAUDE.md and Assumer.md?

They serve the same purpose. AGENTS.md is the open, cross-tool format, CLAUDE.md is what Claude Code reads, and Assumer.md is Assumer’s rules file. Assumer is compatible with AGENTS.md and CLAUDE.md, so one well-written file can serve several tools.

How long should an AGENTS.md file be?

Short enough that every line earns its place. Most effective files fit on one or two screens. Put long reference material in separate documents and point to them, because the rules file is loaded into context on every session.

Where should I put AGENTS.md in a monorepo?

Put shared rules in the root file and add a smaller AGENTS.md inside each package that has its own commands or conventions. Agents that follow the AGENTS.md convention read the nearest file in the directory tree.

Should I commit AGENTS.md to git?

Yes. Committing it means every developer and every agent works from the same instructions, and changes to the rules go through code review like any other change. Keep personal preferences in a global, uncommitted rules file instead, if your tool supports one.