Build with agents: the workflow for your codebase

Building with AI agents means implementing an accepted spec in small slices: the agent drafts a read-only plan, builds one slice at a time in an isolated worktree, and stops when the gates pass. The loop is the same in Claude Code, Codex, and Cursor; the codebase’s shape changes the context, blast radius, and checks.

This section is for developers who run the agent and tech leads who define what a finished change proves. You point the agent at a ticket in a 2-million-line monolith, and it rewrites a shared helper that 40 services import. Unit tests pass; the pull request is unreviewable. The guides below prevent that for each kind of system.

Which build guide fits your codebase?

Your situation	Start with
The agent cannot hold the codebase and edits code it has not read	Million+ LOC strategies
One change cascades across packages that build and release together	Monorepo workflows
You must replace old code whose behavior nobody has written down	Legacy modernization
A change spans services, queues, and repositories	Distributed systems development
Consumers depend on an API contract the agent must not break	API development
The change needs a schema migration or a slow query fixed	Database design and queries

A greenfield feature in a small, well-tested repository needs only the core build loop.

What stays the same in every build workflow?

Every guide adapts this loop; the lifecycle build page adds a plan.md template and hooks.

1. Start from an accepted contract: a spec.md with numbered requirements and acceptance tests that fail now. Without one, go back to plan and specify.
2. Plan read-only. The agent maps the files and blast radius into plan.md. A named engineer accepts it before code changes.
3. Slice the work. Each slice is one reviewable pull request that leaves the build green. Large and legacy codebases need smaller slices, not bigger prompts.
4. Implement in isolation: one slice per worktree, so parallel sessions cannot collide. See running parallel agents in worktrees.
5. Stop on the gates, not the agent’s word. Tests, types, lint, and section checks pass in CI, and the pull request carries an evidence bundle.

How do you start a build session in each tool?

Commands checked against Claude Code 2.1.286 and Codex CLI 0.157.1; Cursor from its documentation on 2026-08-28.

Claude Code

# Terminal: plan without editing files
claude --permission-mode plan

# Terminal: implement the accepted plan in a new git worktree
claude --worktree pay-412-refunds

In an open session, /plan switches to plan mode; Shift+Tab cycles through the permission modes until plan mode is on. For many independent slices, the bundled /batch skill fans them out across worktrees. Before you push, run /code-review to review the diff locally.

Codex

# Terminal: start a session in a new managed git worktree
codex --worktree

# Terminal: non-interactive review of the branch against main
codex review --base main

In the session, type /plan so Codex plans before it writes code.

Cursor

Use Plan Mode for a plan before code, a Worktree (an isolated Git checkout) for the implementation, and Bugbot to review the pull request.

Copy-paste prompt: map the blast radius and slice the change

Read spec.md and the code it touches. Do not edit any files.
1. List every file, public function, and exported type the change
   must modify, and every caller of each one (search the whole repo,
   including other packages and services).
2. Mark which callers have tests that would fail if behavior changed,
   and which have none.
3. Propose an ordered list of slices. Each slice must be one pull
   request under ~400 changed lines that leaves the build green, and
   must name the acceptance tests it makes pass.
4. List what you could not determine from the code and who should
   answer it.
Write the result to plan.md and stop for my review.

Copy-paste prompt: implement one slice and prove it

Implement slice 1 from plan.md and nothing else.
Rules:
- Do not edit test files under tests/acceptance/ or any file outside
  the slice's file list. If you need to, stop and explain why.
- After each change, run the test, typecheck, and lint commands from
  AGENTS.md (or CLAUDE.md) and fix failures before moving on.
- Stop when slice 1's acceptance tests pass and the full suite is green.
Finish with a report: files changed, commands run with their exit
codes, acceptance tests now passing, anything in plan.md that turned
out to be wrong.

How do you know a build is done without reading every line?

Trust checks the agent cannot change; save human attention for decisions.

• Acceptance tests failed before and pass now. A test that never failed proves nothing; see how strong is your oracle.
• The agent cannot edit the oracle. CI rejects acceptance-test changes in an implementation pull request; see protecting the oracle.
• Machines check structure. Types, lint, and architecture fitness functions catch layering breaks.
• Each guide adds its own gate: contract tests for APIs, a migration dry run for databases, characterization tests for legacy code, affected-project builds for monorepos.
• A second agent reviews, a human signs off. The engineer who accepted plan.md approves the pull request against that plan and its evidence; see reviewing an agent’s pull request.

What breaks in agent-driven builds, and how do you recover?

Failure	Signal	Recovery
The agent edits code it never read	Changes in files missing from plan.md	Reject the pull request; rerun the blast-radius prompt and add the missed callers
One slice grows into the whole feature	A pull request too large to review	Revert to the last green commit; split the rest into new slices
Tests pass because the agent changed them	Test files change in an implementation pull request	Protect acceptance tests in CI; rerun the slice in a clean worktree
Parallel sessions collide	Merge conflicts or overwritten work	One slice per worktree and branch; merge in plan order
The plan turns out wrong mid-build	The agent patches around a false assumption	Stop, correct plan.md, and restart the slice in a fresh session

Where to go next after the build section

• Before: plan and specify, and make the codebase agent-ready.
• After: test and verify, then review and ship.
• Why gates let you leave the loop: Level 4: you write the specs.