Separate planning from implementation with a dedicated Claude Code skill

Problem

When you ask Claude Code to build something, it tends to start writing code immediately. The agent jumps to implementation before fully understanding what you want, leading to a cycle of generating code, realizing it's wrong, and regenerating. This wastes tokens, produces suboptimal solutions, and often misses important requirements that only surface through deeper questioning. The planning phase and the implementation phase have fundamentally different goals, yet they get mixed into a single conversation.

Solution

Create a dedicated planning skill that explicitly forbids code generation and forces a structured requirements-gathering conversation before any implementation begins.

Create the skill file at .claude/skills/detailed-change-planning.md:

---
name: detailed-change-planning
description: Creates a detailed change plan to give to an implementation agent. Use when planning or when the user asks to plan something.
---

You are a planning agent. Your job is to fully understand the user's intention and create a detailed implementation plan.

## Rules

- DO NOT WRITE CODE. You are a planner, not an implementer.
- DO NOT create, edit, or modify any files.
- You MAY read files to understand the codebase.

## Process

1. Understand the user's intention by reading relevant code and asking questions
2. Ask ONE question at a time to fully uncover the requirement
3. For each question, give a full accounting of tradeoffs for each option
4. Always give a recommended answer and explain why
5. Continue until you have complete clarity on the desired change
6. Output a detailed plan in markdown format

## Plan output format

Write the plan to PLAN.md with:
- **Goal**: What we're trying to achieve
- **Current state**: How the code works today
- **Changes**: Step-by-step list of modifications
- **Files affected**: Every file that will be created or modified
- **Edge cases**: Anything that could go wrong
- **Testing**: How to verify the changes work

The two-phase workflow:

Phase 1: Planning (high-capability model)
  User → /detailed-change-planning → interactive Q&A → PLAN.md

Phase 2: Implementation (can use a less capable model)
  PLAN.md → Claude Code / Codex → code changes → review

Invoke the planning skill:

# In Claude Code, trigger the skill
> /detailed-change-planning I need to add OAuth support to our API

# The agent will ask questions one at a time:
# "Which OAuth providers do you need to support?"
# "Should tokens be stored in the database or as JWTs?"
# "What's the session expiry policy?"
# ... until requirements are fully captured

Why It Works

Planning and implementation require different cognitive modes. Planning needs broad exploration, tradeoff analysis, and user collaboration. Implementation needs focused, sequential code generation. By putting an explicit DO NOT WRITE CODE instruction in the skill, you prevent the agent from short-circuiting the planning process. The one-question-at-a-time rule ensures the agent doesn't make assumptions -- it surfaces decisions you might not have thought about. The resulting PLAN.md serves as a complete specification that a less capable (and cheaper) model can execute, because all the hard decisions have already been made.

Context

• Keep your CLAUDE.md short and focused on project conventions; put complex behavioral logic in skills instead
• The planning skill works well with Claude Code's / skill invocation syntax
• The plan output can be fed to OpenAI Codex, Claude Code with Sonnet, or any other coding agent for implementation
• A useful extension is adding a review phase: Opus for planning, Sonnet/Codex for implementation, Opus for code review
• This pattern reduces total token spend because you avoid generating and discarding incorrect code during the exploration phase