How to write a CLAUDE.md / AGENTS.md project instruction file

What is a CLAUDE.md or AGENTS.md file?

It is a Markdown file in your repository that a coding agent loads automatically at the start of a session. Claude Code reads CLAUDE.md; AGENTS.md is a shared convention read by several agents, including OpenAI’s Codex and other tools that adopted it.

Think of it as onboarding notes for a fast new colleague who has read none of your history. It is loaded into context every session, so every line costs tokens and competes for attention with the actual task.

The file matters most in repositories where the right way to do things is not visible from the code alone: unusual build steps, generated code, strict module boundaries or safety rules around data. In those projects a good instruction file prevents the same mistakes from repeating across sessions.

It also speeds up every session. Instead of the agent exploring the repository to rediscover how tests run, it reads the answer in the first seconds and spends its effort on the task.

A useful test for every line: would a skilled engineer new to this repository get this wrong without being told? If not, the line can probably go.

Which file names do agents read?

If your team uses several agents, keep one source of truth. A common pattern is putting shared instructions in AGENTS.md and having CLAUDE.md import it with an @AGENTS.md line, since Claude Code supports @path imports.

Whichever combination you use, avoid maintaining the same rules in several files by hand. Copies drift apart within weeks, and agents then receive contradictory guidance depending on the tool.

A single shared file plus small tool-specific additions is easier to keep accurate than full copies for each agent.

Global and project files stack. Claude Code combines your personal file in ~/.claude with the project file and any nested files, so keep personal preferences, like reply language or commit style, in the global file and project facts in the repository. When the two conflict, the agent has to guess, so resolve contradictions instead of relying on precedence.

Folder-level files are loaded on demand, which keeps the root file small in monorepos while still giving each package precise commands.

What should go into the file?

• One or two sentences on what the project is and who uses it.
• Exact commands: install, dev server, build, single test, full test suite, lint, type-check, database migrations.
• A short architecture map: which folders hold what, where entry points are, which modules are generated and must not be edited.
• Conventions the code does not make obvious: naming, error handling pattern, state management, preferred libraries and banned ones.
• Workflow rules: run tests before declaring done, how to name branches and commits, never push to main.
• Hard safety rules: never touch production data, never commit secrets, never run destructive migrations without asking.
• Known traps: flaky tests, slow commands, environment quirks, ports that are already taken.

How to write it step by step

• Generate a starting point: in Claude Code run /init, which scans the repo and drafts a CLAUDE.md.
• Delete everything generic or obvious from reading the code, such as “write clean code” or a restated folder listing.
• Verify every command by actually running it; a wrong test command wastes more time than no command.
• Rewrite rules as specific, checkable instructions: “Use pnpm, never npm” beats “use the right package manager”.
• Order sections by importance: commands and hard rules first, background last.
• Move long reference material (API style guide, domain glossary) into separate files and import or link them only where needed.
• Commit the file, then watch a few agent sessions and add a line each time the agent makes the same mistake twice.

What does a good instruction look like?

Common mistakes in CLAUDE.md and AGENTS.md

• Writing a novel: long files dilute the important rules; aim for something you can read in a couple of minutes.
• Duplicating the README: the agent can read the README when needed; the instruction file should add what it lacks.
• Stale commands after a tooling change, which teach the agent to ignore the file.
• Contradictions between the global file, the project file and folder files.
• Putting secrets, tokens or customer data in the file; it is committed and sent to the model provider.
• Relying on emphasis alone: “IMPORTANT” helps a little, but a precise rule helps more.
• Expecting it to enforce anything: it guides behaviour, while hooks, CI and permissions actually enforce rules.

How do you keep the file useful over time?

Treat it like code. Review changes to it in pull requests, and prune rules that no longer apply after refactors.

When a rule is critical, back it with automation: a pre-commit hook, a CI check or an agent permission setting. The file then explains why, while tooling guarantees it.

Many open-source repositories now ship their own CLAUDE.md or AGENTS.md, and reading a few well-maintained ones is the fastest way to calibrate length and tone. RepoLoot’s catalog highlights projects built for agentic engineering, which is a good place to find such examples.

How is CLAUDE.md different from a README or docs?

The README is for humans deciding whether and how to use the project. Documentation explains features in depth. The instruction file is a compact briefing for an agent that is about to change the code.

That difference shapes the tone. Instructions are imperative and specific, written as rules and commands rather than explanations, and they focus on what the agent would otherwise get wrong.

• README: purpose, installation, usage, contribution notes.
• Docs: architecture decisions, API reference, guides.
• CLAUDE.md or AGENTS.md: commands, boundaries, conventions, traps and a definition of done.
• Hooks and CI: the rules that must be enforced automatically.

What does a lean example structure look like?

A compact file often follows the same order: a short project line, a commands block, an architecture list, conventions, and a final section of hard rules. Each section uses bullets rather than prose, which makes the file easy to scan and easy for the agent to apply.

Commands deserve exact syntax, including flags that matter, such as how to run a single test file. The agent will use whatever you write literally, so a command that requires an extra argument in practice should show that argument.

Add a short “when you finish a task” checklist: run type-check, run affected tests, summarize changed files. That line alone often removes a whole class of half-finished work.

Frequently asked questions

Should I use CLAUDE.md or AGENTS.md?

If only Claude Code is used, CLAUDE.md is enough. If your team mixes agents, keep shared instructions in AGENTS.md and import it from CLAUDE.md with an @AGENTS.md line, so there is one source of truth. Add Claude-specific notes below the import when you need them.

How long should a CLAUDE.md file be?

Short enough that every line earns its place, often well under a couple of hundred lines for a typical project. The file is loaded into context each session, so long files cost tokens and bury key rules. Move detailed references into separate documents and import them only where relevant.

Does the agent always follow CLAUDE.md?

It follows it most of the time, but instructions are guidance, not enforcement. Specific, testable rules are followed more reliably than vague ones. For anything that must never happen, such as pushing to main or editing migrations, add hooks, permissions or CI checks alongside the written rule.

Can I have different instructions for different folders?

Yes. Claude Code loads CLAUDE.md files from subdirectories when it works in them, which suits monorepos where the frontend, backend and infrastructure have different commands and conventions. Keep shared rules at the root and only package-specific details in the nested files.