The Three-Phase Workflow

The single most effective pattern for agentic development separates work into three distinct phases, each with its own context management strategy.

Why Phases Matter

When an agent jumps straight to coding, several things go wrong:

• It solves the wrong problem (no research)
• It chooses a suboptimal approach (no planning)
• Context fills with exploration debris (no isolation)
• Mistakes compound because the agent can’t verify against a plan

The three-phase workflow addresses all of these by treating each phase as a separate context-managed unit.

The Three Phases

1. Research Phase

   Goal: Understand the codebase, architecture, and constraints before committing to an approach.

   Context strategy: Use sub-agents for exploration. They read files, trace code flows, and return compressed summaries. The main context stays clean.

   Outputs:

   • Structured summary of relevant code and patterns
   • Dependency map for affected files
   • Identified constraints and risks
   • Recommended approach options

   Example prompt:

   Use sub-agents to research:
   1. How our auth middleware handles session tokens
   2. What rate limiting patterns exist in the codebase
   3. What the test infrastructure looks like for middleware
   
   Document findings in RESEARCH.md

   Human review point: Validate the research is accurate and complete before planning.

2. Planning Phase

   Goal: Create a detailed, step-by-step implementation plan that can survive context compaction.

   Context strategy: Switch to planning mode if your tool supports it. Work from the research summary, not raw file contents. Keep the plan concrete enough that a fresh agent could execute it.

   Outputs:

   • Step-by-step implementation sequence
   • Exact files to modify and the nature of changes
   • Test plan with specific scenarios
   • Verification criteria for each step
   • Rollback strategy

   Example prompt:

   Based on the research in RESEARCH.md, create a detailed
   implementation plan for adding rate limiting.
   
   For each step, specify:
   - Which file to modify
   - What the change does
   - How to verify it works
   - Dependencies on other steps
   
   Save the plan to PLAN.md

   Human review point: This is the HIGHEST leverage review. One bad plan line = hundreds of bad code lines. Edit the plan directly before implementation.

3. Implementation Phase

   Goal: Execute the plan with test-driven verification at each step.

   Context strategy: Start a fresh context or compact your context. Load the plan. Implement step by step with verification after each.

   Example prompt:

   Follow the plan in PLAN.md. For each step:
   1. Write failing tests first
   2. Implement the minimum code to pass
   3. Run tests and verify
   4. Move to the next step
   
   If you hit a blocker, stop and explain rather than improvising.

   Human review point: Review the code diff, but trust the plan. Most issues should have been caught in planning.

Compaction Between Phases

The key innovation is compacting between each phase:

Research Phase (fills context to ~70%)
    ↓ compact context — preserve findings, discard file reads
Plan Phase (starts at ~20%, fills to ~50%)
    ↓ compact context — preserve plan, discard planning discussion
Implementation Phase (starts at ~15%, fills to ~60%)
    ↓ Done — commit and clear context

Each phase starts with a nearly clean context, carrying forward only the essential artifacts (research summary, plan) rather than the raw exploration data.

When to Use Each Phase

Situation	Phases Needed
Fix a typo	None — just do it
Small bug fix (clear location)	Implement only
Bug fix (unclear location)	Research → Implement
New feature (simple)	Plan → Implement
New feature (complex)	All three phases
Refactoring (major)	All three phases
Architecture change	All three phases + multiple implementation sub-phases

Tip

If you could describe the diff in one sentence, skip the plan. Planning adds overhead — use it when the approach is uncertain, the change spans multiple files, or you’re unfamiliar with the code.

Real-World Results

Evidence from a 300,000-line Rust codebase (BAML project):

Task	Without Phases	With Three-Phase
Single bug fix	~3 hours, multiple attempts	~1 hour, merged first attempt
Major feature (35k LOC)	Not attempted	7 hours total (3 research/planning, 4 implementation)
Refactoring	Frequent context pollution, abandoned	Clean context throughout, completed

The critical success factor: active human participation at phase boundaries. No “magic prompt” exists — the workflow works because humans validate research, critique plans, and review implementation decisions at strategic points.

Phase Artifacts

Each phase produces a durable artifact that survives compaction:

Phase	Artifact	Format
Research	RESEARCH.md	Structured findings, file locations, dependency maps
Planning	PLAN.md	Step-by-step implementation with verification criteria
Implementation	Git commits	Incremental, tested changes

These artifacts serve double duty: they persist critical information across context boundaries AND provide review surfaces for human oversight.

For tool-specific instructions on switching to planning mode and triggering context compaction, see the Tool Configuration Reference.