What should go in an AGENTS.md or coding rules file?

What is an AGENTS.md file?

AGENTS.md is a plain Markdown file in your repository that coding agents read before they work. The AGENTS.md site (read on 16 October 2026) calls it "a README for agents" and answers the format question in one line: "Are there required fields? No. AGENTS.md is just standard Markdown." The site says the format is now stewarded by the Agentic AI Foundation under the Linux Foundation.

A rules file is the general name for the same idea. Several tools have their own file name as well as, or instead of, AGENTS.md:

Tool	File it reads	Notes from the vendor docs
Codex	AGENTS.md, or AGENTS.override.md first	Concatenates files from the repo root down; stops at 32 KiB by default (project_doc_max_bytes)
Claude Code	CLAUDE.md; AGENTS.md when there is no CLAUDE.md	Docs suggest under 200 lines per CLAUDE.md
GitHub Copilot	.github/copilot-instructions.md, AGENTS.md, or a root CLAUDE.md or GEMINI.md	Path rules in .github/instructions/NAME.instructions.md with applyTo
Cursor	.cursor/rules/*.mdc, and AGENTS.md	Docs suggest keeping each rule under 500 lines

Sources: Codex AGENTS.md guide, Claude Code memory docs, GitHub's repository instructions page and Cursor's rules page, all read on 16 October 2026. The coding agents directory covers more tools.

What should you put in it?

The AGENTS.md site lists the popular sections: project overview, build and test commands, code style guidelines, testing instructions and security considerations. Anthropic's Claude Code best practices adds a sharper filter for each line: "Would removing this cause Claude to make mistakes?" If not, cut it. Its include list, which applies to any agent:

• Commands the agent cannot guess, such as pnpm test --filter web rather than "run the tests".
• Code style rules that differ from the language defaults.
• Testing instructions and the preferred test runner.
• Repository etiquette: branch names, commit message format, pull request rules.
• Architectural decisions specific to the project.
• Environment quirks, such as required environment variables (by name, never by value).
• Gotchas that are not obvious from the code.

Be concrete. The Claude Code memory docs give the contrast: write "API handlers live in src/api/handlers/" instead of "Keep files organized".

What should you leave out?

Anthropic's exclude list: anything the agent can figure out by reading the code, standard conventions it already knows, detailed API documentation (link to it instead), information that changes often, long explanations, file-by-file descriptions of the codebase, and self-evident advice such as "write clean code". Cursor's rules page agrees: do not copy entire style guides ("Use a linter instead") and do not document every possible command.

Never put a secret in the file. It is committed to git and read into the model's context every session. The thread on keeping API keys out of a vibe-coded app covers where keys belong.

How long should it be?

Shorter than you think. The Claude Code memory docs say to "target under 200 lines per CLAUDE.md file" because "Longer files consume more context and reduce adherence." Context here means the model's working memory for the session: everything it has read so far, which has a fixed limit. Codex stops reading instruction files once the combined size reaches 32 KiB by default. Cursor suggests under 500 lines per rule.

If one part of the codebase needs its own rules, use nesting. The AGENTS.md site says "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." Codex documents the same order: files closer to your working directory come later in the combined prompt and override earlier guidance.

How do you write one?

1. Create AGENTS.md in the repository root. Claude Code can draft a CLAUDE.md for you with /init; Copilot's docs include a prompt that asks its cloud agent to draft .github/copilot-instructions.md.

2. Write the commands first: install, build, test, lint, each as an exact command in backticks.

3. Add only the rules the agent got wrong in past sessions. Cursor's advice: "Add rules only when you notice Agent making the same mistake repeatedly."

4. Add your security lines, for example:

   ## Security
   - Read secrets from environment variables; never write a key, token or password in code.
   - Write text with textContent, never innerHTML.
   - Do not add a dependency without naming it and saying why.
   

5. Commit it, then check it loaded. In Claude Code, /context shows what is in context. In Copilot Chat, the instructions file appears in the response's references list.

6. Prune it when the agent ignores a rule. Anthropic: "If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost."

The innerHTML line comes from the innerHTML thread, which also shows a lint rule that backs it up.

Does the agent have to obey it?

No. The Claude Code memory docs say Claude treats these files "as context, not enforced configuration", and point to a PreToolUse hook (a script that runs before each tool call and can block it) for anything that must never happen. Cursor says AI guidance "should not be your only security control." Use the rules file to steer, and use tests, lint rules, hooks and code review to enforce. The review thread covers the last of those.

Short version

• Put in exact commands, non-default style rules, conventions, security rules and known traps.
• Leave out what the agent can read from the code, long docs and anything secret.
• Keep it short: Claude Code suggests under 200 lines, Codex reads 32 KiB by default.
• Nested files in subfolders override the root file for that folder.
• A rules file steers; tests, lint rules and hooks enforce.