3 Days of Spec-Driven Development

Context is a budget

Day 1: From chat to spec · Lesson 6 of 6 · 14 min

Everything the agent knows arrived from somewhere and cost tokens, and CLAUDE.md is the part of that bill you pay on every turn. Read the window as a budget and the question about a line changes: not is it true, but is it worth its cost.

Watch first · 7 min

Boris Cherny: We Cut 80% of Claude Code’s Prompt

Y Combinator, 2026-07-27. Segment 3:21 to 10:30. Watch for the method rather than the number: how he decides whether a line is earning its place.

Open a session and the window already holds what loaded before you typed: the system prompt, the CLAUDE.md files that apply where you started, the auto memory Claude keeps for this project where it is on, the attached tools' names, and a description of each available skill. The run fills the rest — the ticket, the files read, every command's output — until something compacts or clears it. Compaction, automatic near the limit or by /compact, replaces the conversation with a summary, then reloads the system prompt, memory, tools, recently modified files and your CLAUDE.md: your instruction file is back on the bill immediately.

Nothing there is free: a file read in the first minute is still there in the fortieth, taking room from the failing test output.

Every command below runs from day1-work. Look at what you are paying:

Swift lane 
wc -l CLAUDE.md
Kotlin lane 
wc -l CLAUDE.md

Around 180 lines for a module of five source files with no dependencies, paid on every turn of every session your team runs.

A context window before and after trimming CLAUDE.md The same fixed context window drawn twice, each split into system prompt plus tool names, CLAUDE.md, files read plus conversation, and a hatched remainder left as room for the task. After the trim, the CLAUDE.md segment, paid on every turn, is a quarter of its former width, and the room for the task grows by exactly that amount. before the trim CLAUDE.md room for the task system prompt + tool names files read + conversation paid on every turn after the trim CLAUDE.md room for the task system prompt + tool names files read + conversation what the cut gives back paid on every turn
What the standing file gives back goes straight to the task.

Look at what actually loaded

/context shows what is in the window right now, broken down by where it came from. Run it before you theorize about an ignored instruction file: often it never loaded, because the session started outside its directory.

You read the numbers off your own screen in Exercise 4's first step, in a session started inside day1-work: the tokens shown for your CLAUDE.md (under Memory files) and the total. The exercise compares both before and after a cut.

CLAUDE.md is the standing spec

Project instructions live at ./CLAUDE.md or ./.claude/CLAUDE.md, loaded from the directory you started in and every directory above it; your personal ones live at ~/.claude/CLAUDE.md. Today's project file is day1-work's, which is why every session today starts inside that folder. The lane also ships a .claude/settings.json whose claudeMdExcludes skips any instruction file above day1-work and whose "autoMemoryEnabled": false turns auto memory off. If a block in the breakdown still surprises you, it is usually your personal file, a managed policy file your organisation ships, a CLAUDE.local.md of your own, or a rules file with no paths: list (below).

In a repository with none, /init generates one from the build commands, tests and conventions it finds: a good first draft and a poor final one, since it records what is true about the codebase, not what an agent gets wrong.

The line test

For each line, ask: if I removed this, would the agent make a specific mistake I can name? If you can, keep it; if not, cut it: every session is paying for it.

Your lane's file holds both kinds: a line that names its mistake, and a block that names none.

Swift lane

Without the line forbidding NumberFormatter and Locale, an agent formatting an amount reaches for the platform formatter and the golden fixture stops matching. None of the Engineering principles lines would have changed a diff.

Kotlin lane

Without the line forbidding java.text.NumberFormat and DateTimeFormatter, an agent formatting an amount reaches for the platform formatter and the golden fixture stops matching. None of the Coding standards lines would have changed a diff.

Boris Cherny described Anthropic doing the large version of this to Claude Code's own system prompt: You delete the entire system prompt, and then you bring it back line by line, keeping what measurably earns its place.

Where the cut lines go

Cutting is not deleting knowledge: a cut line has two places to go, and only one changes its cost.

An @path/to/file reference inside CLAUDE.md imports that file, and an imported file may import others up to four hops deep. That buys you one topic per file, not a smaller bill: count the imported lines as paid on every turn, like the rest of the file.

The sharper tool is a path-scoped rule: a file at .claude/rules/<name>.md whose YAML frontmatter lists paths: globs enters the window when the agent reads a matching file, and stays out otherwise. Exercise 4 moves part of your lane's file into one.

Resetting between tasks

/clear starts a new conversation with an empty window and is the correct move between unrelated tasks, as in Exercise 1. /compact keeps a summary of the thread instead of its transcript, with focus instructions on the same line.

When a long file is the right answer

Short is not the goal; earned is. An unusual build step, a constraint with legal weight, a footgun that has bitten two people: each prevents a mistake you can name, so each stays.

Under about fifty lines, a cut buys back little; and a smaller wc -l alone proves nothing: what counts is whether the agent still avoids the mistakes the file names.

Exercise 4 runs all of this on your lane's file.

Quick check

Your lane's CLAUDE.md carries Don't repeat yourself in its block of general coding advice. Keep it or cut it?

Cut it. You cannot name the mistake its removal would cause, and it is paid for on every turn. A specific convention with a file path, or a lint rule the agent can run, would earn the same space.

You have just finished a merchant-filter task and are starting an unrelated formatter task in the same session. What do you run first, and why?

/clear. The filter transcript is now cost with no benefit, and leftover detail about the wrong file is exactly where the next wrong edit comes from.

Sources

Claude Code documentation; cc-core-40 to cc-core-44 accessed 2026-09-23.