Phase Development

Structured workflow for major features using phase documents and AI planning.

When to Use Phase Development

Use Phase Development when:

  • Adding a major new feature with multiple tasks
  • Development spans multiple days or weeks
  • Need structured planning before coding
  • Want to track progress across multiple tasks
  • Feature requires coordination across multiple files/components

Overview

Phase Development uses a two-stage AI workflow:

  1. Planning Stage: Use Claude Code in plan mode to create a detailed phase document
  2. Development Stage: Use Claude Code to execute the plan task by task

This separation ensures thorough planning before coding begins.

Step 1: Plan with Claude Code in plan mode

Start Claude Code on the repository and switch it to plan mode, where Claude proposes an approach without editing any files. In the desktop app, pick Plan from the permission-mode selector; in the terminal, press Shift+Tab until it shows plan mode. Then describe the feature you want to build and ask for a phase document.

Prompt for creating a phase document
Claude prompt
I'm building a feature for my app called [app-name]. I need you to create a detailed phase document for implementing [feature description]. The phase document should include: 1. Phase goal and expected outcome 2. Prerequisites and dependencies 3. Numbered tasks with detailed implementation steps 4. Verification steps for each task 5. Definition of Done checklist 6. List of files to create/modify Context about my app: - [Brief description of your app] - [Current tech stack] - [Any constraints or requirements] Please format this as a markdown document I can save as a phase file.

Phase Document Structure

Your AI will generate a document following this structure:

# Phase N: Feature Name

## Goal
Brief description of what this phase accomplishes.

## Prerequisites
- [ ] Required setup or dependencies
- [ ] Previous phases completed

## Tasks

### Task 1: Setup/Foundation
**Steps:**
1. Create file X
2. Add configuration Y
3. ...

**Verification:**
- [ ] File exists and compiles
- [ ] Tests pass

### Task 2: Core Implementation
...

## Definition of Done
- [ ] All tasks completed
- [ ] Build passes
- [ ] Tests pass
- [ ] Deployed to staging

## Files to Create/Modify
- `app/feature/page.tsx`
- `app/api/feature/route.ts`
- ...

Step 2: Save the Phase Document

  1. Copy the AI-generated phase document
  2. Save it to your app's ai_docs/plans/ directory
  3. Name it following the pattern: phase-N-feature-name.md
Example file locationbash
apps/my-app/ai_docs/plans/phase-2-user-dashboard.md

Step 3: Update PLAN.md

Reference the new phase in your app's PLAN.md file:

## Current Phase

**Phase 2: User Dashboard** (In Progress)
- See: [Phase 2 Plan](ai_docs/plans/phase-2-user-dashboard.md)

### Status
- [ ] Task 1: Setup dashboard layout
- [ ] Task 2: Add metrics widgets
- [ ] Task 3: Implement data fetching

Step 4: Start Development in Claude Code

Take Claude Code out of plan mode so it can edit files again, then tell it to analyze the phase document and begin development.

Start phase development in Claude Code
Claude prompt
my-app-name: I want to start working on Phase 2 (User Dashboard). Please read the phase document at ai_docs/plans/phase-2-user-dashboard.md and analyze it. Then: 1. Create a feature branch for this phase 2. Start with Task 1 3. Follow the Minor Changes workflow for each task (plan mode, implement, test, commit) Let me know when you're ready to begin.

Claude will:

  1. Read and analyze the phase document
  2. Create a feature branch (e.g., feature/phase-2-user-dashboard)
  3. Break down the first task and begin implementation

Step 5: Execute Tasks One by One

Work through each task in the phase document:

  1. Start task: Tell Claude which task to work on
  2. Implement: Claude implements following Minor Changes workflow
  3. Verify: Check the verification steps pass
  4. Commit: Create a commit for the completed task
  5. Update status: Mark task complete in PLAN.md
  6. Next task: Move to the next task
Moving to the next task
Claude prompt
Task 1 is complete and verified. Let's move to Task 2: Add metrics widgets. Please read the task details from the phase document and begin implementation.

Step 6: Complete the Phase

When all tasks are done:

  1. Final verification: Run full build and tests
  2. Create PR: Submit PR for the entire phase
  3. Update PLAN.md: Mark phase as complete
  4. Archive: Optionally move phase doc to ai_docs/plans/archive/
Complete the phase
Claude prompt
All tasks for Phase 2 are complete. Please: 1. Run a final build to verify everything compiles 2. Create a Pull Request to main with a summary of all changes 3. Update PLAN.md to mark Phase 2 as complete

Tips for Effective Phase Development

Planning Tips

  • Be specific about requirements in your initial prompt
  • Include UI mockups or wireframes if available
  • Mention any existing code patterns to follow
  • Specify testing requirements upfront

Execution Tips

  • Complete one task fully before starting the next
  • Commit after each task (not at the end of all tasks)
  • Update PLAN.md status regularly
  • If a task is too large, break it into subtasks

When to Re-plan

  • If you discover the plan is missing critical steps
  • If requirements change significantly
  • If technical blockers require a different approach

In these cases, update the phase document before continuing.

Example: Adding User Authentication

Phase document excerpt:

# Phase 3: User Authentication

## Goal
Add email-based authentication using Better Auth.

## Tasks

### Task 1: Setup Better Auth
1. Install better-auth package
2. Configure auth in middleware.ts
3. Add environment variables

### Task 2: Create Login Page
1. Create app/[locale]/login/page.tsx
2. Add email input form
3. Implement magic link request

### Task 3: Protected Routes
1. Update middleware for auth checks
2. Add redirect to login for protected pages
...

This phase would take 3-5 commits (one per task) and result in a complete authentication feature.