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

URL: https://developertoolkit.ai/en/claude-code/build/
Description: Claude Code build guides for developers and tech leads: implement an approved plan in slices, run large changes, and prove each change with gates.

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](/en/claude-code/build/implementation/) and [multi-file workflows](/en/claude-code/build/multi-file-workflows/) | Small commits, each green in CI |
| One mechanical change must hit hundreds of files | [Batch operations](/en/claude-code/build/batch-operations/) (the bundled `/batch` skill) and [large-scale refactoring](/en/claude-code/build/refactoring/) | Independent PRs, each with its own gate |
| Better structure, same behavior | [Refactoring patterns](/en/claude-code/build/refactoring-patterns/) | Characterization tests first, then the refactor |
| New REST or GraphQL endpoints | [API development](/en/claude-code/build/api-development/) | A contract, and tests that check it |
| Schema, query, or data changes | [Database work](/en/claude-code/build/database-work/) and [migrations](/en/claude-code/build/migrations/) | Migrations proved on a disposable database |
| A payment, email, or OAuth provider | [Third-party integrations](/en/claude-code/build/integrations/) | Sandbox-tested integration code |
| Docs drift from the code | [Documentation](/en/claude-code/build/documentation/) | Docs regenerated and kept true by a gate |
| The repository exceeds the context | [Large codebases](/en/claude-code/build/large-codebase/) | Scoped sessions that read only what matters |
| Claude forgets your conventions between sessions | [The memory system](/en/claude-code/build/memory-system/) | A `CLAUDE.md` and rules that hold |

The rest of the section is your daily setup: [command-line flags and sessions](/en/claude-code/build/command-line/), [prompt engineering](/en/claude-code/build/prompt-engineering/), [slash commands](/en/claude-code/build/slash-commands-mastery/), [terminal mastery](/en/claude-code/build/terminal-mastery/), [IDE and CLI coordination](/en/claude-code/build/ide-coordination/), [the desktop app](/en/claude-code/build/desktop-app/), [workflow optimization](/en/claude-code/build/workflow-optimization/), [efficiency hacks](/en/claude-code/build/efficiency-hacks/), and [features you haven't tried](/en/claude-code/build/features-you-havent-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](/en/claude-code/plan/).

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

   ```bash
   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 (both release channels on 2026-10-12), Claude Code defaults to Claude Opus 5.5 at `medium` effort; on an older install, 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](/en/ecosystem/models/).

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

```text
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**

```text
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](/en/claude-code/automate/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](/en/ladder/evidence-not-diffs/); the PR format is the [evidence bundle](/en/workflows/ship/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](/en/claude-code/test/): tests that mean something, and finding why they fail.
- [Review and ship with Claude Code](/en/claude-code/ship/): from a green branch to a merged, deployed change.
- [Build workflows for all tools](/en/workflows/build/), [the build stage in the method](/en/method/lifecycle/build/), and the same stage in [Codex](/en/codex/build/) and [Cursor](/en/cursor-ide/build/).