Give an agent standing instructions

A coding agent does not know your project’s conventions, the command that runs your tests, or the one thing you must never do to the production database. You can repeat that in every prompt, or you can write it once in a file the agent reads on every session. That file is the highest-leverage piece of configuration you have: it is standing context, applied to everything the agent does, without you saying it again.

CLAUDE.md (Claude Code)

Claude Code reads files named CLAUDE.md and merges every one it finds:

• the project’s CLAUDE.md at the repo root — checked into version control, shared with the team;
• a CLAUDE.md in a subdirectory — loaded only when the agent works on files there;
• your personal ~/.claude/CLAUDE.md — your preferences across every project;
• and CLAUDE.local.md — project notes you keep out of git.

They concatenate from the top of the tree down, so a project file adds to your personal one rather than replacing it. Two commands help: /init writes a starting CLAUDE.md by reading the codebase, and /memory opens the files for editing. You can also pull another file in with an @path import — which matters in a moment.

AGENTS.md: the cross-tool version

Claude Code is not the only agent with this feature, and the others largely converged on one open format: AGENTS.md, “a README for agents.” It started with OpenAI’s Codex team, is now read by a long list of tools (Codex, opencode, Zed, Cursor, Windsurf, and more), and is stewarded as an open standard under the Linux Foundation. Same idea as CLAUDE.md — one filename many tools agree on.

The catch worth knowing: Claude Code reads only CLAUDE.md, not AGENTS.md. So if you work across tools and want a single source of truth, keep the content in AGENTS.md and make CLAUDE.md a one-line file that imports it:

@AGENTS.md

(Or symlink CLAUDE.md to AGENTS.md.) Then every tool reads the same instructions.

Where each tool looks

What to put in it — and what to leave out

The file is always in context, so every line competes for the model’s attention and costs tokens on every turn. A short, sharp file helps; a long, vague one quietly makes the agent worse. Keep it to what is true, specific, and not guessable from the code itself:

1. The commands. How to build, test, lint, and run — for example, “run tests with pytest -q, not python -m unittest.” These are the things the agent would otherwise guess wrong.
2. Conventions that are not obvious. The patterns the code follows that a newcomer would miss.
3. The hard “do not"s. The handful of actions that cause real damage — “never run migrations against prod”, “do not edit files under generated/.”
4. Nothing else. Leave out anything the agent can read from the code, and resist listing everything; a wall of instructions gets skimmed, not followed.

One honest limit: the file steers the agent, it does not bind it. These instructions are strong context, not a hard guarantee — so a “do not” that really matters belongs behind a real guardrail (a permission, or a hook ), not only a sentence in a file. The same logic as scoping an agent’s tools .

Where to go next

• Writing your first one — a copy-paste starter and where the file goes on each OS: Your first CLAUDE.md .
• Add capabilities, not just rules: Skills, MCP, and extending an agent .
• The agent this configures: Claude Code .