A rules file for an AI agent looks like the easiest part of the job: a few sentences in Markdown. It is also where rules and reality drift apart most easily. My repository for this website has both a CLAUDE.md and an AGENTS.md, and on 20 October 2026, while preparing this article, I found that they were no longer the same. The nine tips below come from that, each with an example from my own repo.
What a harness is and why these files are part of it is explained in my article on the harness. This one is about practice: what to put in the files, how to keep them together and what not to entrust to a sentence alone.
- AGENTS.md is an open format, a "README for agents". It is stewarded by the Agentic AI Foundation under the Linux Foundation and read by 20+ tools, for example Codex, Cursor, the GitHub Copilot coding agent or OpenCode. Claude Code reads CLAUDE.md.
- The trap: Claude Code reads AGENTS.md only when there is no CLAUDE.md in the folder or above it (since version 2.1.277). If you have both files, it reads only CLAUDE.md.
- The fix: one source of truth in AGENTS.md and a CLAUDE.md with the line
@AGENTS.mdplus a few instructions only for Claude. - Rules are context, not enforced configuration. What must never happen has to be guarded by a hook, permissions or a script.
- Nine tips: one truth, verifiable sentences, a ban with a reason, a short file, a link to the source, enforcement by a tool, commands with exceptions, a log, regular checks.
What are AGENTS.md and CLAUDE.md?
AGENTS.md is plain Markdown in the root of a repository. The site agents.md describes it as a "README for agents": a README is for people, AGENTS.md for coding agents. The format grew out of a collaboration between OpenAI Codex, Amp, Google's Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. No fields are required. The recommended sections are a project overview, build and test commands, code style, testing and security.
CLAUDE.md is the same thing for Claude Code. According to the documentation, both CLAUDE.md and auto memory (notes Claude writes itself) are loaded at the start of every session, and Claude treats them as context, not as enforced configuration.
Over 20 tools read AGENTS.md, which makes it a good common base: for example Codex, Cursor, the GitHub Copilot coding agent, OpenCode, Aider, Zed or Warp. OpenCode creates it for you with the /init command. I summarise the open-source coding agents (OpenCode, Codex CLI, Gemini CLI) in my overview of open-source AI projects.
What is the difference between AGENTS.md and CLAUDE.md?
The difference is not the format, both are Markdown, but who reads the file and how the rules are combined.
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Who reads it | Codex, Cursor, GitHub Copilot coding agent, OpenCode, Zed, Warp and others; Gemini CLI and Aider after configuration | Claude Code |
| Where it lives | repository root, in a monorepo also in every subproject | ./CLAUDE.md or ./.claude/CLAUDE.md, personally ~/.claude/CLAUDE.md and ./CLAUDE.local.md |
| Precedence | the nearest file wins, an explicit instruction in chat overrides all of them | files are combined, the closer folder is read later, on a conflict Claude may pick either |
| Recommended length | none; Codex caps the combined text at 32 KiB | under 200 lines per file |
| Extra files | AGENTS.override.md in Codex |
CLAUDE.local.md for personal notes, belongs in .gitignore |
Claude Code also does not read AGENTS.override.md or AGENTS.local.md. The override file is a Codex thing.
How do Claude Code and Codex load the rules?
Both tools assemble rules from several places, each in its own way.
- Claude Code combines rules rather than overriding them: it reads from the parent folders down to the working folder, and the closer folder comes later. Files in subfolders load only when Claude touches a file in them. If two sentences contradict each other, Claude may pick either one.
- Codex reads the global
~/.codexand then goes from the project root (git) down to the current folder, at most one file per folder. The texts are merged top to bottom and the closer file overrides earlier instructions.
Do I need both AGENTS.md and CLAUDE.md, or is one enough?
It depends on what you already have in the repository. The table is based on the Claude Code documentation, status on 20 October 2026.
| What you have in the repository | What Claude Code reads | What to do |
|---|---|---|
| Only AGENTS.md | AGENTS.md (since version 2.1.277) | nothing, it works |
| Both AGENTS.md and CLAUDE.md | only CLAUDE.md | add the import @AGENTS.md to CLAUDE.md |
CLAUDE.md with the import @AGENTS.md |
CLAUDE.md and, through the import, AGENTS.md | the safest option, it also works in sessions that do not read AGENTS.md directly |
| Only CLAUDE.md | CLAUDE.md | other tools do not read it by default |
Your ~/.claude/CLAUDE.md, an organization-wide CLAUDE.md and files in .claude/rules/ do not count in the "is there a CLAUDE.md?" check. CLAUDE.local.md does count: if you add one to a project that relies on AGENTS.md, Claude Code stops reading AGENTS.md.
The documentation offers three ways to share one file: an @AGENTS.md import from CLAUDE.md, a symlink from CLAUDE.md to AGENTS.md, or setting Project instructions to claude-md-and-agents-md in /config. On Windows I choose the import. The documentation warns that a symlink there needs administrator rights or Developer Mode, and without the core.symlinks setting Git checks it out as a plain text file with one line.
@AGENTS.md
## Claude Code only
- Only what concerns Claude Code goes here, for example hooks or skills.
The imported file is read first, the instructions below it after it.
How to write rules for AI? Nine tips from practice
The tips draw on the documentation of Claude Code, Codex and agents.md and on my own repo. For each one I say where the example comes from.
1. Keep one truth instead of two copies
CLAUDE.md and AGENTS.md in the repository of this website started out as copies of the same text. As of 20 October 2026, CLAUDE.md had 46 lines and AGENTS.md had 56 lines, and compared as of that date they differ in two things:
- The React version. AGENTS.md says React 19,
package.jsonhasreact18.3.1. CLAUDE.md correctly says 18.3. - Three bullets only in AGENTS.md: headings with a capital first letter, no long dashes, formal address and first person; do not touch the titles of articles under a running test; do not run
next buildandnext startwhile a dev server runs in the folder or another agent is working.
The consequence follows from the documentation: Claude Code reads AGENTS.md only when there is no CLAUDE.md in the folder or above it. Here there is one, so Claude Code would by default never receive the rules on headings, dashes and builds. Codex, on the other hand, reads AGENTS.md and gets the wrong React 19 instead of the correct 18.3.
Since then the files have drifted further apart: on 21 October 2026 I added rules on writing in the first person singular and on publishing team names to AGENTS.md, so as of 22 October 2026 it has 67 lines, while CLAUDE.md still has 46. That is why I always give line counts with a date.
The fix is small: AGENTS.md as the single source and a CLAUDE.md with the line @AGENTS.md and instructions only for Claude. As of 22 October 2026 I have not done it in this repo yet. My global ~/.claude/CLAUDE.md already works this way: it imports the shared AGENTS.md from my library of rules and below it has only Claude-specific instructions. I make the change in one place.
2. Write sentences that can be verified
The Claude Code documentation gives sentences like "Use 2-space indentation" (instead of "Format code properly") and "Run npm test before committing" as models. That is how you recognise a good rule: it can be checked.
My AGENTS.md says that titles, H1 and H2 start with a capital letter (proper nouns and abbreviations such as AI Act, Kč or SEO are written as they are) and that a long dash is not used as a separator, with a comma, colon or pipe in its place. After the work, it is enough to scan the headings. Two people would not agree on "write well".
3. Give a reason and a date for every ban
In my repo's AGENTS.md, the rule on headings carries a note: on 3 October 2026 a script converted 91 titles and 275 headings to lowercase, fixed by hand, never re-run it. The rule thereby has a cause and an age. The agent can tell how far the ban reaches, and a year from now you can see whether it still applies. In my experience, a ban without a reason looks arbitrary and is harder to maintain.
4. Keep the file short and split the rest
Claude Code recommends under 200 lines per file, because longer files use more context and reduce adherence. An import via @path helps with organisation but does not save context, because imported files load at startup. Things relevant to only part of the project belong in .claude/rules/*.md with a paths: field, which load only when working on matching files, and repeatable procedures in skills. For a monorepo, agents.md recommends an AGENTS.md in every subproject, with the nearest one winning. Codex caps the combined text at 32 KiB.
My two files (CLAUDE.md and AGENTS.md) had 46 and 56 lines as of 20 October 2026, and as of 22 October 2026 they have 46 and 67. The details live elsewhere (SEO strategy in the docs/seo/ folder, prices in the data files of the services) and the file only says where to look.
5. Point to the source of truth, do not copy it
The price rule in my repo says that the price list is canonical and the source is src/data/services/*.ts. It contains no numbers, only the place where the truth lives. A number in a rules file would be a third copy that goes stale. And according to the documentation, when two sentences conflict, the agent may pick either one.
6. Enforce what must never happen with a tool
The Claude Code documentation says it directly: CLAUDE.md is context, not enforced configuration, and a PreToolUse hook is what blocks an action. The layers of protection look like this:
| Method | What it guarantees | Example |
|---|---|---|
| A sentence in CLAUDE.md or AGENTS.md | the agent receives it as context and may overlook or interpret it differently | "do not use long dashes" |
| Permissions and deny rules | the tool does not allow the action | a deny rule for a specific command, see my article on the harness |
| PreToolUse hook | blocks the action before the tool runs and returns the reason to the model | my hook that blocks commands that waste context |
| Lint or test | verifies the result after the work | npm run seo:content:lint |
Two examples from practice:
- Lint.
npm run seo:content:lintwas created on 22 August 2026 after a day of searching by hand for invented references, agency plural instead of first person singular, prices outside the price list and blank lines inside figures. On an error it exits with code 1, so the rule does not depend on whether the agent read it. - Hook. In my global Claude Code settings I have a PreToolUse hook for terminal commands. When a command matches a pattern that wastes context, the script exits with code 2 and sends the model a message on how to do it more cheaply. It is not a security boundary, but it shows the mechanism: a rule the tool actually enforces.
7. Write the verification commands and when not to run them
agents.md says that agents will try to run the tests you list. So the command belongs in the file, and so does its exception. My repo says that after SEO changes npx tsc --noEmit and npm run build must pass, that older tsc errors in src/app/api/cv-pdf and src/lib/cv/pdf-cache.ts are ignored but new ones are not, and that next build and next start are not run while another agent works in the folder, because the shared build output breaks. The last rule came from several agents working in one folder.
The example also shows the trap from the first tip: the exception is only in AGENTS.md. A Claude Code that reads CLAUDE.md learns that the build must pass, but not when to leave it alone.
8. Keep a log for handing over between sessions
Rules describe how a project works, not what is being done right now. That is why I keep docs/worklog.md: the newest entry at the top, in the form Done, Decided, Next, Open, at most eight lines. A hook at the start of a session puts roughly the top 45 lines into the context, so the whole file is never read. On /clear and /compact another hook adds an entry.
The documentation adds that the project-root CLAUDE.md survives /compact, but an instruction given only in the conversation does not. What should keep applying belongs in a file.
9. Regularly check what the agent actually loaded
- Claude Code:
/memoryshows the loaded files (including the path of a directly read AGENTS.md) and/contextthe context usage./doctor prompt-audit(since version 2.1.283) looks for instructions written for older models, references to files and commands that do not exist, and files that contradict each other. It returns a report with proposed edits and changes nothing until you ask. - Codex: the command
codex --ask-for-approval never "Summarize the current instructions."prints which instructions the tool sees.
I found the drift between my two files by a plain comparison of the two texts. It is not a sophisticated tool, you only have to schedule the check.
What does a sample AGENTS.md look like?
A skeleton following the sections recommended on agents.md. Folder names and commands are illustrative, adapt them to your project. In my experience it is worth writing mainly what you cannot tell from the code.
# AGENTS.md
## Project overview
What the project does, for whom, its stack and versions (as in package.json).
## Commands
- Install: `npm install`
- Dev: `npm run dev`
- Test: `npm test` (before every commit)
- Lint: `npm run lint`
- Do not run `npm run build` while a dev server runs in the folder or another agent is working.
## Code style
- TypeScript, 2-space indentation.
- Components in PascalCase, files in kebab-case.
## Sources of truth
- Prices are in `src/data/prices.ts`. Do not copy them into texts by hand.
- Translations are in the `messages/` folder.
## Never
- Do not delete the `migrations/` folder (YYYY-MM-DD: the reason this rule exists).
## Security
- Never print or commit values from `.env`.
## Handover
- After the work, update the top of `docs/worklog.md`: done, decided, open (at most 8 lines).
Most of the tips from this article show up in the skeleton: verifiable sentences, a source of truth instead of a copy, a command with an exception, a ban with a reason and a date, and a log for the handover.
What does the community say about writing rules?
I did not open the threads themselves. I am relying on Google result previews for r/ClaudeAI, so this is community opinion, not data:
- keep the file under 200 lines,
- leave "how to write code" to skills and "how this project works" to CLAUDE.md,
- split files by folder,
- keep a handover file with "what I tried, what worked" for the next session.
The first and third points match the documentation. The others are individual experiences, so test them on your own project.
When does it pay off to introduce agent rules in a company?
In my experience, when more than one person or more than one tool works with AI on one project. If you are only starting with AI in your company, I cover the basics of writing instructions, analysis and research, and safe use (ChatGPT, Claude, automation) in AI training. Connecting AI to your processes and tools is part of my AI automation. You can find courses, including vibe coding, in the course offering.
FAQ
What is AGENTS.md?
An open format, plain Markdown in the root of a repository, that tells agents how to work in the project: overview, build and test commands, code style, security. The agents.md site calls it a "README for agents". No fields are required.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is a common format read by 20+ tools including Codex. CLAUDE.md is the Claude Code file. Claude Code reads AGENTS.md only when there is no CLAUDE.md in the folder or above it. If both exist, it reads only CLAUDE.md.
Do I need both AGENTS.md and CLAUDE.md?
If you use only Claude Code, CLAUDE.md is enough. If you use several tools, keep the rules in AGENTS.md and put the import @AGENTS.md plus Claude-only instructions in CLAUDE.md. AGENTS.md alone without CLAUDE.md also works, and Claude Code has read it since version 2.1.277. In some sessions, such as on Amazon Bedrock before version 2.1.281, it may not read it. The import from CLAUDE.md works there too.
How long should AGENTS.md or CLAUDE.md be?
Claude Code recommends under 200 lines per file, because longer files reduce adherence to the rules. Codex combines the rules up to a default limit of 32 KiB (project_doc_max_bytes). My two files (CLAUDE.md and AGENTS.md) had 46 and 56 lines as of 20 October 2026, and as of 22 October 2026 they have 46 and 67.
Do Cursor, Copilot and Gemini read AGENTS.md?
According to agents.md, Cursor, the GitHub Copilot coding agent and Gemini CLI do. Gemini CLI uses GEMINI.md context files, so you need to set the context file name to AGENTS.md in .gemini/settings.json. For Aider you add read: AGENTS.md to .aider.conf.yml.
Can an agent break the rules?
Yes. CLAUDE.md and AGENTS.md are context, not enforced configuration. The Claude Code documentation recommends a PreToolUse hook to block an action. Rules are also weakened by file length and by contradictions between sentences. Guard what must not happen with permissions, a hook or a test.
Sources and links
- agents.md, description of the format, supported tools and migration, read on 20 October 2026
- Claude Code: How Claude remembers your project, CLAUDE.md, AGENTS.md, imports,
/doctor prompt-audit, read on 20 October 2026 - Codex: AGENTS.md, loading order and the 32 KiB limit, read on 20 October 2026
- OpenCode: documentation, the
/initcommand creates AGENTS.md - Anthropic: donating MCP to the Agentic AI Foundation, 9 December 2025, AGENTS.md among the foundation's founding projects
- r/ClaudeAI, community opinions (Google result previews only)