solo-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/plan

Research the codebase and create a spec + phased implementation plan. Zero interactive questions — explores the code instead.

研究代码库并创建规格说明+分阶段实施计划。无需交互式提问——直接探索代码即可。

When to use

使用场景

Creates a track for any feature, bug fix, or refactor with a concrete, file-level implementation plan. Works with or without

/setup

为任何功能开发、Bug修复或代码重构创建跟踪任务，提供具体到文件级别的实施计划。可配合/setup使用，也可单独使用。

MCP Tools (use if available)

MCP工具（如有则使用）

```
session_search(query)
```
— find similar past work in Claude Code chat history
```
project_code_search(query, project)
```
— find reusable code across projects
```
codegraph_query(query)
```
— check dependencies of affected files
```
codegraph_explain(project)
```
— architecture overview: stack, languages, directory layers, key patterns, top dependencies, hub files
```
kb_search(query)
```
— search knowledge base for relevant methodology

If MCP tools are not available, fall back to Glob + Grep + Read.

```
session_search(query)
```
— 在Claude Code聊天历史中查找类似的过往工作
```
project_code_search(query, project)
```
— 在多项目中查找可复用代码
```
codegraph_query(query)
```
— 检查受影响文件的依赖关系
```
codegraph_explain(project)
```
— 架构概览：技术栈、编程语言、目录层级、核心模式、主要依赖、枢纽文件
```
kb_search(query)
```
— 在知识库中搜索相关方法论

如果MCP工具不可用，则退回到Glob + Grep + Read方式。

Steps

步骤

Parse task description from
```
$ARGUMENTS
```
.
- If empty, ask via AskUserQuestion: "What feature, bug, or refactor do you want to plan?"
- This is the ONE question maximum.
Detect context — determine where plan files should be stored:

Project context (normal project with code):
- Detected by:
```
package.json
```
  ,
```
pyproject.toml
```
  ,
```
Cargo.toml
```
  ,
```
*.xcodeproj
```
  , or
```
build.gradle.kts
```
  exists in working directory
- Plan path:
```
docs/plan/{trackId}/
```
Knowledge base context (solopreneur KB or similar):
- Detected by: NO package manifest found, BUT directories like
```
0-principles/
```
  ,
```
1-methodology/
```
  ,
```
4-opportunities/
```
  exist
- Plan path:
```
4-opportunities/{shortname}/
```
- Note: the shortname is derived from the task (kebab-case, no date suffix for the directory)
Set
```
$PLAN_ROOT
```
based on detected context. All subsequent file paths use
```
$PLAN_ROOT
```
.
Load project context (parallel reads):
- ```
CLAUDE.md
```
  — architecture, constraints, Do/Don't
- ```
docs/prd.md
```
  — what the product does (if exists)
- ```
docs/workflow.md
```
  — TDD policy, commit strategy (if exists)
- ```
package.json
```
  or
```
pyproject.toml
```
  — stack, versions, deps
Auto-classify track type from keywords in task description:
- Contains "fix", "bug", "broken", "error", "crash" →
```
bug
```
- Contains "refactor", "cleanup", "reorganize", "migrate" →
```
refactor
```
- Contains "update", "upgrade", "bump" →
```
chore
```
- Default →
```
feature
```
Research phase — explore the codebase to understand what needs to change:

a. Get architecture overview (if MCP available — do this FIRST):
```
codegraph_explain(project="{project name from CLAUDE.md or directory name}")
```
Gives you: stack, languages, directory layers, key patterns, top dependencies, hub files.

b. Find relevant files — Glob + Grep for patterns related to the task:
- Search for keywords from the task description
- Look at directory structure to understand architecture
- Identify files that will need modification
c. Search past sessions (if MCP available):
```
session_search(query="{task description keywords}")
```
d. Search code across projects (if MCP available):
```
project_code_search(query="{relevant pattern}")
```
e. Check dependencies of affected files (if MCP available):
```
codegraph_query(query="MATCH (f:File {path: '{file}'})-[:IMPORTS]->(dep) RETURN dep.path")
```
f. Read existing tests in the affected area — understand testing patterns used.

g. Read CLAUDE.md architecture constraints — understand boundaries and conventions.
Generate track ID:
- Extract a short name (2-3 words, kebab-case) from task description.
- Format:
```
{shortname}_{YYYYMMDD}
```
  (e.g.,
```
user-auth_20260209
```
  ).

Create track directory:

bash

mkdir -p $PLAN_ROOT

Project context:
```
docs/plan/{trackId}/
```
KB context:
```
4-opportunities/{shortname}/
```

Generate
$PLAN_ROOT/spec.md
: Based on research findings, NOT generic questions.

markdown

# Specification: {Title}

**Track ID:** {trackId}
**Type:** {Feature|Bug|Refactor|Chore}
**Created:** {YYYY-MM-DD}
**Status:** Draft

## Summary
{1-2 paragraph description based on research}

## Acceptance Criteria
- [ ] {concrete, testable criterion}
- [ ] {concrete, testable criterion}
{3-8 criteria based on research findings}

## Dependencies
- {external deps, packages, other tracks}

## Out of Scope
- {what this track does NOT cover}

## Technical Notes
- {architecture decisions from research}
- {relevant patterns found in codebase}
- {reusable code from other projects}

Generate
$PLAN_ROOT/plan.md
: Concrete, file-level plan from research. Keep it tight: 2-4 phases, 5-15 tasks total.

Critical format rules (parsed by

/build

Phase headers:
```
## Phase N: Name
```
Tasks:
```
- [ ] Task N.Y: Description
```
(with period or detailed text)
Subtasks: indented
```
  - [ ] Subtask description
```
All tasks use
```
[ ]
```
(unchecked),
```
[~]
```
(in progress),
```
[x]
```
(done)

markdown

# Implementation Plan: {Title}

**Track ID:** {trackId}
**Spec:** [spec.md](./spec.md)
**Created:** {YYYY-MM-DD}
**Status:** [ ] Not Started

## Overview
{1-2 sentences on approach}

## Phase 1: {Name}
{brief description of phase goal}

### Tasks
- [ ] Task 1.1: {description with concrete file paths}
- [ ] Task 1.2: {description}

### Verification
- [ ] {what to check after this phase}

## Phase 2: {Name}
### Tasks
- [ ] Task 2.1: {description}
- [ ] Task 2.2: {description}

### Verification
- [ ] {verification steps}

{2-4 phases total}

## Phase {N}: Docs & Cleanup
### Tasks
- [ ] Task {N}.1: Update CLAUDE.md with any new commands, architecture changes, or key files
- [ ] Task {N}.2: Update README.md if public API or setup steps changed
- [ ] Task {N}.3: Remove dead code — unused imports, orphaned files, stale exports

### Verification
- [ ] CLAUDE.md reflects current project state
- [ ] Linter clean, tests pass

## Final Verification
- [ ] All acceptance criteria from spec met
- [ ] Tests pass
- [ ] Linter clean
- [ ] Build succeeds
- [ ] Documentation up to date

---
_Generated by /plan. Tasks marked [~] in progress and [x] complete by /build._

Plan quality rules:

Every task mentions specific file paths (from research).
Tasks are atomic — one commit each.
Phases are independently verifiable.
Total: 5-15 tasks (not 70).
Last phase is always "Docs & Cleanup".

Show plan for approval via AskUserQuestion: Present the spec summary + plan overview. Options:
- "Approve and start" — ready for
```
/build
```
- "Edit plan" — user wants to modify before implementing
- "Cancel" — discard the track
If "Edit plan": tell user to edit
```
$PLAN_ROOT/plan.md
```
manually, then run
```
/build
```
.

解析任务描述 从
```
$ARGUMENTS
```
中获取。
- 如果为空，通过AskUserQuestion提问："你想要规划哪些功能、Bug或重构任务？"
- 这是唯一允许的提问。
检测上下文 — 确定计划文件的存储位置：

项目上下文（包含代码的常规项目）：
- 检测依据：工作目录中存在
```
package.json
```
  、
```
pyproject.toml
```
  、
```
Cargo.toml
```
  、
```
*.xcodeproj
```
  或
```
build.gradle.kts
```
- 计划路径：
```
docs/plan/{trackId}/
```
知识库上下文（个体创业者知识库或类似场景）：
- 检测依据：未找到包清单，但存在
```
0-principles/
```
  、
```
1-methodology/
```
  、
```
4-opportunities/
```
  等目录
- 计划路径：
```
4-opportunities/{shortname}/
```
- 注意：shortname由任务衍生而来（短横线命名格式，目录名不带日期后缀）
根据检测到的上下文设置
```
$PLAN_ROOT
```
。后续所有文件路径均使用
```
$PLAN_ROOT
```
。
加载项目上下文（并行读取）：
- ```
CLAUDE.md
```
  — 架构、约束条件、注意事项
- ```
docs/prd.md
```
  — 产品功能说明（如果存在）
- ```
docs/workflow.md
```
  — TDD策略、提交规范（如果存在）
- ```
package.json
```
  或
```
pyproject.toml
```
  — 技术栈、版本、依赖
自动分类跟踪任务类型 根据任务描述中的关键词：
- 包含"fix"、"bug"、"broken"、"error"、"crash" →
```
bug
```
  （Bug修复）
- 包含"refactor"、"cleanup"、"reorganize"、"migrate" →
```
refactor
```
  （代码重构）
- 包含"update"、"upgrade"、"bump" →
```
chore
```
  （常规维护）
- 默认 →
```
feature
```
  （功能开发）
研究阶段 — 探索代码库以明确需要修改的内容：

a. 获取架构概览（如果MCP可用 — 优先执行）：
```
codegraph_explain(project="{project name from CLAUDE.md or directory name}")
```
可获取：技术栈、编程语言、目录层级、核心模式、主要依赖、枢纽文件。

b. 查找相关文件 — 使用Glob + Grep查找与任务相关的模式：
- 搜索任务描述中的关键词
- 查看目录结构以理解架构
- 识别需要修改的文件
c. 搜索过往会话（如果MCP可用）：
```
session_search(query="{task description keywords}")
```
d. 跨项目搜索代码（如果MCP可用）：
```
project_code_search(query="{relevant pattern}")
```
e. 检查受影响文件的依赖（如果MCP可用）：
```
codegraph_query(query="MATCH (f:File {path: '{file}'})-[:IMPORTS]->(dep) RETURN dep.path")
```
f. 阅读受影响区域的现有测试 — 理解所使用的测试模式。

g. 阅读CLAUDE.md中的架构约束 — 理解边界与约定。
生成跟踪任务ID（track ID）：
- 从任务描述中提取简短名称（2-3个词，短横线命名格式）。
- 格式：
```
{shortname}_{YYYYMMDD}
```
  （例如：
```
user-auth_20260209
```
  ）。
创建跟踪任务目录：
bash
```
mkdir -p $PLAN_ROOT
```
- 项目上下文：
```
docs/plan/{trackId}/
```
- 知识库上下文：
```
4-opportunities/{shortname}/
```

生成
$PLAN_ROOT/spec.md
：基于研究结果生成，而非通用模板。

markdown

# 规格说明：{标题}

**跟踪任务ID：** {trackId}
**类型：** {功能开发|Bug修复|代码重构|常规维护}
**创建时间：** {YYYY-MM-DD}
**状态：** 草稿

## 概述
{基于研究结果的1-2段描述}

## 验收标准
- [ ] {具体、可测试的标准}
- [ ] {具体、可测试的标准}
{基于研究结果的3-8条标准}

## 依赖项
- {外部依赖、包、其他跟踪任务}

## 范围外内容
- {本跟踪任务不涵盖的内容}

## 技术说明
- {从研究中得出的架构决策}
- {在代码库中发现的相关模式}
- {来自其他项目的可复用代码}

生成
$PLAN_ROOT/plan.md
：基于研究结果生成具体到文件级别的计划。保持精简：2-4个阶段，总计5-15个任务。

关键格式规则（供/build解析）：

阶段标题：
```
## Phase N: 名称
```
任务：
```
- [ ] Task N.Y: 描述
```
（带句号或详细文本）
子任务：缩进的
```
  - [ ] 子任务描述
```
所有任务使用
```
[ ]
```
（未开始）、
```
[~]
```
（进行中）、
```
[x]
```
（已完成）

markdown

# 实施计划：{标题}

**跟踪任务ID：** {trackId}
**规格说明：** [spec.md](./spec.md)
**创建时间：** {YYYY-MM-DD}
**状态：** [ ] 未开始

## 概述
{关于实施方法的1-2句话}

## Phase 1: {阶段名称}
{阶段目标的简要描述}

### 任务
- [ ] 任务1.1：{包含具体文件路径的描述}
- [ ] 任务1.2：{描述}

### 验证
- [ ] {本阶段完成后需要检查的内容}

## Phase 2: {阶段名称}
### 任务
- [ ] 任务2.1：{描述}
- [ ] 任务2.2：{描述}

### 验证
- [ ] {验证步骤}

{总计2-4个阶段}

## Phase {N}: 文档与清理
### 任务
- [ ] 任务{N}.1：更新CLAUDE.md，添加新命令、架构变更或关键文件信息
- [ ] 任务{N}.2：如果公共API或安装步骤有变更，更新README.md
- [ ] 任务{N}.3：移除无用代码——未使用的导入、孤立文件、过时导出

### 验证
- [ ] CLAUDE.md反映当前项目状态
- [ ] 代码检查无问题，测试通过

## 最终验证
- [ ] 满足规格说明中的所有验收标准
- [ ] 测试通过
- [ ] 代码检查无问题
- [ ] 构建成功
- [ ] 文档已更新

---
_由/plan生成。任务状态[~]表示进行中，[x]表示已完成，由/build更新。_

计划质量规则：

每个任务都提及具体的文件路径（来自研究结果）。
任务需具备原子性——每个任务对应一次提交。
阶段需可独立验证。
总计5-15个任务（而非70个）。
最后一个阶段必须是“文档与清理”。

展示计划以获取批准 通过AskUserQuestion：展示规格说明概述+计划概览。提供选项：
- "批准并开始" — 准备好执行/build
- "编辑计划" — 用户希望在实施前修改计划
- "取消" — 放弃该跟踪任务
如果选择“编辑计划”：告知用户手动编辑
```
$PLAN_ROOT/plan.md
```
，然后运行/build。

Output

输出

Track created: {trackId}

  Type:   {Feature|Bug|Refactor|Chore}
  Phases: {N}
  Tasks:  {N}
  Spec:   $PLAN_ROOT/spec.md
  Plan:   $PLAN_ROOT/plan.md

Research findings:
  - {key finding 1}
  - {key finding 2}
  - {reusable code found, if any}

Next: /build {trackId}

跟踪任务已创建：{trackId}

  类型：   {功能开发|Bug修复|代码重构|常规维护}
  阶段数： {N}
  任务数： {N}
  规格说明：   $PLAN_ROOT/spec.md
  实施计划：   $PLAN_ROOT/plan.md

研究结果：
  - {关键发现1}
  - {关键发现2}
  - {找到的可复用代码（如有）}

下一步：/build {trackId}

Compatibility Notes

兼容性说明

Plan format must match what
```
/build
```
parses:
```
## Phase N:
```
,
```
- [ ] Task N.Y:
```
.
```
/build
```
reads
```
docs/workflow.md
```
for TDD policy and commit strategy (if exists).
If
```
docs/workflow.md
```
missing,
```
/build
```
uses sensible defaults (moderate TDD, conventional commits).

计划格式必须与/build的解析规则匹配：
```
## Phase N:
```
、
```
- [ ] Task N.Y:
```
。
/build会读取
```
docs/workflow.md
```
中的TDD策略和提交规范（如果存在）。
如果缺少
```
docs/workflow.md
```
，/build会使用合理的默认设置（适度TDD、约定式提交）。