# Feature planning in Claude Code: from a one-line request to a verified plan

URL: https://developertoolkit.ai/en/claude-code/plan/feature-planning/
Description: Turn a vague feature request into acceptance criteria and a phased, verifiable plan with Claude Code plan mode, an interview, and a fresh-session plan audit.

Feature planning in Claude Code turns a vague request into a plan that can be verified before any code changes. Plan mode lets Claude read the codebase while edits stay blocked. Claude then runs a requirements interview, drafts acceptance criteria, and writes a phased plan. A fresh session then audits the plan against the code before anyone approves it.

Your product manager posts one line in Slack: "Workspace admins should be able to invite teammates by email." There is no spec. Nobody has said what happens when the invitee already has an account, when the workspace is out of seats, or when an invitation link is forwarded. This page is for the developer who owns that feature, and for the tech lead who signs off on the plan before an agent builds it.

## What this workflow gives you

- A plan-mode session setup, with the effort level and model chosen on purpose rather than by habit.
- Six copy-paste prompts: explore the code, run the requirements interview, write acceptance criteria, write the phased plan, audit the plan in a fresh session, and research scope with subagents.
- A sign-off table that says which check proves each part of the plan and who approves it, so nobody has to re-read the whole plan line by line.
- Recovery steps for the ways planning sessions go wrong: plans that are too vague, invented file paths, interviews that loop, and context that runs out.

## How do you start a feature-planning session in Claude Code?

Plan mode is the `plan` permission mode. Claude can read files and run the commands that are approved for it, but it cannot edit project files until you approve a plan. That is the property you want while the requirements are still wrong.

1. Start a named session in plan mode. In your terminal, run:

   ```bash
   claude --permission-mode plan -n invites-planning
   ```

   `-n` (`--name`) sets the display name that the `/resume` picker shows, so you can find the session again next week. In a session that is already running, press `Shift+Tab` until the mode indicator shows plan mode, or type `/plan` followed by the request. From v2.1.283, interactive sessions start in auto mode on supported models, so `Shift+Tab` cycles through more modes than before.

2. Keep the default model and tune effort first. Claude Opus 5.5 is the Claude Code default on every paid plan from v2.1.280, and it runs at `medium` effort by default. For a feature with real ambiguity, such as invitations that touch auth, billing, and email, raise effort with `/effort high` before you consider changing model. Switch to Claude Fable 5.1 (`/model fable`) only when your own comparison shows Opus at higher effort falls short. The `opusplan` alias uses Opus in plan mode and Sonnet for execution if you want a cheaper build phase. Versions and prices live on the [models hub](/en/ecosystem/models/), and [deep reasoning and effort levels](/en/claude-code/quick-start/deep-reasoning/) explains the effort trade-off.

3. Decide where plans are saved. By default Claude Code writes plan files under `~/.claude/plans/`, outside your repository. To keep plans next to the code, where they can be reviewed in a pull request, set `plansDirectory` in `.claude/settings.json`:

   ```json
   {
     "plansDirectory": "docs/plans"
   }
   ```

   The path is relative to the project root and must stay inside it (checked against the v2.1.283 settings schema).

4. Pull in the ticket, if it lives in a tracker. An MCP server saves you from pasting requirements by hand. For Jira and Confluence, the Atlassian remote server is added from your terminal:

   ```bash
   claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp
   ```

   Then run `/mcp` in the session to sign in. Other trackers and the security trade-offs are in [MCP setup for Claude Code](/en/claude-code/quick-start/mcp-setup/).

If the codebase is new to you, run the [codebase analysis workflow](/en/claude-code/plan/codebase-analysis/) first. If the feature forces a structural choice, such as a new service, a new datastore, or a tenancy model, make that decision with the [architecture analysis workflow](/en/claude-code/plan/architecture/) and record it as an ADR. This page plans a feature inside an architecture you already have.

## Explore the code before you plan anything

The most common planning failure is a plan written against an imagined codebase. Start by making Claude show you what exists, with evidence you can spot-check in seconds.

**Copy-paste prompt: explore before planning**

```text
We are going to plan a feature: workspace admins invite teammates by email.
Do not propose a design yet. First report what already exists:

1. How users, workspaces and memberships are modelled (tables, models, relations).
2. How sign-up and login work today, including any magic-link or token flows.
3. Where roles and permissions are checked for workspace-level actions.
4. How transactional email is sent, and whether there is a template system.
5. Whether seats or plan limits are enforced anywhere, and where.
6. The closest existing feature to this one, which we should imitate.

Cite every claim as path:line. If you did not find something, say
"not found" and list where you looked. Do not guess.
```

Open two or three of the cited lines yourself. If a citation is wrong, stop and correct the session before planning. Every later step inherits the error.

## Let Claude interview you about the requirements

You do not know every question to ask, and the ones you miss become production bugs. Ask Claude to interview you with the `AskUserQuestion` tool, which presents questions with selectable answers in the terminal instead of a wall of text.

**Copy-paste prompt: requirements interview**

```text
Interview me about the team-invitations feature using the AskUserQuestion tool.
Ground every question in what you found in the code, and ask in batches of
at most four questions.

Cover: invitees who already have an account, invitees who belong to another
workspace, seat limits and what happens at the limit, invitation expiry and
revocation, forwarded or reused links, who is allowed to invite, rate limits
and abuse, audit logging, and what happens to pending invitations when the
inviter leaves.

Skip anything the code already answers. After each batch, write down the
decisions so far in one list. Stop when no open question would change the
data model, the API or the permissions, and tell me which questions you
deliberately left open.
```

A good interview produces questions like these, each tied to a line of your code:

- "`memberships` has a unique index on `(user_id, workspace_id)`. Should inviting an existing member be a no-op, an error, or a resend?"
- "Seats are counted in `billing/seats.ts` at checkout only. Should a pending invitation reserve a seat?"
- "Magic-link tokens in `auth/tokens.ts` never expire. Should invitation tokens reuse that code, or have their own expiry?"

Answer in the terminal. When you answer "not sure", tell Claude to record the question under open questions rather than invent an answer.

## Turn the answers into acceptance criteria before the plan

Acceptance criteria are the part of the plan a human approves instead of the diff. Write them before the implementation plan. Otherwise the plan quietly decides the behaviour for you.

**Copy-paste prompt: acceptance criteria**

```text
From the decisions we just recorded, write acceptance criteria for team
invitations as Given/When/Then scenarios.

Rules:
- One observable behaviour per scenario. No implementation details.
- Include the failure cases we discussed: seat limit reached, expired token,
  revoked invitation, token reused by a different email, non-admin inviter.
- Give each scenario an ID (INV-01, INV-02, ...).
- Mark every scenario that depends on an open question as BLOCKED and name
  the question.

Put them under a heading "Acceptance criteria" at the top of the plan.
```

The product owner or the feature's owner approves this list. The full practice, including turning each scenario into a failing test that the implementing agent cannot edit, is in [executable acceptance criteria](/en/workflows/plan/acceptance-criteria/).

## Write a phased plan that ships in slices

Now ask for the plan itself. The prompt forces the three properties that make a plan executable by an agent and checkable by you: named files, independent phases, and a verification command for every phase.

**Copy-paste prompt: phased implementation plan**

```text
Write the implementation plan for team invitations below the acceptance
criteria.

For each phase:
- Goal, and the acceptance-criteria IDs it satisfies.
- Files to create or change, as exact paths. Mark new files as NEW.
- Database migration, if any, and how to roll it back.
- Tests to write first, named after the INV-xx IDs they prove.
- The one command that shows the phase is done (for example
  "pnpm test invitations" plus "pnpm typecheck").
- Risks, and what we do if the phase has to be reverted.

Order the phases so each one can merge and deploy on its own behind a
feature flag. Follow the patterns of the closest existing feature you
found earlier; do not introduce a new library or pattern without
flagging it as a decision for me. End with a list of open questions.
```

When Claude presents the plan, you can approve it, keep planning, or edit it. Press `Ctrl+G` to open the plan in your default text editor. Cut scope you want to defer, reorder phases, and add notes, then save and close the editor. Claude continues from your edited version.

Plan files get a generated name. The audit and resume prompts below read `docs/plans/team-invitations.md`, so give the plan that stable path before you approve it, as the caution below shows, or rename the file yourself afterwards.

Every approve option ends plan mode for that session, and Claude starts editing files; a note typed alongside an approval does not reliably stop that. If you only want a document, choose the keep-planning option instead and type: "Write the plan to `docs/plans/team-invitations.md` and stop. Do not implement." If you already approved, press `Esc` to stop Claude before it edits.

## How do you verify the plan without reading every line?

A plan is a set of claims about your codebase: "this file exists", "this function is the only place seats are checked", "phase 2 does not depend on phase 3". Each claim has a cheap check. Run the checks in a **fresh** session, because a session that wrote a claim tends to confirm it.

**Copy-paste prompt: plan audit in a fresh session**

```text
Read docs/plans/team-invitations.md. You did not write it. Audit it
against the codebase and report a table with one row per finding.

Check:
1. Every path marked as existing exists, and every cited function is
   where the plan says.
2. Every acceptance criterion (INV-xx) is covered by at least one phase
   and at least one named test. List any criterion with no test.
3. No phase depends on a later phase. List any hidden dependency.
4. Every migration has a rollback step.
5. Nothing in the plan contradicts the patterns in the closest existing
   feature. Cite path:line for each contradiction.
6. Every place that checks workspace permissions or seats is in scope.
   Use subagents to search the whole repository and list any the plan
   misses.

Mark each row SUPPORTED, WRONG or MISSING. Do not fix the plan.
```

Start it with `claude --permission-mode plan` in a new terminal. Send WRONG and MISSING rows back to the planning session, and repeat until the audit is clean. Then use this table to decide who signs off on what:

| Part of the plan | How it is checked | Who signs off |
| --- | --- | --- |
| Acceptance criteria | Read in full; they are short by design | Product owner or feature owner |
| File paths and cited code | Fresh-session audit, rows 1 and 5 | Nobody, if the audit is clean |
| Coverage of criteria by tests | Audit row 2, then failing tests written before phase 1 | Developer |
| Phase order and rollback | Audit rows 3 and 4 | Tech lead, for plans with more than one migration |
| Completeness of scope | Subagent search, audit row 6 | Developer spot-checks two findings |

The human reading is concentrated on the acceptance criteria and the open questions. Everything else is checked by a tool or by an independent session, and during implementation by the tests and gates each phase names. The wider practice is described in [reading evidence instead of code](/en/ladder/evidence-not-diffs/).

## Research scope with subagents

On a large codebase the planning session fills up with exploration output. Delegate the searches to subagents, which run in their own context and return only a summary. Explore and Plan are built-in subagents; for your own instructions and tool limits, see [custom subagents](/en/claude-code/automate/custom-subagents/).

**Copy-paste prompt: scope research with subagents**

```text
Before we finalise the plan, use subagents in parallel to find:

1. Every query that reads or writes workspace memberships.
   List by file and line.
2. Every API route that lists users or members, which would need to
   show or hide pending invitations.
3. Every background job or webhook that assumes one user per seat.

Each subagent returns at most 20 lines. Then tell me which findings
change the plan, and update the plan's file list.
```

## Plan across several sessions without losing decisions

Large features take more than one sitting. Resume the named session later with `claude --resume invites-planning`, which opens the session picker filtered by that search term. Rename a running session with `/rename`.

If the session has become heavy with exploration output, run `/compact Keep the decisions, acceptance criteria and open questions` or start fresh from the saved files:

```text
Read docs/plans/team-invitations.md. It holds the acceptance criteria,
the phased plan and the open questions from earlier planning sessions.
List the open questions first, then tell me which phase is ready to
start and which failing tests must exist before it does.
```

The plan file, not the conversation, is the source of truth. If you keep specs as long-lived documents that every pull request updates, follow [spec-driven development](/en/workflows/plan/spec-driven-development/). For the lighter PRD-to-todo-list flow, see [PRD to plan to todo](/en/claude-code/quick-start/prd-workflow/).

## What breaks when you plan features with Claude Code?

**The plan is too high-level to act on.** Phases read like "add invitation logic". Recovery: "For each phase, name the exact files and describe each change in one sentence. If you cannot name the file, say which search you need to run." A plan that cannot name files was written before the code was explored; go back to the exploration prompt.

**The plan cites files or functions that do not exist.** Claude filled a gap with a plausible name. Recovery: the fresh-session audit catches this. Treat any WRONG path as a sign that the surrounding section is also unverified, and re-run exploration for that area.

**The interview loops or asks what the code already answers.** Recovery: "You already asked about X. The code answers Y at path:line. Move on to the areas we have not covered: seat limits and token reuse."

**The plan invents a new pattern.** It proposes a new queue library or a new permissions model when the codebase already has one. Recovery: "Follow how we implemented `<closest feature>`. List every place your plan departs from it, and justify each one or remove it."

**Effort is too low for the ambiguity, or too high for the task.** At `medium`, a plan for a cross-cutting feature can skip edge cases; at `xhigh`, a small change burns time and usage. Recovery: raise effort with `/effort high` for the interview and the plan, and drop back with `/effort medium` for small, well-understood features. Change model only when your own comparison says so.

**The session approves the plan and starts coding before you are ready.** Recovery: press `Esc` to stop, then `/rewind` (or `Esc` twice on an empty prompt) to return to the point before the edits. Next time, choose the keep-planning option and ask Claude to write the plan and stop, instead of approving.

**Context runs out halfway through planning.** Recovery: save the plan file, run `/compact` with an instruction to keep decisions and open questions, or start a fresh session from the plan file.

## Where to go next after the plan is approved

- [Executable acceptance criteria](/en/workflows/plan/acceptance-criteria/) — Turn each INV-xx scenario into a failing test the implementing agent cannot edit.
- [Implementation in Claude Code](/en/claude-code/build/implementation/) — Execute the approved plan phase by phase, with tests and gates at each step.
- [Architecture analysis and system design](/en/claude-code/plan/architecture/) — Make the structural decisions a feature plan should not make on its own.
- [Spec-driven development](/en/workflows/plan/spec-driven-development/) — Keep the spec authoritative as the feature evolves across pull requests.

Working in another tool? The planning stage for Codex is in [planning with Codex](/en/codex/plan/), and for Cursor in [planning with Cursor](/en/cursor-ide/plan/). The rest of this stage is in the [Claude Code planning overview](/en/claude-code/plan/).