Context files that actually work: a field guide for coding agents

Every AI coding agent now reads a context file, CLAUDE.md, AGENTS.md, .cursorrules, whatever your tool calls it. And most of them are useless: vague aspirations ("write clean code"), stale commands, and rules nobody enforces.

The difference between a context file that works and one that's decoration comes down to a few patterns we've seen hold up across Claude Code, Cursor, and the rest.

1. Rules beat wishes

"Write clean, maintainable code" changes nothing. The agent already tries. What changes behavior:

• Hard rules: "Never use a raw hex value, always a design token." "Every DB migration must be reversible."
• Conventions with examples: "Components live in components/, one per file, named PascalCase.tsx." Then show one.
• Anti-patterns: "Don't add a new dependency without asking. Don't refactor unrelated files in the same change."

Agents follow concrete constraints. They ignore philosophy.

2. Put commands where the agent looks

The single highest-value section in any context file is the boring one: how to build, test, and lint.

## Commands
- Build: `npm run build` (must pass with zero errors before committing)
- Test: `npm run test -- <file>`
- Lint: `npm run lint`

Without this, the agent guesses, and guesses wrong, burning loops on commands that don't exist in your repo.

3. Keep it short enough to survive

Context files compete with your actual code for the agent's attention window. The pattern that works: one page of essentials at the root, details colocated where they're used.

• Root AGENTS.md: commands, hard rules, repo layout (under 100 lines)
• components/AGENTS.md: component conventions, only if they differ
• Deep dive docs: linked, not inlined, "see docs/auth.md for the auth flow"

If your context file is 500 lines, the agent is skimming it. Write for the skim.

4. Version it like code

Context files rot faster than code: commands change, rules get superseded, new tools arrive. Treat staleness as a bug:

• Review the file when onboarding breaks or the agent "forgets" something twice
• Delete rules that stopped mattering; a wrong instruction is worse than none
• Note the date of the last review at the top

5. Test the file, not just the code

The fastest way to improve a context file: watch a fresh agent session and note every time it does something the file should have prevented. Each of those is a missing or unclear rule. Two sessions of this usually halves your correction rate.

The checklist

• Build/test/lint commands, verified current
• 3–5 hard rules (things that must never happen)
• Conventions with file paths and one example each
• Anti-patterns from your actual history
• Under ~100 lines at root; details linked or colocated
• Last-reviewed date at the top

Context engineering isn't prompt magic. It's documentation discipline: the same skill that makes a good README makes a good agent. The teams getting the most from coding agents aren't writing better prompts; they're writing better repos.