Plan a Feature

The canonical agentic-coding loop, in four phases: Explore, Plan, Code, Commit. Anthropic's own guidance is that jumping straight to code is the most common way agents go wrong. This skill makes the loop explicit.

When to use this

Invoke /plan-feature (or just follow this loop) for any change where the steps are not already obvious: a new feature, a multi-file refactor, a behavior change, a bug whose cause is unknown.

The one-sentence skip heuristic: if you can describe the entire diff in one sentence ("rename getUser to fetchUser across the repo", "bump the timeout from 5s to 30s"), skip planning and just make the change, then verify. Planning a trivial edit is waste. Everything else gets the loop.

Phase 1: Explore (understand before touching)

Do not write code yet. Build an accurate model of the current state.

• Read the relevant files, tests, and types. Follow the real call paths, do not assume them.
• Find the existing patterns: how does this codebase already solve similar problems? Match them.
• Identify the blast radius: what else depends on what you are about to change? (See .claude/rules/depth-first-impact-analysis.md.)
• For verbose or wide exploration, dispatch a read-only researcher sub-agent so the main context stays clean (see .claude/rules/ai-orchestration-decision-gate.md).

Exit criterion: you can state, in plain language, what exists today and why the change is needed.

Phase 2: Plan (make the approach explicit and reviewable)

Write the plan down before editing. Use plan mode (Shift+Tab to enter it, so the model proposes without making changes) for anything non-trivial.

A good plan states:

• Goal: the one-sentence outcome.
• Approach: the chosen design, and why, over the alternative you rejected.
• Steps: the ordered changes, each small enough to verify on its own.
• Files: the specific files each step touches (this is also the parallel-conflict map if you delegate).
• Acceptance criteria as commands: the exact npm test, npx tsc --noEmit, or curl that proves each step (see .claude/rules/ai-agent-engineering.md).
• Risks and rollback: what could break, and how you back out.

For high-stakes or contested designs, get the plan reviewed before coding: a reviewer or architect sub-agent, or the review-board prompt (.claude/prompts/review-board.md). Cheaper to fix a plan than a diff.

Phase 3: Code (execute one verifiable step at a time)

• Implement one step. Run its acceptance command. Confirm it passes before the next step.
• Prefer test-first where it fits: write the failing test, then make it pass (see .claude/skills/tdd-workflow/SKILL.md).
• Keep changes small and incremental. A 600-line diff that "should work" is worse than six 100-line diffs that each verifiably do.
• If you correct the same problem twice without progress, stop. Clear the cluttered context, re-read, and re-plan with a fresh prompt rather than piling on more attempts.

Phase 4: Commit (capture verifiable units)

• Commit after each logical, verified unit of work, not once at the end. See .claude/skills/commit/SKILL.md.
• Each commit message is descriptive and conventional (type(scope): subject), explains the why, and carries no AI attribution.
• Before declaring done, run the definition-of-done gate: .claude/skills/verification-before-completion/SKILL.md. Paste the actual lint/build/test output; do not claim green from memory.

Anti-patterns

• Editing before exploring (you will fight the codebase's existing patterns).
• A plan with no acceptance commands (you cannot prove the steps).
• A single giant commit at the end (no rollback granularity, no reviewable units).
• Planning a one-sentence change (waste; just do it and verify).

Related

• .claude/rules/ai-orchestration-decision-gate.md, when to delegate exploration vs do it inline
• .claude/rules/depth-first-impact-analysis.md, mapping the blast radius in Phase 1
• .claude/skills/tdd-workflow/SKILL.md, the red-green-refactor cycle for Phase 3
• .claude/skills/commit/SKILL.md and .claude/skills/verification-before-completion/SKILL.md, Phase 4 gates
• .claude/prompts/review-board.md, reviewing a plan before coding