Agent Context Files: Operating Instructions for AI
CLAUDE.md and AGENTS.md are a new doc type — persistent operating instructions a coding agent loads every session. Every line costs tokens. Earn the line.
A New Document Type
The context file — CLAUDE.md, AGENTS.md, or whatever convention a given toolchain uses — is the newest entry in the documentation taxonomy. It emerged from the same shift that makes documentation a priority in the first place: coding agents that read files before touching code.
A README orients. A context file operates. The distinction matters. A README is written for humans scanning a repository for the first time and for agents making their first contact. A context file is written specifically for a coding agent that will read every word, take every rule literally, and operate inside this codebase on a recurring basis.
The consequence of that distinction: a context file carries a different class of content than a README. Not an overview of the architecture. Not the full history of the project. Not marketing for the team's choices. Instead: commands, hard rules, topology facts, known gotchas, and conventions — the minimum set of operational knowledge that, if missing, causes mistakes.
The hierarchy diagram shows three levels: global, project, and subdir. The override chain is simple — narrower scope wins. A project-level rule can override a global default; a subdir rule can override a project rule. This allows a global context file to define safe defaults (never commit to main, run tests before pushing) while individual projects or directories override where their context genuinely requires it.
The Anchor Incident
Here is a concrete case for what a context file can do.
A developer maintained a codebase across two machines: a dev laptop and a production server. Both machines had the same directory structure, the same file paths, the same localhost URLs pointing to local services. The git repos were in sync. Tests ran on both. Everything looked equivalent.
An agent session on the dev laptop worked through a full set of fixes. Every test passed. Every localhost check returned the expected results. The developer looked at the output and shipped. Production crashed immediately.
The production server was a separate machine. The agent had verified fixes on the dev laptop, which shared no runtime with the production server despite sharing the same file paths. The service on the production server was still running the old code. The fix required SSH-ing to the production machine, pulling the same changes already on main, and rebuilding the containers. Fifteen minutes of diagnosis once the topology was understood.
The rule extracted from that incident (Tailscale is a VPN whose status command prints a machine-unique address — any command that uniquely identifies the host would work just as well here):
## Hard Rules
Before any deploy or "this works in production" claim, run this command
to verify which machine you are on:
PATH=/opt/homebrew/bin:/usr/local/bin:$PATH tailscale status 2>/dev/null \
| awk 'NR==1 {print $1, $2}'
| Output | You are on | Implication |
|---------------------------------|--------------------|----------------------------------|
| 100.x.x.x dev-laptop | Dev laptop | DO NOT claim production is fixed |
| 100.x.x.x prod-server | Production server | Changes here affect real traffic |
One rule in the context file, three lines of table. The class of mistake became impossible to repeat: every subsequent agent session reads the rule before doing anything, runs the check when the situation arises, and knows that a successful localhost check on the dev laptop is not a production verification.
This is the value proposition of a context file in its sharpest form. Not documentation for humans to read during onboarding. Executable context that prevents a specific, costly mistake from ever happening again.
What Belongs (and What Doesn't)
The tradeoff matrix is the tool for every context file decision. The earn-the-line test is the filter:
Keeps the line: Removing it would cause a mistake, or force the agent to rediscover something that is costly to learn.
Remove it: Removing it loses nothing because the agent can read the code, or the rule is never violated anyway.
Move it: The content is valid but belongs at a different scope — global rules at global scope, module-specific rules at module scope.
The patterns are consistent:
Always in: Commands. An agent needs npm run dev and npm test on every session. These are zero-stale, high-value, low-cost. The context file is the right place.
Always in: Hard rules. "Never commit to main." "Never git add -A in this repository." "Always run the host-check before any deploy claim." Rules that prevent costly mistakes earn every token they cost.
Always in: Environment facts. "The production server is the remote machine. Local tests do not prove production works." Topology facts are stable, high-value, and the agent has no other way to know them.
Out: Stale state. "We are currently migrating to the new schema." This was true on day 1 and misleading on day 30. State that decays does not belong in a file that loads on every session.
Out: Prose essays. A 400-word explanation of why the team chose this architecture belongs in an ADR, not in a context file. An agent reading 400 words of philosophy is paying tokens for nothing actionable.
Out: Anything derivable from the code. The fields on the Lesson type are in types/academy.ts. An agent can read that file. Duplicating the type definition in the context file costs tokens, will drift, and serves no purpose.
Context File Structure
A minimal context file has four sections:
# CLAUDE.md — <repo-name>
## Commands
npm run dev # local dev server
npm run test # vitest unit tests (run before every PR)
npm run build # production build
npx tsc --noEmit # type-check only
## Key Files
| File / Dir | Purpose |
|-------------------------|----------------------------------------------------|
| lib/tracks.ts | Master track registry — lesson order, tier mapping |
| content/academy/ | MDX lesson files |
| components/mdx/ | MDX component overrides |
| app/(learn)/ | Learn routes: dashboard, lesson, track, exam |
## Hard Rules
- Never commit to main — feature branch + PR
- Never git add -A — stage explicit paths
- Run npm run test before pushing
## Known Gotchas
- A concurrent agent may have untracked WIP files — check git status
before staging anything
- The Vercel-served frontend reads the remote server's API — a local
backend check does not prove the live site works
Four sections. Commands first — an agent needs these before anything else. Key files second — orientation map. Hard rules third — the constraints that matter. Gotchas last — the things that bit the last person here.
Notice what is absent: no architecture overview, no sprint state, no type definitions, no philosophy. The file is terse by design. Every line has a job. Every line earns its place.
The Hierarchy in Practice
The override hierarchy enables a pattern that is difficult to achieve without it: global safe defaults that project-specific contexts can override where the situation genuinely requires it.
Global context file (applies to all repositories):
- Always create feature branches — never commit to main
- Run the full test suite before pushing
- Run sec-scan before adopting any new repository
Project context file for a specific prototype (overrides global):
- This is an internal prototype — direct main commits are acceptable
during the initial build phase
The override is explicit, local to the project, and readable in a PR. It is not "someone's memory of a decision made in a meeting." It is auditable and discoverable. When the prototype graduates to a real service, removing the override automatically reinstates the global rule.
Building the Context File Habit
The context file is not something you write at project creation and forget. It is a living document with a specific update trigger: corrections. When an agent makes a mistake — when a PR is wrong, when a deployment fails, when a test breaks for a reason the agent could not have known — the correction becomes a rule, and the rule goes in the context file.
This is the compounding loop from the “Documentation is King” lesson in its concrete form. One incident, one rule, one line in the context file. The next agent session reads the line. The mistake cannot recur.
The discipline is small: after every correction, ask "what rule would have prevented this?" Write that rule. Keep the line. Let it compound.
Now author one. Take a repository you work in regularly and write the CLAUDE.md it deserves — not the one that captures everything, but the one that earns every line.