# What each phase starts with

> When planning ends, decide what the implementation phase starts with: the same session, a cleared session and the written plan, or a compacted summary. Know what each keeps, and what the starting context costs before you type.

Page: https://schubergphilis.github.io/ai-training/coding-with-agents/what-a-phase-starts-with/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

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*](https://schubergphilis.github.io/ai-training/coding-with-agents/scoping-and-referencing/#point-at-the-file-instead-of-describing-it)
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*](https://schubergphilis.github.io/ai-training/customizing-agents/compaction/#what-the-summary-replaces-and-what-comes-back)
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

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 (Explore the context window, Claude Code documentation).
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
(Manage costs effectively, Claude Code documentation), 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
(Explore the context window, Claude Code documentation).

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 (Manage costs effectively, Claude Code documentation). The lesson [*Writing project instructions the agent reads every session*](https://schubergphilis.github.io/ai-training/coding-with-agents/project-instructions/)
gave a second reason to keep the instructions file short: the agent follows
a short file more reliably than a long one.

#### Checkpoint: What do the 400 lines cost today?

The engineer fixes one typo in this session and closes it. What did the 400
migration lines cost?

- Nothing, because the agent reads the migration part of the file only when a migration comes up.
- Nothing after the first request, because the file is sent only once, at the start of the session.
- They are in the window from the first message and go with each request, although the task never needs them.
- They push the oldest messages out of the window, so the agent forgets the typo it was asked to fix.

## 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
(Best practices for Claude Code, Claude Code documentation). Every request in the implementation phase
also sends the whole planning conversation again (Manage costs effectively, Claude Code documentation).

**Clear, and start from the written plan.** In Claude Code, `/clear` starts
a new session (Manage costs effectively, Claude Code documentation). 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
(Best practices for Claude Code, Claude Code documentation). The costs page adds that `/clear`
costs nothing (Manage costs effectively, Claude Code documentation). 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 (Explore the context window, Claude Code documentation). When a big
piece of work comes next, the context-window page suggests `/compact` with
instructions that name what the summary keeps (Explore the context window, Claude Code documentation).
A compaction of a long conversation is itself a large request, because the
agent reads all of it to write the summary (Manage costs effectively, Claude Code documentation). And a
summary can drop a detail whose importance shows only later
(Effective context engineering for AI agents, Anthropic Engineering).

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
(Effective context engineering for AI agents, Anthropic Engineering).

#### Checkpoint: What does implementation start with?

Match what the implementation phase has at its start with the option that
gives it.

Statements:

- Every file read, test output and turned-down idea from planning, word for word
- The starting context, the repository and the plan file, and nothing that was only said in the chat
- A summary of the conversation, with CLAUDE.md, the memory notes and recent files read again from disk

Options:

- Continue in the session
- Clear, and start from PLAN.md
- Compact, then continue

## 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 (Best practices for Claude Code, Claude Code documentation).
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 (Effective context engineering for AI agents, Anthropic Engineering).

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:

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

#### Checkpoint: Planning is done

What does the implementation phase start with?

- Go on in the same session, because it already knows everything that was explored.
- Run /compact with no instructions and go on in the same session.
- Run /clear, then tell the new session to implement PLAN.md from step 1.
- Run /clear, then describe the plan to the new session from memory.

#### Pitfall: The reason the summary dropped

At the end of a long planning session, an engineer runs `/compact` and goes
on to implementation. The plan is in the summary, and the reason for
turning down free-text dates is not, because it was said once in the chat
an hour earlier. An hour later the agent proposes free-text dates "to keep
the change small", and the engineer explains the reason a second time. A
summary keeps what its writer judges important at that moment, and a
detail can turn out to matter later (Effective context engineering for AI agents, Anthropic Engineering). The
rule: before you clear or compact, put what the next phase must keep in a
file, and read the file.

## 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

1. 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 (Explore the context window, Claude Code documentation) (Manage costs effectively, Claude Code documentation).
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.
3. Continuing keeps everything, and a full window makes the agent follow its instructions less well (Best practices for Claude Code, Claude Code documentation).
4. Clearing and starting from the written plan fits a phase that starts a new problem, such as implementation after planning (Best practices for Claude Code, Claude Code documentation).
5. Compacting keeps a summary and drops the detail, and it is itself a large request (Manage costs effectively, Claude Code documentation).
6. Before you clear or compact, write what the next phase must keep in a file and read the file back.

#### Habit

At the end of your next planning session, add the decisions from the chat to the plan file before you clear, and start implementation in a session that points at the file.

## References

- Explore the context window, Claude Code documentation, https://code.claude.com/docs/en/context-window
- Manage costs effectively, Claude Code documentation, https://code.claude.com/docs/en/costs
- Best practices for Claude Code, Claude Code documentation, https://code.claude.com/docs/en/best-practices
- Effective context engineering for AI agents, Anthropic Engineering, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents