AI Engineering

Overview

This chapter covers:

• What is already occupying the window before you type a character
• Why a subagent is the cheapest way to read a lot of files
• Exactly what compaction re-injects, summarises and drops — including the five-file rule
• Why the prompt cache means changing model mid-task costs more than the switch itself
• The difference between /compact, /clear and /rewind, and when each is right

The window is not empty when you start

Before your first prompt, a session has already spent tokens. Representative figures for a modest setup:

Two of those numbers are the ones you control, and Chapters 6 and 7 were about both. A 4,000-token CLAUDE.md is not just costly — it also reduces adherence, so the incentive points the same way twice.

The MCP line is worth noticing because of what it isn’t. By default only tool names load; the full schemas stay deferred until a task needs them. Ten connected servers therefore do not blow up your window. ENABLE_TOOL_SEARCH=false loads everything upfront, which is the setting that undoes this.

What fills it as you work

Then the session runs, and everything appends:

• Every file Claude reads — a mid-size source file is 1,000–2,500 tokens.
• Path-scoped rules, as their matching files are read (Chapter 7).
• Tool results — a grep, a test run, a hook’s output.
• Every message, yours and Claude’s.

The one thing that does not land in your window is a subagent’s work. It runs in its own context and returns only a summary, which is why “send the research to a subagent” is the standard advice for anything that means reading twenty files.

Watch it fill

Compaction

As you approach the limit, Claude Code summarises the conversation and continues. Your session does not end. But compaction is not uniform — what happens to a piece of context depends on how it got there.

Three practical consequences fall out of that table:

• Five files. A file over 5,000 tokens comes back as a path reference rather than content, shown as Referenced file. Everything read beyond the five is gone until Claude reads it again.
• Skill truncation keeps the start of the file. Put the instructions that matter at the top of a SKILL.md, not the bottom.
• A paths: rule that must survive should not have paths:. Drop the frontmatter or move it into the project-root CLAUDE.md.

Three ways to reclaim space, and they are not interchangeable

/rewind is the underused one, and the reason is in the next section: it truncates back to a prefix that is already cached, where compaction builds a new one.

You can also move the trigger point — /autocompact 500k — or compact part of the conversation from /rewind with Summarize from here.

Making the focus permanent

/compact focus on the auth bug steers one compaction. For a project where the same thing always matters, put a Compact Instructions section in your CLAUDE.md instead:

## Compact Instructions

When compacting, always retain the current migration plan, any failing
test names, and decisions about the API contract. Drop exploratory
file reads and tool output that has been superseded.

That survives every compaction in every session, including the automatic pass that fires while you are mid-task and not thinking about what to keep. Which is the general lesson of this section: anything that must outlive a compact belongs in a file, not in the conversation.

The other budget: the prompt cache

Every turn re-sends the whole conversation. The API avoids reprocessing it by matching the prefix of the request against what it recently processed — and the match is exact, so a change anywhere invalidates everything after it.

Claude Code orders each request to make that work in your favour:

flowchart TB
    A["System prompt — tool definitions, output style
changes on upgrade"] --> B["Project context — CLAUDE.md, memory, unscoped rules
changes on /clear or /compact"]
    B --> C["Conversation — messages, tool results
changes every turn"]
    C --> D(["Only the new tail is reprocessed"])

Cache reads bill at roughly 10% of the standard input rate, so a good hit ratio is most of why a long session stays affordable. Which makes the invalidation list worth knowing:

Two entries deserve expanding.

opusplan makes every plan-mode toggle a model switch. It resolves to Opus while planning and Sonnet while executing, so entering and leaving plan mode each start a fresh cache. That is a real cost against a real convenience.

Editing CLAUDE.md mid-session keeps the cache — because the edit does not apply. The file is read once at session start and held in memory. Your change loads on the next /clear, /compact or restart. The same is true of outputStyle. This is the mechanism behind Chapter 5’s “some keys are read once at session start”; it is a caching decision, not an oversight.

Cache lifetime

Cached prefixes expire after inactivity, and each hit resets the timer. The API offers a five-minute and a one-hour TTL. Where you land by default:

Set it yourself with promptCacheTtl (5m or 1h) and subagentPromptCacheTtl, both v2.1.242+. On an API key, "promptCacheTtl": "1h" is the single most useful line for a working day with breaks in it.

Cache scope is worth one sentence: effectively one machine and one directory. The system prompt embeds your working directory, so two worktrees of the same repository never share a cache.

/usage reports a Prompt cache (main) line with your hit ratio and, since v2.1.260, the likely cause of the last miss.

Habits

The five that do the work, in rough order of payoff:

1. Pick your model and effort at the start. Both are cache keys. Mid-task switching costs a full re-read of the conversation.
2. /clear between unrelated tasks. Old conversation crowds out the files you need next and is re-sent on every message.
3. Delegate large reads to a subagent. Twenty files land in its window, and a summary lands in yours.
4. /compact at a natural break, with a focus. You choose what the summary keeps instead of letting the automatic pass guess mid-task.
5. /rewind rather than /compact when abandoning a direction — it returns to a cached prefix instead of building a new one.

/context shows the live breakdown by category, with suggestions. It is the first thing to run when a session feels sluggish or expensive.

Or stop asking, and put it on screen

/context answers “how full am I” once. A status line answers it continuously — a strip at the bottom of the session showing whatever you choose.

The contract is small: Claude Code sends your script a JSON object on stdin — model, cost, context percentage, git directory, session ID — your script prints one line to stdout, and that line is displayed. Any language; it is just a program that reads stdin and writes stdout.

You do not have to write it. Describe what you want and Claude Code generates the script, drops it in ~/.claude/, and wires up the setting:

/statusline show model name and context percentage with a progress bar

The manual form is a settings key:

{ "statusLine": { "type": "command", "command": "~/.claude/statusline.sh", "padding": 2 } }

It is also where the prompt_cache fields from the previous section surface, so a cache hit ratio can sit on screen next to the context gauge.

If you need a bigger window rather than a smaller conversation, Fable 5.1, Fable 5, Sonnet 5, and Opus 4.6+ / Sonnet 4.6+ support 1M tokens — a [1m] model variant, except Sonnet 5, which runs at 1M with nothing to select.

Summary

• A session starts with roughly 8,000 tokens already spent. Your CLAUDE.md is the part you control.
• MCP schemas are deferred by default, so many servers cost little. ENABLE_TOOL_SEARCH=false undoes that.
• Compaction re-injects CLAUDE.md, auto memory and the plan from disk, re-reads only five files, truncates skills to 5,000 tokens each, and summarises everything else.
• A paths: rule does not survive compaction until its file is read again. Drop the frontmatter if it must.
• The prompt cache matches an exact prefix, so a change anywhere invalidates everything after it. Reads bill at about 10% of input rate.
• Each model and effort level has its own cache. opusplan makes every plan-mode toggle a model switch.
• Editing CLAUDE.md mid-session is cache-safe because the edit does not apply until /clear, /compact or restart.
• /rewind returns to a cached prefix; /compact builds a new one. Prefer rewinding when abandoning a path.
• A Compact Instructions section in CLAUDE.md makes your focus survive every compaction, including the automatic one.
• A status line turns /context from a question into a gauge: JSON in on stdin, one line out on stdout, and /statusline <description> writes the script for you.
• Full reference: context window, prompt caching, statusline, costs.

Chapter 9 closes Part 2 with the machinery underneath all of this: sessions on disk, checkpoints, and what /rewind can and cannot restore.