A context file tells the agent what it can't infer fast from the code: how to run things, which conventions to follow, where the boundaries are, and what to leave alone. Keep it to one screen. Put commands, architecture, and conventions in; keep secrets, the full codebase, and aspirational rules out. Treat it as code — review it in PRs and delete lines that have gone stale. A wrong context file is worse than none, because the model trusts it.
What a Context File Actually Is
When an agent starts a task, it doesn't know your project. It can read files, but reading is slow and lossy — it samples a few directories, guesses at conventions, and fills the gaps with whatever was most common in its training data. That is where the off-key defaults come from: the test runner you don't use, the folder structure you abandoned, the import style your linter rejects.
A context file is the document the agent reads first to skip that guessing. Different tools look for different filenames — CLAUDE.md for Claude Code, AGENTS.md as an emerging cross-tool convention, a rules file for editor-based tools — but they all serve the same purpose: a small, high-signal brief that loads into context before the model does anything. The format barely matters. What goes in it is the whole game.
- Would the agent get this wrong without it? If the model already defaults to the right thing, the line is noise.
- Is it stable? Facts that change every week belong in the task prompt, not the standing file.
- Is it true today? A confidently wrong instruction is followed confidently.
What Belongs In It
The useful content falls into four buckets. If your file covers these and little else, it is already better than most.
1. Commands
How to install, run, test, lint, and build — the exact invocations, not a description of them. This is the highest-value section because the agent uses it constantly and gets it wrong constantly. If your tests run with pnpm test --filter web and not npm test, that one line prevents a dozen failed attempts.
2. Architecture in one paragraph
A short map of the major pieces and how they relate: where the API lives, where the UI lives, what the shared types package is, which directory is generated and should never be hand-edited. Not a diagram of every module — just enough that the agent puts new code in the right place instead of inventing a new one.
3. Conventions that aren't obvious from the linter
Your formatter already enforces spacing; don't spend lines on it. Spend them on the decisions a model can't derive: "use the existing Result type instead of throwing," "all dates are UTC and stored as ISO strings," "feature code goes in features/, never in lib/." Conventions a linter can catch belong in the linter, not here.
4. Boundaries
What the agent must not touch without asking: the migration history, the auth module, the public API surface, anything under a generated directory. Boundaries are the cheapest insurance in the whole file. One sentence — "never edit files in db/migrations/; create a new migration instead" — prevents an entire category of damage.
What to Keep Out
A context file fails more often from too much than too little. Every line you add dilutes the rest, and the model has no way to know which lines are load-bearing. Cut anything that isn't earning its place.
Secrets and credentials — the file is read by a tool and often committed to the repo; treat it as public. The whole codebase — pasting file trees and full module lists just burns context the agent could spend reading the actual code it needs. Stale aspirations — "we are migrating to GraphQL" that has been true for a year teaches the model to do the wrong thing. Generic best practices — "write clean code, add tests" is filler the model already knows; it crowds out the specific rule that actually matters.
The hardest one to cut is the rule you wrote for a problem that no longer exists. Context files accumulate these: a workaround for a bug that's fixed, a warning about a service that's gone. They read as harmless, but each one is an instruction the agent will dutifully follow into a wall.
Keep It Short
The single most common mistake is length. A context file that runs to several screens stops being read carefully — by you when you maintain it, and effectively by the model, which weighs a 2,000-word file differently than a tight one. Aim for something a new teammate could skim in under a minute. If it's longer than that, you're probably documenting things the code should document itself.
When a section genuinely needs depth — a complex deployment flow, a non-obvious domain model — link to a dedicated doc instead of inlining it. The context file is an index and a set of guardrails, not the manual. Most tools also support nested files: a directory-level AGENTS.md that only applies when the agent works in that subtree, so the root file stays lean.
# Project
One sentence on what this is and who uses it.
## Commands
Install: pnpm install
Dev: pnpm dev
Test: pnpm test
Lint: pnpm lint
## Architecture
apps/web — React UI. apps/api — Express API. packages/types — shared types.
## Conventions
- Dates are UTC ISO strings.
- Use the Result type; don't throw for expected errors.
## Boundaries
- Never edit db/migrations/ — add a new migration.
- Don't change the public API in packages/types without flagging it.
Maintain It Like Code
A context file is the only documentation in your repo that gets read on every single task. That makes its accuracy unusually valuable — and unusually expensive when wrong. The fix is to stop treating it as a README you wrote once and start treating it as code that ships with the rest.
- Review it in the PR. If a change moves a command or a convention, the context file changes in the same diff — or the diff isn't done.
- Delete on sight. When you notice a line that's no longer true, remove it then, not later. Stale lines never get cleaned up in a dedicated pass.
- Let the agent help. After a session where the agent guessed wrong about your project, ask it what one line would have prevented the mistake — then add that line.
- Prune on a schedule. Every month or so, re-read the whole file as if you were new. Cut anything you'd have to explain or apologize for.
The signal that your file is working is quiet: the agent stops making the same wrong assumption. When you find yourself correcting the same thing in prompt after prompt — the wrong test command, the wrong directory, the throw instead of the Result — that correction belongs in the file, not in your next message.
The File Is a Lever, Not a Wall
A context file won't make a model careful, and it won't substitute for review. What it does is remove an entire class of avoidable mistakes — the ones that come from the agent not knowing things you could simply have told it. That is a high return for a document that fits on one screen.
Write down what the agent can't infer, leave out what it can, and keep the whole thing true. The reward is an agent that starts each task already pointed in the right direction instead of guessing — and a lot fewer prompts spent correcting the same assumption twice.
Pair this with The AI Session Resume Packet, The AI Plan Before Code, AI for Technical Leads & Architects, and Running AI Agents in Parallel.