Context files (CLAUDE.md, AGENTS.md)
Last verified: June 2026· definition
Conventions differ by tool — CLAUDE.md for Claude Code, AGENTS.md as a cross-tool convention, .cursorrules and rules files for Cursor — but the purpose is identical: give the agent the priors a new senior engineer would get on day one, so it does not re-derive them (slowly, and often wrongly) on every task.
A good one is short and load-bearing: how to run the tests, how the modules are laid out, the conventions that are non-obvious from the code, the things that look wrong but are deliberate, and the actions that need a human. A bad one is a wall of aspirational prose the agent has to wade through.
This is consistently the cheapest, highest-return item in a codebase-readiness audit. It takes hours to write, it is version-controlled alongside the code, and it improves the output of every agent and every engineer who touches the repo afterwards.
Write what to do, not what exists
The most common mistake is describing the codebase — listing directories, restating what is obvious from the file tree. An agent can read the repository; what it cannot infer reliably is judgement. The useful content is decisions and conventions: how errors should be handled, which patterns are deprecated and what replaced them, why a surprising choice was made, what to do rather than what is there. Anything an agent could work out by looking is wasted space.
Stale instructions are worse than none
Because agents follow context files fairly literally, an out-of-date instruction produces confidently wrong work — and does so repeatedly, since every agent reads the same file. This makes staleness more costly than for human documentation, where a reader would notice the mismatch. Keeping the file short enough that updating it is easy, and treating changes to it as part of the change that made them necessary, is what keeps it trustworthy.
They compete for context budget
Context files are read on every task, so their contents occupy space on every request. A long file crowds out the code and material the agent actually needs to reason about, and can degrade the results it was meant to improve. Brevity is a functional requirement rather than a stylistic preference, which argues for stating conventions crisply and letting the agent read code for detail.
Scope them where conventions differ
A single repository-wide file works until different parts of the codebase genuinely follow different conventions, at which point it becomes a list of exceptions nobody can apply correctly. Placing more specific guidance closer to the code it governs keeps each piece short and unambiguous, and means an agent working in one area is not carrying rules for another.
Common misconceptions
MythA context file should document the architecture.
RealityAgents read code well. What they need is conventions and decisions — the judgement that is not recoverable from the source.
MythMore detail produces better results.
RealityContext files consume budget on every request, so length competes with the code the agent needs to see. Long files frequently make outcomes worse.
MythWriting one is a one-off task.
RealityA stale file actively misleads every agent that reads it. It needs maintaining alongside the conventions it describes, or it becomes a liability.
Frequently asked questions
What should go in a context file?
Conventions and decisions an agent cannot infer: how errors and logging are handled, which patterns are deprecated and what supersedes them, naming and structure rules that are not obvious from a sample, constraints that exist for reasons not visible in the code, and how to run tests and checks. Leave out anything discoverable by reading the repository — directory listings and restatements of the file structure consume budget without adding information.
How long should a context file be?
Short enough that keeping it current is easy and it does not crowd out the code on every request. Length has a real cost here because the file is read on every task, competing for the same context budget as the material the agent needs to reason about. If it is growing past what fits comfortably on a screen or two, that usually indicates conventions belong closer to the code they govern.
Do different AI tools read the same context file?
Not necessarily — conventions vary by tool, and several look for their own filenames. Where a team uses more than one, it is worth checking what each expects rather than assuming a shared standard. The content is largely portable even when the filename is not, so the maintenance burden is usually smaller than the fragmentation suggests.