What each phase starts with
In this lesson we look at the moment between two phases of work, such as the end of planning and the start of implementation. A planning session fills its context window with the files it read and the ideas it tried, including the ones you turned down. When the plan is written, you choose what the next phase starts with: the same session, a new session that starts from the written plan, or a summary of the old one. Each choice keeps different things, and each costs something different. The page has no code to run.
The lesson builds on two earlier ones. Telling the agent where the task is and where it stops showed how to point an agent at a file by path, and a plan file is the file you point the next phase at. Directing the summary before compaction listed what Claude Code puts back after a compaction. This page uses that list to compare the options. Where it names a Claude Code feature it says so, and the vendor pages were checked on the date at the end of the lesson.
What a session holds before you type
Section titled “What a session holds before you type”A new session doesn’t start empty. Its starting context is everything
in the context window before your first message. In Claude Code that’s the
system prompt, the CLAUDE.md or AGENTS.md instructions, the auto-memory
notes, the names of the tools from connected Model Context Protocol (MCP)
servers and a one-line description of each skill [1].
Other agents load their own set, and most load an instructions file.
The starting context stays in the window for the whole session. Claude
Code sends the whole conversation with each request it makes
[2], and the starting context goes with it. A large starting context takes room
from the task in every session, including the short ones. In Claude Code
the /context command shows what fills the window, by category
[1].
To make it smaller, move instructions for one workflow, such as how to run
a database migration, out of CLAUDE.md and into a skill, which loads its
full text only when it is used. Also run /mcp to turn off the servers you
don’t use [2]. The lesson Writing project instructions the agent reads every session
gave a second reason to keep the instructions file short: the agent follows
a short file more reliably than a long one.
What do the 400 lines cost today?
Section titled “What do the 400 lines cost today?”A project's instructions file, loaded by the coding agent at the start of every session, has 600 lines. 400 of them describe a database migration that the team runs once a month. Today an engineer starts a session to fix one typo in a help text.
The engineer fixes one typo in this session and closes it. What did the 400 migration lines cost?
When does the agent load the instructions file, and what goes into each request after that?
Three ways to start the next phase
Section titled “Three ways to start the next phase”Take a planning session on the to-do program from earlier lessons. You asked
the agent for a due <n> <date> command. It read todo.py, store.py and
the tests, and tried two date formats. You turned down free-text dates,
because the list must sort by date. In the chat you also reminded the
agent not to edit legacy/. The agent wrote the plan to PLAN.md:
five steps, the files to change and the test to write first. The plan is
done, and implementation comes next. Here is what each option starts it
with.
Continue in the same session. The next phase has everything: each file the agent read, each command output and each idea you turned down, word for word. That history is also the problem. As the context window fills, the agent follows earlier instructions less well and makes more mistakes [3]. Every request in the implementation phase also sends the whole planning conversation again [2].
Clear, and start from the written plan. In Claude Code, /clear starts
a new session [2]. The next phase has the starting context,
the repository with its uncommitted changes and the files you point it at,
and nothing from the conversation. Once a spec is finished, the
best-practices page recommends a new session for the implementation
[3]. The costs page adds that /clear
costs nothing [2]. What you lose is anything that was said
and not written down.
Compact, then continue. /compact replaces the conversation with a
summary. After it, Claude Code reads the project-root CLAUDE.md, the
auto-memory notes again from disk, and the plan from plan mode, which is
Claude Code’s own plan file. It also reads up to five of the files the agent
read or edited, the most recently modified first. A PLAN.md that the agent
wrote into the repository is one of those files, so it comes back only when
it is among the five. What the commands printed and the steps the agent reasoned
through are not kept word for word [1]. When a big
piece of work comes next, the context-window page suggests /compact with
instructions that name what the summary keeps [1].
A compaction of a long conversation is itself a large request, because the
agent reads all of it to write the summary [2]. And a
summary can drop a detail whose importance shows only later
[4].
Two more options are variations on these. A handoff file is a written plan for a session that is not done: what was done, what is left and what was decided. And a subagent starts with a clean context of its own and reports back a short summary, so a large search stays out of your window [4].
What does implementation start with?
Section titled “What does implementation start with?”A coding agent session in Claude Code has just finished planning a new command, and the plan is in PLAN.md in the repository. The engineer is choosing how the implementation phase starts: going on in the session, running /clear and pointing the new session at PLAN.md, or running /compact and going on.
Match what the implementation phase has at its start with the option that gives it.
Which option keeps the conversation word for word, which keeps a summary of it, and which keeps none of it?
Decide at the boundary
Section titled “Decide at the boundary”Deciding at a phase boundary is choosing what the next phase starts with when one phase ends. The sources give no rule for it, but they point at one question: does the next phase go on with the same problem, or start a new one?
Implementation that follows a finished plan is a new problem. It needs the plan, the files the plan names and the reasons behind the plan’s choices. It doesn’t need the planning conversation, so clear, and start from the plan file. A debugging session in the middle of one hard bug is the other case. The same best-practices page says that a long history can be worth keeping while you work on one hard problem [3]. Between the two, the context-engineering article matches compaction to work with a long exchange of turns on one problem, and notes in a file to work that moves in planned steps [4].
Whatever you choose, do one step first: write down what the next phase
must keep. Clearing drops the whole conversation, and compacting keeps only
what the summary states. In the planning session above, that is the reason
you turned down free-text dates. Add it to PLAN.md and read the file back.
Then clear, and start the new session with a brief that points at it:
Implement the due command as PLAN.md describes. Start with step 1, the test.The rule about legacy/ that you typed in the chat an hour ago needs no
line, because it is already in AGENTS.md, and the new session loads that
file. A rule that is only in the chat needs a line in a file, or it is gone.
Planning is done
Section titled “Planning is done”An engineer and a coding agent spent two hours planning a new command. The session read many files, tried two approaches in scratch scripts, and the engineer turned one down for a reason given in the chat. The agent then wrote a five-step plan to PLAN.md that names the files and the first test. The engineer added the turned-down approach and its reason to PLAN.md and read the file. The context window is about two thirds full.
What does the implementation phase start with?
Does implementation need the two hours of exploration, or what is in PLAN.md?
Still there after /clear?
Section titled “Still there after /clear?”An engineer runs /clear in Claude Code at the end of a planning session, which starts a new session in the same repository. A new session loads its starting context, including the instructions file, and reads files in the repository when it needs them or is pointed at them. The conversation before /clear is not in it.
Sort each item by what the session after /clear has of it.
Is the item in a file on disk, or was it only said or shown in the conversation?
An hour into one bug
Section titled “An hour into one bug”An engineer has worked with a coding agent for an hour on one hard bug in one session. Together they ruled out three causes, each with a test run whose output is in the conversation. The context window is about a quarter full, and the next step is to test a fourth cause. That test reuses the setup and the outputs of the earlier runs.
What should the next step start with?
Has a phase ended, and does the next step need the history of what was ruled out?
Every session, or only when used?
Section titled “Every session, or only when used?”In Claude Code, some content is in the context window before the first message of every session and goes with each request. Other content enters the window only when the task uses it. The project has an instructions file, two connected MCP servers and three skills.
Sort each item by when it enters the context window.
Is it there before you type anything, or does something in the task have to call for it?
Exercise
Judge one phase boundary on paper. A session has just finished planning a
tag <n> <word> command for the to-do program. Over ninety minutes it read
todo.py, store.py and the tests, and tried two ways to store tags in a
scratch script. You turned down storing tags as part of the item text,
because the list output must not change. The agent wrote a four-step plan
to PLAN.md, which doesn’t mention the turned-down approach. In the chat
you also reminded the agent not to edit legacy/, which AGENTS.md already
says. The window is about two thirds full. Write three short lines: what
implementation starts with and why, what the new phase loses, and what you
add to a file before the switch. Ten minutes is enough.
A good result: implementation starts from a cleared session and
PLAN.md, because it is a new problem and the plan is written. The new
phase loses the exploration with its scratch script output, and everything
said only in the chat. Before the /clear you add the turned-down approach and
its reason to PLAN.md. The legacy/ rule doesn’t need a line, because
AGENTS.md holds it. Then answer one question: what in the work itself
would make you continue in the session instead?
Stretch: Do the same at the end of your next real planning session. Before you choose, run /context, or your agent's way of showing the context, and note how full the window is. At the start of the next session, check its starting context too, and name one thing in it that the task doesn't need.
Recap
- The starting context is everything in the window before your first message, and it goes with each request, so keep what the task never needs out of it [1] [2].
- At a phase boundary you choose what the next phase starts with. It can keep the whole history or a summary of it, or start again from what’s in files.
- Continuing keeps everything, and a full window makes the agent follow its instructions less well [3].
- Clearing and starting from the written plan fits a phase that starts a new problem, such as implementation after planning [3].
- Compacting keeps a summary and drops the detail, and it is itself a large request [2].
- Before you clear or compact, write what the next phase must keep in a file and read the file back.
You can now
- Chooses deliberately what each phase of work starts with, including the starting context
References
Section titled “References”- Anthropic. Explore the context window. Claude Code documentation. Reference.
Claude Code context window - Anthropic. Manage costs effectively. Claude Code documentation. Reference.
Claude Code costs - Anthropic. Best practices for Claude Code. Claude Code documentation. Reference.
Claude Code best practices - Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, Jeremy Hadfield. Effective context engineering for AI agents. Anthropic Engineering. Reference.
Anthropic context engineering