Short answer

Context engineering for a large codebase means controlling what an AI coding agent reads. Keep one short instruction file, CLAUDE.md or AGENTS.md, with the commands, boundaries and rules it cannot guess. Load narrower rules only for the paths they cover. Let the agent search instead of preloading files. End every task with a checkable definition of done, and delete stale docs.

What is context engineering?

Deciding what goes into the model's context window, and what stays out, for the whole run. Anthropic frames it as finding the smallest set of high-signal tokens that gets the outcome. In a large repository the risk is rarely too little information. It is the wrong information, loaded first and followed confidently. Manage three layers:

  • Standing instructions that load every session.
  • Scoped rules that load only when the agent touches certain paths.
  • Evidence the agent finds for itself during the task: the file, its callers, its tests, the logs.

CLAUDE.md and AGENTS.md best practices: what belongs in the file?

What an experienced engineer would tell a new colleague before a first change, and nothing a linter enforces. Claude Code reads CLAUDE.md. AGENTS.md is the cross-tool convention started by OpenAI, now stewarded by the Agentic AI Foundation, and read by Codex, Cursor, Gemini CLI, GitHub Copilot and others. As of September 2026, Claude Code also reads AGENTS.md when a repository has no CLAUDE.md, and a CLAUDE.md can import it with @AGENTS.md so there is one source for every tool.

# Payments service

## Commands
- Test one package: pnpm test --filter @acme/ledger
- Typecheck before any commit: pnpm typecheck
- Never run migrate:prod. Migrations go through the release job.

## Boundaries
- packages/ledger is the only code that writes to the ledger tables.
- src/gen/ is generated from openapi.yaml. Edit the spec, then run pnpm gen.
- Changes under infra/ need a platform reviewer. Say so in the PR.

## Done means
- Tests for the changed package pass and typecheck is clean.
- New endpoints have an integration test.
- The PR description lists what you did not test.
  • Keep it short. Anthropic's Claude Code docs target under 200 lines per CLAUDE.md, because longer files are followed less well.
  • Write rules as rules, with the exact command, path or name.
  • Remove contradictions. If two rules disagree, the agent may pick either.

How do you scale instructions across a monorepo?

  • Nest instruction files. A CLAUDE.md or AGENTS.md inside a package applies when the agent works there. Keep the root file for what is true everywhere.
  • Scope rules to paths. Claude Code's .claude/rules/ files can carry a paths field so, for example, database rules load only when the agent opens migration files.
  • Exclude what is not yours. Claude Code's claudeMdExcludes setting skips other teams' instruction files that are irrelevant to your work.
  • Remember imports are not lazy. A file pulled in with @path loads at launch like the file that imports it. Use it for organization, not to save context.

How should an agent spend its context on a task?

On evidence it finds, not files you guessed it would need.

  • Point, do not paste. Name the entry file, the failing test or the ticket, and let the agent search for callers and interfaces.
  • Ask for the plan before the edit on anything that crosses a package boundary, and read it.
  • Send exploration to a sub-agent where the tool supports it. In Claude Code a sub-agent has its own context window and returns a summary, so a wide search does not crowd the main task.
  • Start fresh between unrelated tasks instead of carrying one long session across all of them.

Why are stale docs worse than missing ones?

An agent follows a wrong instruction as confidently as a right one. A missing doc makes it search. An outdated doc sends it the wrong way.

  • Delete obsolete setup steps rather than marking them old.
  • Link each rule to the test, script or config that proves it, so it breaks visibly when it stops being true.
  • Review instruction files when a pull request changes what they describe. Claude's Code Review flags code changes that make a CLAUDE.md statement outdated.
  • Instructions are context, not enforcement. Use a hook when an action must be blocked whatever the model decides.

Common questions

What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is Claude Code's own file of project instructions. AGENTS.md is a cross-tool convention read by Codex, Cursor, Gemini CLI, GitHub Copilot and others. Claude Code reads AGENTS.md when there is no CLAUDE.md, and a CLAUDE.md can import it so every tool shares one set of instructions.

Will an AI coding agent always follow the instructions file?

No. The file is context the model reads, not a setting it must obey, and conflicting or vague rules are followed inconsistently. For anything that must never happen, such as running a production migration, enforce it with a hook, permissions or CI rather than a sentence.

Should I let the AI write the instructions file?

It is a reasonable first draft. Claude Code's init command reads the repository and proposes a CLAUDE.md. Then cut it hard: remove anything a linter enforces, anything obvious from the code, and anything you cannot check, and add the rules only your team knows.

What is a definition of done for an AI coding task?

A short list the agent can check before it hands over: which tests must pass, which checks must be clean, what must be added, and what the pull request must say, including what was not tested.

Related reading