The tech-lead pattern: planning before coding

TLDR; The tech-lead pattern is planning before coding, sized to the change. Triage the request into one of three lanes and apply only that lane’s gate: 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 cycle, with a plan file that carries interfaces, file paths, and dependency order. Anthropic’s RL Engineering team reports that its small-to-medium attempts worked first time about a third of the time before additional guidance or manual intervention. My own planned workflows complete in fewer correction cycles, but the source does not measure planning as the cause.

The first version of a client’s notification system took three hours. Not because the code was complex, it was a standard Rails ActionMailer setup with two templates and a background job. Three hours because I didn’t plan it.

Claude built the mailer first. Solid code. Then I asked for the background job, and Claude made assumptions about the mailer’s interface that didn’t match what it had just written; the mailer code had scrolled into the middle of the context window where it gets deprioritised. I corrected the interface. Claude fixed the job but broke the template variables. I corrected again. Claude introduced a test targeting the old interface. Three correction cycles deep, the session was in what I’ve come to call a correction spiral: each fix introducing new assumptions from a degraded context.

I rolled back to the last clean commit, started a fresh session, and spent ten minutes in Plan Mode. Mapped the mailer interface, the job arguments, the template variables, the test expectations, all in a plan file on disk. Exited Plan Mode and told Claude to implement. It one-shot the entire feature. Forty minutes, including the planning.

This is the tech-lead pattern: plan the work before doing the work, in proportion to the work. It sounds obvious; every software engineering book preaches it. But with AI-assisted coding, the impulse to skip planning is stronger than ever. Claude can write code so fast that planning feels like overhead. Anthropic’s RL Engineering team reports that small-to-medium PR attempts worked on the first try about a third of the time, otherwise needing guidance or manual intervention. The same team recommends trying once, then collaborating. The source does not compare planned and unplanned tasks; the improvement I describe here comes from my own workflow.

Triage first: size the gate to the change

Before planning anything, classify the request into one of three lanes. Each carries the smallest gate that still makes the work safe, and the call takes about ten seconds: it decides whether the next thing I produce is a document or a branch.

Scroll sideways →

I used to apply planning evenly, and that was wrong in both directions: ceremony on one-line fixes, nothing on the changes that quietly contained a decision. The middle lane is the one I kept missing. “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 a null. If I decide those inside the implementation, they are invisible by the time the code is reviewed.

Two rules cover the cases the table doesn’t.

When two lanes both look plausible, take the larger one. A brief I didn’t need costs five minutes. A brief I skipped costs a correction spiral.

Promote mid-flight when the work outgrows its lane. A third file, a second viable approach, or a behaviour question I’m about to answer by guessing: that is the signal to stop and write the brief. If I’m about to settle something the request left open, the lane was wrong.

Classify after reading the code. Lane signals live in the codebase, not in the wording of the request, and a bug report tells you nothing about whether its cause is obvious. Read the relevant file, or run one Explore pass, then classify; that read costs less than a wrong lane.

The threshold that most reliably predicts whether planning pays off: does the task involve interfaces between components? If the model passes data to the controller which renders a view which is tested by a system test, those interfaces are where mistakes happen. Planning them takes five minutes. Fixing interface mismatches during implementation takes thirty.

The single most expensive mistake I see developers make with Claude Code is starting a complex feature with “build this” and no plan. Claude starts confidently, produces reasonable-looking code, and you don’t notice the interface mismatch until three files in. By then the context is loaded with assumptions from the early files, and every correction introduces new mismatches. The second most expensive: entering Plan Mode for a one-line config change, which burns context on a plan that adds nothing.

The explore-plan-code-commit cycle

This is the Feature lane in full, four phases in an order that matters. The Change lane runs a compressed version of the same thing: less exploring, a brief instead of a plan file, one to three tasks instead of a decomposition.

Explore: before planning anything, understand the current state. What files are involved? What patterns does the codebase already use? What interfaces exist that the new code needs to conform to?

I use Explore agents for this: fast, read-only agents that search the codebase and return focused summaries without polluting my main context with dozens of file reads. Two or three Explore agents running in parallel can map a feature’s surface area in a single round trip. The multi-agent guide covers the mechanics.

If the task is smaller, a single-file change, a familiar part of the codebase, skip the Explore agents and have Claude read the relevant files directly.

Plan: with the codebase mapped, enter Plan Mode (cycle Shift+Tab to Plan, or prefix the prompt with /plan). Claude reads, analyses, and reasons, but doesn’t write code. The plan should cover:

• what files to create or modify
• what interfaces exist between components
• what the test scenarios are
• what order things should be built in

Write the plan to a file, not to the chat. A plan document on disk survives context compaction. A plan discussed in conversation gets compressed to a sentence or disappears entirely.

/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

Code: exit Plan Mode, point Claude at the plan file, and let it implement. With a solid plan, this phase often completes in a single pass. Boris Cherny, who created Claude Code, frames it directly: pour your energy into the plan so Claude can one-shot the implementation (his post).

Commit: checkpoint your work with a git commit before moving to the next task. This creates a reviewable rollback point. If the next task goes sideways, inspect the diff and deliberately restore the affected paths or revert the checkpoint as appropriate. Whether to roll back or fix forward depends on the size and clarity of the change.

The cycle then repeats: explore the next concern, plan the approach, implement, commit.

Plan Mode and model routing

Plan Mode (cycle Shift+Tab to Plan, or prefix the prompt with /plan) puts Claude into a read-only thinking mode. It can read files, search code, and reason about architecture, but it won’t make changes. This constraint is the feature: it prevents Claude from jumping to implementation before the approach is solid.

Interactive terminal and VS Code sessions now start in auto mode on every plan (Claude Code v2.1.283 and later), so Plan Mode is an explicit choice. For a feature, make it before the first prompt.

The model routing pattern I use daily: Opus 5.5 in the main session for planning, at /effort high for the planning turn and back to medium to implement, with the routine implementation handed to Sonnet 5.5 sub-agents. I change effort rather than model mid-session: each model has its own cache, and on the 5.5 models an effort change keeps it. The built-in opusplan alias (Opus in Plan Mode, Sonnet everywhere else) is cheaper per token on metered billing, but every plan-mode toggle is a model switch and starts a fresh cache, so it pays off only when you enter and leave plan mode rarely. The model selection guide covers the full routing table.

A good plan is specific, structured, and short:

• What files to create or modify (exact paths)
• What interfaces exist between components (method signatures, argument types)
• What data flows through the system
• What the test scenarios cover
• What order to build in (dependency chain)

In my projects, plans touching roughly seven or more files are often easier to execute in batches. That is a workflow heuristic, not a model limit. For larger refactors, break the work into sequential plans: plan and implement the first batch of files, commit, /clear, then plan the next batch in a fresh session.

My own split lands around 80/20 in favour of problem definition when the planning includes persistent artefacts. The ten minutes I spend on a plan saves thirty to sixty minutes of correction spirals.

Ask before you plan

Plan Mode’s first job is to keep the open questions open long enough for someone to answer them. Writing the plan comes second.

Agents default to proceeding on an underspecified request rather than asking for the missing detail. Ambig-SWE, an ICLR 2026 paper that rebuilt SWE-Bench Verified with detail deliberately withheld, put numbers on the cost. Claude Sonnet 4 resolved 68.0% of issues given the full specification and 40.0% when the detail was hidden. Allowing it one round of clarifying questions recovered it to 61.4%. All six models tested dropped when detail was withheld and gained when allowed to ask; only the size of the recovery varied. It is one benchmark on one task shape, and one round of questions is a cruder instrument than a plan. The behaviour it exposes is the one that matters here: an agent handed an ambiguous brief guesses silently, and by the time you read the code the guess looks like a decision.

Scroll sideways →

So I run the questions before the plan, and they have a shape:

• Only questions whose answers change the design. Everything else is noise the model can resolve by reading.
• Each one with options and my recommendation attached, never open-ended. “How should exports handle nulls?” gets a shrug; “empty cell, the string NULL, or skip the row; I’d use the empty cell” gets an answer.
• All of them in one round. Three is usually enough, and dribbling them out one at a time is how a ten-minute plan becomes an hour.

“Whatever you think” is a legitimate answer, but then I state the choice back and get it confirmed before writing the plan. A plan built on an unconfirmed assumption fails the same way, just later and with more code attached.

Persistent plan files

A plan written to a file outlives the session that produced it.

It survives context compaction. Conversation summaries are lossy and their size varies by model and release; a carefully articulated decision can become a sentence fragment or disappear. A markdown file on disk remains intact. Point Claude back to it after compaction so it reads the source rather than relying on the summary. The session craft guide covers why this matters.

Plan files are also annotatable. The pattern: annotate plan documents inline across multiple rounds. Read the plan, mark what’s wrong, have Claude update it, repeat. (Ctrl+G opens the plan directly in your text editor before Claude proceeds, which makes the round trip faster than chat-side annotation.) Each annotation round catches assumptions that would have become bugs during implementation. The cost of an annotation round is a fraction of what a correction spiral costs.

For significant plans, I also use a separate reviewer briefed to attack assumptions. That may be another session or a different model family. Separation removes the generation transcript and can diversify the review, but it does not guarantee independent errors; the value is the explicit adversarial brief and the requirement to cite the plan and code.

And they’re reusable. A plan file for “add notification mailer” becomes a template for the next mailer feature. I keep completed plans after the code ships. When the same area needs modification later, Claude reads the original plan and understands the design intent, not just the code that resulted from it.

For Change-lane work the same logic applies at a tenth of the size. The brief is one page: the problem, the approach I picked and the one I rejected, the files it touches, what’s explicitly out of scope, and how I’ll know it worked. When someone later asks why the export writes an empty cell instead of NULL, the answer is in the file rather than in a session that was compacted away.

The simplest implementation: ask Claude to write the plan to a markdown file in a docs/ or plans/ directory, review it before implementation begins, annotate anything wrong, and have Claude revise before touching code.

The orchestrator pattern

The tech-lead pattern scales from a single feature to an entire workflow through orchestration: decomposing complex work and delegating it to specialised agents and skills.

Claude Code now ships the scaffolding for this natively. Agent teams coordinate multiple sessions with shared task lists and messaging under a team lead; workflows run a script that fans out parallel subagents from a single session, 16 at a time by default and up to 1,000 per run; and subagents can run in isolated git worktrees, which stops two agents writing over each other in one checkout but leaves the integration conflicts to you. Agent teams are still experimental and off by default, so you have to switch them on first. What you still build yourself is the judgement layer on top: what decomposes, in what order, to which model.

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 all point at the same unit of work. Decomposition is tiered by what each sub-task needs rather than defaulting everything to the strongest model: mechanical fetch-and-parse and search-and-locate work go to Haiku, reasoning stays with the primary model. And delegated agents get hard scope caps, because an agent briefed past its capacity returns a truncated report, and a truncated report is worse than none: it reads as done when it isn’t.

The same pattern runs my marketing workflow, a strategist skill coordinating a dozen specialist skills for research, content, and fact-checking, which is the proof that this is about structured thinking, not any particular domain.

The value is structured thinking, not automation. Decomposing a feature into tasks with dependencies forces you to think about the interfaces between components before any code is written. It surfaces the questions that would otherwise appear as bugs: which model does this controller depend on? What arguments does this job expect? What does the test need to set up?

For workflows I repeat, new client onboarding, campaign setup, feature builds in specific Rails projects, I’ve codified the decomposition into skills. The skill doesn’t just know what tasks to create; it knows the order, the dependencies, and the quality checks for each step.

Planning for the machine, not the meeting

There’s a trap that catches developers coming from structured team environments: they replicate human ceremonies when planning for Claude. Formal PRDs with stakeholder sign-off sections. User stories in “As a... I want... So that...” format. Acceptance criteria in Gherkin syntax. Story points. Sprint capacity calculations.

These artefacts exist for good reasons in a human team. They align stakeholders who aren’t in the room. They create accountability across departments. They help six engineers who’ve never met coordinate asynchronously across time zones.

Claude doesn’t need any of it. Writing “Given a user with an expired token / When they attempt to log in / Then they should see an error message” is seven lines of ceremony when “reject expired tokens with a clear error” does the same job in one.

What Claude needs from a plan:

• File paths: which files to create, which to modify
• Interfaces: method signatures, argument types, return values
• Dependency order: what to build first so later steps can reference it
• Constraints: what not to do, what patterns to follow, what conventions apply
• Test expectations: what behaviour to verify, what edge cases matter

A plan for Claude is a technical blueprint, not a communication artefact. The more it reads like a senior engineer’s notes on a whiteboard, the better Claude executes from it.

I’ve seen developers spend thirty minutes writing a formal PRD for Claude that would have taken five minutes as a bullet-point plan with file paths. The PRD didn’t produce better code; it produced a longer context window and a slower start. A three-line plan that specifies exact interfaces outperforms a three-page spec that describes the user journey.

Quality through structure

In a structured workflow, every phase ends at a checkpoint. Errors get caught at a boundary instead of compounding silently until the chain needs a rollback.

• After triage: is this really the lane it looks like? Is there a decision hiding in it?
• After Explore: do I understand the codebase correctly? Are there patterns I need to conform to?
• After Plan: do the interfaces make sense? Have I missed any dependencies?
• After each implementation task: does the code match the plan? Do the tests pass? If the change made a doc wrong, does the same commit fix it?
• After commit: is this a clean state I’d be happy to roll back to?

Review is the one gate that applies in every lane. A patch skips the brief, so the review is the only place anyone reads the change before it ships. Size it to the work: a twenty-line fix gets an inline self-review instead of a full pass.

The cost of fixing a wrong assumption in the plan is near zero; just edit the markdown file. The cost of fixing that same assumption after three files of code have been built on it is a session rollback and a fresh start.

The commit checkpoint deserves emphasis. Before starting any autonomous work, commit the current clean state. Autonomous work here means anything multi-step: Claude writing multiple files, running and fixing tests, working through a plan unattended. If it goes wrong, roll back to the checkpoint and start a fresh session with a refined prompt. This is faster and cheaper than fixing forward in a session where Claude’s context is loaded with its own mistakes.

The main lever on cost is workflow structure (session hygiene, commit checkpoints, structured planning), not prompt tweaking. The savings show up in fewer correction spirals and fewer wasted long-context sessions, not in cleverer wording.

Human teams need the same structure; when I join one as a fractional CTO, sizing the planning to the change is among the first routines I set.

---

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
• CLAUDE.md, the file that changes everything, the persistent instructions that shape every plan and every implementation

Sources

• 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, p.19. The source does not test planning as the causal variable. Primary source
• How Boris Uses Claude Code, Pour energy into the plan so Claude can one-shot the implementation. A fan-made collection of Boris Cherny’s public posts, not an Anthropic property. Secondary source
• 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, one round of clarifying questions); Claude Sonnet 3.5 at 49.4, 24.2 and 39.6. Peer-reviewed paper (ICLR 2026), linked as arXiv preprint
• 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 triage the request 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?

A correction spiral usually starts from an unclear plan. Fixing the plan up front, in a file the model and I both work from, means the code phase executes a decision instead of discovering it, so there is far 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 pure overhead. But once a request contains a real choice about placement, data format, API shape, or error handling, it earns a written brief however small the diff 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 schema, auth, or a public API: feature. When two lanes look plausible, take the larger one.