plan-fast

[IMPORTANT] 开始前必须使用 TaskCreate 将所有工作拆分为小任务——包括每个文件的读取任务。这可以避免因长文件导致上下文丢失。对于简单任务，AI 必须主动询问用户是否跳过。

先理解代码 — 严格门槛：在阅读现有代码之前，不得编写、规划或修复。

1. 搜索 3 个以上的相似模式（grep/glob）——引用 file:line 证据
2. 阅读目标区域中的现有文件——了解结构、基类和惯例
3. 当 .code-graph/graph.db 存在时，运行 python .claude/scripts/code_graph trace <file> --direction both --json
4. 通过 connections 或 callers_of 梳理依赖关系——了解哪些内容依赖目标
5. 对于非简单任务（涉及 3 个以上文件），将调查结果写入 .ai/workspace/analysis/
6. 实施前重新阅读分析文件——绝不能只凭记忆开展工作
7. 如果现有模式可用，绝不另创模式——严格遵循，或记录偏离原因

未完成以下事项前禁止开始： - [ ] 阅读目标文件 - [ ] 搜索 3 个以上模式 - [ ] 图谱追踪（如果存在 graph.db） - [ ] 用证据核实假设

估算 — 修改版斐波那契：1（琐碎）→ 2（小型）→ 3（中型）→ 5（大型）→ 8（超大型）→ 13（史诗级，应拆分）→ 21（必须拆分）。在计划 frontmatter 中输出 story_points 和 complexity。复杂度自动推导：1-2=低，3-5=中，8=高，13+=严重。

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体/模型时阅读）（内容由 hook 自动注入——阅读前检查是否有 [Injected: ...] 标头）
• docs/test-specs/ — 按模块划分的测试规范（阅读现有 TC，以便在计划中纳入测试策略）

计划质量 — 每个计划阶段都必须包含测试规范。

1. 在每个阶段文件中添加 ## Test Specifications 部分，并使用 TC-{FEAT}-{NNN} ID
2. 将每项功能需求映射到至少 1 个 TC（或明确标记 TBD 并说明理由）
3. TC ID 遵循 TC-{FEATURE}-{NNN} 格式——通过 ID 引用，绝不嵌入完整内容
4. 开始任何新的工作流步骤前：调用 TaskList 并重新阅读阶段文件
5. 上下文压缩时：先调用 TaskList——绝不创建重复任务
6. 将阶段标记为完成前，核实该阶段的 TC 是否满足（证据必须为 file:line，不能是 TBD）

模式： TDD 优先 → 引用现有 TC，并将 Evidence 标为 TBD。实施优先 → 使用 TBD → /tdd-spec 之后补全。

迭代阶段质量 — 规划前先评估复杂度。

复杂度信号： 文件数 >5 +2，跨服务 +3，新模式 +2，数据库迁移 +2 得分 >=6 → 必须拆分为多个阶段。每个阶段：

• 修改文件 ≤5 个
• 工作量 ≤3 小时
• 遵循周期：计划 → 实施 → 审查 → 修复 → 验证
• 第 N 阶段通过 VERIFY 前，不得开始第 N+1 阶段

阶段成功 = 所有 TC 均通过 + code-reviewer agent 批准 + 无 CRITICAL 发现。 修复层级责任 — 绝对不要在崩溃点修复。追踪完整流程，在负责的层级修复。

AI 的默认行为：在 A 处看到错误 → 修复 A 处。这是错误的。崩溃点是症状，不是原因。

进行任何修复前，必须：

1. 追踪完整数据流 — 跨越所有层级（存储 → 后端 → API → 前端 → UI），梳理从数据来源到崩溃点的完整路径。找出错误状态从哪里进入，而不是它在哪里崩溃。
2. 确定不变量的负责方 — 哪个层级的契约保证此值有效？该层级负责修复。在拥有该不变量的最低层级修复，而不是在使用该值的最高层级修复。
3. 一次修复，最大程度保护 — 思考：“如果在这里修复，是否能通过一次更改保护所有下游使用方？”如果修复需要修改 3 个以上文件并添加防御性检查，那就说明你选错了层级，应该再往下找。
4. 确认不存在绕过路径 — 确认所有数据流都会经过修复点。检查以下情况：直接构造而绕过工厂、克隆或展开时未重新验证、原始数据未封装为领域模型、在模型层之外修改数据。

在以下条件满足前，禁止继续： - [ ] 已追踪完整数据流（来源 → 崩溃点） - [ ] 已通过 file:line 证据确定不变量的负责方 - [ ] 已审查所有访问点（grep 计数） - [ ] 已论证修复层级合理（能保护最多使用方的最低层级）

反模式（拒绝以下做法）：

• “在崩溃处修复” — 崩溃点 ≠ 原因点。沿上游追踪。
• “在每个使用方添加防御性检查” — 分散防护 = 层级错误。一个权威修复 > 多个分散的防护措施。
• “两处都修复更安全” — 选择一个权威层级。在多个层级重复检查，会让不变量的负责方变得模糊。

即使是快速计划，也要评估复杂度分数。分数 >=3 → 必须认真考虑，并划分为多个阶段，每个阶段都要进行质量检查。

快速摘要

目标： 分析代码库并创建结构化实施计划，不编写任何代码。

工作流：

1. 检查计划上下文 — 重用现有计划，或按照命名约定创建新目录
2. 分析代码库 — 阅读 backend-patterns-reference.md、frontend-patterns-reference.md、project-structure-reference.md
3. 创建计划 — 生成带有 YAML frontmatter 的 plan.md + phase-XX-*.md 文件
4. 验证 — 运行 /plan-review，并在实施前请用户确认

关键规则：

• 不要使用 EnterPlanMode 工具；不要编写任何代码
• 与用户协作：提出决策问题，并给出选项和推荐方案
• 创建计划后，始终使用 /plan-review 验证计划

绿地模式

自动检测： 如果找不到现有代码库（没有 src/、app/、lib/、server/、packages/ 等代码目录，没有 package.json/*.sln/go.mod 等清单文件，也没有已填充内容的 project-config.json），此技能会转向 /plan-hard。规划产物（docs/、plans/、.claude/）不计入其中——项目必须包含实际且有内容的代码目录。

检测到绿地项目时：

1. 转向 /plan-hard — 绿地项目的构思需要深入研究，而不是快速规划
2. 告知用户：“检测到绿地项目。正在转向 /plan-hard，进行全面研究和规划。”
3. 原因：快速规划会跳过研究，但绿地项目需要市场调研、技术评估和领域建模——这些都离不开深入分析

保持怀疑态度。运用批判性思维和序贯思维。每项主张都需要可追溯的证据和置信度百分比（想法应高于 80%）。

启用 planning 技能。

仅规划模式 — 需要协作

不要使用 EnterPlanMode 工具——你已经处于规划工作流中。 不要实施或执行任何代码更改。 与用户协作：提出决策问题，并给出选项和建议。 创建计划后，始终运行 /plan-review 以验证计划。 在进行任何后续步骤之前，先请用户确认计划。

你的任务

$ARGUMENTS

创建前检查（活动计划与建议计划）

检查注入上下文中的 ## Plan Context 部分：

• 如果“Plan:”显示一个路径 → 已有活动计划。询问用户：“要继续使用此计划吗？[Y/n]”
• 如果“Suggested:”显示一个路径 → 这只是与分支匹配的提示。询问用户是要启用该计划，还是创建新计划。
• 如果“Plan: none” → 使用 ## Naming 部分中的命名规则创建新计划。

工作流

使用 planner 子代理执行以下操作：

1. 如果创建新计划：使用 ## Naming 部分中的 Plan dir: 创建目录，然后运行 node .claude/scripts/set-active-plan.cjs {plan-dir} 如果复用计划：使用 Plan Context 中的活动计划路径。 确保在整个过程中向每个子代理传递目录路径。
2. 严格遵循 planning 技能中的“计划创建与组织”规则。
3. 阅读 backend-patterns-reference.md、frontend-patterns-reference.md 和 project-structure-reference.md 文件，分析代码库。 3.5. 外部记忆：将分析结果写入 .ai/workspace/analysis/{task-name}.analysis.md。创建计划前重新阅读此文件。
4. 收集所有信息，并为此任务创建实施计划。
5. 请用户审阅计划。

输出要求

计划目录结构（使用 ## Naming 部分中的 Plan dir:）

{plan-dir}/
├── reports/
│   ├── XX-report.md
│   └── ...
├── plan.md
├── phase-XX-phase-name-here.md
└── ...

计划文件规范

• 每个 plan.md 都必须以 YAML 前置元数据开头：

  ---
  title: '{简要标题}'
  description: '{用于卡片预览的一句话说明}'
  status: pending
  priority: P2
  effort: {各阶段总工作量，例如 4h}
  story_points: {各阶段总 SP，例如 8}
  branch: {当前 git 分支}
  tags: [相关, 标签]
  created: { YYYY-MM-DD }
  ---
  

• 将概览入口文件保存到 {plan-dir}/plan.md。内容保持通用，不超过 80 行，并列出每个实施阶段的状态、进度以及阶段文件链接。

• 每个阶段都创建 {plan-dir}/phase-XX-phase-name-here.md，并按以下顺序包含这些部分：上下文链接（引用父计划、依赖项、文档）、概览（日期、说明、优先级、实施状态、审查状态）、关键见解、需求、架构、UI 布局（见下文）、相关代码文件、实施步骤、待办清单、成功标准、风险评估、安全注意事项、后续步骤。

• UI 布局：对于面向前端的阶段，包含 ASCII 线框图。按层级（通用／领域共享／页面应用）对组件分类。对于仅涉及后端的阶段：## UI Layout → N/A — Backend-only change.

重要任务规划说明（必须严格遵守）

• 始终使用 TaskCreate 规划并拆分工作，创建许多小型待办任务。
• 始终添加一个最终审查待办任务，用于验证工作质量并找出需要修复或改进的内容。
• **强制最终任务：**创建完所有规划待办任务后，始终添加以下三个最终任务：
  1. 任务：“为每个阶段编写测试规范” — 为每个阶段文件添加 ## Test Specifications，并使用 TC-{FEAT}-{NNN} ID。如果存在功能文档，则使用 /tdd-spec。采用 TDD 优先模式时，使用 Evidence: TBD。
  2. 任务：“运行 /plan-validate” — 触发 /plan-validate 技能，通过访谈用户提出关键问题并验证计划假设。
  3. 任务：“运行 /plan-review” — 触发 /plan-review 技能，自动审查计划的有效性、正确性和最佳实践。

计划后验证

创建计划后，使用 AskUserQuestion 工具询问：“要我运行 /plan-review 进行验证，还是继续实施？”并提供以下选项：

• “运行 /plan-review（推荐）” — 执行 /plan-review 验证计划
• “继续实施” — 跳过验证并开始实施

重要说明

• 重要： 在保持高质量的同时，确保高效使用令牌。
• 重要： 分析技能目录，并在任务过程中启用所需技能。
• 重要： 撰写报告时，宁可牺牲语法，也要力求简洁。
• 重要： 如有未解决的问题，请在报告末尾列出。

提醒——仅限规划的命令

不要使用 EnterPlanMode 工具。 不要开始实施。 创建计划后，始终使用 /plan-review 验证。 开始任何实施前，询问用户是否确认计划。 存在多种方案时，向用户询问决策问题，并提供你的建议。

---

计划粒度自检（强制）

计划粒度 — 每个阶段在开始实施前都必须通过以下 5 项检查：

1. 列出要修改的确切文件路径（不能只写“实施 X”之类的笼统描述）
2. 不包含规划类动词（研究、调查、分析、确定、弄清）
3. 每个步骤 ≤30 分钟，每个阶段总计 ≤3 小时
4. 每个阶段涉及的文件 ≤5 个
5. 方案中没有未决事项或待定内容

未通过的阶段 → 创建子计划。重复此过程，直到所有叶子阶段都通过检查（最多 3 层）。

自检问题：“我现在能立刻开始编写代码吗？如果任何步骤还需要‘弄清楚’，就拆分为子计划。”

创建所有阶段文件后，运行递归拆解循环：

1. 根据 5 项标准（文件路径、无规划类动词、每个步骤 ≤30 分钟、每个阶段文件 ≤5 个、无未决事项）为每个阶段评分
2. 对每个未通过的阶段 → 创建任务，将其拆解为子计划（子计划需经过自身的 /plan → /plan-review → /plan-validate → 修复流程）
3. 重新评估新阶段。重复此过程，直到所有叶子阶段都通过检查（最多 3 层）
4. 自检问题：“对于每个阶段，我现在能立刻开始编写代码吗？如果任何阶段还需要‘弄清楚’，就拆解为子计划。”

后续步骤（独立调用：必须通过 AskUserQuestion 询问用户。在工作流内则跳过。）

强制重要事项——必须遵守，不得例外： 如果此技能是在工作流之外调用的，必须使用 AskUserQuestion 向用户提供以下选项。不要因为任务看起来“简单”或“显而易见”就跳过——由用户决定：

• “继续执行完整工作流（推荐）” — 我会从这里（计划已创建）开始，检测并继续执行最合适的工作流，确保不会跳过审查、验证、实施和测试步骤。
• “/plan-review” — 自动审查计划的有效性和最佳实践
• “/plan-validate” — 通过询问用户确认计划决策
• “跳过，手动继续” — 由用户决定

如果已在工作流内，则跳过此步骤——工作流会负责处理后续流程。

最后提醒

• 重要，务必注意：开始前使用 TaskCreate 将工作拆分为小型待办任务

• 重要，务必注意：创建新代码前，搜索代码库中 3 个或更多相似模式

• 重要，务必注意：每项声明都要引用 file:line 证据（置信度 >80% 才能采取行动）

• 重要，务必注意：添加最终审查待办任务，以验证工作质量

• 重要，务必注意：在计划 frontmatter 中包含 Test Specifications 部分和 story_points

• 重要，务必注意：确认所有阶段都通过 5 点粒度检查。未通过的阶段 → 子计划。“我现在能立刻开始编码吗？”

• 重要，务必注意：修改前搜索 3 个或更多现有模式并阅读代码。如果 graph.db 存在，则运行图追踪。

• 重要，务必注意：在计划 frontmatter 中包含 story_points 和 complexity。SP > 8 时拆分。

• 重要，务必注意：包含带有各阶段 TC ID 的 ## Test Specifications。创建新任务前调用 TaskList。

• 重要，务必注意：先评估复杂度。评分 >=6 时进行分解。每个阶段：计划 → 实现 → 审查 → 修复 → 验证。不得跳过。

• 重要，务必注意：追踪完整数据流，并在所属层修复问题，而不是在崩溃发生处修复。添加 ?. 前审查所有访问位置。