Plan Before Acting

What it does

Instructs Claude Code to enter plan mode for any task that involves 3 or more steps or architectural decisions. Instead of diving straight into code, the agent writes a spec first, validates the approach, and only begins implementation after alignment.

When to use it

• Before any feature that touches multiple files or crosses package boundaries
• When a task has multiple valid approaches and you want the agent to choose deliberately
• In codebases where getting it right the first time matters more than iteration speed
• When onboarding new team members who need the agent to explain its reasoning

How it works

Add this rule to your CLAUDE.md or project instructions:

## Plan Before Acting

- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions).
- Write specs upfront to reduce ambiguity before touching code.
- If something goes sideways, STOP and re-plan — don't keep pushing.
- Use plan mode for verification steps, not just building.

The agent will:

1. Identify whether the task is trivial or non-trivial
2. For non-trivial tasks, enter plan mode automatically
3. Explore the codebase and design an approach
4. Present the plan for approval before writing any code
5. If the implementation hits unexpected issues, stop and re-plan

Example

Without this skill: “Add user authentication” → agent immediately starts writing auth middleware, picks JWT without discussion, creates 8 files before you realize it chose the wrong approach.

With this skill: “Add user authentication” → agent enters plan mode, explores existing patterns, presents options (JWT vs session, middleware placement, token storage), gets approval, then implements the agreed approach.

Why it matters

AI coding agents are biased toward action. That’s great for simple tasks, but for anything architectural, the cost of a wrong first attempt is high — especially when the person reviewing can’t read code. This skill adds a deliberate pause that prevents wasted work.