Build with Claude Code: from an approved plan to a proved change

The Claude Code build section is 21 guides for developers and tech leads that turn an approved plan into a merged change: implementing across files, running one change over hundreds of files, API, database and documentation work, and the setup around them. Each guide ends in evidence, such as passing tests and a scoped diff, rather than a line-by-line read.

You approved a plan for per-key rate limiting this morning. By lunch, Claude Code has touched 14 files, quietly edited two tests to pass, and produced a 900-line pull request (PR) diff nobody wants to review. The plan was fine; the build had no checkpoints.

These guides build in small slices: each slice runs your test, typecheck, and lint commands and proves itself before the next starts, and the change ends in an evidence report that you and your reviewer check instead of every line.

Which build guide do you need?

Your situation	Start with	What you leave with
An approved plan spans several files	From plan to working code and multi-file workflows	Small commits, each green in CI
One mechanical change must hit hundreds of files	Batch operations (the bundled /batch skill) and large-scale refactoring	Independent PRs, each with its own gate
Better structure, same behavior	Refactoring patterns	Characterization tests first, then the refactor
New REST or GraphQL endpoints	API development	A contract, and tests that check it
Schema, query, or data changes	Database work and migrations	Migrations proved on a disposable database
A payment, email, or OAuth provider	Third-party integrations	Sandbox-tested integration code
Docs drift from the code	Documentation	Docs regenerated and kept true by a gate
The repository exceeds the context	Large codebases	Scoped sessions that read only what matters
Claude forgets your conventions between sessions	The memory system	A CLAUDE.md and rules that hold

The rest of the section is your daily setup: command-line flags and sessions, prompt engineering, slash commands, terminal mastery, IDE and CLI coordination, the desktop app, workflow optimization, efficiency hacks, and features you haven’t tried.

Run the build loop on one change

The loop needs a plan saved in the repository; if you have none, start in Plan with Claude Code.

1. Start an isolated, named session in a new git worktree, so the build cannot collide with your other work:

   claude --worktree rate-limit -n rate-limit

2. Give Claude the plan and the first slice only, with the first prompt below.

3. After each slice, Claude runs the verification commands and reports. You check the report, not the diff.

4. Before the PR, run /code-review in the session, fix what it finds, then produce the evidence report with the second prompt.

5. If a slice goes wrong, press Esc twice (or run /rewind) and pick the checkpoint before the slice. Checkpoints restore only files Claude edited with its edit tools; they do not undo a commit or changes made through Bash. If the slice was already committed, also run git reset --hard HEAD~1, then restate the slice.

From v2.1.280 (the latest channel), Claude Code defaults to Claude Opus 5.5 at medium effort; the stable channel (2.1.274 on 2026-09-26) has not reached it, so check claude --version. For a hard slice, raise effort first (/effort high or --effort xhigh) and change model only when your own results say so. See the models hub.

Copy-paste prompt: implement the plan one slice at a time

Implement docs/plans/rate-limit.md one step at a time. Start with step 1 only.

For each step:
1. Write or update the tests named in the plan's acceptance criteria and
   run them. Show me they fail for the right reason.
2. Make the smallest change that makes them pass. Touch only the files the
   plan lists as in scope.
3. Run the test, typecheck, and lint commands from the plan's
   Verification section, exactly as written.
4. Commit with a message that names the step.
5. Stop and report: files changed, commands run with pass/fail, and
   anything that differs from the plan.

Never edit an existing test to make it pass. If the plan is wrong or a
step needs an out-of-scope file, stop and ask instead of improvising.

Copy-paste prompt: an evidence report before the PR

Compare this branch against main and write an evidence report for the PR:
- Each acceptance criterion from docs/plans/rate-limit.md, the test that
  proves it, and the result of running that test now.
- Output of the full test, typecheck, and lint commands.
- Every changed file, marked in scope or OUT OF SCOPE per the plan.
- Every existing test that was modified or deleted, with the reason.
- Anything you are not sure about, listed as open questions.
Do not fix anything in this step. Report only.

How do you check a build without reading every line?

You sign off on evidence the agent cannot fake with prose. A build is done when these five checks pass:

1. The acceptance tests went from red to green, and you saw the red.
2. The same test, typecheck, and lint commands pass in CI, not only on the laptop.
3. git diff --stat main lists only files the plan put in scope.
4. No existing test changed without a reason you accept.
5. /code-review (or your CI review agent) raised nothing that is still open.

You read only what those checks flag. To catch type errors during the build rather than in CI, add a typecheck hook (hooks automation). The developer signs off on a change inside an approved plan; a tech lead signs off on anything that changes its scope. The reasoning is in evidence, not diffs; the PR format is the evidence bundle.

What goes wrong when you build with Claude Code?

Symptom	Likely cause	Recovery
Tests pass, but the feature is broken	Claude edited the tests, or the assertions are weak	Restore each edited test with git restore --source=main -- TEST_PATH, where TEST_PATH is the edited test file, and rerun the slice with “never edit an existing test”
The diff touches files outside the plan	The slice was too large, or the plan missed a caller	Press Esc twice (or run /rewind) and pick the checkpoint before the slice; if the slice was already committed, also run git reset --hard HEAD~1. Update the plan before you continue
Quality drops late in a long session	Earlier slices fill the context	Commit, start a fresh session, and point it at the plan and the next step
Two sessions overwrite each other’s files	Both worked in one checkout	Give each session its own worktree with --worktree

Where to go after the build

• Test and debug with Claude Code: tests that mean something, and finding why they fail.
• Review and ship with Claude Code: from a green branch to a merged, deployed change.
• Build workflows for all tools, the build stage in the method, and the same stage in Codex and Cursor.