Coding agent context fills up: put constraints in a file

In a long coding agent session, the constraint you gave in your first message is the one most likely to get lost. Every file the agent reads and every command output lands in the same context window, which the agent summarises when it fills. Claude Code’s docs say it plainly: “detailed instructions from early in the conversation may be lost.”

So manage the window on purpose. Keep what the agent reads small. Write decisions and constraints to a file it can read again. Explore in a separate context, clear between unrelated tasks, and hand long tasks over with a note. Below are the commands to see, compact and clear context in five coding agents, a task notes template and three prompts.

This is part 14 of the series. Part 1 covered the files that load before you type, and Part 5 covered skills that load only when needed. This part is about the window during a task.

Claude Code is the worked example. The tool behaviour below comes from each tool’s official docs and Anthropic’s engineering post on context engineering. It was last verified on 11 October 2026; none of it was tested for this post.

A long session buries the constraint you gave first

The context window is everything the model can consider in one request, measured in tokens. Anthropic’s best practices list what goes in. “Claude’s context window holds your entire conversation, including every message, every file Claude reads, and every command output.” The same page warns that “a single debugging session or codebase exploration might generate and consume tens of thousands of tokens.”

before you type   system prompt, instructions files, memory,
                  tool definitions, MCP server instructions
during the task   your prompts and corrections
                  every file the agent opens
                  test runs, logs, command output
                  sub-agent results

A fuller window has a cost. Anthropic’s engineering post, Effective context engineering for AI agents, calls it context rot. In its words, “as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases.” OpenAI’s Codex subagents docs add a second name, context pollution: “useful information gets buried under noisy intermediate output.”

The same post sets the goal: “the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome.” For a coding task, high-signal means the goal, the constraints, the files that matter and the result of the last check. A long test log with one failing line is mostly noise.

MCP servers count too. In Claude Code, MCP tool definitions are deferred by default, so “only tool names and server instructions consume context until Claude uses a specific tool” (docs). GitHub Copilot CLI’s /context lists MCP tools as their own line (docs), and Cursor’s context breakdown has an MCP category (docs). Claude Code’s cost docs suggest running /mcp and disabling servers you are not using.

Compaction keeps your files and summarises your chat

Compaction is what an agent does when the window gets close to full: it replaces older conversation with a summary. Most agents run it on their own, and you can run it by hand.

Claude Code documents what compaction keeps. “It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved,” says its how it works page. Its context window page lists what survives:

The memory docs name the trap. If an instruction disappeared after compaction, “it was given only in conversation”, or it lives in a file that has not reloaded yet. Their fix is “Add conversation-only instructions to CLAUDE.md to make them persist” (docs).

Other agents say the same in their own words. GitHub Copilot CLI’s context docs list what may not make it into the summary. That includes the exact wording of messages, the full output of commands and “minor decisions made early in a long conversation”. They also warn: “You can’t reverse a compaction once it has completed.” VS Code’s context docs say details from earlier messages “might be summarized or omitted”.

See, compact and clear context in five coding agents

Every agent below gives you the same three moves under different names: look at what fills the window, summarise it, or start clean.

Not clearing has a name in Anthropic’s best practices: “the kitchen sink session”. That is one task, then an unrelated question, then back to the first task, with the context “full of irrelevant information”. The same page says that after correcting Claude more than twice on the same issue, “the context is cluttered with failed approaches”. It adds: “A clean session with a better prompt almost always outperforms a long session with accumulated corrections.” Clearing is also cheap. Claude Code’s cost docs note that /compact reads the whole conversation it summarises, while “/clear costs nothing”.

Every row comes from the linked docs, last verified on 11 October 2026; none was tested for this post. Gemini CLI’s docs also note that for unpaid tier and Google One users, Gemini CLI was replaced by Antigravity CLI on 18 June 2026.

Keep decisions and constraints in a task notes file

You can steer a summary. Claude Code, Copilot CLI and Copilot in VS Code take a focus after /compact, like /compact focus on the auth module. Claude Code also reads a # Compact instructions section in CLAUDE.md (cost docs). But a summary is still a summary. A constraint that lives only in chat can be summarised away. One that must hold needs to be written down.

Project-wide rules belong in AGENTS.md or CLAUDE.md, as Part 1 set out. The state of one task needs a smaller home: its goal, the limits you agreed, what was decided and what is left. A notes file the agent updates as it works can hold it. Anthropic’s engineering post describes the pattern: “Like Claude Code creating a to-do list, or your custom agent maintaining a NOTES.md file, this simple pattern allows the agent to track progress across complex tasks, maintaining critical context and dependencies that would otherwise be lost across dozens of tool calls.”

Saved memory is not the same thing. Windsurf, now documented as Devin Desktop, has a legacy Cascade agent that can write memories on its own. Its memories docs still recommend a file: “For knowledge you want Cascade to reliably reuse, write it as a Rule or add it to AGENTS.md in your repo rather than relying on auto-generated Memories.”

An example task notes file might look like this:

# Task: <one line: what this change does>

## Goal
<what "done" looks like, and how it will be checked>

## Constraints (do not change without asking)
- <for example: the public API of the orders module stays the same>
- <for example: no new dependencies>

## Decisions
- <date>: <what was decided>. Why: <reason>

## Rejected approaches
- <what was tried or considered>. Why not: <reason>

## Done
- <change>, in <file path>

## Next
- <the next step, small enough for one session>

## Checks
- <test, lint and build commands, and their last result>

## Open questions
- <anything waiting on a person>

Rejected approaches get their own heading because a summary can keep what was tried and lose why it failed. Once the task is merged, anything that should outlive it, such as a design decision, moves to the project’s decision log (Part 1’s DECISIONS.md).

Explore in a separate context, then implement in a clean one

Exploration is the noisiest part of a task. Reading many files to find the few that matter fills the window with the ones that don’t. A sub-agent does that reading in its own context window and sends back a summary. Claude Code’s best practices put it as “Subagents run in separate context windows and report back summaries”. Codex, Cursor and Copilot in VS Code document the same isolation (Codex, Cursor, VS Code).

Anthropic’s engineering post gives a sense of the scale: a sub-agent “might explore extensively, using tens of thousands of tokens or more, but returns only a condensed, distilled summary of its work (often 1,000-2,000 tokens).”

A sub-agent does not know your constraints unless you pass them on. Cursor’s docs say “Subagents start with a clean context”, so the parent has to put what matters in the sub-agent’s prompt. And isolation costs tokens: Codex’s docs say sub-agent workflows “consume more tokens than comparable single-agent runs”. VS Code’s docs add that “Context isolation is not code isolation”. On its own, isolation does not give the sub-agent a separate worktree or sandbox.

A separate session does the same job without sub-agents. Anthropic suggests writing a spec first, then starting “a fresh session to execute it. The new session has clean context focused entirely on implementation” (best practices). VS Code’s context engineering guide says to keep “planning, coding, testing, debugging” in separate chat sessions. What to explore before a change is Part 8; running several agents at once is Part 13.

Long logs deserve the same treatment. Claude Code’s cost docs suggest sending test runs and log processing to a sub-agent. That way “the verbose output stays in the subagent’s context while only a summary returns”. By default, Copilot CLI saves any tool output over 20 KiB to a temporary file. The model gets the path and a preview (docs). Which lines of a log count as evidence is Part 9.

Hand off a long task with a note, then start clean

A long task outlives one context window. At some point you choose between compacting, clearing and handing off:

Copilot CLI’s docs draw the same line. They say to start a fresh session when “The conversation has gone through many compactions, and you feel that important context is being lost in the summarization process” (docs). Resuming an old session, with /resume in Claude Code or Gemini CLI, brings back the full history. A handoff note brings back only what matters.

The new session should not trust the note blindly. It reads the note and the files the note names, then says back the goal and constraints. It checks them against the code before it changes anything. If the note and the code disagree, that is a question for you, not a guess for the agent.

Three prompts for long tasks

Each prompt is an example to adapt. Prompt 1 needs sub-agents, which Claude Code, Codex, Cursor and Copilot in VS Code have. In other agents, run it in a separate read-only session instead.

Prompt 1: explore in a separate context

Use Prompt 1 at the start of a task that touches code you don’t know well.

Task: <describe the task>

Use a sub-agent to explore before we change anything.
If you cannot start a sub-agent, explore yourself
without editing any file.

Give the sub-agent this brief:
- the task above
- these constraints: <list them>
- read only what this task needs
- do not edit, create or delete files
- never print, expose or commit secret values

Return a summary of no more than 40 lines:
1. Files that matter, each with its path and one line on why
2. Entry points and the call path for this task
3. Existing code or patterns to reuse
4. Risks and edge cases
5. What was not checked, and open questions

Do not include raw file contents or full command output.
Do not commit, push, deploy, run destructive commands or
make external changes unless I explicitly authorise it.
If two reasonable attempts fail, stop and report the
failure rather than repeatedly guessing.

Prompt 2: write the handoff note

Use Prompt 2 before you compact a long session, clear it or stop for the day.

Task: <describe the task>

Before this session ends, update TASK-NOTES.md so a new
session can continue without this conversation.

Write these sections: Goal, Constraints, Decisions (with
the reason), Rejected approaches (with the reason), Done
(with file paths), Next, Checks (commands and their last
result), Open questions.

Copy the constraints I gave in this session word for word.
Record only what happened in this session or is in the
repository. Mark anything you are not sure about as
"unverified".

Change no file other than TASK-NOTES.md.
Never print, expose or commit secret values, and never
copy them into the notes.
Do not commit, push, deploy, run destructive commands or
make external changes unless I explicitly authorise it.
If two reasonable attempts fail, stop and report the
failure rather than repeatedly guessing.

Read the note before you clear: a constraint missing from it is missing from the next session too.

Prompt 3: resume from the handoff note

Use Prompt 3 as the first message of the new session.

Task: <describe the task>

Read TASK-NOTES.md first, then only the files it names.

Before changing any code, tell me in five lines or fewer:
the goal, the constraints, and the next step.
Then check the notes against the repository. If a file,
decision or check result in the notes does not match the
code, stop and ask me.

After I confirm, do only the next step, run the checks
listed in the notes, and update TASK-NOTES.md.

Never print, expose or commit secret values.
Do not commit, push, deploy, run destructive commands or
make external changes unless I explicitly authorise it.
If two reasonable attempts fail, stop and report the
failure rather than repeatedly guessing.

A context checklist for long tasks

An example checklist for a long task:

• The goal, constraints and checks are in a file the agent can read again.
• Exploration ran in a sub-agent or a separate session, and only a summary came back.
• Long logs went to a sub-agent or a file; the main chat got the lines that matter.
• MCP servers the task does not need are turned off.
• You compact with a focus before a new phase, while the window still has room.
• You clear between unrelated tasks.
• Before you clear a long task, the notes file is up to date and you have read it.
• The new session checks the notes against the code before it edits.

Quick answers

What is context engineering for coding agents?

Context engineering for coding agents is the work of choosing what sits in the agent’s context window during a task. The goal, the constraints, the files that matter and recent check results stay in. Long logs, old attempts and unrelated chat are kept out or summarised.

What happens when a coding agent’s context window is full?

When a coding agent’s context window fills, agents such as Claude Code, Codex, Cursor and GitHub Copilot compact it. Older conversation is replaced by a summary. Files on disk can be read again afterwards, but detail that existed only in the chat may be lost.

Should you compact or clear a coding agent’s context?

Compacting keeps a summary of the current task and suits a long task that needs more room. Clearing starts with an empty conversation and suits a new, unrelated task, or a session full of failed attempts and repeated corrections.

Do sub-agents save context?

Sub-agents in Claude Code, Codex, Cursor and GitHub Copilot work in their own context window. Their file reads and tool output stay out of the main conversation, and only a summary comes back. They use more tokens in total.

How do you hand off a long coding agent task to a new session?

To hand off a long coding agent task, have the agent write a notes file. It should hold the goal, constraints, decisions, rejected approaches, progress, next step and checks. Start the new session from that file and have it check the notes against the code first.

More on AI coding is in the AI category.