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

Source: https://codelifter.com/forum/posts/what-should-go-in-an-agentsmd-or-coding-rules-file/
Site: CodeLifter Forum, category Vibe coding prompts
Published: 2026-10-19. Updated: 2026-10-25. Replies: 2.

## Question by CodeLifter editors (staff), 2026-10-19

An AGENTS.md file should hold what a coding agent cannot work out from your code: the exact build, test and lint commands, style rules that differ from the defaults, project conventions, security rules and known traps. Keep it short, specific and checked into git, and move anything that must never be broken into a hook or lint rule.

## 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](https://agents.md/) (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](https://learn.chatgpt.com/docs/agent-configuration/agents-md), [Claude Code memory docs](https://code.claude.com/docs/en/memory), [GitHub's repository instructions page](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) and [Cursor's rules page](https://cursor.com/docs/rules), all read on 16 October 2026. The [coding agents directory](https://codelifter.com/agents/) 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](https://code.claude.com/docs/en/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](/forum/posts/how-do-i-stop-a-coding-assistant-from-using-innerhtml/), 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.

## Reply 1 by CodeLifter editors (staff), 2026-10-20

**Do you need both CLAUDE.md and AGENTS.md?** Usually one is enough, and which one depends on the tools your team uses. According to the [Claude Code memory docs](https://code.claude.com/docs/en/memory) (read 16 October 2026), Claude Code reads `AGENTS.md` only when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in the working directory or above it. If both exist, it reads the `CLAUDE.md` files only, so rules you put in `AGENTS.md` are silently skipped. The docs give two fixes: keep only `AGENTS.md`, or add a line `@AGENTS.md` to `CLAUDE.md`, which imports the file at launch. Imports can nest up to four levels deep, and paths are resolved relative to the importing file. The docs note that reading `AGENTS.md` directly needs Claude Code v2.1.277 or later. On the other side, [GitHub's instructions page](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) says Copilot can use `AGENTS.md` files anywhere in the repository, or a single `CLAUDE.md` or `GEMINI.md` in the root. For a mixed team, one `AGENTS.md` with a one-line `CLAUDE.md` import is the simplest setup that both read.

## Reply 2 by CodeLifter editors (staff), 2026-10-25

**What is the difference between Cursor rules and AGENTS.md?** Cursor supports both, and they behave differently. [Cursor's rules page](https://cursor.com/docs/rules) (read 16 October 2026) says project rules live in `.cursor/rules` as `.mdc` files, and each has frontmatter with three fields: `description`, `globs` and `alwaysApply`. With `alwaysApply: true` the rule is in every chat. With `globs` set, it attaches when a matching file is in context, for example `src/**/*.tsx`. With only a `description`, the agent decides when it is relevant. With none of them, it applies only when you @-mention it. A plain `.md` file inside `.cursor/rules` is ignored, because it has no frontmatter. AGENTS.md has none of that machinery: it is plain Markdown in the project root or any subfolder, and nested files combine with their parents, the more specific one winning. Two details are easy to miss. Rules do not affect Cursor Tab, the inline completion feature. And Team Rules, set by admins on team plans, take precedence over project rules, which take precedence over user rules. If you also use other agents, put shared rules in AGENTS.md and keep `.mdc` files for Cursor-only, file-scoped rules.

---
Cite as: CodeLifter Forum, "What should go in an AGENTS.md or coding rules file?", https://codelifter.com/forum/posts/what-should-go-in-an-agentsmd-or-coding-rules-file/, accessed 2026-11-12.