TLDR; The tech-lead pattern in Claude Code is planning before coding, sized to the change. Sort each request into one of three lanes. A patch has nothing to decide and gets no document. A change carries one decision and gets a forty-line brief. A feature gets the full explore, plan, code, commit cycle, with a plan file that names the files, how they connect, and the order to build them. Ask the open questions before you plan, keep the plan on disk, and commit (save a git checkpoint you can roll back to) before you let Claude work unattended.
When to use the tech-lead pattern
- Any request that hides a decision. “Add a CSV export” sounds like a patch and is not: someone has to decide the column order, the date format, and what happens to an empty value.
- Anything touching the database schema (how the data is structured), logins and permissions, a public API (the interface other software calls) or data sync, and any work that spans more than one session. These get the full cycle.
- Skip it when there is nothing to decide: the cause is obvious, the pattern exists, and the change is one fix plus its test. Plan Mode is where Claude reads and plans but writes no code. On a one-line settings change it adds nothing: the plan only uses up Claude’s context window, the amount of text it can hold at once.
How the tech-lead pattern works
Two facts about coding agents make planning pay.
First, they guess rather than ask. Ambig-SWE, an ICLR 2026 paper, rebuilt a standard test set of real GitHub issues (SWE-Bench Verified) with detail deliberately withheld. Claude Sonnet 4 resolved 68.0% of issues with the full specification, 40.0% with the detail hidden, and 61.4% when it could ask clarifying questions. All six models tested dropped when detail was withheld and gained when allowed to ask. It is one benchmark on one kind of task, but the guessing matters: by the time you read the code, the guess looks like a decision.
Second, early decisions fade. In a long session, the code Claude wrote first ends up in the middle of the context window. In my sessions, that is the point where later steps start to assume interfaces that don’t match it. (An interface is how one piece of code calls another.) A plan file helps with both: you answer the questions before any code exists, and when Claude Code compresses a long conversation to free up space, the answers stay on disk for Claude to reread.
The mistakes land in the interfaces between components. In my projects, planning them takes five minutes. Fixing interface mismatches during implementation takes thirty.
How to plan work with Claude Code
The feature lane runs the full cycle below: explore, plan, code, commit. A change runs a shorter version: less exploring, a brief instead of a plan file, one to three tasks. A patch skips steps 2 and 3.
- ExploreMap the files, patterns and interfaces
- PlanPlan Mode; write the plan to a file
- CodePoint Claude at the plan file
- CommitA reviewable rollback point
Feature laneFour phases, in order
The cycle then repeats: explore the next concern.
1. Map the code, then pick a lane
Read before you classify. The signs of a lane are in the code, not in the wording of the request: a bug report tells you nothing about whether its cause is obvious. For a single file in familiar code, have Claude read it directly. For a feature, start two or three Explore agents to map the files, patterns and interfaces at once. Explore agents are read-only sub-agents: helper sessions Claude starts for one job. They read the files, so your own session doesn’t fill up with their contents (multi-agent guide).
| Lane | Signals | Gate before code |
|---|---|---|
| Patch | Cause obvious or given; one change plus its test; a few files; established pattern; nothing to decide | None. Branch (a separate copy of the code to work on), write a failing test, fix, run the tests, review, merge (fold it back in) |
| Change | A bug whose cause is unknown, or a tweak where at least one choice exists: placement, format, API shape, error handling; one session, one to three files | A brief, about forty lines: problem, approach chosen and the one rejected, files touched, out of scope, acceptance |
| Feature | New project; multi-session; four or more files; a new pattern; anything touching the schema, logins, a public API, or data sync | The full cycle: explore, plan to a file, code in tasks, commit |
Two rules cover what the table doesn’t:
- When two lanes look plausible, take the larger one. In my experience, a brief you didn’t need costs about five minutes; a brief you skipped can cost a correction spiral, where each fix breaks something else.
- Move up a lane when the work outgrows the one you picked. If a patch turns up a choice, stop and write a brief. If a change grows past three files or needs a new pattern, stop and write a plan.
Check: you can name the lane and, for a change or a feature, the decision it contains.
2. Enter Plan Mode and ask the questions that change the design
From Claude Code v2.1.283, terminal and VS Code sessions start in auto mode, one of Claude Code’s permission modes. Switch to Plan Mode before your first prompt: press Shift+Tab until the mode reads Plan, or start the prompt with /plan. Open with:
Before you plan, list the questions whose answers change the design.
One round; three is usually enough. Give each two or three options and
your recommendation. Don't ask anything you can answer by reading the
code. If I say "whatever you think", state your choice and wait for me
to confirm it.
The options matter. “How should exports handle empty values?” gets a shrug; “empty cell, the string NULL, or skip the row; I’d use the empty cell” gets an answer.
Check: every question has a confirmed answer. A plan built on an unconfirmed assumption fails the way a guess does, only later and with more code attached.
3. Write the brief or the plan to a file
A change gets a brief. This template is adapted from my tech-lead skill, a set of instructions Claude Code loads for planning work:
# [Change name]
## Problem
[1–2 sentences. What's broken or missing, for whom.]
## Decision
[The approach chosen and the alternative rejected, one line each.]
## Change
- [File or module → what changes]
## Docs
- [Which doc changes with it, or "none" and why]
## Out of scope
- [Explicitly excluded, with the reason if it's not obvious]
## Acceptance
- [ ] [The behaviour in one line, e.g. "reject a login with an expired token and show an expired-session error"]
- [ ] [Test name or command that proves it]
The Decision section is the reason the brief exists. If the brief grows past forty lines, the work is a feature, and a feature gets a plan:
/plan Write an implementation plan to docs/plan-notifications.md.
Cover:
- NotificationMailer interface (which methods, which arguments)
- NotifyUserJob (arguments, retry policy, error handling)
- Mailer templates (which variables, which partials)
- Test scenarios (happy path, failed delivery, missing user)
- File creation order and dependencies
Write it for Claude. It needs file paths, each interface with its method names and arguments, the build order, constraints and test expectations. It doesn’t need the user stories, story points or Given/When/Then scenarios a team process asks for. “Given a user with an expired token / When they attempt to log in / Then they should see an error message” is three lines of ceremony; “reject a login with an expired token and show an expired-session error” says the same in one.
Ctrl+G opens the plan in your editor. Mark what’s wrong, have Claude revise, repeat; each round can catch an assumption before it becomes a bug. Keep the plan after the code ships: when that area changes later, Claude reads the original plan and sees why the code is shaped as it is.
In my projects, a plan that touches seven files or more goes better in batches. That is my rule of thumb; the model sets no limit. Plan and build the first batch, commit, run /clear to start a fresh conversation, then plan the next.
Check: every file has an exact path, every interface names its methods and arguments, and you have read the plan through once.
4. Build and commit
Exit Plan Mode and point Claude at the file: Implement docs/plan-notifications.md. In my experience, Claude often builds a plan like this in one pass. Boris Cherny, who created Claude Code, passes on his team’s advice: “Pour your energy into the plan so Claude can 1-shot the implementation” (his post).
Commit before each new task and before Claude works unattended, for example when it writes several files, fixes tests or works through a plan alone.
git add app/mailers app/jobs app/views/notification_mailer test/mailers test/jobs
git commit -m "feat(notifications): mailer, job and templates"
git status --short # should print nothing; anything listed is not in the checkpoint
Effort sets how long the model thinks before it answers. I plan on Opus 5.5 at /effort high, drop back to medium to build, and hand routine coding tasks to Sonnet 5.5 sub-agents. Claude Code keeps a processed copy of the conversation, a cache, so it isn’t reprocessed every turn. Each model keeps its own cache, so a model switch starts it again. On the 5.5 models, with an API key or a Claude subscription, a change of effort keeps the cache. Mid-session, change the effort and keep the model.
The built-in opusplan setting uses Opus in Plan Mode and Sonnet everywhere else. If you pay per use, it costs less per token, the word-fragment unit Claude bills by. But every switch in or out of Plan Mode changes the model and starts a fresh cache, so it saves the most when you switch rarely. The model selection guide has the full table.
Check: the tests pass, the code matches the plan, and any doc the change made wrong is fixed in the same commit.
5. Review at every boundary
Each phase ends at a review, so an error stops there instead of piling up:
- After sorting: is there a decision hiding in this?
- After exploring: are there patterns the new code must follow?
- After planning: do the interfaces make sense, and are any dependencies missing?
- After each task: does the code match the plan?
Review is the one gate in every lane. A patch skips the brief, so review is the only place anyone reads the change before it ships; a twenty-line fix needs only a quick read-through by someone other than the author. For a significant plan, ask a separate reviewer, another session or a model from another maker, to attack its assumptions and point to the plan or code behind each objection. A separate reviewer comes to the plan fresh, but it can still make the author’s mistakes.
Check: someone other than the author, a person or a reviewer agent, has read the change before it merges.
Pitfalls
| Symptom | Cause | Fix |
|---|---|---|
| Each fix breaks something else | Claude is working from early guesses that no longer hold; no plan on disk | Roll back to the last checkpoint, start a fresh session, plan first |
| The code settles a choice nobody was asked about | Change-lane work treated as a patch | Stop and write the brief |
Claude forgets the plan after /compact (Claude Code’s conversation compression) |
The plan lived in the chat | Write it to docs/; point Claude back at the file (session craft) |
| Planning takes longer than the build | Plan Mode on a patch, or a full product requirements document (PRD) written for people | Patch lane, or a bullet plan with file paths |
| A sub-agent reports done and isn’t | Given more than it could finish, so its report was cut short | Cap each sub-agent’s scope, and check its files and test results before you accept “done” |
| The build drifts late in a long plan | Too much in one plan | Plan in batches, with a commit and /clear between |
In practice
The first version of a client’s notification system took three hours because I didn’t plan it. It was a standard Rails email setup (ActionMailer) with two templates and a background job. Claude built the mailer, the code that sends the emails, then wrote a background job (a task that runs after the page has responded) against an interface that didn’t match the mailer it had just written; each correction broke something else, three cycles deep. I rolled back to the last clean commit, started a fresh session, and spent ten minutes in Plan Mode mapping the mailer interface, the job arguments, the template variables and the test expectations to a plan file. Claude built the whole feature in one pass. Forty minutes, including the planning.
Claude Code now has built-in tools for larger work: agent teams (experimental, off by default), workflows that run many sub-agents at once from one session, and sub-agents in isolated git worktrees. Worktrees give each agent its own copy of the code so they can’t overwrite each other’s files, but merging their work back together is still your job. You still supply the judgement: how the work splits up, in what order, and which model does each part. Mine lives in a tech-lead skill, and three of its rules do most of the work:
- Every task gets a stable ID that follows it from the task file into the branch name (
feature/T-3-sessions-controller), so the plan, the branch and the review point at the same unit of work. - Each task goes to the cheapest model that can do it. Fetching pages, reading structured files and code search go to Haiku; anything that needs reasoning stays on the main model.
- Each sub-agent gets a strict limit on scope, because a cut-short report reads as done when it isn’t.
When planning produces files on disk, my time splits about 80/20 in favour of defining the problem. Ten minutes on a plan saves me thirty to sixty minutes of correction spirals. Those numbers come from my own workflow. Anthropic’s reinforcement-learning (RL) Engineering team reports that its attempts at small-to-medium pull requests (proposed code changes) worked first time about a third of the time, and recommends trying once, then collaborating. That source doesn’t measure planning as the cause.
Human teams need the same structure. When I join one as a fractional CTO, sizing planning to the change is one of the first habits I set up.
Related reading
- Multi-agent orchestration, running parallel agents on real projects, parallel execution for when the plan decomposes into independent tasks
- Session craft, when to start fresh, resume, or compact, managing the context window across the plan-code-commit cycle
- Model selection, which Claude for which job, the model and effort for planning, implementation, review and search
- How to write a CLAUDE.md file for Claude Code, the persistent instructions that shape every plan and every implementation
Sources
- Ambig-SWE: Interactive Agents to Overcome Underspecificity in Software Engineering, ICLR 2026. Figure 3 resolve rates: Claude Sonnet 4 at 68.0% (full specification), 40.0% (detail hidden) and 61.4% (detail hidden, with up to three clarifying exchanges); Claude Sonnet 3.5 at 49.4, 24.2 and 39.6. Peer-reviewed paper (ICLR 2026), linked as arXiv preprint
- How Anthropic teams use Claude Code, team appendix (PDF), RL Engineering’s checkpoint-heavy, try-once-then-collaborate workflow and its roughly one-third first-attempt observation, pp.19–20. The source does not test planning as the causal variable. Primary source
- How Boris Uses Claude Code, “Pour your energy into the plan so Claude can 1-shot the implementation.” A fan-made collection of Boris Cherny’s public posts, not an Anthropic property. Secondary source
- I Tested Three Spec-Driven AI Tools. Here’s My Honest Take, Ran Isenberg, Spec-driven AI tools (BMAD, Spec-Kit, OpenSpec) for catching design issues before implementation. Blog post
Common questions
What is the tech-lead pattern in Claude Code?
Planning before coding, sized to the change. You sort the request into a lane first, then apply only the gate that lane needs: none for a patch, a short written brief for a change that contains a decision, the full explore, plan, code, commit cycle for a feature. The point is to stop correction spirals before they start, without paying for ceremony the work doesn’t need.
How does planning first reduce wasted work?
In my sessions, a correction spiral, where each fix breaks something else, usually starts with an unclear plan. Settling the plan first, in a file the model and I both work from, means the code phase carries out a decision instead of discovering it, so there is less rework.
When should you skip the planning step?
When there is nothing to decide. If the cause is known, the pattern is established, and no choice is left open, planning is overhead. But once a request contains a choice about placement, data format, API shape, or error handling, it earns a written brief however small the code change turns out to be.
How do you decide how much planning a task needs?
Read the code before you classify, because lane signals live in the codebase rather than in the wording of the request. Then ask what is left to decide. Cause known and pattern established: patch. One open choice: change. Four or more files, several sessions, or anything touching the schema, logins, or a public API: feature. When two lanes look plausible, take the larger one.