# Context management for coding agents

URL: https://developertoolkit.ai/en/workflows/context/
Description: How to keep Claude Code, Codex, and Cursor working from the right context: which page fixes which problem, the reset commands, and how to check.

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](/en/workflows/context/context-windows/) |
| The agent ignores or misreads `CLAUDE.md`, `AGENTS.md`, or Cursor's Rules | [Documentation as context](/en/workflows/context/documentation-as-context/) |
| The instruction file has grown to hundreds of lines of one-off fixes | [Pruning context files](/en/workflows/context/pruning-context-files/) |
| The agent reads a whole directory to change one function | [Project structure for agents](/en/workflows/context/file-organization/) |
| The agent cannot find the right code, or finds the wrong copy | [Code search and indexing](/en/workflows/context/codebase-indexing/) |
| Every new session relearns what the last one discovered | [Long-term context retention](/en/workflows/context/memory-patterns/) |
| The token bill rises faster than the work delivered | [Context cost optimization](/en/workflows/context/cost-per-context/) |

## 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 (both release channels on 2026-10-12), 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](/en/cursor-ide/quick-start/context-management/) for rule scoping.
    - **When a chat drifts:** write a handoff note and start a new chat; see [token management in Cursor](/en/cursor-ide/operate/token-management/) 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**

```text
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**

```text
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](/en/workflows/test/oracle-strength/).
- **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](/en/workflows/context/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](/en/workflows/context/pruning-context-files/).
- **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](/en/workflows/harness/permissions-and-sandboxing/).

## Where to go next with context management

- [Context windows and token limits](/en/workflows/context/context-windows/) — Measure the window, and decide when to compact, clear, or delegate.
- [Documentation as context](/en/workflows/context/documentation-as-context/) — Write instruction files that each tool loads and follows.
- [The agent harness](/en/workflows/harness/) — Context alongside tools, permissions, hooks, skills, and environments.
- [Concise AGENTS.md and CLAUDE.md](/en/developer-scorecard-guide/claude-md-context/) — A short, scored version of a good repository instruction file.
