plan

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会将旧版 Claude /skill-name 引用改写为 $skill-name。
• 任务跟踪要求：在执行任何工作流或技能步骤之前，先为所有步骤创建或更新任务跟踪，并随进度变化保持同步。
• 遇到要求向用户提问的提示时，表示要在 Codex 中直接询问用户。
• 忽略出现的 Claude 专属模式切换指令。
• 严格执行约定：用户明确调用某项技能时，按原样执行该技能协议。
• 子 Agent 授权：当用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权为此任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，明确执行列出的每个子技能步骤，并逐步提供证据。
• 如果所需步骤或工具无法在此环境中运行，请停止并在调整方案前询问用户。

Codex 项目参考资料加载（无钩子）

Codex 使用静态项目参考资料加载，而非运行时注入项目文档。 进行编码、规划、调试、测试或审查时，请按照以下路由明确打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块以及工作流/测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录的路由）
• docs/project-reference/lessons.md（始终适用的防护措施和反模式）

上下文缺失或过时时的处理方式： 如果 docs/project-config.json、文档索引、lessons.md、CLAUDE.md、AGENTS.md 或任何任务必需的参考文档缺失或过时，请在常规项目工作之前自动运行 $project-init 或范围较窄的设置流程（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）。如果 Codex 镜像或 AGENTS.md 缺失或过时，请要求用户运行 $sync-codex；不要自动运行。

按情境查阅文档：

• 项目结构/架构/技术栈/部署/设置（任意层——后端、前端或基础设施）：project-structure-reference.md
• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md
• 前端/UI/样式/设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 编写规范、docs/specs/ 路径或 TC 格式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 行为/公共契约变更或规范-测试-代码同步：workflow-spec-test-code-cycle-reference.md，以及上述规范文档
• 派生规范索引/ERD/重实现指南：spec-system-reference.md 和 docs/specs/ 下的源功能规范
• 集成测试的实现/审查：integration-test-reference.md
• E2E 测试的实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及基于变更文件选择的领域文档

不要不加区分地阅读所有文档。从 docs-index-reference.md 开始，然后仅打开相关文件。

[BLOCKING] 按声明的顺序执行技能步骤。未经用户明确批准，绝不得跳过、重排或合并步骤。 [BLOCKING] 每个步骤或子技能调用开始前，更新任务跟踪：开始时标记为 in_progress，结束时标记为 completed。 [BLOCKING] 每个已完成或跳过的步骤都必须附上证据或明确的跳过原因。 [BLOCKING] 如果任务工具不可用，请维护具有相同状态转换的等效逐步计划跟踪。

快速摘要

目标： 研究代码库并与用户协作，交付经过验证、可直接实施的分阶段计划——每个阶段都能立即启动（包含确切文件路径、没有待决事项、映射的 TC ID），从而让编码工作无需返工，并将未来变更成本降至最低。

摘要：

• 仅限规划——绝不实现或执行代码；生成 plan.md、各阶段的 phase-XX 文件以及目标契约 goal.md，然后移交。
• **主要流程（AI 总会忘记的步骤）：**预检查有效/建议中的计划 → 初始化目标契约（goal.md）→ 一轮研究（同时启动 researcher + scout 子 Agent，综合前先设屏障）→ 代码库 + 项目参考资料分析（缺少文档时由 scout 执行）→ planner 子 Agent 编写 plan.md + phase-XX 文件（替代方案、理由、UI 布局、测试规格）→ 并行处理检查（为每个阶段标注 PAR/SEQ + 写入集，并编写 ## Execution Waves）→ 计划粒度事后自检 → 必需的最终任务。
• 计划输出本身包含并行性元数据——每个阶段都必须标注 PAR/SEQ 及其负责的写入集；每个 SEQ 阶段都必须注明导致其串行的依赖项（参见计划并行性元数据）。遗漏此项属于本技能的缺陷：$plan-execute 只会依据计划中声明的内容分发任务。
• --mode={ci|cro} 路由：ci 根据 GitHub Actions 运行记录/日志规划修复（加载 references/mode-ci.md）；cro 规划转化率优化（25 项框架，references/mode-cro.md）；默认（无标志）= 标准流程。模式只会新增一个参考资料载荷——使用相同的引擎、相同的 $plan-review 把关流程以及相同的 planner Agent。
• 默认采用 HARD 模式（并行子 Agent、项目参考文档、在 3 轮上限内完成 $plan-review 收敛循环）；只有在满足所有琐碎任务条件时，才能使用 fast 模式。每个阶段都必须通过 5 点粒度检查（“我现在就能开始编码吗？”），包含带 TC ID 的 ## Test Specifications，并采用自底向上的估算方式（阶段工时决定人日；SP 为推导值）。
• **必需的最终任务 + 把关流程：**为每个阶段编写测试规格 → $plan-validate → $plan-review（收敛循环，上限 3 轮）→ $why-review（独立执行）→ 根据最终确定的阶段重新估算；审批前必须通过新技术/库把关；领域实体把关（计划涉及实体/VO/聚合时为必需）——应用 SYNC:domain-entity-change-gate，使计划确定分类、不变量归属、聚合边界、并发、构造、事件和测试义务（每项都须注明所属文件），而不是将这些事项推迟到实施阶段；在进行任何下一步之前，直接请用户确认。

工作流：

1. 预检查——检测有效/建议中的计划，或创建新目录
2. 研究阶段——在一条消息中启动所有相互独立的研究线程（researcher + scout 子 Agent，每个最多调用 5 次工具），然后设置屏障，再进行综合
3. 代码库分析——搜索项目参考文档（patterns-reference、project-structure、architecture、adr）；未找到时由 scout 执行
4. 计划创建——Planner 子 Agent 创建包含完整章节的 plan.md + phase-XX 文件
5. 并行处理检查——为每个阶段标注 PAR/SEQ 及其写入集；在 plan.md 中声明 ## Execution Waves
6. 验证后处理——可选择采访用户，通过 $plan-validate 确认决策

关键规则：

• 仅限规划：不得实现或执行代码更改
• 创建计划后始终运行 $plan-review
• 进行任何下一步之前，请用户确认
• 强制重要注意事项：检测计划中的新技术/库，并创建验证任务（参见下方的新技术/库把关流程）
• 强制重要注意事项：当计划涉及实体、值对象或聚合时，运行下方的领域实体把关流程——在任何实体任务之前说明范式与子域的适配情况，并为每个触发的决策行注明其所属文件；“在实施时再发现”不算答案。若未触发，把记录写为 No domain-entity surface — gate N/A

第一原则——易于修改

每项编码决策的成功指标：未来的修改成本。 DRY、SRP、抽象、设计模式、命名、分层、测试——所有 技术都服务于一个目标：降低下一次修改的成本。

评估代码、重构、测试或抽象时，问： 这会让下一次修改更便宜，还是更昂贵？

• 拒绝会提高修改成本的“最佳实践”（过早抽象、 推测性通用设计、泄漏的间接层、没有收益的形式主义）。
• 在发现的问题中指出真正的敌人：耦合、隐藏状态、重复的 知识、意图不明确、过早暴露的不可逆决策。
• 易于修改的简单设计，胜过难以修改的复杂设计。

在应用以下任何规则、模式或检查清单之前，先用这一视角审视； 如果后续规则提高了修改成本，以此原则为准。

---

默认模式策略

默认模式为 HARD（全面严谨）。 以下各节的所有要求——并行研究子 Agent、完整的 $plan-review 收敛循环（最多 3 轮）、基类 grep、微服务／事件驱动分析、强制用户批准——默认均适用。

仅当以下条件全部满足时，才可选择快速模式（任务确实非常简单）：

• 单文件编辑，修改不超过 30 行
• 无设计选择（只有一种合理方案）
• 无跨服务影响、无契约变更、无新增依赖
• 无新模式——遵循现有代码库模式
• 用户明确要求快速修改

任一条件不满足 → 使用以下完整流程。 如有疑问，默认采用 HARD 模式——在非简单任务中省略严谨流程所造成的返工，往往比严谨流程节省的更多。

快速模式仅跳过以下事项： 并行研究子 Agent（改为直接 grep）、$plan-review 再审循环（仅一轮，即使仍有发现也不重新审查）、$plan-validate 访谈（仅在流程中确认）、新技术／库准入门槛（仅当确实没有新增依赖时）。

新技术／库准入门槛（所有计划均为强制要求）

创建计划后，必须重点检查是否使用了项目中尚未采用的新技术／包／库。如果发现：为每个库建立任务跟踪 → 使用 WebSearch 搜索排名前三的替代方案 → 进行比较（适配度、大小、社区、学习曲线、许可证）→ 给出建议及置信度百分比 → 直接询问用户确认。如果计划仅使用现有依赖，则跳过。

领域实体门禁（当计划涉及实体、值对象或聚合时，必须执行）

应用 SYNC:domain-entity-change-gate（下文内联）——$plan-review 和 $changes-review 读取的同一协议，其 A–P 检查清单由 $domain-entities-review 负责。— 原因：如果计划把聚合边界、不变量归属或并发问题留到“实现时再发现”，最终交付的设计就会被评审否决，返工成本也要付两次。

触发条件： 计划引入或更改领域实体／值对象／聚合根及其字段、不变量、关系或状态转换；聚合边界、仓储或跨聚合引用；领域事件；或并发／重建相关问题。否则记录 No domain-entity surface — gate N/A。

计划必须为每个触发行明确写出决策和负责文件——未回答的事项意味着计划不可执行：

1. 分类——实体、值对象还是聚合根（应用交换测试）。
2. 不变量归属——实体负责强制执行哪些规则，边界负责验证哪些规则；失败信号（抛出异常还是 Result）须与项目惯例一致。
3. 聚合边界 + 并发——哪些内容共享一个事务，以及原因；跨聚合引用使用 ID；并发令牌放在根上；任何基于集合的不变量采用何种强制机制。
4. 构造与重建——创建和加载路径分开；加载时不引发事件。
5. 事件——引发哪些事件、何时分派（提交后／通过 outbox），以及领域契约与集成契约。
6. 测试要求——每个不变量都要规划一个属性 TC 和一个边界反例测试用例任务，绝不能留作隐含要求。

在规划实体任务之前，必须明确说明范式（面向对象可变／类型驱动不可变／事件溯源）和子域适用类型（核心／支撑／通用／CRUD）——绝不能为 CRUD 子域规划丰富领域模型，也绝不能针对不可变或事件溯源模型规划 setter／可变性任务。

Greenfield 模式

**自动检测：**未发现现有代码库（未发现源代码目录、清单文件，或有内容的 project-config.json）→ 技能自动切换到 Greenfield 模式。规划产物（docs/、plans/、.claude/）不计入其中——仓库必须包含实际且有内容的代码目录。

检测到 Greenfield 时：

1. 跳过代码库分析阶段（研究员子 Agent 搜索代码）
2. **替换为：**通过 WebSearch + WebFetch 开展市场研究和业务评估
3. 将架构决策委派给 solution-architect Agent
4. 输出：包含 Greenfield 专属阶段（领域模型、技术栈、项目结构）的 plans/{id}/plan.md
5. 跳过阅读项目参考文档（Greenfield 项目中不会存在这些文档）
6. 扩大网络研究范围：技术领域、最佳实践、框架对比
7. 每个决策点都必须直接向用户询问，提供 2-4 个选项 + 置信度百分比
8. **[CRITICAL] 业务优先协议：**技术栈决策必须在完整的业务分析之后进行。不要一开始就询问用户选择技术栈。应先完成业务评估 → 推导技术要求 → 研究当前市场选项 → 生成对比报告 → 呈现给用户。完整的技术栈研究方法请参阅 solution-architect Agent。

• 研究报告不超过 150 行；plan.md 不超过 80 行
• **外部记忆：**将所有研究/分析写入 .ai/workspace/analysis/{task-name}.analysis.md。生成计划前，重新阅读分析文件的全部内容。

运行规划方法引擎。为每个阶段加载相关的 references/engine-*.md（按各阶段自身的跳过规则跳过）：

• references/engine-research.md — 研究与分析（如已提供研究员报告则跳过）
• references/engine-figma.md — 设计上下文提取（如无 Figma URL / 仅后端则跳过）
• references/engine-codebase-understanding.md — 代码库理解（如已提供侦察报告则跳过）
• references/engine-solution-design.md — 解决方案设计（权衡、安全性、性能、边缘情况、架构）
• references/engine-plan-organization.md — 计划创建、组织与输出标准

模式分派（--mode={ci|cro}）

默认情况（未指定 --mode 标记）：忽略本节——按下方标准计划流程执行，逐字节保持不变。 --mode 只会在同一引擎、同一必需的 $plan-review 审核关卡和同一 planner Agent 的基础上，额外加载领域专属参考资料 + 接收约定。它不会取代引擎。

标记	位置参数 $ARGUMENTS	规划前加载	计划 frontmatter 覆盖项
--mode=ci	GitHub Actions 运行记录/日志 URL	references/mode-ci.md（CI 失败类型：构建/测试/环境/Docker/依赖项）	priority: P1, tags: [ci, bugfix]
--mode=cro	要优化的内容/问题（可选截图/URL）	references/mode-cro.md（25 项 CRO 框架 + 多模态接收流程）	priority: P2, tags: [cro, conversion]

指定 --mode 时：（1）读取匹配的 references/mode-*.md；（2）将其接收流程 + 领域重点应用于 $ARGUMENTS；（3）运行下方标准计划工作流——使用同一 planner 子 Agent、相同的阶段文件结构，以及必需的 $plan-review。该模式只额外添加参考资料内容。

脚手架优先协议（条件性）

激活条件（必须全部满足）：

1. 当前工作流为 workflow-greenfield-init 或 workflow-big-feature
2. AI 必须主动调查是否存在现有的基础／底层抽象，使用以下模式：
   • 抽象／基类：abstract class.*Base|Base[A-Z]\w+|Abstract[A-Z]\w+
   • 泛型接口：interface I\w+<|IGeneric|IBase
   • 基础设施抽象：IRepository|IUnitOfWork|IService|IHandler
   • 工具／扩展层：Extensions|Helpers|Utils|Common（目录或类）
   • 前端基础结构：base.*component|base.*service|base.*store|abstract.*component（如果存在前端）
   • DI／IoC 注册：搜索符合项目框架惯例的 DI 注册模式
3. 如果发现现有脚手架 → 跳过。 记录：“在 {file:line} 检测到现有脚手架。跳过第 1 阶段脚手架搭建。”
4. 如果未发现基础抽象 → 继续脚手架阶段。

激活时：

计划的第 1 阶段必须是架构脚手架搭建——包含所有基类、泛型接口、基础设施抽象，以及遵循 OOP／SOLID 原则的 DI 注册。必须在功能故事之前运行。AI 应自行调查技术栈所需的基类。所有基础设施都必须置于接口之后，并至少有 1 个具体实现（依赖倒置）。第 1 阶段的交付物还必须包含 $scaffold 生成的黄金路径示例集——每种适用模式各有一个经过编译检查、可运行的 *.example.*：后端包括命令 · 查询 · 处理器 · 带不变量的实体 · 值对象 · 仓储 · 领域事件 + 事件处理器；有 UI 的前端包括表单 · 列表 · store · API 服务；测试包括一个涵盖成功路径和失败路径的集成测试。示例集应置于隔离的 examples/ 目录树中，并排除在生产构建之外，同时使用脚手架搭建的基础抽象，以便在任何功能开发开始前，脚手架完成后的 $architecture-review-full 门禁就有真实且可评分的代码。

**跳过时：**计划照常进行——功能故事基于现有基类构建。

仅限规划 — 需要协作

不要使用手动切换计划模式的工具——当前已处于规划工作流中。 不要实现或执行任何代码更改。 与用户协作：提出决策问题，并提供带有建议的选项。 创建计划后，始终运行 $plan-review 来验证计划。 在执行任何下一步之前，先请用户确认计划。

你的任务

$ARGUMENTS

创建前检查（当前计划或建议计划）

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

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

工作流

1. 如果创建新计划：使用 ## Naming 部分中的 Plan dir: 创建目录，然后运行 node .claude/scripts/set-active-plan.cjs {plan-dir}。如果复用计划：使用 Plan Context 中的活动计划路径。将目录路径传递给每个子 Agent。
2. 目标契约初始化（调查和编写阶段之前）： 根据 SYNC:goal-contract-satisfaction-loop 确定当前目标——使用 .claude/templates/goal-contract-template.md 创建或更新 {plan-dir}/goal.md，记录原始请求、目的、成功标准、约束和所需证据。每个阶段的成功标准都必须对应一项已保存的目标标准。对秘密信息进行脱敏。
3. 严格遵循 references/engine-plan-organization.md 中的“计划创建与组织”规则。
4. 项目参考文档预检——派发之前。 首先确定并阅读所需的项目参考文档。将缺失或过时的参考文档记录为范围明确的研究输入；切勿等到工作者启动后才发现起约束作用的规范。
5. 研究轮次——一条消息，一个屏障。 列出此任务所需的独立研究线程——按模块进行代码调查、模式发现、依赖映射、既有方案／库搜索——然后为每个线程标记 PAR／SEQ，并在派发前声明 Parallel plan: wave 1 = [...] · SEQ = [...] (reason)。研究是只读的，因此除非某个线程需要使用另一线程的输出（需注明该输出），否则应标记为 PAR。在一条消息中启动整个轮次：外部／既有方案线程使用 researcher Agent（最多 2 个），每个 Agent 最多调用工具 5 次；代码库线程使用 scout Agent，每个模块／区域分配一个，并确保读取范围互不重叠。为每个 Agent 在 {plan-dir}/research/ 或 {plan-dir}/scout/ 下指定各自的报告路径，避免两个 Agent 写入同一文件。
6. 根据预检参考文档分析代码库。仅当所需参考文档缺失或超过 3 天时： 在研究轮次中加入一项范围明确的 $scout <instructions>，用于收集缺失证据；不要之后再临时启动未计划的往返轮次。
7. 设置屏障，然后综合分析。 只有在本轮每个成员都已返回后（跳过的线程也视为已返回），才能继续。读取报告文件（而非依赖记忆），调和相互矛盾的发现，并记录尚未解决的缺口——仅当首轮暴露出缺口时，才派发第二轮。
8. 主 Agent 收集研究／scout 报告文件路径，并传递给 planner 子 Agent，要求其制定实施计划。
9. 并行性检查（交接前必须执行）。 验证每个阶段的 Mode、Wave、写入范围和 SEQ 依赖，然后编写 ## Execution Waves 行——参见计划并行性元数据（每份计划输出均为必填项）。这是 $plan-execute 能够分派并行任务的依据；未标记的计划将严格按顺序执行。
10. 主 Agent 收到 planner 制定的实施计划后，请用户审核。

计划后验证（可选）

创建计划后，可提供验证访谈，以便在实施前确认决策。

检查 ## Plan Context → Validation: mode=X, questions=MIN-MAX：

模式	行为
prompt	询问用户：“要通过简短访谈验证此计划吗？” → 是（推荐）／否
auto	自动执行 $plan-validate {plan-path}
off	完全跳过验证步骤

如果模式为 prompt： 直接使用询问用户工具，并提供上述选项。 如果用户选择验证或模式为 auto： 执行 $plan-validate {plan-path} SlashCommand。

输出要求

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

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

研究输出要求

• 研究 Markdown 报告应简洁（<=150 行）；涵盖所有主题并附上引用。

计划文件规范

• 每个 plan.md 必须以 YAML frontmatter 开头：

  ---
  title: '{Brief title}'
  description: '{One sentence for card preview}'
  status: pending
  priority: P2
  effort: { sum of phases, e.g., 4h }
  story_points: { sum of phase SPs, e.g., 8 }
  man_days_traditional: '{ total e.g., 6d (4d code + 2d test) }'
  man_days_ai: '{ total with AI e.g., 3d (2d code + 1d test) }'
  branch: { current git branch }
  tags: [relevant, tags]
  created: { YYYY-MM-DD }
  ---
  

• 在 {plan-dir}/plan.md 中保存概览（<80 行）：列出每个阶段的状态、进度、**模式（PAR/SEQ）**及阶段文件链接；在阶段表格下方添加 ## Execution Waves 行。

• 对于每个阶段，创建 {plan-dir}/phase-XX-phase-name-here.md，并包含以下章节：Context links、Overview、Key Insights、Requirements、Alternatives Considered（至少 2 种方案，并列出优缺点）、Design Rationale（说明选择该方案的原因）、Architecture、UI Layout（见下文）、Related code files、Parallel Execution（模式 PAR/SEQ · 写入集 · SEQ 依赖——见下文）、Implementation Steps、Todo list、Success Criteria、Risk Assessment、Security Considerations、Next steps。

• UI Layout： 对于面向前端的阶段，包含 ASCII 线框图。按层级（common/domain-shared/page-app）对组件分类。对于仅涉及后端的阶段：## UI Layout → N/A — Backend-only change.

计划并行性元数据（强制要求——每份计划输出都必须包含）

$plan-execute 仅会并行执行计划中声明的内容。未标记的计划会强制按顺序执行，因此遗漏此元数据属于本技能的缺陷，而不是执行器的问题。

1. 为每个阶段标注 PAR 或 SEQ——在 plan.md 阶段表格的 Mode 列，以及每个阶段文件的 ## Parallel Execution 章节中都要标注。PAR = 其输入不包含任何待执行阶段的输出，且其写入集与所有其他 PAR 阶段均不重叠。

2. 声明每个阶段的写入集——列出该阶段创建、修改或删除的确切文件路径（仅当计划中可枚举通配符成员时才可使用通配符）。两个 PAR 阶段的写入集必须互不重叠；如有重叠 → 合并阶段，或将后续阶段降为 SEQ 并注明共享文件。

3. 每个 SEQ 都要注明导致其必须按顺序执行的依赖——SEQ — needs phase-02's {migration | generated type | contract | file}。“感觉需要按顺序执行”“按顺序更安全”或未命名的依赖都不是充分理由：应改标为 PAR。

4. 将 PAR 阶段分组为执行波次，并在 plan.md 中的 ## Execution Waves 行中说明： Execution waves: wave 1 = [phase-01, phase-03] · wave 2 = [phase-04] · SEQ = [phase-02 (needs phase-01 schema), phase-06 (approval gate)]。

5. 关卡和评审是 SEQ 边界——用户审批、评审、验证或迁移阶段绝不能与其所控制的阶段处于同一波次；它们必须在该波次结束后运行。

6. 阶段文件区块格式（逐字复制到每个阶段文件中）：

   ## Parallel Execution
   
   - Mode: PAR | SEQ
   - Write set: `src/a/x.ts`, `src/a/x.spec.ts`
   - Wave: 1
   - SEQ dependency: {name the phase + the exact artifact it produces — omit when Mode: PAR}
   

行为变更／同步计划检查

• 对于会改变行为的工作，每个阶段都应说明要更改的行为、需要保留的不变行为、TC／测试证明，以及文档／规范同步操作。
• 对于 AI 提取的规范／TC，计划必须将其标记为仅供参考，直到正式接纳为准。
• 对于 .claude 技能／钩子／工作流／同步工具，计划必须包含生成镜像同步，或明确说明无需同步并提供依据。

重要的任务规划说明（必须注意并遵循）

• 始终通过任务跟踪将工作拆分为多个小型待办任务
• 始终添加一个最终审查待办任务，以验证工作质量并找出需要修复或改进的地方
• **强制要求的最终任务：**完成所有规划待办任务后，始终添加以下最终任务：
  1. 任务：“为每个阶段编写测试规范” — 在每个阶段文件中添加 ## Test Specifications，并使用 TC-{FEATURE}-{NNN} ID。如果存在功能文档，则使用 $spec [mode=tests]；对于 TDD 优先模式，使用 Evidence: TBD。
  2. 任务：“运行 $plan-validate” — $plan-validate 技能会通过关键问题访谈用户，并验证计划假设。
  3. 任务：“运行 $plan-review” — $plan-review 技能采用收敛循环（审查 → 验证发现 → 修复 → 重新进行完整审查），最多 3 轮，但绝不能把 3 轮当作目标：任何一轮（包括第 1 轮）通过后，循环立即结束；第 3 轮结束时若仍有 CRITICAL/HIGH/MEDIUM 问题未解决，则直接询问用户，不得默默判定为通过。SP 会提高每轮的严格程度，但绝不设置最低轮数：≤3 → 检查清单 + 代码证据追踪；4-8 → 加入对抗式模拟；>8 → 每轮都必须进行代码证据追踪。
  4. 任务：“运行 $why-review（仅限独立运行）” — 如果不在工作流中，则 $why-review 会验证设计依据、考虑过的替代方案和风险评估。如果工作流已包含 $why-review，则跳过。
  5. 任务：“根据最终计划重新评估估算” — 完成前的估算基于范围猜测；最终确定的阶段会揭示实际成本。阶段/TC/决策确定后：(a) 根据最终阶段文件重新推导 bottom_up_hours = Σ phase_hours；(b) 根据 SYNC:estimation-framework 重新计算 likely_days、risk_margin_pct、min-max range；(c) 与当前 frontmatter 中的 man_days_traditional / story_points 进行比较。如果 |delta| > 20% → 更新 frontmatter，添加 reestimate_delta_pct: <signed> 和一行 reestimate_reason。如果 |delta| > 50% → 标记为 SHOULD-RESCOPE，并在实施前直接询问用户。

重要说明

• 在过程中从目录中启用所需技能。
• 在不牺牲质量的前提下提高 Token 使用效率。报告中可牺牲语法严谨性，以求简洁。
• 未解决的问题 → 列在报告末尾。

---

独立审查关卡（仅限非工作流场景）

强制重要要求，必须注意：如果在工作流之外调用技能（独立运行 $plan），生成的计划必须包含 $changes-review，并将其作为计划中的最终阶段/任务。这样即使没有工作流强制执行，也能确保所有实施变更在提交前都经过审查。

如果已在工作流中运行（例如 workflow-feature、workflow-bugfix），则跳过此步骤——工作流会在适当环节处理 $changes-review。

后续步骤（独立运行：必须直接询问用户。若在工作流中则跳过。）

**强制重要要求，必须注意——没有例外：**完成此技能后，必须直接询问用户并提供以下选项。即使任务看起来“简单”或“显而易见”，也不得跳过——由用户决定：

• “继续执行完整工作流（推荐）” — 检测并继续执行最合适的工作流（计划已创建）。确保不会跳过审查、验证、实施和测试。
• “$why-review” — 在实施前验证设计依据（仅限独立运行——若工作流已包含此步骤则跳过）
• “$plan-review” — 在实施前验证计划
• “$plan-validate” — 通过访谈确认计划决策
• “$plan-execute” — 开始按照最终计划编写代码并进行测试。计划验证后推荐的实施方式。
• “跳过，继续手动处理” — 由用户决定

计划后粒度自检（强制）

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

1. 按 5 项标准为每个阶段打分（文件路径、无规划动词、步骤 ≤30 分钟、≤5 个文件、无未决事项）
2. 对每个未通过的阶段 → 创建任务，将其拆解为子计划（使用独立的 $plan → $plan-review → $plan-validate → 修复循环）
3. 重新为新阶段打分。重复执行，直到所有叶阶段都通过（最大深度：3）
4. 自问：“每个阶段是否都能让我现在马上开始编码？如果有任何阶段需要‘弄清楚’→ 将其拆成子计划。”

保全清单（修复缺陷时强制执行）

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

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体/模型时阅读）
• docs/specs/ — 按模块划分的测试规格（阅读现有 TC，将测试策略纳入计划）

每个阶段文件必须特别满足：每个阶段 ≤5 个文件、工作量 ≤3 小时、成功标准明确、映射到测试用例。

证据门槛： 强制要求：每项声明、发现、建议都必须提供 file:line 证明或可追溯的证据，并标明置信度百分比（>80% 才能采取行动，<80% 必须先核实）。

外部记忆： 对于复杂或耗时较长的工作（研究、分析、扫描、审查），将中间发现和最终结果写入 plans/reports/ 中的报告文件，以避免上下文丢失并作为交付物。

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

1. 列出要修改的确切文件路径（而非笼统的“实现 X”）
2. 不含规划动词（research、investigate、analyze、determine、figure out）
3. 每个步骤 ≤30 分钟，阶段总计 ≤3 小时
4. ≤5 个文件
5. 方法中没有未决事项或 TBD

未通过的阶段 → 创建子计划。重复执行，直到所有叶阶段都通过（最大深度：3）。 自问：“我现在马上就能开始编码吗？如果有任何步骤需要‘弄清楚’→ 将其拆成子计划。”

保全清单 — 编写缺陷修复计划时强制执行。计划标题/前置元数据中的触发关键词：fix、bug、regression、broken、defect。作者必须在编写实施步骤之前生成此表。

列： Invariant | file:line | Why (data consequence if broken) | Verification (TC-ID or grep)

阻塞条件：≥3 行 · 每个 File 单元格都包含 file:line · 每个 Verification 单元格都包含 TC-ID 或 grep（不能写“手动验证”）

嵌套任务展开约定 — 对于工作流步骤调用，[Workflow] ... 行仅为父容器；子技能仍需创建可见的阶段任务。

1. 首先获取当前任务列表。如果存在匹配的活动父工作流任务行，则设置 nested=true 并记录 parentTaskId；否则独立运行。
2. 在阶段工作开始前，为声明的每个阶段创建一个任务。嵌套时，主题前缀为 [N.M] $skill-name — phase。
3. 嵌套时，使用 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 关联父任务。
4. 编排器必须预先展开子技能的阶段列表，并在调用该子技能或子 Agent 前关联工作流任务行。
5. 开始工作前，恰好将一个子任务标记为 in_progress；证据写入后立即将其标记为 completed。
6. 只有所有子任务均已完成，或已明确取消并说明原因后，才能完成父任务。

**阻塞条件：**已获取当前任务列表、已创建子阶段、嵌套时已关联父任务、首个子任务已标记为 in_progress。 项目参考文档门禁 — 在任务跟踪初始化之后、读取目标文件或源文件、搜索、编辑或分析之前运行。项目文档优先于通用框架假设。

1. 确定范围：文件类型、领域和操作。
2. 先阅读 docs/project-config.json——项目的机器可读映射。 它是本仓库的唯一事实来源（模块/路径、框架及搜索关键词、测试/E2E/集成运行命令、设计系统、架构规则、工作流模式）；在调查、规划或编码之前，依据它确认确切路径、运行命令和约定——切勿假设框架默认设置（CLAUDE.md 和参考文档均由它派生）。如果它、文档索引、lessons.md、CLAUDE.md、AGENTS.md 或任何必需的参考文档缺失或已过时，请先自动运行 $project-init 或范围更窄的流程（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）；如果 Codex 镜像或 AGENTS.md 已过时，请让用户运行 $sync-codex（切勿自动运行）。
3. 按触发条件确定必需文档：始终需要 docs/project-reference/lessons.md；文档查找需要 docs-index-reference.md；审查需要 code-review-rules.md；后端/CQRS/API 需要 backend-patterns-reference.md；领域/实体需要 domain-entities-reference.md；前端/UI 需要 frontend-patterns-reference.md；样式/设计需要 scss-styling-guide.md + design-system/design-system-canonical.md；集成测试需要 integration-test-reference.md；E2E 需要 e2e-test-reference.md；功能文档/规格说明需要 feature-spec-reference.md + spec-system-reference.md + spec-principles.md；行为/公共契约/规格测试代码同步需要 workflow-spec-test-code-cycle-reference.md；派生规格索引/ERD/重新实现指南需要 spec-system-reference.md + docs/specs/ 下的源功能规格说明；架构/新领域需要 project-structure-reference.md。
4. 阅读所有必需文档，然后在开展目标工作之前说明：Reference docs read: ... | Not applicable: ...。

准备就绪条件： 已评估范围、已查阅 docs/project-config.json、已检查/阅读必需文档或已完成初始化流程、已确认 lessons.md、已提供引用说明。

任务跟踪与外部报告持久化 — 执行前完成此初始化；随后在处理目标/源文件之前预先读取项目参考文档。

1. 在读取目标文件或源文件、搜索、编辑或分析之前，创建简要的任务拆分。上下文丢失时，先检查当前任务列表。
2. 开始工作前将一个任务标记为 in_progress，取得证据后立即标记为 completed；切勿批量转换状态。
3. 对于规划/审查工作，在发现首个问题之前创建 plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md。
4. 每完成一个文件/章节/决策后追加发现，最后根据报告文件综合整理。
5. 最终输出注明：Full report: plans/reports/{filename}。

未满足以下条件前禁止继续： 已创建任务拆分；规划/审查工作已声明报告路径；已在记录下一项发现前持久化首项发现。

批判性思维准则 — 运用批判性思维和顺序思维。每项主张都需要可追溯的证据，置信度须高于 80% 才能采取行动。 反幻觉： 切勿将猜测当作事实陈述——每项主张都要引用来源，坦诚承认不确定性，自查输出中的错误，独立交叉验证，并对自己的判断保持审慎——缺乏证据的确信是一切幻觉的根源。 顺序思考协议 — 为复杂或含糊的工作提供结构化的多步推理。在规划、审查、调试或完善想法时使用，尤其是在一次性推理不可靠的情况下。

触发条件： 复杂问题分解 · 需要调整的自适应计划 · 需要纠正方向的分析 · 范围不明确或不断变化 · 多步解决方案 · 假设驱动的调试 · 跨领域权衡评估。

格式（显式模式 — 展示思路）：

1. Thought N/M: [aspect] — 每条思路只讨论一个方面，并说明假设和不确定性
2. Thought N/M [REVISION of Thought K]: ... — 先前推理失效时使用；说明原始内容／修订原因／影响
3. Thought N/M [BRANCH A from Thought K]: ... — 探索替代方案；通过决策依据得出结论
4. Thought N/M [HYPOTHESIS]: ... 然后是 [VERIFICATION]: ... — 先验证，再行动
5. Thought N/N [FINAL] — 仅在验证完成、所有关键方面均已处理且置信度 >80% 时使用

强制收尾内容： 说明置信度百分比 · 列出假设 · 提出未解决的问题 · 明确下一步行动。

停止条件： 对任何关键决策的置信度 <80% → 直接向用户提问并升级处理 · 同一条思路修订 ≥3 次 → 重新梳理问题 · 分支数 >3 → 拆分为子任务。

隐式模式： 在显式标记会使回复显得冗长时，在内部应用此方法（适用于推理有助于提高准确性的常规工作）。

深入了解： 请参阅 $sequential-thinking 技能（.claude/skills/sequential-thinking/SKILL.md），了解示例（API 设计、调试、架构）、高级技巧（螺旋式完善、假设测试、收敛）和元策略（不确定性处理、修订级联）。

先理解代码 — 硬性门槛：在阅读现有代码之前，禁止编写、规划或修复。

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 存在） - [ ] 通过证据验证假设 跨服务检查 — 微服务／事件驱动：在结束调查、计划、规范或功能文档之前，必须执行。遗漏下游消费者会导致静默回归。

边界	Grep 词
事件生产者	Publish、Dispatch、Send、emit、EventBus、outbox、IntegrationEvent
事件消费者	Consumer、EventHandler、Subscribe、@EventListener、inbox
Saga／编排	Saga、ProcessManager、Choreography、Workflow、Orchestrator
同步服务调用	与其他服务之间的 HTTP／gRPC 调用
共享契约	OpenAPI 规范、proto、共享 DTO——标记不兼容变更
数据所有权	其他服务读写同一张表／集合 → 共享数据库反模式

每个接触点： 所属服务 · 消息名称 · 消费者 · 风险（NONE / ADDITIVE / BREAKING）。

以下事项完成前禁止继续： 已扫描生产者 · 已扫描消费者 · 已检查 Saga · 已审查契约 · 已标记不兼容变更风险 估算框架 — 优先自下而上；故事点（SP）为推导值；预计用时可能 ≥3d 时，输出最小值至最大值范围。与技术栈无关。基准：3-5 年经验的开发者，每天 6 个有效工作小时。AI 估算假设使用 Claude Code + 项目上下文。

方法：

1. 影响范围检查（见下文）——决定代码和测试成本
2. 分解阶段 → 每阶段小时数 → bottom_up_hours = Σ phase_hours
3. likely_days = ceil(bottom_up_hours / 6) × productivity_factor
4. 累加风险余量（基础值 + 附加值）→ max_days = likely_days × (1 + margin)
5. min_days = likely_days × 0.9
6. 当 likely_days ≥3 时输出范围；<3 时可用单点值（仍须记录余量）
7. man_days_ai = 相同范围 × AI 加速比
8. story_points 根据 likely_days 通过 SP-Days 推导——绝不作为估算驱动因素。偏差 >50% → 以自下而上估算为准

效率系数： 0.8 脚手架、代码生成和 AI 钩子完善 · 1.0 成熟默认值 · 1.2 模式薄弱 · 1.5 从零开始

成本驱动因素启发式规则（在选择工作类型行之前应用）：

• UI 占主导：CRUD/业务应用中通常如此——成本为后端的 1.5-3 倍（状态、验证、响应式、无障碍、打磨）
• 仅以下情况由后端占主导： 多聚合不变量、跨服务契约、架构迁移、复杂查询/性能、新事件流

复用与创建轴（首要杠杆，按层计算）：

UI 层级	成本
复用现有屏幕上的组件	0.1-0.3d
在现有屏幕上添加控件/列	0.3-0.8d
将组件组合成新屏幕	1-2d
新屏幕，含自定义布局/状态/验证	2-4d
新建共享/通用组件（含主题、测试）	3-6d+

后端层级	成本
在新位置复用查询/处理程序	0.1-0.3d
小幅更新现有处理程序/实体	0.3-0.8d
在现有仓库/模型上新增查询	0.5-1d
在现有聚合上新增命令/处理程序（增量式）	1-2d
新建聚合/实体（仓库、验证、事件）	2-4d
新建跨服务契约或架构迁移	各 2-4d
多聚合不变量/复杂领域规则	3-5d

规则： 将 UI、后端和测试各层级成本相加，再应用效率系数。复用可直接跳过对应层级——请注明。

测试范围驱动因素（明确计算 test_count——用“+测试”含糊带过是首要失败原因）：

驱动因素	数量
顺利路径用户旅程	每个用户故事/验收标准主流程 1 项
状态机转换	可达转换数 × 允许的操作者数
多实体状态组合	state(A) × state(B)——仅计算可达组合，不计算笛卡尔积
授权矩阵	（所有者、非所有者、较高权限、未认证）× 每种变更操作
验证规则	每个必填字段/边界/格式/跨字段规则 1 项
UI 状态（每个新屏幕/对话框）	顺利、加载中、空状态、错误、部分状态——仅计算实际存在的状态
负向路径/不变量	每条可违反的业务规则 1 项

测试层级（传统方式，含设置、断言和偶发失败处理）	成本
1-5 个用例，复用测试夹具	0.3-0.5d
6-12 个用例，新增 1 个测试夹具	0.5-1d
13-25 个用例，多实体设置	1-2d
26-50 个用例，或新增状态机覆盖	2-3d
>50 个用例，或完整端到端旅程	3-5d

测试乘数： 新增测试夹具/种子数据框架 +0.5d · 每个跨服务/总线断言 +0.3d · UI 端到端测试 ×1.5 · 每新增一个角色 +1-2 个用例

影响范围（强制预检查——影响代码和测试）：

1. 直接修改的文件/组件——计数
2. 其中的“复杂”项（>500 LOC、多处理程序、核心、频繁修改）——计数
3. 下游使用方（调用方、事件订阅者、跨服务）——列出
4. 是否改动共享/通用代码（影响多个应用）——是/否
5. 回归范围——需要重新测试的区域

规则： 改动复杂项 → 添加 risk_factors。每个下游使用方 → +1-3 个回归用例。影响范围 >5 个区域或 >2 个复杂项 → 估算前重新评估是否应拆分。

风险余量（决定最大值上限）：

预计天数	基础余量
<1d 微小	+10%
1-2d 小型增量	+20%
3-4d 实际功能	+35%
5-7d 大型	+50%
8-10d 特大型	+75%
>10d	+100% 并标记为应拆分

风险因素附加值（累加——在 risk_factors 中逐项列出）：

因素	+余量
touches-complex-existing-feature（>500 LOC、多处理程序、核心）	+20%
cross-service-contract 变更	+25%
schema-migration-on-populated-data	+25%
new-tech-or-unfamiliar-pattern	+30%
regression-fan-out（≥3 个下游区域需重新测试）	+20%
performance-or-latency-critical	+20%
concurrency-race-event-ordering	+25%
shared-common-code（多个使用方/多个应用）	+25%
unclear-requirements-or-design	+30%

合并规则： 总余量 >100% → 停止并拆分（缓冲超过 2 倍就是不诚实）。likely_days ≥5 时余量 <15% → 估算偏低，应扩大范围。

工作类型上限（likely_days 的硬性上限）：

工作类型	最大 SP	最大预计天数
单个字段/配置标记/样式修复	1	0.5d
在现有模型中添加属性并绑定到现有 UI	2	1d
新增端点 + 轻量 UI 控件（按钮/菜单/列），复用测试夹具	3	2-3d
新增端点 + 新 UI 界面，或增量式多层变更 + 新领域规则 + 2 个以上测试文件	5	3-5d
新模型/聚合，或迁移，或跨模块契约，或复杂测试（>1.5d），或新 UI + 非简单后端	8	5-7d
新 UI 界面 +（新聚合或迁移或跨服务契约）	13	应拆分
跨服务契约 + 迁移组合	13	应拆分
超出以上范围	21	必须拆分

SP→天数（仅用于验证）： 1=0.5d/0.25d · 2=1d/0.35d · 3=2d/0.65d · 5=4d/1.0d · 8=6d/1.5d · 13=10d/2.0d（传统/AI 预计天数） AI 加速比： SP 1≈2x · 2-3≈3x · 5-8≈4x · 13+≈5x。AI 成本 = (code_gen × 1.3) + (test_gen × 1.3)（30% 审查开销）。

强制前置元数据：

story_points: <n>
complexity: low | medium | high | critical
man_days_traditional: '<min>-<max>d' # likely ≥3d 时用范围；<3d 时用 '<N>d'
man_days_ai: '<min>-<max>d'
risk_margin_pct: <n> # 基础值 + 附加值
risk_factors: [touches-complex-existing-feature, regression-fan-out] # 来自附加值的封闭列表；没有则为 []
blast_radius:
    touched_areas: <n>
    complex_touched: <n>
    downstream_consumers: [列表或数量]
    shared_common_code: yes | no
estimate_scope_included: [代码，集成测试，前端，i18n，文档]
estimate_scope_excluded: [单元测试，端到端测试，性能测试，部署，代码审查轮次]
estimate_reasoning: |
    用 5-7 行说明：
    (a) UI 层级——应用的行
    (b) 后端层级——应用的行
    (c) 测试范围——按驱动因素拆分用例数、文件数、测试夹具、层级行
    (d) 成本驱动因素——占主导的层级及原因
    (e) 影响范围——改动项、复杂项、回归范围
    (f) 风险因素——导致余量的因素；说明为何余量不更大/更小
    示例："UI：组合 Form/Table/Dialog → 新屏幕（约 1.5d）。后端：在现有聚合上新增命令，
    复用验证和仓库（约 1d）。测试：4 个转换 × 2 个操作者 + 3 个验证规则 + 2 个 UI 状态 = 13 个用例，
    新增 1 个测试夹具 → 13-25 个用例层级，约 1.5d。驱动因素：UI 组合 + 新状态。影响范围：4 个区域，1 个复杂项。
    风险：基础值 35% + 复杂项改动 20% = 55% → 最大值 3.9d → 范围 2.5-4d。"

合理性自检：

• likely_days ≥3d 却给出单点值？→ 拒绝，必须给出范围

• likely_days ≥5d 时余量 <15%？→ 估算偏低，应扩大范围

• 余量 >100%？→ 停止，改为拆分，而不是增加缓冲

• 改动了现有复杂功能，但 (c) 中没有回归预算？→ 拒绝

• 影响范围 >5 个区域或 >2 个复杂项，却没有讨论拆分？→ 拒绝

• 仅在现有模型和现有 UI 上做增量修改？→ SP 上限为 3，除非测试 >1.5d

• 新 UI 界面（页面/复杂表单/仪表板）？→ 即使后端只有一个端点，SP 也至少为 5

• 后端涉及跨服务/迁移/多聚合？→ 无论 UI 如何，SP 至少为 8

• bottom_up_hours / 6 与 SP-Days 的偏差 >50%？→ 以自下而上估算为准，调低 SP

• 去掉测试后，SP 是否至少下降一个档位？→ 测试占主导；请明确说明

• 推理是否说明了 UI 与后端的差异、影响范围和风险因素？→ 缺少则补充 计划质量 — 每个计划阶段 MUST ATTENTION 包含测试规范。

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

模式： TDD 优先 → 使用 Evidence: TBD 引用现有 TC。实现优先 → 使用 TBD → $spec [mode=tests] 在之后补全。

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

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

• 修改文件数 ≤5
• 工作量 ≤3 小时
• 遵循周期：规划 → 实现 → 审查 → 修复 → 验证
• 仅在第 N 阶段通过 VERIFY 后才开始第 N+1 阶段——原因：基于未经验证的阶段继续构建，会导致错误在后续不断累积

阶段成功 = 所有 TC 均通过 + code-reviewer agent 批准 + 没有 CRITICAL 发现。

修复层级责任 — 绝不在崩溃点修复。追踪完整流程，在所属层级修复。

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

任何修复前均必须：

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

以下内容完成前视为受阻： - [ ] 已追踪完整数据流（源头 → 崩溃点） - [ ] 已通过 file:line 证据确定不变量所属层级 - [ ] 已审查所有访问点（grep 计数） - [ ] 已说明修复层级的合理性（能保护最多使用方的最低层）

反模式（拒绝这些做法）：

• “在崩溃处修复”——崩溃点 ≠ 原因点。应向上游追踪。
• “在每个使用方添加防御性检查”——分散防护意味着层级错误。一个权威修复 > 多个分散的保护措施。
• “两处都修复更安全”——选择一个权威层级。在多个层级添加冗余检查，会混淆不变量的所属方。 防止 AI 出错 — 每项任务都应避免的失败模式：

上下文变化后重新阅读文件。 上下文压缩、恢复工作或长时间运行的任务可能导致记忆过时；采取行动前，请核实当前文件。 根据源证据核实生成的内容。 AI 可能会对 API、名称、声明和文档事实产生幻觉。记录或引用前，请检查相关源文件。 删除或重命名前检查下游引用。 移除某个产物可能导致文档、生成的镜像、配置和调用方过时；请先梳理引用。 编辑后追踪完整的影响链。 更改定义可能遗漏派生输出和使用方。宣布完成前，请追踪受影响的链路。 核实所有受影响的输出，而不只是第一个。 一项检查通过不代表所有检查都通过；请验证变更可能影响的每个输出面。 假定现有值都是有意设置的——更改或指出其为缺陷前，先问清原因。 更改或报告常量、限制、标志、阈值、措辞或模式前，请阅读附近的上下文和历史、调用方的顺序，以及至少 2 个采用相同约定的同类调用点。文档说明了是什么，却没有说明为什么，这意味着缺少依据，而非证明缺少防护措施。 行动前明确提出歧义——不要默默做出选择。 存在多种合理解释时，应明确提问，或说明假设及其风险。 验证系统负责的最终结果，而非基础设施负责的中间状态。 验证异步工作时，应断言最终业务状态，绝不要检查由共享基础设施记录的交付／重试状态，因为任何同时运行的进程都可能写入这些状态。此类检查单独运行时会通过，一旦有其他进程共用该基础设施，就会时好时坏。 确保共享指导与接收方角色相关。 通用指导必须对每个接收它的技能或 Agent 都有帮助；代码专属要求应仅放在代码专属协议中。 领域实体变更关卡 — 一套协议，约束每个规划、实现或审查涉及领域实体、值对象或聚合的变更的技能或 Agent，使规划者、实现者和审查者对同一变更应用相同规则。$domain-entities-review 是完整 A–P 检查清单的权威归属；此关卡是共享触发条件，以及必须回答的决策集。切勿重新推导出较弱的本地副本——原因：当规划和审查对实体规则意见不一致时，计划会交付一种设计，随后又被审查否决，返工成本因此付出两次。

触发条件——满足任一项即触发： 引入新实体／值对象／聚合根 · 为现有实体／值对象／聚合根新增或移除字段、不变量、关系或状态转换 · 聚合边界、仓储或跨聚合引用发生变化 · 添加、重命名或重新定义负载的领域事件 · 根的并发或重建相关事项发生变化。如果均不满足，则写明 No domain-entity surface — gate N/A。

步骤 1 — 先检测，再做决定。 两项判断都会改变实际适用的规则：

• 范式（按聚合，从代码判断——绝不预设）：面向对象可变 · 类型驱动／不可变 · 事件溯源。Setter、可变性和重建规则是为面向对象可变范式编写的；将其应用于另外两种范式会凭空制造错误发现和错误计划任务。
• 子域适配性： 核心（应采用丰富模型）· 支撑（活动记录或轻量模型）· 通用（购买，不要建模）· CRUD（事务脚本——在此处使用丰富实体只会徒增形式）。如果子域除了必填字段之外没有不变量，绝不要规划或标记丰富模型。

步骤 2 — 回答全部 6 项决策。 每一项都是变更必须明确做出的决策：

#	决策项	满足以下条件即视为已回答
1	分类——实体 vs 值对象 vs 聚合根	已应用替换测试（“一个完全相同的副本是否可以互换？”）；值对象不可变、具有结构相等性，且没有仓储
2	不变量归属——实体负责“这种状态能否存在？”，边界负责“此输入是否可接受？”	每条规则都归属一侧并有明确命名；失败信号（抛出异常 vs Result）始终符合项目约定；数据库约束是兜底机制，绝不是规则
3	聚合边界 + 并发	只有真正需要始终保持一致的不变量才属于同一聚合；跨聚合引用使用 ID；每个事务只修改一个聚合；根携带并发令牌；基于集合的不变量（实例间唯一性）须指明真实的强制执行机制，绝不能仅做内存检查
4	构造 vs 重建	创建和加载采用不同路径；加载路径不会引发任何领域事件，也不会重新运行任何创建规则；必需数据位于构造函数／工厂中
5	事件	在聚合内部引发；在提交后分发（跨进程时使用 outbox）；内部领域事件与已发布的集成契约保持区分；处理程序具备幂等性
6	测试义务	每个不变量都映射到一个全称量化的属性测试用例（TC），加上一个边界反例——规范明确列出，且由测试守护（双重反馈）；单个成功路径示例不算覆盖

步骤 3 — 按上下文应用。 决策相同，义务不同：

调用上下文	义务
规划（$plan）	计划必须为每个触发的行写明决策和对应文件。未回答的行意味着计划不可执行——应将其明确指出，切勿让实现阶段才发现。
计划审查（$plan-review）	未回答、含糊带过或推迟到实现阶段的行，都构成一项发现，并须在计划中标出 file:line。出现“entity”一词绝不算作回答。
实现（$plan-execute、$fix 及任何实现 Agent，例如 backend-developer）	这些决策是输入，而非要重新讨论的问题：按照计划／规范中的决定，在其指定的归属文件中实现每个触发的行。未回答的行是阻塞项——应将其明确指出并取得决定；绝不能在敲代码时默默敲定，也绝不能因为计划未明确聚合边界，就根据数据库表或 UI 屏幕自行选定边界。范式和子域适配性仍决定适用哪些规则。
变更审查（$changes-review）	转交给责任方——模式 A（默认）： 阅读 $domain-entities-review 的 Phase 2 A–P 检查清单，并将其作为审查视角应用。模式 B（升级处理）： 仅当独立调用且差异包含 3 个或更多实体文件时，委派给 $domain-entities-review。发现应加入常规发现集，并附上 file:line + 严重性。

重复执行防护——满足任一行时，完全跳过此关卡。 记录延期说明，然后继续：

抑制上下文	延期说明
正在运行的技能就是 $domain-entities-review	Gate is this skill's own body — A–P checklist owns it.
在 $workflow-review-changes 中调用（其步骤 5 会将 $domain-entities-review 作为专用的条件并行成员运行）	Gate deferred to workflow step 5 $domain-entities-review.
$why-review 在 --validate-findings 终端模式下运行	Gate N/A — validate-findings is terminal, no sub-skill calls.

——原因：若不加防护，此边会重复审查父工作流已经执行的内容，并形成 changes-review → domain-entities-review → why-review → changes-review 循环。

解除阻塞前必须满足： 已评估触发条件（或记录 gate N/A）· 已说明范式 + 子域适配性 · 已回答所有 6 项触发的决策，或将其列为发现 · 委派前已检查防护行。 必须注意 当变更规划或评审新的／已更新的领域实体、值对象或聚合时，应用 领域实体变更门禁 — $domain-entities-review 负责完整的 A–P 检查清单；首先识别范式和子域是否匹配，然后回答全部 6 个决策点（分类 · 不变量归属 + 失败信号 · 聚合边界 + 并发 · 构造与重建 · 事件 · 属性 TC 测试义务）。规划必须明确写出每项决策；计划评审将未回答的条目视为一项发现；变更评审将任务转交给负责人（模式 A：阅读／模式 B：委派）。在 3 行重复防护条件下跳过，并记录延期说明。— 原因：规划者和评审者共用同一套协议，才能防止计划交付一个实体设计，却在评审时遭到否决。

• 强制注意 估算：自下而上的各阶段小时数决定 man_days_traditional（Σh/6 × productivity_factor）；SP 为派生值。UI 成本通常占主导 — 若有新的 UI 界面（页面／复杂表单／仪表板），将 SP 上调一档。Frontmatter 必须包含 story_points、complexity、man_days_traditional、man_days_ai、estimate_scope_included、estimate_scope_excluded、estimate_reasoning（UI 与后端的成本驱动因素）。若是在现有模型 + 现有 UI 上增量改动，除非测试范围 >1.5d，否则 SP 上限为 3。SP 13 应拆分，SP 21 必须拆分。

重要注意 必须包含 ## Test Specifications，并为每个阶段提供 TC ID。创建新任务前，先调用当前任务列表。

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

重要注意 任何修改前，搜索至少 3 个现有模式并阅读代码。如果 graph.db 存在，则运行图追踪。

• 强制重要注意 每项主张都必须附上 file:line 证据。置信度 >80% 才执行，<60% 则不要提出建议。

重要注意 首先评估复杂度。评分 >=6 → 分解。每个阶段：计划 → 实施 → 评审 → 修复 → 验证。不得跳过。

重要注意 追踪完整的数据流，并在所属层修复，而非在崩溃点修复。添加 ?. 前，审查所有访问位置。

重要注意 微服务／事件驱动：扫描任务范围内的生产者、消费者、Saga 和契约。每个触点注明：负责人 · 消息 · 消费者 · 风险（NONE／ADDITIVE／BREAKING）。遗漏消费者会导致静默回归。

必须注意 运用批判性思维和顺序思维 — 每项主张都需要适当的追踪证据（仓库／代码主张需提供 file:line；研究、产品、内容和文档主张需提供来源 URL 或产物章节）；置信度 >80% 才执行，<60% 不要提出建议。防止幻觉：绝不将猜测当作事实，坦诚承认不确定性，独立交叉核对，并对自己的信心保持怀疑。

必须注意 运用 sequential-thinking — 多步骤内容使用 Thought N/M、REVISION／BRANCH／HYPOTHESIS 标记，并标注置信度百分比；参见 $sequential-thinking 技能。

必须注意 落实 AI 错误预防措施 — 对照证据核验生成内容，删除或重命名前追踪下游引用，验证所有受影响的输出，失去上下文后重新阅读文件，并在采取行动前明确指出歧义。

• 强制要求 在处理目标工作前初始化任务跟踪；每次只转换一个任务状态。

• 强制要求 将计划／评审发现逐步保存到 plans/reports/，并从磁盘内容综合整理。

• 必须 在调查、规划或编码之前，先阅读 docs/project-config.json（项目地图：模块/路径、运行命令、约定、架构/工作流规则）和必需的项目参考文档，并注明 Reference docs read: ...。

• 必须 始终包含 lessons.md；项目配置和约定优先于通用框架默认设置。

• 必须 如果项目配置、根目录指令文件或任何必需的参考文档缺失或已过时，则在开展常规项目特定工作之前，自动运行 $project-init 或范围更窄的底层流程。

• 必须 父级工作流条目不能替代子阶段跟踪；嵌套时应展开各阶段并关联父级。

• 必须 编排器在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵守单个 in_progress 纪律。

• 必须 在开始工作之前确定当前有效的目标契约（有效计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 根据当前请求创建），并在编辑前阅读已保存的成功标准。

• 必须 在执行后追加迭代证据；报告 PASS 之前，先输出目标满足度矩阵（PASS/FAIL/BLOCKED）；对经验证的 FAIL 继续循环；对反复无进展或阻碍升级处理。绝不可在目标文件中存储密钥。

并行子 Agent 调度 — 一旦任务拆解完成，立即规划并行执行，必须在执行之前完成；按顺序运行可明确独立的任务会浪费实际耗时。适用于所有多步骤工作：工作流步骤、规划、批量更新、调查、研究、扫描、审查、文档同步。计划执行由元数据控制，绝不可默认并行 — 扇出仅遵循计划中的声明（PAR/SEQ 标签和各阶段写入集）；未标记的计划按顺序执行——原因：推导出的写入集无法发现级联或生成的写入。

1. 为每项任务标记 PAR 或 SEQ。 PAR = 输入不依赖任何待处理任务的输出，且写入集与其他所有 PAR 任务互不重叠。否则标记为 SEQ —— 必须明确指出导致依赖的原因。
2. 将 PAR 分组为多个波次。 波次成员之间不得有依赖边。同一文件的两个写入者绝不能处于同一波次。只读工作（搜索、调查、审查、研究）可自由并行。
3. 调度前声明： Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason)。
4. 每个波次在一条消息中启动 — 一条回复中发出该波次的所有 spawn_agent 调用，绝不可分多轮逐个发送。将每项任务交给对应的专业人员（.claude/skills/shared/sub-agent-selection-guide.md）；绝不可把 code-reviewer 当作万能人选。
5. 向每个子 Agent 提供完整独立的任务说明： 目标 · 范围和负责的文件 · 参考文档 · 返回要求（摘要 + Full report: 路径，遵循 SYNC:subagent-return-contract）· 增量持久化到 plans/reports/（遵循 SYNC:incremental-persistence）。
6. 每个波次都设屏障。 仅在所有成员都返回后才能继续（跳过的条件分支也算已返回）。合并结果，将每项任务标记为已完成/已跳过，然后再调度下一波。修改步骤必须等待屏障。
7. 仅一层深度。 已调度的子 Agent 执行自身的任务说明；除非该 Agent 的 .claude/agents/*.md 定义授权，否则进一步扇出仍由编排器负责。

绝不可并行处理： 共享写入目标的任务 · 使用待处理任务输出的任务 · 微不足道的单文件工作（调度开销大于收益）· 技能或工作流明确规定顺序的任务 · 等待用户批准的关卡。

解除阻塞的条件： 必须为每项标记为 PAR/SEQ 的任务明确指出原因（每项 SEQ 任务都要单独说明）· 声明各波次并检查写入集互不重叠 · 每个波次都在一条消息中启动 · 在进入下一波之前遵守屏障。

• 必须执行 规划任务后，为每项 PAR/SEQ 添加标签，并在一条消息中将每个 PAR 波次作为并行子 Agent 启动——工作流、批量更新、调查、研究和审查默认并行；计划执行只对计划声明的内容进行分派。
• 必须执行 每个波次的写入范围必须互不重叠 · 下一波开始前必须等待所有任务返回 · 按专业领域分派 · 除非其自身 Agent 定义授权，否则子 Agent 绝不进一步分派任务。

项目协议叠加规则 — 执行此技能前，解析叠加在此技能之上的任何项目规则：将此技能名称与项目技能协议索引中的 Target 列匹配（默认路径为 docs/project-reference/skill-protocols-reference.md；docs/project-config.json 中的 referenceDocs 条目可覆盖该路径），并且只采用匹配度最高的层级——精确名称 > glob > *。此优先级仅用于排列叠加规则彼此之间的优先级，绝不用于确定叠加规则与此技能之间的优先级。 只读取匹配条目的正文，路径解析为 <protocols-dir>/<Name>.md；行中的 Body 链接仅为显示文本，绝不可作为读取路径。若匹配的正文缺失或格式错误，则报告并跳过——绝不根据索引中的 Description 重构正文。没有索引或没有匹配项 -> 不应用叠加规则，且无需说明。完整约定：.claude/skills/project-skill-protocol/references/registry.md。

叠加规则只能补充：它们只能在此技能自身协议的基础上添加规则，绝不能替换、覆盖、禁用或重新解释此技能已有的规则——移除所有叠加规则后，此技能必须恢复为与其文档所述完全一致的行为。叠加规则是简要补充，不是权限升级：绝不能豁免工作流关卡、Git 规范、审查关卡或用户确认关卡。若叠加规则与技能之间确实冲突，或两个匹配度相同的叠加规则直接矛盾 -> 向用户指出双方内容；绝不可默默自行裁决。

必须注意：执行前，先为此技能解析项目协议叠加规则——仅采用匹配度最高的层级（精确 > glob > *；此优先级仅用于排列叠加规则彼此之间的优先级，绝不用于确定叠加规则与此技能之间的优先级），只读取 <protocols-dir>/<Name>.md 中匹配的正文；正文缺失或格式错误时必须报告，绝不可重构。叠加规则只能补充（绝不替换此技能自身的规则），且仅为简要补充，绝非权限升级；匹配度相同的规则若彼此矛盾，应交由用户处理。

收尾提醒

**重要，必须注意目标：**交付经过验证、可直接实施的计划——每个阶段都能立即启动（提供确切文件路径、不留未决事项、映射 TC ID）——确保编码工作无需返工，并将未来变更成本降至最低。

生效中的协议（此技能所含 SYNC/共享区块的简要摘要）：

• 计划粒度： 每个阶段都必须通过 5 点检查，或拆分为子计划。
• 保留项清单： Bug 修复计划必须列出不变量，并注明 file:line 和验证方式。
• 嵌套任务创建： 子技能必须展开可见的阶段任务；嵌套时链接到父任务。
• 项目参考文档指南： 开始目标工作前，务必阅读所需的项目文档。
• 任务跟踪与外部报告： 初始化任务；将发现持久化到 plans/reports/。
• 批判性思维： 每项断言都必须有可追溯的证据；置信度 >80% 才能采取行动。
• 顺序思维： 多步骤思考须使用 Thought N/M，并标记 REVISION/BRANCH/HYPOTHESIS。
• 先理解代码： 规划前先阅读代码，并通过 grep 检索至少 3 种模式。
• 跨服务检查： 扫描生产者、消费者、saga 和契约，检查是否存在破坏性风险。
• 估算框架： 按自底向上的方式估算各阶段工时，再推算人日；SP 必须推导得出。
• 计划质量： 每个阶段都必须包含带有 TC ID 的 ## Test Specifications。
• 迭代式阶段质量： 先评估复杂度；分数 ≥6 时进行拆分。
• 修复层级责任： 绝不能在崩溃点修复；应修复不变量的归属层。
• 防止 AI 出错： 根据证据验证生成的内容，追踪下游引用，验证所有受影响的输出，在上下文丢失后重新阅读，并明确指出歧义。
• 并行子 Agent 调度： 为任务标记 PAR/SEQ，将 PAR 任务按互不重叠的写入集分组成多个波次，在一条消息中启动每个波次，并在继续前设置屏障。 重要，务必注意 仅做规划——绝不实现或执行代码；生成 plan.md、各阶段文件和 goal.md 目标契约，然后交接——原因：此技能的约定是制定计划，而不是进行更改。 重要，务必注意 默认模式为 HARD——仅当所有简单任务条件都满足时，才可选择退出并使用 fast mode——原因：对非简单任务跳过严谨流程所造成的返工，远高于严谨流程节省的成本。 强制，重要，务必注意 开始前通过任务跟踪将工作拆分为小型待办任务；添加最终审查待办；上下文丢失时先调用当前任务列表——绝不重复创建任务。 强制，重要，务必注意 调查前先初始化目标契约（根据 goal-contract-template.md 创建 goal.md）；每个阶段的成功标准都必须对应一个已保存的目标标准。对机密信息进行脱敏。 强制，重要，务必注意 直接询问用户以确认决策——绝不因为某项任务看起来“显而易见”就自行决定；下一步由用户决定。 强制，重要，务必注意 每个阶段都必须通过 5 点粒度检查（“我现在能立刻开始编码吗？”）——未通过的阶段必须编写子计划（最大深度为 3）。 强制，重要，务必注意 发现项目中未使用的新技术/库时，按每个库分别进行任务跟踪 → WebSearch 搜索前 3 个结果 → 比较 → 给出带置信度百分比的推荐 → 直接询问用户——原因：未经审查的依赖一旦过早引入，就会成为不可逆的决策。 强制，重要，务必注意 估算必须自底向上——各阶段工时决定 man_days_traditional（Σh/6 × productivity_factor）；SP 仅为派生值，绝不可作为估算依据；UI 成本通常占主导；输出完整的 estimate_reasoning frontmatter。 强制，重要，务必注意 每个阶段都必须包含 ## Test Specifications，并使用 TC-{FEATURE}-{NNN} ID；每项功能需求至少映射到 1 个 TC（或在测试驱动开发优先的情况下明确标注 Evidence: TBD）。 强制，重要，务必注意 对 .claude 技能/钩子/工作流/同步相关工作，计划必须包含生成镜像的同步操作，或明确的无需同步证据——原因：镜像可能在无人察觉时过时并偏离源文件。 强制，重要，务必注意 创建计划后绝不可跳过 $plan-review——单独运行，或将其作为工作流步骤；独立运行 $plan 时，还必须将 $changes-review 追加为最终任务。 重要，务必注意 规划前搜索至少 3 个现有模式并阅读目标代码；引用 file:line；如果存在 .code-graph/graph.db，则运行图追踪——原因：本地惯例优先于通用框架默认设置。 强制，重要，务必注意 按顺序运行完整的主流程——预检计划 → 初始化 goal.md → 一轮研究（在同一条消息中运行 researcher + scout）→ 屏障 → 代码库与项目参考分析（缺少文档时运行 scout）→ planner 编写 plan.md + phase-XX → 并行性检查（PAR/SEQ + 写入集 + ## Execution Waves）→ 粒度自检 → 必须包含最终任务；绝不可因为某一步看起来显而易见就跳过——原因：被跳过的那一步（目标契约、粒度检查、测试规格）正是 AI 会悄然遗漏的步骤。 强制，重要，务必注意 在一轮消息中一次性派发所有研究线程（先声明 Parallel plan:，并为每个 Agent 指定一个报告路径），仅当所有成员都返回后才能综合结果——原因：每次只派发一位研究人员，会让规划中最容易并行的部分变成串行流程。 强制，重要，务必注意 输出的计划必须包含并行性元数据——每个阶段都要标记为 PAR/SEQ，声明其写入集，每个 SEQ 都要命名其等待的确切产物，并在 plan.md 中包含 ## Execution Waves——原因：$plan-execute 只会根据计划中的声明进行分派，因此未标记的计划会悄然强制采用串行执行。 强制，重要，务必注意 将最终任务区块排入每个计划——每阶段的测试规格 → $plan-validate → $plan-review（收敛循环，最多 3 轮；任意一轮通过后即可结束）→ $why-review（仅限独立运行）→ 根据最终阶段重新估算（差异 >50% 时标记 SHOULD-RESCOPE）。 重要，务必注意 --mode={ci|cro} 只会在同一引擎、门控和 planner Agent 基础上，额外加载领域参考（references/mode-ci.md / mode-cro.md）并进行信息收集——不带标志时，默认流程逐字节运行标准流程；绝不可让模式替代引擎或跳过 $plan-review。 反合理化：

推脱理由	反驳
“任务太简单，不必规划”	默认模式为 HARD。只有在所有琐碎条件都满足时，才能选择退出。
“我已经熟悉代码库”	展示来自 3+ 个模式的 file:line，并提供图谱追踪。没有证据 = 没读过。
“阶段已经足够清晰”	进行 5 点粒度检查：“我现在能立刻开始编码吗？”——否则就制定子计划。
“计划看起来不错，跳过审查”	绝不能跳过 $plan-review——新视角能发现作者的盲点。
“只用现有库，跳过关卡”	拿出证据——搜索清单文件。任何新技术/库 → WebSearch，并在批准前直接询问用户。
“我直接估算 SP 就行”	SP 应从自底向上的阶段工时推导得出，绝不能作为估算依据。先计算 Σh/6 × 生产率。
“这是 .claude 变更，不需要同步”	说明镜像操作，或提供明确的不需要同步的证据——过时的镜像无法通过 oracle 检查。
“--mode=ci，所以跳过常规流程”	此模式只会增加一个参考负载——使用相同引擎、相同 $plan-review 和相同 planner Agent。
“计划完成了，跳过最后的任务”	测试规范 → $plan-validate → $plan-review → $why-review → 重新估算，这些都是强制步骤，不是可选项。
“这些阶段看起来是顺序执行的，跳过标签”	“看起来是顺序执行的”不代表存在依赖关系。标注 PAR/SEQ，声明写入集合，并指出每个 SEQ 所等待的产物。
“执行器自己会安排顺序”	不会——$plan-execute 只会根据已声明的写入集合扇出执行。没有标签 = 你导致了顺序执行。

[TASK-PLANNING] 执行前，分析任务范围，并通过任务跟踪系统，将任务系统地拆分成小型待办任务和子任务。

IMPORTANT MUST ATTENTION 仅限规划——绝不实施；引用 file:line 证据（置信度 >80% 才能采取行动）；绝不跳过 $plan-review 和 New Tech/Lib + Goal-Contract 关卡。

---

最后提醒——易于变更才是成功指标。 每项发现、 测试、重构和抽象都必须回答一个问题：这会让 下一次变更更省力，还是更费力？ 如果它不能降低未来的变更成本，就拒绝它。耦合、隐藏状态、重复的知识和意图不明才是真正的敌人——要明确指出它们。

无钩子提示词协议镜像（自动同步）

来源：.claude/.ck.json + .claude/skills/shared/sync-inline-versions.md（:full 块）+ .claude/scripts/lib/hookless-prompt-protocol.cjs

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制要求，重要，必须执行，关键。任何情况下都不得跳过。

**通用可移植性边界：**可复用技能和协议文本应保持项目中立；从 docs/project-config.json 和 docs/project-reference/ 中了解项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。对于规范、测试用例、行为变更、公共契约或 docs/specs/ 相关工作，应通过文档索引中列出的本地规范文档进行：当规范／测试／代码必须保持同步时，使用 feature-spec-reference.md、spec-system-reference.md、spec-principles.md 和 workflow-spec-test-code-cycle-reference.md。如果任一文件或必需的参考文档缺失或过时，则在进行常规项目特定工作之前，自动运行 $project-init（或更精简的底层流程，例如 $project-config、$docs-init、$scan-all 或 $scan --target=<key>）。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. **检测：**如果提示以明确的斜杠技能／工作流命令开头，则直接执行。否则，根据工作流目录和技能列表匹配提示。
2. **分析：**选择最佳方案：直接执行、调用技能、启动标准工作流，或组合自定义步骤。
3. **自动选择：**自行选择最佳方案。不要让用户在直接执行、技能、标准工作流或自定义工作流之间做选择。
4. **启动：**对于选定的工作流，调用 $start-workflow <workflowId>；对于选定的技能，调用该技能；对于自定义工作流，直接按顺序执行自定义步骤；对于直接执行，继续处理任务。
5. **创建任务：**如果选定路径包含多个步骤，则在执行前为所有工作流／技能／自定义步骤创建任务跟踪。
6. **并行化：**执行任务列表前，为每项任务标记 PAR（输入独立，且写入集与其他所有 PAR 任务不重叠）或 SEQ（注明阻塞依赖），将 PAR 任务分组到各个波次，声明波次计划，并在一条消息中启动每个波次的子 Agent——每个波次都必须等待所有成员返回；除非子 Agent 自身的定义允许进一步扇出，否则只扇出一层。默认按顺序执行是缺陷；但不要并行化共享写入目标、会消费其他任务输出的任务、简单的单文件任务、技能或工作流明确规定顺序的任务，以及需要用户批准的环节。
7. **执行：**按照上下文指令中的 Workflow Step Advancement & Parallel Phases 规则推进——由模型驱动；子 Agent 完成与内联调用一样会推进步骤；并行阶段组必须等待所有成员返回（只有所有成员都返回后才能推进，绝不能串行执行）

共享 AI-SDD 协议标记

来源：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 工件契约 — 共享的规范驱动开发规则应保持可移植，并由源文件管理。

1. 将可复用的 AI-SDD 原则保存在 .claude 中；将特定于仓库的路径、命令、负责人、产品和格式放在项目配置／参考文档中。
2. 保持以下周期：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. 通过决策、任务、TC／测试、源证据以及文档／规范更新，追踪每项要求或不变量。
4. 将从代码提取规范的内容仅视为参考，直到规范的权威负责人接受为止。
5. 任何受支持的 AI 工具都可基于同步的上下文进行规划、实现、审查或验证；使用多个工具是可选的。
6. 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。— 原因：镜像是生成的工件；下次同步时，手动修改会被覆盖
7. 如果 docs/project-config.json、根目录指令文件或必需的项目参考文档缺失或过时，则在进行常规项目特定工作之前，自动运行 $project-init 或范围更窄的底层流程。

当前参考文档： 当前技能根目录中的 shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• MANDATORY 应用 shared/sdd-artifact-contract.md；将可复用的 AI-SDD 保存在 .claude 中，并将本地规则保存在项目文档中。
• MANDATORY 从代码提取的规范仅供参考，直到权威规范获批；任何受支持的 AI 工具都可基于同步的上下文执行工作。
• MANDATORY 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。
• MANDATORY 如果项目配置、根目录指令文件或必需的参考文档缺失或过时，则应自动通过 $project-init 或范围更窄的设置流程来处理项目特定工作。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；之后随着各步骤开始／完成，持续同步更新任务跟踪。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — MANDATORY。不得跳过。

开始前将工作拆分为小任务（任务跟踪）。添加最终任务：“分析 AI 错误与经验教训”。

提取经验教训——仅关注根本原因，而非修复表象：

1. 指明失败模式（推理／假设失误），而非表面症状——“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，则再向上抽象一层。
3. 写成通用规则——去除特定于项目的名称／路径／类。规则应适用于任何代码库。
4. 合并：多个错误若属于同一种失败模式，则合并为一条经验教训。
5. 复发门槛：“如果没有这条提醒，未来会话中是否会再次出现此问题？”——不会 → 跳过 $learn。
6. 自动修复门槛：“$code-review／$code-simplifier／$security-review／$lint 能否发现此问题？”——能 → 改进审查技能。
7. 两个门槛都通过 → 请用户运行 $learn。 [CRITICAL-THINKING-MINDSET] 运用批判性思维和序贯思维。每项断言都需要可追溯的证据；采取行动前，置信度须 >80%。 **反幻觉原则：**绝不将猜测当作事实——为每项断言引用来源，坦诚承认不确定性，自行检查输出错误，独立交叉核对，并对自己的信心保持怀疑——缺乏证据的确信是所有幻觉的根源。 **AI 注意力原则（首因－近因效应）：**在较长提示词／协议的开头和结尾都放置最关键的 3 条规则，以确保指令在较长的上下文窗口中仍能得到遵循。 **目标驱动执行：**先定义成功标准，持续循环直至验证完成；仅当可观察的检查均通过后才停止。 **测试验证意图：**测试必须保护业务规则／不变量，并在受保护的意图遭到破坏时失败，而不只是复现当前行为。

常见 AI 错误预防（系统经验）

• 上下文压缩后重新读取文件。 编辑前必须在同一上下文中先读取文件；上下文压缩会清除读取状态。编辑前重新读取。
• 批量替换后 grep 旧术语。 AI 过度相信查找/替换已覆盖所有内容。批量编辑后，对整个仓库执行 grep，检查文档/配置/目录中遗漏的引用。
• 删除前检查下游引用。 删除会连带导致文档/代码过时。移除前先梳理引用文件。
• 丢失记忆后，创建新内容前先检查现有状态。 上下文压缩会清除先前工作的记忆。查询当前状态以便继续——绝不要盲目重复创建。
• 根据实际代码验证 AI 生成的内容。 AI 会幻觉出 API、类名和方法签名。记录/引用前先用 grep 确认其确实存在。
• 编辑后追踪完整依赖链。 更改定义却漏掉下游使用方。追踪完整链路。
• 重命名时，对所有使用方文件类型执行 grep。 某些文件类型会静默忽略缺失的引用（不会产生编译错误）。搜索代码、模板、配置和生成文件。
• 验证正确性时追踪所有代码路径。 代码存在 ≠ 代码会执行。追踪提前退出、错误分支和条件跳过——不要只看正常路径。
• 源数据变更时，更新包含规范数据的文档。 内嵌派生数据（工作流、架构、配置）的文档会静默过时。源数据变更时，同时更新所有内嵌该数据的文档。
• 恢复上下文后验证子 Agent 的结果。 父 Agent 压缩上下文期间，后台 Agent 可能已经完成——用 grep 验证输出，不要相信对任务已完成的假设。
• 将完整目标列表与子 Agent 的分配任务交叉核对。 按类别并行分配子 Agent 会漏掉边界项。继续前，将各分配任务的并集与目标列表核对。
• 子 Agent 只能从其 Agent 的 .md 定义继承知识——使用自定义 Agent 类型，不要使用内置 Explore。 采用工具 = 权限 + 知识 + 执行（编号工作流步骤）。
• 逐步记录子 Agent 的发现，不要等最后一次性提交。 长时间运行的子 Agent 可能在最终写入前达到截断限制——导致发现丢失。指示其按章节追加到报告文件。
• 调试时，修复前先问“责任在谁？” 追踪调用方（数据错误）还是被调用方（处理错误）。在责任层修复——绝不要只修补症状出现的位置。
• 测试失败 → 先记录暂定结论，再追踪/编辑，然后调查。 使用完整的五类分类：SOURCE-WRONG（生产代码违背意图）、TEST-WRONG（断言/设置已过时）、TEST-NOT-OPTIMAL（测试有效但脆弱或信号弱）、ENVIRONMENT-BLOCKED（外部状态阻止得出结论），或 AMBIGUOUS（意图/证据不足以安全判断）。然后追踪根因，并对照规范依据（如果存在，查看 docs/specs/**）和源代码进行交叉验证。绝不要只为让测试变绿而削弱断言、添加跳过、放宽超时或更改源代码。
• 提取/重构后，对所有已移除名称执行 grep。 主文件“完成” ≠ 次要文件干净。宣布完成前，在整个范围内搜索每个已移除的符号。
• 假定现有值是有意设定的——更改或将其标记为缺陷前先问为什么。 仅凭模式匹配判定“错误”会忽略上下文。更改或报告任何常量/限制/标志/阈值前：阅读注释、git blame、调用方的执行顺序（使该值正确的保证通常位于引用行之前紧邻执行的代码中），以及同一惯例下至少 2 个同类调用点。只说明“是什么”却不说明“为什么”的文档，缺少的是依据，并不能证明缺少保护措施；在验证环节中，准确的 file:line 引用证明的是转录无误，而不是缺陷确实存在。
• 验证所有受影响的输出，而不只是第一个。 一个构建成功 ≠ 全部成功。涉及多个技术栈的变更（后端/前端/测试/文档）要求验证每一项输出。
• 复制相近模式前，先评估是否适用。 最接近的示例 ≠ 前提相同——确认新上下文具有相同的约束、基类、作用域和生命周期。
• 整体优先的调试方式——抵制注意力就近陷阱。 不要一头扎进第一个看似合理的原因。列出所有前提（配置、环境变量、路径、数据库、端点、凭据、版本、DI、数据）。用证据（grep/查询——而非推理）逐项验证。问“什么证据可以推翻这个假设？”——如果没有，那就不是假设。代价最高的失败：在“显而易见”的层继续深挖，而 Bug 实际位于从未质疑过的层。
• 精准修改——应用 diff 测试（结合上下文判断）。 两种模式：（1）Bug 修复 → 每一行都能追溯到该 Bug；不做样式调整；只清理因你的修改而变得未使用的孤立内容。（2）审查/增强 → 实施改进，并声明为“超出主要请求的增强：[内容]”。绝不要悄悄扩大范围。Diff 测试：“如果我没有被要求做 X，这一行还会存在吗？”——如果不会，就删除或明确说明。
• 编码前先指出歧义——不要默默自行选择。 存在多种有效解释时，逐一列出并说明工作量：“[请求] 可能指 (1) [N 小时]、(2) [N 小时]。哪一个更重要？”先列出范围/格式/数量/约束方面的假设。如果有更简单的方案，也要说明。绝不要默默自行选择。
• [MANDATORY FIRST ACTION] 回复前务必先启用合适的技能或工作流。 将任务与工作流目录和技能列表进行匹配；通过技能调用或 $start-workflow <workflowId> 启用。检查之前绝不要回答或编写代码。跳过 = 违反协议。
• Why-Review 对抗性思维——审查任何计划、决策或设计时都要运用。 默认持怀疑态度，而非验证者态度：充分论证被否决的替代方案，将每项既定理由反向审视（“它牺牲了什么？”），对最重要的 2-3 项假设进行压力测试，开展事前验尸（“已发布，3 个月后失败——什么会出问题？”），并指出作者遗漏的 1-2 种替代方案。章节齐全 ≠ 质量过关；质量取决于因果推理、具体缓解措施和证据，而不是“这样更好”或“密切关注”。
• 大型审查的子 Agent 提示词应优先安排报告写入。 处理许多文件的子 Agent 可能在最终写入前耗尽预算——导致发现丢失。设计提示词时应确保：（1）报告写入是第一个明确的交付项，（2）按文件/章节逐项追加（不要批量写入），（3）限定范围，避免读取耗尽预算。若输出在句中被截断且没有报告文件 → 启动范围更窄的任务，不要原样重试相同提示词。
• 上下文压缩后，继续前重新验证此前各阶段的所有结果。 摘要描述的是意图，不是环境状态（git 索引、文件系统、进程）。恢复时，首先审查：git status、重新读取修改过的文件、验证文件系统。每一项“已完成”的声明，在证据确认前都是未经验证的假设。
• OOM/内存：先检查行数，再检查行大小。 排查顺序：（1）无界查询——触发条件是否没有数据库筛选？将筛选推到数据库端；这可消除 OOM。（2）行是否很大？投影可按比例减少数据量。减少行数比投影的收益更大。
• 断言系统自身负责的结果，绝不要断言基础设施负责的中间状态。 测试任何异步行为（队列/代理传递、重试、后台任务、缓存、复制）时，应断言最终业务/实体状态。绝不要断言传递记录——消费/发送状态、尝试次数、最后错误、代理、调度程序或 outbox/inbox 表中的行存在与否或数量。这些记录属于共享基础设施，任何同时运行的进程（同伴 Worker、第二个副本、遗留的本地容器）都可能写入，且通常使用确定性的共享键；因此，断言会悄悄测试开发者的环境，而不是系统：单独运行时通过，一旦有其他进程共享该代理和数据库就会不稳定。每个断言都要问：“无论哪个进程执行了这项工作，该断言都会成立吗？”——如果不会，就改为断言已收敛的数据状态。推论：进程本地的故障注入和进程内遥测不能用于控制任何进程都可能执行的工作——将它们用作压力放大器（启用 → 限定时间窗口 → 停用 → 断言收敛），绝不要用作前置条件。
• 不要让领域概念进入通用/共享/基础设施层。 可复用层（共享库、框架、基础设施模块）不得引用任何特定使用方的领域概念——租户/客户/产品 ID、业务实体、功能规则。泄漏进来后，代码能够编译并运行，因此会悄无声息地通过审查，同时让“可复用”层与某个使用方耦合。保持共享类型与领域无关；通过子类/组合将领域字段/逻辑下放到使用方。——原因：与某个使用方的领域耦合的层不再可复用。