Build

4 min read

Build

Time required: Varies by project (hours to days)
What this does: Implements the project phase-by-phase, following the implementation plan.
When to use: After architecture is approved. Repeat this process for EACH phase.
Critical rule: One phase at a time. Never ask Claude to build everything at once.
What you will have after this: Build phases complete with all steps implemented, tests passing, and ACs verified.

Before EVERY build phase: The Phase Startup Checklist

Do this at the START of every phase. No shortcuts.

Check context usage: Type /context in Claude Code. If above 40%, start a fresh session with /clear.
Check cost: Type /cost to see your token usage.
Check Beads: Type bd status to see current issues and which phase you are on.
Create a branch:

plaintext

Create a new branch from main: feature/phase-[N]-[short-description]

First Run Only: Database Setup

If your architecture includes a database (per your ADRs), the first build phase typically needs a running local database before any code works. Before starting Phase 1 implementation as Claude to:

plaintext

Can you please verify with the PRD, ARD and Implementation plan to:

1. Install and start the specified database locally (PostgreSQL, MySQL, SQLite, etc.)
2. Create the development database: check the ADR for the chosen database and naming convention
3. Add the connection string to your .env file (copied from .env.example)
4. Run initial migrations if the implementation plan's Phase 1 includes them
5. Verify the connection works before asking Claude to build against it

If using Docker for local databases (common for PostgreSQL and MySQL): docker compose up -d db

The implementation plan should specify database setup in Phase 1's prerequisites. If it does not, add it before starting the build.

Building a phase: The Loop

For each step in the phase, follow this loop:

1\. Give Claude ONE step at a time

Do NOT paste all the steps at once. Give Claude the first step:

plaintext

Run `bd ready` to load the current phase.

Then read:
- The matching phase section in /docs/implementation-plan.md
- AGENTS.md for file ownership and coordination rules
- /docs/interfaces.md for integration points
- Any page specs referenced in the phase (if frontend work)

Before writing any code, confirm:
1. What is being built this phase (user stories and AC numbers)
2. Execution mode: Solo, Sub-agents, or Agent Team
3. Team composition and lead mode (if Agent Team)
4. Prerequisites: are all prerequisite phases complete?
5. Branch name to work on
6. The ordered steps from the implementation plan
7. Definition of done
8. Libraries and frameworks used in this phase -- check Context7 for the current API of each one before planning any code. Flag anything deprecated or changed.
9. Existing code this phase touches -- use Serena to explore the current codebase structure (find references, check type hierarchies, navigate to definitions)rather than reading entire files. This preserves context tokens for actual work.

Show me this summary and wait for my go-ahead. We will use this summary as context and /clear before starting the build so we have a clean context window for implementation.

If execution mode is Agent Team:
- Prepare spawn prompts for each teammate including:
  - Their role and directory ownership from AGENTS.md
  - Relevant API contracts or interfaces they build against
  - Relevant page specs (if frontend)
  - What "done" looks like for their tasks
  - Instruction to read CLAUDE.md and AGENTS.md
  - Key library versions and API notes from the Context7 check
- Show me the proposed team and spawn prompts before spawning

If execution mode is Solo or Sub-agents:
- Walk through the steps in order from the implementation plan
- When navigating existing code, prefer Serena's semantic tools (find references,
  go to definition, type hierarchy) over reading full files
- Run tests after each meaningful change
- Check off AC items as they pass

When Claude presents a plan, review and update if necessary, otherwise give permission to continue

Only do this if you had to /clear the context window because you needed a larger context window:

plaintext

Run `bd ready` to reload the current phase context.
Read the implementation plan at /docs/implementation-plan.md for this phase.

Continue with the next step of the plan based on the implementation plan,
Beads status, and other project context.

Before writing any code:
- Check Context7 for the current API of any libraries you plan to use in this step
- Show me the plan for this step and wait for approval before starting

When all steps for a phase are done continue:

2\. After EVERY build phase run the full test suite, check acceptance criteria, update acceptance checklist, commit and push, update beads

plaintext

Run `bd ready` to confirm the current phase.
Read the implementation plan at /docs/implementation-plan.md for this phase's
acceptance criteria, definition of done, and execution mode.

Step 1: Clean up Agent Team (if applicable).
If this phase used an Agent Team:
- Ensure all teammates have finished their work
- Shut down all teammates
- Call TeamDelete to clean up -- do not leave orphaned sessions

Step 2: Run the full test suite.
Run the complete test suite (not just the tests for this phase).
Show me all results including coverage.
If any tests fail, fix them before continuing.

Step 3: Verify acceptance criteria.
Read /docs/prd/acceptance-checklist.md.
For each acceptance criterion that this phase covers (per the implementation plan),
verify whether our code satisfies it.

Show me a status report:
- ✅ AC-XXX: [description] -- PASSES because [reason]
- ❌ AC-XXX: [description] -- FAILS because [reason]

If any AC fails, fix it before continuing. Re-run the test suite after any fix.

Step 4: Update documentation.
- Mark all passing ACs as checked [x] in /docs/prd/acceptance-checklist.md
- Update CLAUDE.md "Current phase" to the next phase
  (or "Complete" if this was the final phase)

Step 5: Commit and push.
Commit all changes with message: "feat: complete phase [N] -- [short description]"
Push the branch.

Step 6: Close the issue.
Mark the Beads issue for this phase as complete using `bd complete [issue-id]`.

Step 7: Prepare for next phase.
Show me:
- Summary of what was completed
- Any issues or notes for the next phase
- What the next phase is and its execution mode

Then /clear to start the next phase with a clean context window.

3\. Clear context for next phase (if it doesn't do it itself)

css

/clear

THIS IS THE LOOP UNTIL YOUR PRODUCT IS BUILT:

Go back and run 1, 2, 3 in order. Remember to give Claude ONE step at a time

Continue this loop (give step → review approach → approve → run tests) for every step in the phase.

This resets the conversation while keeping CLAUDE.md. You are now ready for the next phase.

Using git worktrees for parallel phases (advanced)

If two phases have no dependencies on each other, you can work them in parallel using git worktrees. Each worktree is an independent copy of your repo on a different branch, with its own Claude Code session.

Create a worktree:

plaintext

git worktree add ../my-project-phase-3 feature/phase-3-description
cd ../my-project-phase-3
claude

Important rules for parallel work:

Each worktree has its own branch and file state
Changes in one worktree do NOT affect the other
When both phases are done, merge them into main one at a time
Resolve any merge conflicts carefully

Using subagents for focused tasks

For complex steps, you can ask Claude to spawn a specialist subagent:

plaintext

Use a subagent to: [describe the focused task, e.g., "write all the database migration files for the User and Project schemas"] The subagent should: - Only work on [specific files/scope]
- Report back when done with a summary of what was created

Claude will use the Task tool to spawn a subagent in a separate context. The subagent does its focused work and reports back. This keeps your main context clean.

Context management during long builds

Watch your context like a hawk. Follow these rules:

Important At 40% context: Consider compacting. Type /compact preserving current Phase progress, test results, and current step
At 60% context: MUST compact or clear. No exceptions.
Between phases: Always /clear
If Claude starts forgetting things or repeating mistakes:Your context is too full. Clear and reload.
Auto-compaction triggers at ~85% and can interrupt your work at a bad time. Do not let it get this high.

When things go wrong

Claude wrote broken code: Type /rewind to backtrack. This undoes both the conversation and the code changes.
Tests are failing and you cannot figure out why: Commit what works, /clear, and start the step fresh with explicit error context.
Claude is going in circles: Stop. /clear. Re-read the implementation plan step. Give Claude a more specific, constrained instruction.
You need to undo everything from this phase:git checkout main and delete the branch. Start the phase fresh.
Claude is debugging in circles: Superpowers' systematic-debugging skill should auto-activate and trace the bug backward through the call stack to find the root cause. If it is not activating, prompt Claude explicitly: "Use your systematic debugging skill to trace this issue to its root cause." If that still fails, /clear and start fresh with explicit error context as described above.
CI/CD is failing and you cannot figure out why: If the GitHub MCP server is connected, ask Claude: "Read the CI logs for the latest failed run on this branch." Claude can pull the full log output and diagnose the failure without you switching to the browser.

See Troubleshooting for more recovery scenarios.

Checkpoint

After each phase is complete, you should have:

All steps implemented and tested
All relevant acceptance criteria verified and checked off
A clean commit on the feature branch
Beads issue marked complete
Context cleared for the next phase

After building each phase, run verification. Open Test and Verify.

Sign up to read the full guide

Free access to all 12 workflow guides. No password needed.