CLAUDE.md and AGENTS.md: what they are, what to write in them and why the agent ignores rules

What CLAUDE.md and AGENTS.md are

These are plain Markdown files in the root of the repository, which the agent loads automatically into its context at the start of a session. With them you tell the agent what it cannot learn from the code itself: how to set up the environment, which commands check the work, which project rules are not up for discussion and where the detailed documentation lives.

CLAUDE.md is the file that Claude Code reads. AGENTS.md is an open format with the same idea, supported by many coding agents. If a team uses different agents, it is convenient to keep the main content in AGENTS.md and reference it from CLAUDE.md. Claude Code supports importing another file with a line starting with @:

# CLAUDE.md
@AGENTS.md

This way the rules live in one place and do not drift apart between two files.

How the agent reads these files

The content of the instructions file goes into the model's context window together with the system prompt and stays there for the whole session. This has three important consequences.

• Every line takes up space in the context. The file is read in full at every start, even if the current task needs one tenth of it.
• These are not executable rules, just text. The model takes them into account along with the rest of the context, and nothing guarantees 100% compliance. Hard prohibitions must be backed by mechanisms: checks, hooks, access rights.
• Files can be nested. Claude Code loads CLAUDE.md from the project root and from the user folder ~/.claude/, and files in nested directories are loaded when the agent works with files in those directories. This lets you keep the rules of a module next to the module.

What to write in CLAUDE.md and AGENTS.md

A good instructions file is a map, not a textbook. It answers the questions an agent would ask an experienced colleague on the first day.

1. How to build and check the project

The most valuable section. Concrete commands the agent must run before it says "done": tests, linter, type checking, starting the environment. Without them the agent checks its work "by eye".

2. Hard constraints

A short list of things that must never be broken under any circumstances: security and data invariants. Phrase them as invariants, not as implementation instructions: "all SQL queries are parameterized", not "use this particular function in that particular file".

3. A map of the project

Where things are: a few lines about the directory structure and where to find details. For each large topic, a link to a separate document that the agent opens only when it starts working on that topic.

4. Where the state of the work is kept

Where to look to continue from where the previous session stopped: a plan file, a progress log, a backlog. This cures the agent's "amnesia" between sessions.

What not to write

• Things the agent can learn from the code. The list of dependencies is in package.json or pyproject.toml, the structure of classes is in the code itself.
• General advice. "Write clean code" or "be careful" do not change behavior and only take up space.
• Project history and one-off notes. "In March we moved from MySQL 5.7" does not help the current task.
• Detailed instructions for rare tasks. A deployment or data migration procedure is needed once a week — move it to a separate document or a skill.
• Secrets. The file lives in the repository and goes entirely into the model. Tokens and passwords belong only in environment variables.

Why the agent ignores a rule that is written in the file

A typical story: the agent made a mistake, so a rule was added to the file. It made another mistake, so one more rule was added. A few months later the file has hundreds of lines, and the critical security rule is broken as if it did not exist. There are usually four causes, and they act at the same time.

A bloated file

A 600-line file is roughly 10–20 thousand tokens. The context window looks huge, but it is shared with code, command output and the dialogue history. The more space the instructions take, the less attention each rule gets and the more room is taken from the task itself.

The rule is in the middle

Language models use information from the middle of a long text noticeably worse than from its beginning and end. A rule on line three hundred of six hundred ends up in the weakest place.

No priorities

A non-negotiable prohibition and a passing remark about style are written the same way — as one line in a list. The agent has no way to tell what matters more. And if the file contains three contradictory style rules, the behavior becomes random from run to run.

Rot

Adding a rule costs nothing, but deleting one is scary: "what if something depends on it". So the file grows steadily while the share of useful lines falls. It is handy to measure this as a signal-to-noise ratio: how many lines are really needed for a typical task and how many are not.

How to fix it: a router instead of a wall of text

Fixing one cause is useless: if you shorten the file but leave it unstructured, the rules are still mixed together. A set of measures works.

1. Make the entry file a router. 50–150 lines: check commands, hard constraints, a project map and links to topic documents.
2. Move topics into separate files. For example, docs/agents/deploy.md, docs/agents/database.md. The agent opens them as needed. In Claude Code, skills are convenient for repeated procedures — they load only when needed.
3. Move the critical items to the top. Hard constraints go at the beginning of the file, in a short separate block with an explicit MUST label.
4. Remove contradictions. One rule per topic. If there is an exception, write it right next to the rule.
5. Back the rule with a mechanism. If a violation is unacceptable, text is not enough. You need a check that catches it: a linter, a test, a pre-commit hook or an agent hook, or a restriction at the access-rights level.
6. Review regularly. Set a line limit, and each time you add something ask what can be removed or moved elsewhere.

Rule or check?

Example of a compact AGENTS.md

# AGENTS.md — payment backend (FastAPI, PostgreSQL)

## MUST — do not break
- Money amounts are int in cents, never float
- SQL only parameterized, no f-strings
- Do not change applied migrations, only add new ones
- Secrets only from environment variables

## Check before saying "done"
docker compose up -d     # environment
make lint                # ruff + mypy
make test                # pytest
make e2e                 # checkout scenario
Green unit tests without e2e is not "done".

## Map
- app/payments/   — amount calculation, discounts, provider webhooks
- app/api/        — HTTP handlers
- tests/e2e/      — user scenarios
Details: docs/agents/architecture.md, docs/agents/database.md

## State of the work
- PLAN.md      — current goal, completion criteria, next step
- PROGRESS.md  — what was done and how it was checked, dead ends
- BACKLOG.md   — things noticed "on the side": write them here, do not fix them now

At the end of the session, update PROGRESS.md and the next step in PLAN.md.

Notice what is missing: no list of libraries, no style advice, no project history. All of that is either visible in the code, enforced by checks, or kept in topic documents.

Amnesia between sessions: an instructions file plus a plan file

The instructions file describes how to work in the project, but not what is happening right now. For that you need a separate state file, which the agent reads at the start and updates at the end of the session. It contains the goal, what has been done with an indication of how it was verified, decisions with their reasons, rejected options and one formulation of the next step. A simple quality check: open a new session, write "continue" and see whether the agent starts useful work without asking questions.

Do not confuse the two files. Instructions change rarely and apply to all tasks. A plan changes every session and applies to the current task. If you mix them, the instructions file quickly fills with outdated notes.

How to check that the file works

The instructions file also needs testing. Take a few typical tasks — a bug fix, a small feature, a refactoring — and see what the agent does without prompts: does it run the right commands, does it open the correct topic document, does it respect the hard constraints. If a rule is broken, first ask yourself whether it is visible, whether it contradicts something and whether it can be replaced with an automatic check. Adding a new line is the last resort.

Summary

CLAUDE.md and AGENTS.md are the agent's entry point to the project. They work when they stay a short map: check commands, hard constraints at the top, links to details and to the plan file. If a rule is ignored, the cause is almost always a bloated, unstructured file, and truly critical rules must be backed by checks and hooks. The design of the agent's instructions and state is covered in practice in the harness engineering course.