Build: plan.md, then implement

The build stage turns an accepted spec.md into a committed plan.md, an isolated implementation, and its first verification evidence. Plan mode separates investigation from mutation; repository instructions, skills, hooks, and worktrees then keep execution reproducible without granting the agent authority to merge or deploy.

Traditional: An engineer reads the design and starts writing code. How the change will be made stays in their head. The first thing a reviewer sees is the finished diff, and by then rework is slow.

AI-native: Work starts with a written plan the agent produces in plan mode, where it can read the codebase without changing anything. The engineer corrects the plan before code is written. The approved version is committed as plan.md.

Before you begin

• intent.md and spec.md if they exist
• A project instruction file: CLAUDE.md, .cursor/rules, or AGENTS.md
• A test or build command the agent can run locally (see Test)

Start in plan mode

1. Start the session in plan mode so the agent cannot edit files yet.

2. Give the agent intent.md and spec.md and ask for an implementation plan that names the files that change, the order of the work, and the tests that prove it.

3. Interrogate the plan.

   Ask what the change could break, which step is most risky, and what other options the agent chose not to take.

4. Iterate until an engineer who has never seen the conversation could implement the change from the plan alone.

5. Commit the approved plan as plan.md.

   Later review checks the eventual diff against this file.

6. Accept the plan and let the agent implement.

   With a solid plan, implementation is often a single pass.

7. When implementation departs from the plan, update plan.md in the same commit.

Claude Code

Shift+Tab cycles permission modes until plan mode is active, then:

Read intent/FEATURE.md and spec.md. Produce plan.md that names the
files that change, the order of work, the risks, and the tests that
prove it. Do not edit application code until I accept the plan.

After accepting the plan, switch to the least permissive mode that can complete the approved slice. Isolate parallel work in separate worktrees:

claude -w feature-auth

The verified -w/--worktree option creates an isolated Git checkout for the session. Use a repository helper instead when setup also needs explicit ports, ignored configuration, or local database state.

Cursor

Switch to Plan mode, attach spec.md, and ask for plan.md in the repo — not only a plan under .cursor/plans/. The repo copy is what later review and other tools can read.

For parallel work, start a Cloud Agent per independent task, or use git worktrees locally. Cloud agents run command-based hooks from .cursor/hooks.json.

Codex

Use /plan or Shift+Tab. /plan exists in the Codex CLI, not only in the web app. approval_policy is a separate control (when to ask for approval), not a substitute for planning.

Save the accepted plan in the repository for longer work. Choose Worktree in the Codex app or create one explicitly with Git; Codex CLI 0.146.0 has no --worktree flag.

Institutional knowledge

Knowledge that used to sit in people’s heads becomes a file the agent reads at the start of every session.

1. Generate a starting file (/init in Claude Code, or ask the agent to draft AGENTS.md / .cursor/rules from the repo).

2. Cut it down to what a new joiner needs on day one: build, test, and lint commands; conventions that matter; the mistakes the agent keeps making.

3. Check the file into git at the repo root so the whole team shares one version.

4. When the agent makes a mistake twice, put the correction in the file.

5. Keep it short. Stale text costs context and helps nobody.

Example CLAUDE.md (the same content belongs in AGENTS.md or a Cursor rule):

# Payments service

## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint

## Conventions
- Java 21, Spring Boot 3. No new Lombok.
- Money is always BigDecimal, never double.
- Every endpoint needs an integration test in src/itest.

## Things the agent gets wrong
- Do not bump dependency versions; the platform team owns them.
- The legacy v1/ package is frozen; changes go in v2/.

Skills versus rules

Write a skill (SKILL.md) for institutional knowledge that must be applied consistently: a security standard, an API convention, a brand rule. Put it in .claude/skills/NAME/, .cursor/skills/, or .agents/skills/. Cursor also reads .claude/skills/ for compatibility.

Do not write a skill for facts that belong in CLAUDE.md / AGENTS.md (commands, local conventions). A skill is advisory. A policy that must always hold needs a hook behind it.

Build-time hooks

A hook is the deterministic layer behind a skill. During implementation, hooks can:

• Block edits to protected paths (generated classes, a frozen package)
• Run the formatter and linter after file edits
• Keep credentials out of the diff

Keep build-phase hooks fast and scoped to the file that changed. Heavier checks belong at commit or PR. A hook that asks a human for approval belongs in Deploy, because an approval prompt during build puts a person back on the critical path of every parallel session.

Claude Code: .claude/settings.json plus scripts under .claude/hooks/. Cursor: .cursor/hooks.json. Codex: sandbox mode plus approval_policy — there is no hook runtime identical to Claude Code; encode must-hold policy as sandbox denies and CI.

Parallel sessions and subagents

Split work that touches different files. Tasks that share files run in a single session, one after another.

A parallel session is another full agent in its own worktree. A subagent runs inside one session with its own context and tool limits (verifier, researcher, simplifier). Two or three sessions is a sensible start; the ceiling is how many streams one person can review.

Turn repeated jobs into subagents checked into git (.claude/agents/ or the Cursor/Codex equivalent). Example verifier:

---
name: verifier
description: Runs the app and checks the change works before the session reports done
tools: Bash, Read
---
Start the app with make run. Exercise the changed behavior and the two
nearest neighboring flows. Report what you ran, what you saw, and any
behavior that does not match plan.md. Do not fix anything; report only.

The verifier is not the feedback loop. The loop runs throughout the task; the verifier is a fresh context window at the end so the verdict is not colored by the assumptions that produced the code. See Test.

Governance

Design review happens before any code is generated, when changing course is still editing a document. Plan mode enforces this: the agent cannot edit files until the engineer accepts the plan. Routine changes are approved by the engineer. Higher-risk work goes to a tech lead or architect.

More sessions means more output, so controls have to come from configuration in the repo. Hooks and permission settings there apply to all sessions. What a session does is attributed to the engineer who ran it.

Verify

• plan.md is committed before application code changes land.
• The instruction file lists commands the agent actually ran.
• Tests or the build ran inside the session before you opened a PR.

Leading indicator: share of changes that merge from the first implementation pass, and time from plan approval to merged PR.

Lagging indicator: rework cycles per change, and how often the merged diff still matches the committed plan.md.

Apply the play in your tool

Claude Code adapter Use Plan mode, claude -w, subagents, and deterministic hooks.

Cursor adapter Use Plan mode, Agents Window worktrees or /worktree, and project rules.

Codex adapter Use /plan, app or Git worktrees, AGENTS.md, and an explicit sandbox.

Feed the implementation into verification

Give the session a way to check its own work — Test — then send the diff through Deploy.