Start With A Router, Not A Briefing
A coding agent is different from a chat model because it can use tools. A tool might let it read files, edit code, run tests, search a repo, open a browser, or call an external service through MCP, which is a standard way to connect agents to apps and APIs. Because the agent can go look things up, your project context file should not try to explain the whole project up front. Its job is to route the agent.
Use `AGENTS.md`, `CLAUDE.md`, or the equivalent file your agent reads automatically as a short map of the repo: what the project is, which folders matter, where rules live, how to test, and what the agent should never touch. The failure mode is stuffing it with architecture essays, old gotchas, meeting notes, and every preference you have ever written. That burns context before the agent has even inspected the task.
A useful starting shape is simple: one paragraph for the product, one section for commands, one for folder pointers, one for coding rules, and one for safety limits. Instead of pasting the database schema into the file, point to `docs/schema.md`. Instead of explaining every deployment edge case, point to `docs/deploy.md`. The agent can load those only when the task calls for them.
Make Context Progressive
Once the root file is a router, the next step is to organize the files it points to so the agent can drill down without reading everything. This is progressive context: the agent starts with an index, follows the relevant pointer, then reads the narrower file. It is often more reliable than hoping the model remembers a huge prompt or searching blindly through a pile of notes.
For a small project, this can be as basic as `docs/index.md`, `docs/architecture.md`, `docs/testing.md`, and `docs/api.md`. For a larger knowledge base, add indexes at each folder level. A top-level index says what exists. A folder index says what belongs in that area and when to read each file. This gives the agent a path like: root rules, then docs index, then payment architecture, then the one integration note it actually needs.
Keep evergreen context separate from noisy context. Evergreen context includes product goals, architectural decisions, naming conventions, and folder responsibilities. Noisy context includes Slack threads, raw call notes, emails, logs, and one-off debugging transcripts. Store raw material if you need it, but do not make the agent ingest it by default. Summarize durable decisions into cleaner markdown and link to raw files only for audit or detail.
Write Rules That Change Behavior
After the map comes rules, but rules should earn their place. Good rules prevent repeated mistakes: “Do not edit generated files in `src/generated`; update the schema and regenerate.” “Use `pnpm test:unit` before claiming a frontend fix is done.” “Never mix client data between folders under `clients/`.” These are short, enforceable, and tied to real failure modes.
Bad rules are vague, stale, or model-shaped: “Be careful,” “write great code,” “always think step by step,” or long instructions added because an older model struggled. Agents improve, repo structure changes, and workflows move. Review the file after major model or tool changes and delete instructions that no longer carry weight. Every stale sentence competes with the task for attention.
For critical safety rules, prefer tool-level controls when your agent supports them. A prompt can say “never delete important directories,” but a pre-tool hook or approval rule can actually block dangerous commands. Use the context file to document those boundaries, then enforce the highest-risk ones outside the model. Prompts guide judgment; hooks stop accidents.
Promote Repeated Work Into Skills Or Sub-Agents
A clean context file also tells you when not to keep adding to it. If you notice the same multi-step workflow appearing again and again, turn it into a separate skill, playbook, or command file. A skill is a reusable procedure: inputs, steps, checks, and expected output. For example, “prepare release notes,” “investigate flaky test,” or “triage support log” should not live as giant paragraphs in `AGENTS.md`.
Sub-agents are useful when work can be delegated as a bounded role. Think of a sub-agent as another agent thread with a job: inspect one folder, review one migration, summarize one document set, or verify one proposed change. They are powerful because they can work in parallel, but they add coordination cost. Do not create five permanent agents on day one. Start with a written workflow, use it manually, and only materialize a sub-agent when the responsibility is stable.
The root file can point to these workflows without loading them. For example: “For release work, read `skills/release.md`.” “For database investigations, use `docs/db/index.md` first.” “For large docs migrations, split by folder and give each sub-agent the same format spec.” This keeps the everyday context lean while still making deeper capability available.
Maintain The Map Like Code
The final habit is maintenance. Treat project context as part of the codebase, not a magical prompt you write once. When the agent fails because it missed a folder, add a pointer. When it repeats bad advice, add a concrete rule. When a rule stops mattering, remove it. When a playbook becomes routine, move it out of the root file and link to it.
A practical review rhythm is enough: skim the root file monthly, after major model upgrades, and after big repo changes. Check whether commands still work, folder names still exist, rules still match reality, and linked docs are still the best source of truth. If you maintain many skills, agents, or integrations, keep a small “rot” note that says what should be reviewed weekly, monthly, or only when broken.
The point is not to make the agent know everything. The point is to make it know where to look, what boundaries to respect, and when to ask for more context. A good `AGENTS.md` or `CLAUDE.md` is short enough to stay loaded, specific enough to shape behavior, and connected enough that the rest of the project is only one pointer away.
Key takeaways
- Use `AGENTS.md` or `CLAUDE.md` as a routing map, not a place to paste the whole project history.
- Organize docs with indexes and folder pointers so the agent can load context progressively.
- Keep evergreen decisions separate from noisy raw material like logs, emails, and meeting transcripts.
- Add rules only when they prevent real repeated failures, and prune stale rules after model or repo changes.
- Move repeated workflows into skills or playbooks, then create sub-agents only when a role is stable.
- Use hooks and approvals for dangerous actions; prompts should guide behavior, not be your only safety layer.