solo-plan

/plan

此技能完全独立——请按照以下步骤操作，不要委派给外部规划技能（superpowers 等）。

研究代码库，并制定规范和分阶段实施计划。不提任何互动问题——直接探索代码。

适用场景

为任何功能、错误修复或重构创建一条包含具体文件级实施计划的轨道。可与 /setup 配合使用，也可单独使用。

MCP 工具（如可用）

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

如果 MCP 工具不可用，则使用 Glob + Grep + Read。

步骤

1. 解析任务描述，内容来自 $ARGUMENTS。

   • 如果为空，通过 AskUserQuestion 提问：“你想规划什么功能、错误修复或重构？”
   • 最多只问这一个问题。

2. 检测上下文——确定计划文件的存放位置：

   项目上下文（含代码的常规项目）：

   • 检测依据：工作目录中存在 package.json、pyproject.toml、Cargo.toml、*.xcodeproj 或 build.gradle.kts
   • 计划路径：docs/plan/{trackId}/

   知识库上下文（以文档为主的项目）：

   • 检测依据：未找到包清单，但存在 docs/、notes/ 等目录或带编号的结构化目录
   • 计划路径：docs/plan/{shortname}/
   • 注意：shortname 根据任务生成（kebab-case），目录名不带日期后缀

   根据检测到的上下文设置 $PLAN_ROOT。后续所有文件路径都使用 $PLAN_ROOT。

3. 加载项目上下文（并行读取）：

   • CLAUDE.md — 架构、约束、应做事项／禁止事项
   • docs/prd.md — 产品功能说明（如果存在）
   • docs/workflow.md — TDD 策略、提交策略（如果存在）
   • package.json 或 pyproject.toml — 技术栈、版本、依赖

4. 自动分类轨道类型，依据任务描述中的关键词：

   • 包含 “fix”、“bug”、“broken”、“error”、“crash” → bug
   • 包含 “refactor”、“cleanup”、“reorganize”、“migrate” → refactor
   • 包含 “update”、“upgrade”、“bump” → chore
   • 默认 → feature

5. 研究阶段——探索代码库，了解需要修改的内容：

   a. 获取架构概览（如果 MCP 可用，则先执行此项）：

   codegraph_explain(project="{来自 CLAUDE.md 或目录名的项目名称}")
   

   提供：技术栈、语言、目录层级、关键模式、主要依赖、核心文件。

   b. 获取 RepoMap（如果 MCP 可用）：

   codegraph_repomap(project="{来自 CLAUDE.md 或目录名的项目名称}")
   

   提供重要文件及其导出符号（类／函数）的 YAML 映射。

   c. 查找相关文件——使用 Glob + Grep 搜索与任务相关的模式：

   • 搜索任务描述中的关键词
   • 查看目录结构以了解架构
   • 找出需要修改的文件

   d. 检索先例（上下文图谱模式——规划前先搜索以往的解决方案）：

   • 搜索过往会话（如果 MCP 可用）：

     session_search(query="{任务描述关键词}")
     

     查找：类似任务的解决方式、出错之处、有效模式。
   • 搜索知识库中的相关方法论：

     kb_search(query="{任务类型}: {关键词}")
     

     查看：harness 模式、架构约束、质量评分。

   e. 跨项目搜索代码（如果 MCP 可用）：

   project_code_search(query="{相关模式}")
   

   f. 检查受影响文件的依赖项（如果 MCP 可用）：

   codegraph_query(query="MATCH (f:File {path: '{file}'})-[:IMPORTS]->(dep) RETURN dep.path")
   

   g. 阅读受影响区域中的现有测试——了解所使用的测试模式。

   h. 阅读 CLAUDE.md 中的架构约束——了解边界和约定。

   • 检查 harness 部分：模块边界、数据验证规则、lint 配置。
   • 如果 docs/ARCHITECTURE.md 和 docs/QUALITY_SCORE.md 存在，请阅读。

   i. 检测部署基础设施——搜索部署脚本/配置，以便在计划中加入部署阶段：

   find . -maxdepth 3 \( -name 'deploy.sh' -o -name 'Dockerfile' -o -name 'docker-compose.yml' -o -name 'wrangler.toml' -o -name 'sst.config.ts' \) -type f 2>/dev/null
   

   如果找到，请阅读它们以了解部署目标。在计划中加入部署阶段，并列出具体命令。

6. 检测计划重叠——创建新跟踪项之前，检查是否有现有计划涵盖相似范围：

   ls docs/plan/*/plan.md docs/plan/*/spec.md 2>/dev/null
   

   对找到的每个现有计划：

   • 阅读其 spec.md 中的 Summary 和 Acceptance Criteria
   • 将其范围与新任务描述进行比较
   • 检查任务是否重叠（共同涉及的文件或验收标准是否超过 50%）

   如果检测到重叠：

   • 如果现有计划尚未完成（仍有 [ ] 任务）：建议扩展该计划，而不是创建新的跟踪项。向用户显示：“现有跟踪项 {trackId} 涵盖了相似范围（{overlap description}）。要扩展它，还是创建单独的跟踪项？”
   • 如果现有计划已完成（所有任务均为 [x]）：继续创建新跟踪项，但在 spec.md 的 Dependencies 中引用之前的跟踪项
   • 如果多个现有计划彼此重叠：建议先将它们整合为一个跟踪项，再继续

   **如果没有重叠：**按常规流程继续。

7. 生成跟踪项 ID：

   • 从任务描述中提取一个简短名称（2-3 个单词，使用 kebab-case）。
   • 格式：{shortname}_{YYYYMMDD}（例如：user-auth_20260209）。

8. 创建跟踪项目录：

   mkdir -p $PLAN_ROOT
   

   • 项目上下文：docs/plan/{trackId}/
   • 知识库上下文：docs/plan/{shortname}/

9. 生成 $PLAN_ROOT/spec.md： 根据研究结果生成，而不是提出泛泛的问题。

   # 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}
   

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

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

    • 阶段标题：## Phase N: Name
    • 任务：- [ ] Task N.Y: Description（包含句号或详细文本）
    • 子任务：缩进 - [ ] Subtask description
    • 所有任务使用 [ ]（未勾选）、[~]（进行中）、[x]（已完成）

    # 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-1}: Deploy (if deploy infrastructure exists)
    _Include this phase ONLY if the project has deploy scripts/configs (deploy.sh, Dockerfile, docker-compose.yml, wrangler.toml, sst.config.ts, vercel.json). Skip if no deploy infra found._
    
    ### Tasks
    - [ ] Task {N-1}.1: {concrete deploy step — e.g. "Run python/deploy.sh to push Docker image to VPS", "wrangler deploy", etc.}
    - [ ] Task {N-1}.2: Verify deployment — health check, logs, HTTP status
    
    ### Verification
    - [ ] Service is live and healthy
    - [ ] No runtime errors in production logs
    
    ## 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
    
    ## Context Handoff
    _Summary for /build to load at session start — keeps context compact._
    
    ### Session Intent
    {1 sentence: what this track accomplishes}
    
    ### Key Files
    {list of files that will be modified, from research}
    
    ### Decisions Made
    {key architecture decisions from research phase — why X over Y}
    
    ### Risks
    {known risks or edge cases discovered during research}
    
    ---
    _Generated by /plan. Tasks marked [~] in progress and [x] complete by /build._
    

    计划质量规则：

    • 每个任务都要提及具体文件路径（来自研究结果）。
    • 任务必须是原子性的——每个任务对应一次提交。
    • 阶段必须可独立验证。
    • 总计 5-15 个任务（而非 70 个）。
    • 最后一个阶段始终为 “Docs & Cleanup”。
    • 标准与任务的覆盖关系：spec.md 中的每项验收标准都必须对应 plan.md 中至少一个任务。生成两个文件后，逐项核对：列出每项标准并确认有任务对应。若某项标准没有对应任务，就添加一个。未覆盖的标准是导致“计划已完成但未满足规范”问题的首要原因。
    • **考虑 harness：**如果任务引入了新模式，请加入更新 lint 规则或 CLAUDE.md 约束的任务。如果涉及模块边界，请加入依赖方向验证。思考：“怎样调整 harness 才能防止未来的 Agent 破坏这一点？”

11. 创建进度任务列表，以便在流水线中跟踪进度：

写入 plan.md 后，创建 TaskCreate 条目，使进度可跟踪：

• 每个阶段创建一个任务：“Phase 1: {name}”，并将任务列表作为描述。
• 这样用户和流水线就能实时了解计划内容。
• /build 会在执行过程中更新这些任务。 如果 superpowers:writing-plans 技能可用，请遵循其粒度格式：将任务拆分为小块（每项 2-5 分钟），在任务描述中提供完整代码，注明准确的文件路径，并为每项任务列出验证步骤。这能进一步完善上述内置格式。

11. 通过 AskUserQuestion 展示计划并征求批准： 展示规格摘要和计划概览。选项：

• “批准并开始” — 可立即执行 /build
• “编辑计划” — 用户希望在实施前修改计划
• “取消” — 放弃此轨道

如果选择“编辑计划”：告知用户手动编辑 $PLAN_ROOT/plan.md，然后运行 /build。

输出

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}

合理化说辞目录

这些想法意味着立即停止——你正在跳过研究：

想法	实际情况
“我了解这个代码库”	你只了解自己看过的内容。搜索尚未查看的部分。
“计划很明显”	看似显而易见的计划会遗漏边缘情况。先做研究。
“我先开始写代码吧”	花 10 分钟研究，可以避免 2 小时返工。
“这只是个小功能”	小功能也会涉及很多文件。先摸清影响范围。
“我边做边想办法”	那不叫计划。先写出文件路径。
“70 项任务应该够了”	应有 5-15 项任务。如果需要更多，就拆分成多个轨道。

兼容性说明

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

常见问题

计划中的任务太多

原因： 功能范围过广，或任务拆分得不够细。 解决方法： 将任务控制在 2-4 个阶段内的 5-15 项。大型功能应拆分为多个轨道。

上下文检测错误（项目与 KB）

原因： 目录中既有代码清单文件，又有类似知识库的目录。 解决方法： 如果存在 package.json/pyproject.toml，则优先采用项目上下文。

研究阶段没有找到相关代码

原因： 这是一个代码库很精简的新项目，或 MCP 工具不可用。 解决方法： 技能会改用 Glob + Grep。对于新项目，计划会更多地依赖 CLAUDE.md 中的架构和技术栈约定。