Plan Mode Guide

Your strategic planning and architecture agent — focused on thoughtful analysis before implementation, helping developers understand their codebase, clarify requirements, and create structured implementation plans.

When to Use This Agent

Choose Plan Mode Guide when:

• Starting a new feature that needs design thinking before coding
• Analyzing a codebase to understand its architecture and patterns
• Creating implementation plans with clear steps and dependencies
• Evaluating different approaches before committing to one
• Breaking down complex requirements into actionable work items

Consider alternatives when:

• You need actual implementation — use a developer agent
• You need code review — use a code reviewer agent
• You need multi-agent orchestration — use a coordinator agent

Quick Start

Copy
# .claude/agents/plan-mode.yml
name: Plan Mode Guide
model: claude-sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
description: Strategic planning agent for codebase analysis, requirements clarification, and implementation planning — analysis only, no code modifications

Example invocation:

claude "Analyze our authentication module and create an implementation plan for adding OAuth2 social login — consider the existing auth patterns, database schema, and frontend components"

Core Concepts

Planning Process

Phase	Activity	Output
Explore	Read code, understand structure	Architecture map
Clarify	Identify ambiguities, ask questions	Clear requirements
Design	Evaluate approaches, choose pattern	Design decision
Plan	Create step-by-step implementation	Executable plan
Review	Validate plan against requirements	Refined plan

Plan Document Structure

Copy
# Implementation Plan: [Feature]

## Context
- Current state of the system
- Relevant existing patterns
- Constraints and requirements

## Approach
- Chosen approach and rationale
- Alternatives considered and why they were rejected

## Implementation Steps
1. [Step with specific files and changes]
2. [Step with dependencies noted]
3. [Step with verification criteria]

## Risks and Mitigations
- [Risk]: [Mitigation]

## Open Questions
- [Questions that need answers before proceeding]

Configuration

Parameter	Description	Default
analysis_depth	How deeply to explore the codebase	thorough
plan_granularity	Step detail level (high-level, detailed, line-level)	detailed
include_alternatives	Document alternative approaches	true
include_risks	Include risk assessment	true
output_format	Plan format (markdown, checklist, tasks)	markdown

Best Practices

1. Explore the codebase before planning. Read the relevant files, understand existing patterns, and map dependencies before writing a plan. Plans based on assumptions about code structure (rather than actual knowledge) produce incorrect implementation steps.

2. Ask clarifying questions early. Ambiguous requirements lead to plans that solve the wrong problem. When requirements are unclear, surface the ambiguity explicitly with specific questions rather than assuming an interpretation.

3. Evaluate at least two approaches. Documenting alternatives (even briefly) forces you to justify your chosen approach. If you can't articulate why option A is better than option B, you haven't analyzed deeply enough.

4. Include verification steps in the plan. Each implementation step should have a way to confirm it worked. "Add the database migration" should be followed by "Run migrations and verify the new table exists with the expected schema."

5. Keep plans to a manageable size. If a plan exceeds 15 steps, consider splitting it into phases. Each phase should produce a working increment. Monolithic plans create all-or-nothing risk.

Common Issues

Plan becomes outdated before implementation starts. Long delays between planning and implementation cause drift. Keep plans lightweight and implement within 1-2 sprints. If the plan sits for a month, re-validate before proceeding.

Plan is too abstract to implement. "Update the service layer" doesn't tell the implementer what to do. Include specific file paths, function names, and code patterns. A good plan reads like a recipe — follow the steps and you get the result.

Planning phase takes longer than implementation would. Analysis paralysis disguised as thorough planning. Set a time-box for planning (half a day for a 1-week feature). If you're still planning after that, start implementing and iterate — you'll learn more from code than from analysis.