Context management for coding agents

Context management for coding agents is the practice of controlling what Claude Code, Codex, or Cursor holds in its context window: instruction files, file reads, command output, and conversation. Too little context makes the agent guess; too much makes it drift from earlier instructions. The fix is tight scoping, timely resets, and a check of what the agent works from.

In the morning the agent fixed a bug cleanly. By afternoon, in the same chat, it edits a module your rules put off limits. This section is for developers who drive agents daily and tech leads who own shared instruction files.

Which context page solves your problem?

Start from the symptom; each page owns one layer.

Symptom	Page
The agent forgets rules mid-session, or quality drops after auto-compaction	Context windows and token limits
The agent ignores or misreads CLAUDE.md, AGENTS.md, or Cursor’s Rules	Documentation as context
The instruction file has grown to hundreds of lines of one-off fixes	Pruning context files
The agent reads a whole directory to change one function	Project structure for agents
The agent cannot find the right code, or finds the wrong copy	Code search and indexing
Every new session relearns what the last one discovered	Long-term context retention
The token bill rises faster than the work delivered	Context cost optimization

Three habits that prevent context problems

Every good prompt carries intent (what to change and what “done” means) and state (the files, errors, and test output that describe the code now). A bad session lacks one of them, or buries the intent under state. These three habits keep the balance:

1. One task per session. Leftover exploration pulls edits toward stale files.
2. Name the exact files. Point at the function or file, not the directory, so reads stay small.
3. Keep a short instruction file. Build, test, and lint commands plus the conventions the agent gets wrong, so no session spends tokens rediscovering them.

The commands differ by tool:

Claude Code

• Measure: /context draws current usage as a grid by category.
• Reset: /clear starts a new session with empty context; the old one stays resumable with /resume.
• Compact: /compact followed by what to keep, for example /compact keep the acceptance criteria and the test command.
• Point at files: type @ and a path to attach a file to the prompt.
• Instructions: CLAUDE.md; /memory edits it. From v2.1.277 (the latest channel), Claude Code reads AGENTS.md when a project has no CLAUDE.md (v2.1.281 on Bedrock, Google Cloud, Foundry, and LLM gateways); toggle it under Project instructions in /config.

Checked on 2026-09-26 against Claude Code 2.1.283 (the latest channel).

Codex

• Measure: /status shows the session configuration and token usage.
• Reset: /new starts a new chat; /clear also clears the terminal.
• Compact: /compact summarizes the conversation to stay under the context limit.
• Point at files: /mention attaches a file; start in the right directory with codex -C DIR.
• Instructions: AGENTS.md; /init creates one. Codex loads a project’s AGENTS.md only when you trust the project (since 0.150.0); if it seems ignored, check trust first.

Checked on 2026-09-26 against Codex CLI 0.157.1.

Cursor

• Reset: start a new chat for each task.
• Point at files: @-mention the files the task needs instead of letting the agent search.
• Instructions: Rules (project rules in Cursor). See Cursor context management for rule scoping.
• When a chat drifts: write a handoff note and start a new chat; see token management in Cursor for usage tracking.

Cursor details last checked against Cursor’s documentation on 2026-08-28.

Prompts that set and check the agent’s context

Copy-paste prompt: start a task with intent and state

Task: make POST /api/subscriptions/cancel idempotent. A second cancel request for an
already-cancelled subscription must return 200 with the current state, not 500.

State: the handler is src/routes/subscriptions/cancel.ts; persistence is in
src/db/subscriptions.ts. The failing case is reproduced by
tests/subscriptions/cancel.test.ts ("cancels twice").

Scope: read only those three files and anything they import directly. Do not open
other directories without asking. Done when `npm test -- cancel` passes and no other
file changes.

Copy-paste prompt: show what you are working from

Before you change anything, list:
1. Every instruction file and rule you loaded for this session, by path.
2. The constraints from those files that apply to this task, quoted verbatim.
3. The files you have read so far.
4. The command that will prove this task is done.
Mark anything you are assuming rather than reading from a file. Do not edit code yet.

How do you know the agent had the right context?

Skip the transcript. Three checks take seconds; the fourth is for instruction-file edits:

• Restate and compare. Run the second prompt at the start and again after any compaction. A missing or reworded constraint means the context was lost; point the agent back at the file before it writes more code.
• Tests as the oracle. The “done when” command decides whether the behaviour exists. See how strong your oracle is.
• Diff scope. git status --short should list only the files the prompt named, including new ones; an unexpected path means the agent lost scope.
• Measure instruction-file changes. Run the same task in a fresh session before and after you edit CLAUDE.md or AGENTS.md, at least three times each way. Compare the pass rate and git status --short, not one result. /context (Claude Code) or /status (Codex) shows what the edit costs in tokens.

The developer owns the restate check; the reviewer owns tests and diff scope. Shared instruction files change through code review with a named owner.

When context management goes wrong

• A decision from earlier in the session disappears. Compaction summarized it away. Write decisions and acceptance criteria to a file the agent re-reads; context windows shows a handoff note and a compaction hook.
• The instruction file keeps growing and adherence keeps falling. Every line competes for attention. Archive the file, log what the agent gets wrong, and restore a line only when the same mistake happens twice, following the ablation protocol.
• The agent follows an instruction nobody on the team wrote. Instruction files are supply chain: review them like code, and never let a CI agent holding secrets load them from an untrusted branch. See how to lock down what CI agents load.

Where to go next with context management

Context windows and token limits Measure the window, and decide when to compact, clear, or delegate.

Documentation as context Write instruction files that each tool loads and follows.

The agent harness Context alongside tools, permissions, hooks, skills, and environments.

Concise AGENTS.md and CLAUDE.md A short, scored version of a good repository instruction file.