CLAUDE.md and AGENTS.md: Writing Instruction Files That Work
Short answer: A good CLAUDE.md or AGENTS.md is short, specific and operational: exact build and test commands, architecture boundaries, conventions the agent cannot infer, and explicit do-not rules. It is not documentation for humans or a style essay. Keep one source of truth, review it like code and update it whenever an agent repeats the same mistake.
On this page
What belongs in CLAUDE.md or AGENTS.md?
An instruction file is loaded into the agent's context at the start of every session. Claude Code reads CLAUDE.md, OpenAI Codex and a growing number of other agents read AGENTS.md. Everything in it costs context on every task, so every line should change the agent's behavior in a useful way.
The highest-value content is information the agent cannot reliably infer from the code: how to run things, what not to touch and which conventions are deliberate.
- Commands: exact install, build, lint, type-check and test commands, including how to run a single test
- Architecture map: three to ten lines on which directories do what and where boundaries are
- Conventions: naming, error handling, logging, state management patterns that differ from defaults
- Hard rules: forbidden directories, generated files, migration policies, dependency rules
- Definition of done: what must pass before the agent reports a task as complete
What to leave out
Long instruction files are a common failure. When the file grows to hundreds of lines, important rules drown in generic advice and agents follow them less consistently. Cut anything the agent already does well by default and anything that describes how to write good code in general.
Leave out secrets, credentials and internal URLs that should not leak into logs or pull requests. Leave out outdated decisions. And leave out aspirational rules nobody enforces, because an agent that sees the codebase violating a rule everywhere will rightly be confused.
- Generic advice such as write clean code or follow best practices
- Full API documentation that lives elsewhere, link to the file path instead
- Personal preferences of one engineer that the team never agreed on
- Anything that changes weekly, such as current sprint goals
A structure that works
Most effective instruction files follow a similar shape. Keep sections short and use imperative sentences. Agents respond well to concrete, checkable statements like Run npm run test -- path/to/file after changing a module rather than vague guidance.
- One-sentence project description: what it is and who uses it.
- Setup and commands block with copy-paste ready commands.
- Architecture overview with key directories and their responsibilities.
- Conventions that deviate from framework defaults.
- Rules: never and always statements, kept to the ones that matter.
- Workflow expectations: small diffs, tests with every change, how to report uncertainty.
Need a hand? neooutput helps with exactly this. Book a call for free and get a clear plan in 15 to 30 minutes.
One source of truth across multiple agents
Many teams use more than one agent, for example Claude Code in the terminal, Codex in the cloud and Cursor in the editor. If each tool gets its own hand-written rules, they drift within weeks. Choose one canonical file, usually AGENTS.md because several tools read it, and make the others point to it. Claude Code supports importing other files from CLAUDE.md, and a symlink works for tools that only read their own file name.
Large repositories and monorepos benefit from nested instruction files. A root file covers global rules, and files in subdirectories add package-specific commands and conventions. Agents typically pick up the files relevant to the directory they work in, which keeps the root file short.
Maintaining instruction files like code
Treat the instruction file as part of the codebase. Changes go through pull requests and reviews, and someone owns it. The most effective maintenance trigger is simple: whenever an agent makes the same mistake twice, add a precise rule. Whenever a rule stops being true, delete it the same day.
Review the file quarterly with fresh eyes. Ask a new team member to read it: if it confuses them, it probably confuses the agent too. Also check token cost. If the file is several thousand words, split it into nested files or move reference material into separate documents the agent can open on demand.
A quick quality check: ask the agent to summarize the rules back to you at the start of a session. If its summary misses a rule you consider critical, the rule is either buried or ambiguous.
Getting the team aligned
Instruction files encode team agreements, so writing them is as much a people exercise as a technical one. The best results come when engineers, leads and whoever reviews agent output agree together on commands, boundaries and the definition of done.
neooutput workshops often start exactly here: the team writes its first CLAUDE.md or AGENTS.md on its real repository, tests it with live agent sessions and iterates until the agent behaves predictably. That single artifact tends to improve agent results more than any model upgrade. A neooutput trainer can also review an existing file in a 1:1 session. A free 15-minute call is enough to find out what would help most.
Frequently asked questions
Should I use CLAUDE.md or AGENTS.md?
Use the file your main agent reads, and make it the single source of truth. Claude Code reads CLAUDE.md, while Codex and several other agents read AGENTS.md. If you use more than one agent, keep the content in one file and import or symlink it under the other name so the rules never diverge.
How long should an instruction file be?
As short as possible while still covering commands, architecture, conventions and hard rules. For most repositories that means roughly 50 to 200 lines. If it grows much longer, move package-specific details into nested files and reference documentation by path instead of pasting it in.
Can the agent update its own instruction file?
Yes, and it is often helpful: ask the agent to propose an addition after it learns something important about the project. But review those changes like any other pull request. Agents tend to add verbose or overly specific notes, and unchecked edits slowly bloat the file.
Do instruction files replace code review?
No. They raise the baseline quality of agent output and reduce repeated mistakes, but agents still misread rules, miss edge cases and occasionally ignore instructions. Every agent-authored change should go through the same tests and human review as any other change.
