plan-review

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/ 下的源 Feature 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] 如果任务工具不可用，请创建并维护等效的逐步计划跟踪，并使用相同的状态转换。

快速摘要

目标： 通过自动审查实施计划的有效性、正确性和最佳实践，阻止任何计划在达到无幻觉（每项关于现有代码的声明都有 file:line 证据）且可直接实施（每个步骤都具体明确、小到可以立即据此编码）的标准前进入实施阶段。递归流程： 只要存在任何发现，就使用 $why-review --validate-findings 验证这些发现，只修复计划文件中已验证的发现，然后重新运行完整计划审查，直到本轮的退出门槛达标——第 1–2 轮必须零发现；从第 3 轮起，必须没有 CRITICAL/HIGH/MEDIUM 级发现（如果一轮只剩 LOW 级发现，则循环结束，不予修复）。

每个阶段的审查都将 Mode、Wave、写入集和 SEQ 依赖关系视为不可拆分的元数据契约；任何字段不匹配都会阻止批准。

摘要： AI 自审查（自动执行，并非像 $plan-validate 那样访谈用户），用于在实施前把关计划。

• 目的： 以怀疑者的视角审查，而不是充当验证者——每项关于现有代码的声明都需要 file:line 证据（反幻觉门槛）；每个阶段都必须达到“详细且足够小”的粒度门槛（≤5 个文件、≤3 小时、不含规划类动词）——过于模糊就补充细节，规模过大就拆分。
• 主要步骤（按顺序执行）： 第 0 阶段检测计划类型 → 第 1 步读取 plan.md、goal.md 和所有 phase-*.md，提取需求、步骤、文件和风险 → 第 2 步评估 4 组检查清单：有效性（摘要、需求、步骤、文件）· 正确性（粒度门槛 + 反幻觉/代码证据门槛 + 规格/TC 覆盖情况 + 目标契约映射）· 最佳实践（YAGNI/KISS/DRY/架构）· 完整性（风险、测试、成功标准、安全性、图依赖关系）→ 运行 11 项对抗性技术 + 反偏见门槛 + 8 个计划维度 → 对每个修改过的文件进行图追踪（存在 graph.db 时）→ 第 3 步评定 PASS/WARN/FAIL → 第 4 步输出结果 → 第 5 步执行递归的验证-修复-重新审查循环。
• 务必先检测计划类型（第 0 阶段），以应用正确的审查重点——bugfix 必须包含行为差异矩阵；security/performance/refactor/contract/infra/data-schema 各自会增加针对性检查。
• 绝不盲目修复发现： 在编辑任何 plan.md/phase-*.md 之前，先通过 $why-review --validate-findings 门槛；仅在最小且责任明确的位置修复已验证的发现，然后使用全新的、零记忆子 Agent 重新开始完整审查——持续循环，直到通过本轮门槛。
• 严重性门槛——从第 3 轮起，LOW 不再阻止通过。 第 1–2 轮要求所有严重级别的发现都为零。从第 3 轮起，门槛为：已验证的 CRITICAL/HIGH/MEDIUM 级发现为零——如果某轮已验证的发现全部为 LOW，则循环结束。 不要仅因 LOW 级发现就重新开始完整审查：在报告的 ## Deferred LOW Findings (severity floor, round ≥3) 下记录这些发现，并判定为 PASS。绝不要为了达到退出条件而将实际的 CRITICAL/HIGH/MEDIUM 级发现降为 LOW；也绝不要将该门槛用于代码幻觉声明或缺少证据的发现——根据定义，这些属于 HIGH，不能作为 LOW 延后处理。严重性级别遵循 SYNC:severity-rubric。
• 最多 3 轮——这是上限，绝非目标； 任何一轮通过审查，都应立即结束循环（包括第 1 轮）。如果同一阻碍在连续 2 次完整重新审查后仍未解决且毫无进展、第 3 轮结束时仍有未解决的发现，或某项发现需要产品/负责人的判断，则直接升级并询问用户——达到轮数上限应升级处理，绝不能据此判定为 PASS。

工作流：

1. 解析计划 — 使用 $ARGUMENTS 路径或 ## Plan Context 中的活动计划
2. 读取文件 — 读取 plan.md 和所有 phase-*.md 文件，提取需求、步骤、文件和风险
3. 评估检查清单 — 有效性（摘要、需求、步骤、文件）、正确性（具体、路径、无冲突）、最佳实践（YAGNI/KISS/DRY、架构）、完整性（风险、测试、成功标准、安全性）
4. 评分与分类 — PASS（所有 Required 均通过，且 ≥50% Recommended 通过）、WARN（所有 Required 均通过，且 <50% Recommended 通过）、FAIL（任意 Required 未通过）
5. 输出结果 — 状态、通过的检查、问题、建议、结论
6. 如仍有任何发现 — 先对计划审查报告运行 $why-review --validate-findings；只修复经过验证且可采取行动的问题，然后重新审查（回到步骤 2 循环，直到达到本轮标准：第 1–2 轮为零发现，第 3 轮起无 CRITICAL/HIGH/MEDIUM，除非触发重复阻塞规则或达到 3 轮上限）

核心原则 — 详细且规模适当：

• 太含糊？ → 补充细节：添加具体文件路径、明确的操作、准确的方法名
• 太大而无法细化？ → 拆分：分成更小的阶段/子计划，直到每个计划都足够详细
• 无法直接据此开始编码的计划尚未就绪。每个步骤都必须可直接实施。

关键规则：

• 不得臆造：计划中关于现有源代码的每项断言，都必须有 file:line 作为证据——未经验证的路径、类名或行为 = FAIL
• PASS：继续实施
• WARN：谨慎继续，并注明缺漏
• FAIL（存在任何发现）：使用 $why-review --validate-findings 验证发现，只修复经过验证的计划问题，然后从头重新运行完整审查。重复此自循环——不设最低轮数，最多 3 轮——直到完整审查得出零发现。
• 有界循环 — 两个升级触发条件，均非完成标准：(a) 无进展保护 — 同一阻塞问题在连续 2 次完整重新审查中仍未解决，且毫无进展；(b) 轮数上限 — 第 3 轮结束时仍有未解决的发现。无论哪个条件先触发 → 停止并直接向用户升级，询问用户，绝不可默默给出“差不多就行”的 PASS。若审查通过，立即结束循环，即使是在第 1 轮——上限是上限，不是配额。
• 注重建设性：聚焦阻碍实施的问题，而非吹毛求疵的细节

保持怀疑。运用批判性思维和顺序思维。每项断言都需要可追溯的证据和置信度百分比（Idea 应高于 80%）。

第一原则 — 易于变更

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

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

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

在应用下方的任何规则、模式或检查清单之前，先用这一视角审视——任何会提高变更成本的后续规则，都必须让位于此原则。

---

对抗性审查思维（不可妥协）

默认立场：怀疑，而非验证。你的任务是找出行不通之处，而不是确认看起来正确的内容。

**确认偏误陷阱：**读完结构良好的计划后，AI 很容易自然地找出赞同它的理由。本节旨在打破这种循环，避免最终沦为走过场的批准。

对抗性技巧（下结论前全部应用）

技巧 1–6 检验计划能否落地（现实情况、工作量、范围、依赖项）。技巧 7–10 检验所选设计是否正确——这是与 $why-review 的理由审查共用的决策质量视角。两组都要应用：建立在错误决策上的可执行计划，依然是失败的计划。

1. 实施现实检验 逐个阶段问：“开发者现在就开始实施，最先会在哪里出问题？” 具体梳理关键路径。若某个阶段含糊不清（例如“实现服务层”），无法追溯到具体文件／类，则判定为失败。

2. 假设压力测试 列出最重要的 3 个隐含假设；逐一问：“如果这个假设不成立呢？” 有效的计划在 3 个假设中有 2 个不成立时仍能成立。常见的隐藏假设包括：现有代码状态明确 · 外部 API 不会变更 · 团队已具备该领域的知识。

3. 工作量现实检验 对每个估算阶段问：“这份代码库里类似的工作是否曾在这个时间内交付？上次有哪些因素拖慢了进度？” 低估 2 倍或更多时，这只是乐观猜测，不能算有效计划。

4. 事前验尸 假设计划已完全按原样交付，功能也已在生产环境运行一个月。写出一个具体且合理的失败场景。若想不出任何场景，说明你还没有深入审视。

5. 范围蔓延检测器 标记任何非交付所述功能所直接必需的任务。“既然都做了，我们顺便重构一下 X”就是范围蔓延。

6. 依赖盲点 列出计划假定稳定的 2–3 个外部依赖项（服务、API、数据源）；逐一问：“如果它发生变更或不可用，这里会出什么问题？” 未在任何地方处理的依赖项故障，就是风险缺口。

7. 为被否决的方案作最强辩护 针对每个选择 X 而非其他方案的设计决策，尽可能有力地论证被否决方案的优势。资深该领域 10 年的人会选它吗？如果会，否决它就需要比“我们选了 X”更有力的证据——原因是：从未说明放弃了什么的决策，只是默认接受，并非真正做出的选择。

8. 为什么不选别的？ 对于每个“因为 Y 而选择 X”，都要问 X _牺牲_了什么。只列优点的计划是在掩盖取舍，并非避免取舍。要求明确写出缺点。

9. 未考虑的替代方案 指出计划从未提及的 1–2 个可行方案。若未提及某个方案，也没有说明为何排除，则说明覆盖不足，并非已作出定论。

10. 优缺点对称性 统计所选方案陈述的优点与缺点数量。优点超过缺点 2:1 以上，说明可能存在确认偏误——在接受之前，要求补充遗漏的缺点。

11. 反方审查 在给出任何结论之前，先写至少 2 句话论证相反意见。准备判定为通过时，就先论证需要改进，反之亦然。然后根据证据选择更有力的论点。

禁止的模式

• “结构看起来不错” → 结构不等于质量。能否实施？
• “阶段定义得很清楚” → 有阶段不代表计划正确。阶段里具体包含什么？
• “已考虑替代方案” → 它们是真正的替代方案，还是被塑造成必然失败的稻草人？
• “风险已得到管理” → “密切监控”不算缓解措施。具体采取什么行动、由谁执行、由什么触发？
• 未梳理关键路径就说**“看起来可行”** → 这不是有效评估。

反偏见关卡（定稿前必须完成）

写出最终结论前，必须完成所有检查（务必注意）：

• 对风险最高的阶段进行实现现实性检查
• 找出 3 个隐含假设并进行压力测试
• 根据代码库复杂度核对工作量估算
• 进行预演分析（设想一个具体的生产环境故障场景）
• 检查是否存在范围蔓延（即超出所述功能要求的任务）
• 确认已排查依赖盲点
• 为至少一种被否决的设计方案提出最有力的论据（支持它）
• 指出计划未提及的至少 1 种可行替代方案
• 检查计划主要设计决策的优缺点是否均衡

若有任何检查未完成，就说明你尚未完成对抗性审查。请返回继续检查。

**Why-review 关系：**技巧 7-10 加上这些关卡检查，是在审查过程中应用的 理由 视角（计划的设计是否经得起检验？）。独立的 $why-review --validate-findings 关卡则在已有发现之后运行（这些发现本身是否正确，能否据此修复？）。两者都要保留——它们验证的是不同内容，不得合并。

计划维度思考框架

完成计划类型检测（阶段 0）后，按照以下推理模式评估下列每个维度：

针对每个维度：（1）理解它在计划所属领域中的作用，（2）阅读计划对此的描述，（3）从基本原理推导实际风险——如果此维度薄弱，可能会出什么问题？（4）结合你对计划技术栈的了解，找出特定于该技术栈的缺口。

维度 1：范围完整性

**思考：**计划范围是否与既定目标完全一致——既不扩大，也不缩小？

• 实现既定目标所需的最小改动是什么？
• 计划添加了哪些目标中没有的内容？→ 范围蔓延。
• 目标中有哪些内容未被计划覆盖？→ 范围缺口。
• 压力测试：“如果跳过阶段 X，功能仍然可用吗？”→ 如果可用，该阶段就不在范围内。

维度 2：数据流正确性

**思考：**我能否追踪数据在计划每个阶段中的流转？

• 数据从哪里产生？最终到达哪里？
• 中间有哪些转换？计划是否说明了这些转换？
• 数据经过系统边界（API、消息总线、存储、UI）时会发生什么？计划是否覆盖了每个边界？
• 哪些数据状态无效？计划是否对此设防？

维度 3：依赖链完整性

**思考：**计划是否考虑到了变更会影响的一切？

• 计划涉及的每个文件或模块：哪些内容导入它？哪些内容调用它？有哪些内容依赖它的契约？
• 如果计划更改接口或契约，是否列出了所有使用方？
• 外部依赖（第三方服务、共享基础设施）是否稳定？如果它们发生故障，有什么回退方案？
• 如果存在 graph.db，则运行图追踪——将计划中的文件列表与下游影响进行比较。

维度 4：故障模式覆盖

**思考：**计划对出错时的处理有何说明？

• 对于每个外部调用、异步操作或状态变更，发生错误时如何处理？
• 对于不可逆操作，计划是否包含回滚策略？
• 部分失败时会是什么状态？（迁移或部署只完成一半、发生竞态条件）是否有解决办法？
• 新代码路径是否有监控和告警计划？

维度 5：测试可观测性

**思考：**开发者如何判断此计划的实现是否正确？

• 声明的验收标准能否通过测试进行机械验证？
• 是否存在只能通过日志／追踪（而非单元测试）观察到的行为？
• 哪个阶段会引入风险？该阶段是否有对应测试？
• “测试通过”不是成功标准——请明确指出测试的具体行为。
• Spec-Loop 排期（测试质量门禁）。计划 MUST 安排 spec-loop，而不只是“添加测试”：(1) 每条 [HARD] §4 规则／§5 不变量都要配套一个全称量化的属性测试规范和一个边界反例——不能只有示例测试；(2) 更改后的核心逻辑必须通过变异分数质量门槛（存活的变异体 = 缺失的不变量 ⇒ 必须补上能杀死该变异体的测试），而非设定行覆盖率 % 目标；(3) 必须有双重反馈 + 重新审查步骤，确保每个改变行为的发现都同时完善规范和测试，并重新审查该软件包，直至不再发现新缺口。若计划设定的是行覆盖率 % 而非变异分数门槛，或未为其 [HARD]／§5 规则编写属性／不变量测试规范，则判定为 FAIL。

维度 6：知识前提

**思考：**实现此计划是否需要计划中未明确说明的知识？

• 领域知识：业务规则是否已明确说明，还是要求实施者事先了解？
• 系统知识：是否记录了集成点，还是要求实施者掌握内部经验？
• 工具知识：计划是否假定存在未列出的设置步骤？
• 如果有任何前提未说明 → 此计划尚未达到可供实施的状态。

维度 7：估算偏差

**思考：**前置元数据中的估算是否仍与最终计划相符，还是范围锁定改变了成本？

• 完成前的估算基于粗略的范围猜测；最终确定的阶段则揭示实际成本。根据各阶段文件中已锁定的任务／TC，重新推导 bottom_up_hours = Σ phase_hours，并与当前前置元数据中的 man_days_traditional／story_points 进行比较。
• 根据 SYNC:estimation-framework 重新计算 likely_days、risk_margin_pct 和 min-max range。未解决因素是否已经消除（风险余量应降低），或是否出现了新风险（风险余量应提高）？
• 若 |delta| > 20% → 必须更新前置元数据，加入 reestimate_delta_pct: <signed> + 一行 reestimate_reason。未更新 = FAIL。
• 若 |delta| > 50% → 在审查结论中标记 SHOULD-RESCOPE；实施开始前，计划必须向用户说明范围调整决定。
• 留意隐藏的成本膨胀：规划期间新增的阶段、原估算未计入的 TC，以及后期才发现的集成工作。

维度 8：领域实体设计（条件触发——计划涉及实体、值对象或聚合时）

**思考：**计划是否真的确定了领域模型，还是把难题留给实现阶段？

应用 SYNC:domain-entity-change-gate（下方内联）——这是 $plan 编写计划时遵循、$changes-review 审查计划时也会遵循的同一协议，其 A–P 检查清单由 $domain-entities-review 负责。若未触发，请注明 No domain-entity surface — Dimension 8 N/A。

• 未回答、含糊带过或推迟到实现阶段的决策点属于 FINDING，并须标注计划中的 file:line。任务中出现“实体”一词，绝不算作回答。
• 对于任何实体任务，MUST ATTENTION 核实计划是否说明了范式和子领域适配性——计划若为 CRUD 子领域提出丰富的领域模型，则属于 FINDING（没有不变量需要保护，却徒增形式）；若计划要在不可变模型或事件溯源模型上实施 setter/封装任务，也同样属于 FINDING。
• 检查每个触发的检查项是否都指明了归属文件，而非只说明意图：分类 · 不变量的归属与失败信号 · 聚合边界与并发 · 构造与重建 · 事件 · 属性测试义务。
• 最值得优先排查的遗漏：按 UI 屏幕或数据库表而非真正的不变量划定聚合边界 · 将跨聚合引用规划为对象导航 · 有争用的聚合根未设置并发令牌 · 集合性不变量（如“邮箱唯一”）没有强制执行机制 · 将不变量规划到验证器/处理程序而非实体中 · 规划事件却未说明分发时机。
• 指出问题前，先为计划的边界选择提出最有力的论据——若有意采用更大的聚合来保护确实需要始终保持一致的不变量，这是正确的；应要求说明不变量，而非要求缩小边界。

使用以下维度生成有针对性、以证据为依据的问题——不要提出泛泛的“补充更多细节”建议。

---

你的任务

自我审查实现计划——检查其是否有效、正确并符合最佳实践，并找出所有需要修复的问题，确保在继续实现之前解决。

**关键区别：**这是 AI 自我审查（自动进行），不是像 $plan-validate 那样的用户访谈。

计划解析

1. 已提供 $ARGUMENTS → 使用该路径
2. 否则，检查 ## Plan Context 部分 → 使用当前计划路径
3. 未找到计划 → 报错："No plan to review. Run $plan first."

工作流

阶段 0：识别计划类型

在查看任何清单之前，先阅读 plan.md 并对计划进行分类——原因：类型决定了子 Agent、关注重点，以及是否必须使用行为差异矩阵：

计划中的信号	类型	额外审核重点
标题或描述中包含“fix”“bug”“regression”或“defect”	Bug 修复	行为差异矩阵（必须）、保留项清单、回归测试
“migrate”“schema”“database”或“index”	数据/架构	回滚路径、零停机策略、数据保留、迁移幂等性
“auth”“permission”“security”“encrypt”“token”或“RBAC”	安全	威胁建模、攻击面、信任边界变更、子 Agent：security-auditor
“performance”“latency”“cache”“N+1”或“throughput”	性能	基准指标、回归风险、测量策略、子 Agent：performance-optimizer
“refactor”“extract”“rename”或“restructure”	重构	行为保留、影响范围、悬空引用
“API”“contract”“endpoint”“consumer”或“event”	契约/集成	向后兼容性、对使用方的影响、版本策略
“infra”“CI”“pipeline”或“deploy”	基础设施/DevOps	回滚计划、环境一致性、机密处理
以上都不符合	功能	标准清单、验收标准映射、YAGNI

如果匹配多个信号，列出所有类型并应用其全部关注重点。

计划类型决定：

• 使用哪种子 Agent 类型（参见上文“子 Agent 类型选择”）
• 重点关注对抗式审核思维中的哪些部分
• 是否必须使用行为差异矩阵（仅 Bug 修复需要）

---

步骤 1：读取计划文件

读取计划目录：

• plan.md - 概述、阶段列表、frontmatter
• goal.md - 目标契约（如存在）：原始请求、目的、成功标准（必需与可选）、约束
• phase-*.md - 所有阶段文件
• 提取：需求、实施步骤、文件列表、风险

如果缺少 {plan-dir}/goal.md，则查找 plans/goals/{YYMMDD-HHmm}-{slug}/goal.md；如果完全不存在目标契约，则记录 No active goal — plan reviewed against plan.md requirements only.。

步骤 2：根据清单进行评估

有效性（必需 — 以下各项必须全部通过）

#	检查项	存在性	质量深度
1	包含执行摘要 — 清晰的 1–2 句话描述	是否存在摘要部分？	是否准确？是否界定了工作范围，或掩盖了复杂性？
2	包含明确的需求部分 — 列出明确需求	是否存在需求部分？	需求是具体的用户需求，还是模糊的技术目标？
3	包含实施步骤 — 可执行的任务	是否列出了实施步骤？	步骤是否具体（文件名、方法名），还是模糊的行动？
4	列出要创建／修改的文件 — 提供文件清单	是否存在文件清单？	文件路径是否真实（通过 glob/grep 验证）？是否遵循项目惯例？

正确性（必需 — 以下各项必须全部通过）

• 粒度门槛 —“详细且足够小” — 如果任一阶段未通过以下任一标准，则判定为失败。无法立即据此编写代码的计划尚未就绪。

决策树 — 对每个阶段应用：

Phase too vague? (no file paths, planning verbs, unclear actions)
  → YES → DETAIL IT: add specific file paths, exact method names, concrete actions
  → NO ↓
Phase too big? (>5 files OR >3h effort OR single step is a mini-project)
  → YES → BREAK IT: split into smaller sibling phases until each meets limits
  → NO → PASS this phase

5 项标准（每个阶段都必须全部通过）：

#	标准	通过示例	未通过示例
1	步骤注明具体文件	“修改 {source-root}/auth/login”	“实现身份验证”
2	不包含规划动词	“添加 validateToken() 方法”	“确定最佳身份验证方案”
3	每个步骤耗时 ≤30 分钟	“为端点添加错误处理程序”	“构建整个身份验证模块”
4	每个阶段 ≤5 个文件且 ≤3 小时	3 个文件，2 小时	12 个文件，8 小时
5	不存在未解决的决策	所有方案均已确定	“待定：使用哪个库”

会触发失败的规划动词：“研究”“确定”“弄清楚”“决定”“评估”“探索”“调查”——这些应属于调查阶段，而非实施计划。

失败时的处理（Findings Validation Gate 通过后）：

在 $why-review --validate-findings 针对当前计划审查报告返回 CLEAN 之前，不要应用这些优化。

• 过于模糊 → 就地细化：补充步骤中的文件路径、方法名和具体操作
• 规模过大（≤9 个文件） → 将阶段拆分为同级阶段（Phase 2A、2B、2C）
• 规模过大（10 个及以上文件） → 创建子计划：{plan-dir}/sub-plans/phase-{XX}-{name}/plan.md

示例： 未通过："Phase 2: Data Layer — Set up database models, Create repositories, Implement data access patterns. Effort: 4h, Files: ~8" 拆分后通过："Phase 2A: Data Schema (1h, 3 files) — Create {source-root}/models/user-entity, Create {source-root}/models/session-entity, Create {migration-root}/create-users-sessions" + "Phase 2B: Repository Layer (1.5h, 3 files) — Create {source-root}/repositories/user-repository, Create {source-root}/repositories/session-repository, Register in {composition-root}"

• 文件路径遵循项目模式
• 不存在冲突或重复的步骤
• 步骤间的依赖关系清晰
• 防幻觉与代码证据门槛 — 如果计划中关于现有源代码的任何声明缺少 file:line 证据，则判定为失败。 | 声明类型 | 所需证明 | | ---------------------- | --------------------------------- | | 文件路径 | 文件存在（glob/read） | | 类/方法名称 | 符号 grep → file:line | | 行为（“X 调用 Y”） | 代码证据 file:line | | 基类/接口 | 已验证继承关系（grep/graph） |

触发 FAIL 的情况： 未读取的文件路径、未通过 grep 查证的方法名称、使用“应该是”“可能”“通常”等措辞描述现有代码，或根据类似项目而非当前代码库推定行为。仅针对全新项目的计划（没有现有代码引用）→ PASS。

• 新技术/库门槛： 如果计划引入项目中尚未使用的新软件包/库/框架，需确认已评估替代方案（比较排名前 3 的方案），并且用户已确认选择。未经过评估就添加新技术则 FAIL。
• 测试规范覆盖 — 每个阶段都包含 ## Test Specifications 部分，并列出 TC 映射。TDD 优先模式下，“TBD”有效。
• TC-需求映射 — 每项功能需求至少映射到 1 个 TC（或明确标记为“TBD”并说明理由）
• 行为保留 — 变更行为的阶段需说明预期行为、需保留的不变行为，以及 TC/测试证明。
• 文档/规范/测试同步 — 相关阶段需包含规范文档/文档/测试的权威来源更新，或提供明确的 N/A 证据。
• 产物时效性 — AI 提取的规范/TC 在获准前须标记为仅供参考；涉及共享工作流/技能/工具变更时，需包含生成镜像同步。
• Goal Contract 映射 — 存在有效 goal.md 时：每项已保存的必需成功标准都至少由 1 个阶段覆盖，且各阶段的成功标准都能追溯到已保存的标准（或标记为支持性工作并说明原因）。如果某项已保存的必需标准没有对应阶段，或计划交付了 Goal Contract 从未要求且没有记录理由的工作，则 FAIL。若不存在 Goal Contract，则以 No active goal 作为证据跳过。

最佳实践（必需 — 全部通过）

#	检查	是否具备	质量深度
1	YAGNI — 不添加不必要的功能，也不过度设计	每个计划组件是否都能追溯到明确的需求？	标记任何描述为“可能有用”或为未来灵活性而添加、但当前没有需求支持的内容。
2	KISS — 选择最简单可行的解决方案	每个主要步骤是否都说明了采用的方法？	是否有任何计划中的抽象可以在保持效果不变的情况下变得更简单？是否存在不必要的层级、间接调用或框架选择？
3	DRY — 不计划重复实现逻辑	是否多次描述了相似模式？	计划是否在现有模式可用时引入了新模式？是否有重复步骤表明实现时可能出现重复？
4	架构 — 遵循 .claude/docs/ 中的项目模式	计划是否引用或遵循 .claude/docs/ 中的模式？	是否遵循既定模式，还是有所偏离？任何偏离都需要明确说明理由。

完整性（建议 — ≥50% 的检查项应通过）

#	检查项	是否包含	质量深度
1	包含风险评估及缓解措施 — 已识别风险并给出应对方案	是否有风险章节，且至少包含一项？	缓解措施是具体行动（由谁执行、何时执行、由什么触发），还是模糊意向（如“密切关注”）？
2	已定义测试策略 — 概述测试方法	是否有测试章节，或各阶段的测试引用？	是否涵盖单元、集成和边缘案例路径，还是只说“编写测试”？测试方法是否可追溯至验收标准？
3	各阶段均有成功标准 — 定义可衡量的结果	每个阶段是否都列出了成功标准？	标准是否可衡量？未达标是否会触发回滚，还是仅为理想目标？
4	已考虑安全因素 — 记录安全方面的注意事项	是否有安全章节或行内安全说明？	安全问题是否针对该功能的攻击面，还是通用套话（例如“使用 HTTPS”“验证输入”）？
5	图依赖检查 — 检查已修改文件的导入方	如果 .code-graph/graph.db 存在：是否对每个已修改文件运行了 importers_of 查询？	是否检查了所有导入方，而不仅是直接调用方？是否明确说明 graph.db 是前提条件？是否标记了遗漏的依赖项？

第 3 步：评分和分类

状态	标准	操作
PASS	所有必需项均通过，且 ≥50% 的建议项通过	继续实施
WARN	所有必需项均通过，但通过的建议项少于 50%	谨慎继续，并注明差距
FAIL	任一必需项未通过	停止 — 必须先修复再继续

第 4 步：输出结果

## Plan Review Result

**Status:** PASS | WARN | FAIL
**Reviewed:** {plan-path}
**Date:** {current-date}

### Summary

{1-2 sentence summary of plan quality}

### Checks Passed ({X}/{Y})

#### Required ({X}/{Y})

- ✅ Check 1
- ✅ Check 2
- ❌ Check 3 (if failed)

#### Recommended ({X}/{Y})

- ✅ Check 1
- ⚠️ Check 2 (missing)

### Issues Found

- ❌ FAIL: {critical issue requiring fix}
- ⚠️ WARN: {minor issue, can proceed}

### Recommendations

1. {specific fix 1}
2. {specific fix 2}

### Verdict

{PROCEED | REVISE_FIRST | BLOCKED}

通过图追踪验证计划覆盖范围

图数据库可用时，请验证计划是否涵盖所有受影响文件：

• 对计划中“要修改的文件”列表里的每个文件，运行 python .claude/scripts/code_graph trace <file> --direction downstream --json
• 将计划中未列出的任何下游文件标记为“可能遗漏”
• 这可以捕获计划编写者可能忽略的跨服务影响（MESSAGE_BUS 消费者、事件处理程序）

递归修复与审查协议（关键）

协议： SYNC:double-round-trip-review + SYNC:fresh-context-review + SYNC:review-protocol-injection（均已内联在本文件上方）。

如果审查结果为 FAIL、WARN 或存在任何非零数量的发现项，plan-review 必须先运行发现项验证门，再编辑任何计划文件。只有经 $why-review --validate-findings 验证的发现项才能修复。修复已验证且可操作的发现项后，必须从当前计划的第一项审查步骤开始，重新运行完整的 plan-review 协议。不要仅为了在修复前重新审查已知发现项而启动新的子 Agent。如果重启后的完整审查使用子 Agent，必须使用下方 SYNC:review-protocol-injection 中的标准 Agent 模板，并从头重新读取所有计划文件，不保留任何先前修复的记忆。

发现项验证门（修复计划发现项前必须执行）

只要 plan-review 输出中包含任何发现项，就触发此验证门：FAIL、WARN、要求编辑计划的建议、缺失证据、未解决的风险，或阻碍实施的歧义。仅当已完成的审查轮次没有任何发现项时，或从第 3 轮开始，唯一已验证的发现项均为 LOW（记录为延期处理并判定 PASS）时，才可跳过此验证门。

1. 完成 plan-review 报告，列出所有发现项，并提供足够证据供其他审查者验证。
2. 在主审查流程中，对该报告调用 $why-review --validate-findings。
3. 如果 why-review 返回 CLEAN，只在最适当的计划位置，以最小改动修复已验证且可操作的发现项。
4. 如果 why-review 质疑、驳回或缩小发现项范围，先协调并更新 plan-review 报告，然后再运行 $why-review --validate-findings，之后才能进行任何修复。
5. 如果发现项有效，但需要产品或负责人作出判断，请停止并询问用户，不要绕过不确定性进行编辑。

在此验证门通过前，绝不可编辑 plan.md 或 phase-*.md 来修复审查发现项。 此验证门用于验证发现项；只有完成已验证发现项的修复周期后，才进行新的完整计划审查。

构造第 N 轮 Agent 调用提示词时（N≥2）：

1. 原样复制 SYNC:review-protocol-injection 模板中的 Agent 调用格式
2. 使用 agent_type: "general-purpose"（这是计划审查，不是代码审查）
3. 嵌入以下 SYNC 块的完整原文（均已内联在此技能文件上方）：SYNC:evidence-based-reasoning、SYNC:rationalization-prevention、SYNC:graph-assisted-investigation、SYNC:understand-code-first（省略不适用于计划文件的代码专用协议，例如 SYNC:bug-detection、SYNC:test-spec-verification）
4. 将 Task 设为 "Review plan files under {plan-dir}. Validate structural completeness, code-proof anti-hallucination (every file:line claim about existing source code must exist), and adversarial simulation (imagine implementing each phase right now — what fails first?)."
5. 将 Target Files 设为 "read plan.md and all phase-*.md files under {plan-dir}"
6. 将报告路径设为 plans/reports/plan-review-round{N}-{date}.md

子 Agent 返回后：

1. 阅读子 Agent 的报告
2. 在主报告中以 ## Re-Review {N} Findings 的形式整合发现项——不得筛除或覆盖
3. **如果仍有 FAIL、WARN 或任何发现项：**运行发现项验证门，仅修复已验证且可操作的发现项，然后从第一项审查步骤开始重新启动完整的 plan-review 协议
4. **重复阻断项上限：**如果同一阻断项在完整流程连续运行 2 次后仍未取得进展，直接向用户升级询问
5. 最终判定必须纳入所有实际执行的审查轮次中的发现项

流程

┌──────────────────────────────────┐
│  Round 1: Main-session review    │
│  (structural checklist + basic   │
│   code-proof trace)              │
│  Output: PASS / WARN / FAIL      │
└──────────────┬───────────────────┘
               │
        ┌──────▼──────┐
        │ ZERO        │
        │ FINDINGS?   │──YES──→ Proceed to next workflow step
        └──────┬──────┘
               │ NO
        ┌──────▼──────────────────────────────────┐
        │  VALIDATE: Run $why-review              │
        │  --validate-findings on the report.     │
        │  Only validated findings may be fixed.  │
        └──────┬──────────────────────────────────┘
               │
        ┌──────▼──────────────────────────────────┐
        │  FIX: Modify plan files to resolve       │
        │  validated actionable findings           │
        │  (plan.md/phase-*)                       │
        └──────┬──────────────────────────────────┘
               │
        ┌──────▼──────────────────────────────────┐
        │  Round 2+: FULL PLAN RE-REVIEW          │
        │  Re-run the complete plan-review        │
        │  protocol from the first review step.   │
        │  If the protocol uses agents, spawn     │
        │  new agents for that restarted pass.    │
        └──────┬──────────────────────────────────┘
               │
               └──→ Loop until the round's bar is clear (zero findings rounds 1-2; zero CRITICAL/HIGH/MEDIUM round 3+), repeated-blocker rule, or 3-round cap

迭代规则

1. 重复阻塞项上限 — 持续进行，直到完整的全面审查通过本轮门槛（第 1–2 轮要求零项发现；从第 3 轮起，要求没有 CRITICAL/HIGH/MEDIUM，只有 LOW 时即可结束）；如果同一阻塞项在 2 次完整调用中重复出现且毫无进展，则停止并直接询问用户，向用户升级处理
2. 跟踪轮数 — 每轮开始时记录“计划审查第 N 轮（完整重新审查）”
3. 零项发现 = 退出 — 只有完整的计划审查没有任何发现时才能继续。除非用户/负责人明确接受 WARN 为无需处理，否则 WARN 仍算一项发现。
4. 逐轮缩小范围 — 每轮发现的问题都应比上一轮少。如果第 N 轮发现的问题比第 N-1 轮多，则停止并升级处理
5. 修复范围 — 仅在计划中最恰当的位置修复经 why-review 验证、且可采取行动的问题。不要重写计划。
6. 修复方法：
   • 步骤含糊 → 补充具体文件路径和明确操作
   • 缺少章节 → 添加相应章节（风险、测试策略、成功标准）
   • 步骤冲突 → 解决冲突并说明理由
   • 过度设计 → 简化并移除不必要的复杂性
   • 缺少 TC 映射 → 添加 TC 引用，或注明“TBD”并说明理由
7. 每次验证修复后 — 从第一项审查步骤开始，重新运行完整的计划审查流程；重新启动的流程使用 Agent 时，必须发起新的 Agent 调用，不得重复使用之前的 Agent
8. 禁止静默回退 — 如果同一阻塞项在 2 次完整调用中重复出现且毫无进展，必须直接询问用户进行升级处理。绝不能回退到任何先前流程。

后续步骤

• 如果 PASS 且零项发现（或从第 3 轮起，PASS 且仅列出已延后的 LOW 项）：宣布“计划审查完成。正在继续下一项工作流步骤。”
• 如果仍有 WARN 或其他发现：运行发现项验证关卡；仅修复计划文件中经验证且可采取行动的问题，或者请用户明确接受无需处理的风险，然后再继续。
• 如果 FAIL：运行发现项验证关卡，仅修复计划文件中经验证且可采取行动的问题，然后递归地重新运行完整的计划审查流程。
• 如果达到重复阻塞项上限：列出剩余问题。停止。直接询问用户修复或重新生成计划。

重要说明

• 务必提出建设性意见，避免吹毛求疵——重点关注会导致实施问题的事项
• WARN 并非自动退出条件；如果可以采取行动，就予以修复；否则，继续前应记录明确的接受决定。
• FAIL 表示确实缺少必需内容；在问题解决或得到明确接受前，仍须跟踪较低严重级别的发现。
• 绝不能进行快速审查——即使是“简单”的计划，在真实测试中也曾发现 13 个错误。务必运行完整的既定审查流程；不得因任意轮数限制而停止。

---

技能互联（独立运行：必须通过直接询问用户来征求用户意见。在工作流中时跳过。）

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

• “继续完整工作流（推荐）” — 我将判断接下来最合适的工作流（计划已审查）。这样可确保不会跳过验证、实施、测试和文档步骤。
• “$plan-validate” — 通过访谈确认计划假设
• “$feature-implement”或“$plan-execute” — 如果计划已获批准且可以开始实施
• “跳过，手动继续” — 由用户决定

[阻塞] 这是验证关卡。必须直接询问用户，呈现审查发现并获得用户确认。至少提出一个问题后才能完成，否则即属违规。 [IMPORTANT] 开始前，使用任务跟踪将所有工作拆分成小任务——包括为每个读取的文件创建任务。这样可以避免因文件过长而丢失上下文。对于简单任务，AI 必须询问用户是否跳过此步骤。

关键目的： 确保质量——没有缺陷、没有错误、没有遗漏更新、没有过时内容。验证代码和文档。

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

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

OOP 与 DRY 强制要求： 强制要求——标记应提取到基类、泛型或辅助工具中的重复模式。同一组中的类（后缀相同、生命周期相同、用途相同）必须共用一个基类（即使目前为空——这样便于未来共享逻辑并支持子类重写）。验证项目是否为所用技术栈配置了代码 lint 或分析工具。

行为差异矩阵——修复审查时强制要求。在给出 PASS/FAIL 结论之前，必须先生成此表。叙述性描述不能替代此表。

输入状态	修复前行为	修复后行为	差异
{condition}	{current behavior}	{fixed behavior}	Preserved ✓ / Fixed ✓ / REGRESSION ✗

规则： ≥3 行 · ≥1 行涉及缺陷报告未提及的情况 · 差异为 REGRESSION → FAIL，直到有保留行为测试覆盖该情况（spec-tests-template.md#preservation-tests-mandatory-for-bugfix-specs）

解除阻塞的条件： ≥3 行 · ≥1 行涉及缺陷报告之外的情况 · 没有未缓解的 REGRESSION

图辅助调查——当 .code-graph/graph.db 存在时强制要求。

硬性门槛： 得出任何调查结论前，必须针对关键文件至少运行一条图命令。

模式： Grep 查找文件 → trace --direction both 揭示完整系统流程 → Grep 验证细节

任务	最低图操作
调查/侦察	对 2-3 个入口文件运行 trace --direction both
修复/调试	对有问题的函数运行 callers_of 和 tests_for
功能/增强	对要修改的文件运行 connections
代码审查	对已更改的函数运行 tests_for
影响范围分析	运行 trace --direction downstream

CLI： python .claude/scripts/code_graph {command} --json。先使用 --node-mode file（噪声少 10-30 倍），再使用 --node-mode function 查看细节。 跨服务检查 — 微服务／事件驱动：在结束调查、计划、规格说明或功能文档前必须执行。遗漏下游消费者会导致静默回归。

边界	搜索词
事件生产者	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 · 已审查契约 · 已标记破坏性变更风险

全新上下文重新审查 — 适用时，通过使用隔离的子 Agent 从头重新开始完整审查，消除编排者在修复后产生的确认偏误。

**原因：**主 Agent 知道自己（或 $feature-implement）刚刚修复了什么，因此会据此合理化审查结果。全新的子 Agent没有任何记忆，会从头重新阅读并发现主 Agent 忽略的问题。通过以下方式减轻子 Agent 的偏误：（1）使用全新上下文；（2）逐字注入协议；（3）主 Agent 不过滤报告内容。

**适用时机：**仅在验证审查发现的问题并完成修复后。若某轮审查未发现问题，则循环结束——不要启动确认用的子 Agent。若某轮审查发现问题，则执行：验证发现 → 修复 → 从第一阶段重新开始完整审查。

操作方式：

1. 启动全新的完整审查调用／任务拆分；当该协议要求使用 Agent 时，调用全新的 spawn_agent 工具——代码审查使用 code-reviewer agent_type，计划／文档／产物审查使用 general-purpose
2. 将所有必需的审查协议逐字注入提示词——完整列表和模板见 SYNC:review-protocol-injection。切勿通过文件路径引用协议；通过读取文件的间接方式会降低 AI 的遵循度（参见 SYNC:shared-protocol-duplication-policy）
3. 子 Agent 通过自己的工具调用从头重新读取所有目标文件——切勿在提示词中直接传入文件内容
4. 子 Agent 将结构化报告写入 plans/reports/{review-type}-round{N}-{date}.md
5. 主 Agent 阅读报告，将发现整合到自己的报告中，不得覆盖或过滤

规则：

• 如果上一次完整审查未发现问题，则跳过全新的子 Agent 审查（没有修复，就没有需要重新验证的内容）

• 修复后绝不跳过完整审查重启——每次修复都会使先前的结论失效

• 绝不在不同轮次间重复使用子 Agent——每一轮全新审查都必须调用全新的 spawn_agent

• 持续审查，直到某轮完整审查通过 SYNC:double-round-trip-review 规定的退出标准：第 1-2 轮 → 各严重级别的问题均为零；第 3 轮及之后 → CRITICAL／HIGH／MEDIUM 问题为零，因此若某轮验证后的发现全部为 LOW，则循环结束（将这些 LOW 列为延期处理项，而不是启动新一轮）。如果同一阻碍连续 3 次重复且没有进展，直接向用户升级求助

• 在对话上下文中跟踪迭代次数和重复出现的阻碍（仅限当前会话，不创建持久文件） 嵌套任务展开约定 — 对于工作流步骤调用，[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. 在读取目标文件、运行 grep、编辑或分析之前，先创建简短的任务分解。上下文丢失时，先检查当前任务列表。
2. 开始工作前将一个任务标记为 in_progress，证据写入后立即标记为 completed；不得批量变更状态。
3. 对于计划或审查工作，在记录首条发现前创建 plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md。
4. 每处理完一个文件、章节或决策后，追加记录发现；最后根据报告文件整理总结。
5. 最终输出需注明：Full report: plans/reports/{filename}。

解除阻塞条件： 已创建任务分解；计划或审查工作已声明报告路径；已持久化首条发现，之后才能记录下一条发现。 估算框架 — 优先自下而上；故事点（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 与后端的差异、影响范围和风险因素？→ 缺少则补充 批判性思维模式 — 运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度 >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 → 拆分为子任务。

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

深入了解： 有关实例（API 设计、调试、架构）、高级技巧（螺旋式完善、假设检验、收敛）和元策略（不确定性处理、修订级联），请参阅 $sequential-thinking 技能（.claude/skills/sequential-thinking/SKILL.md）。 项目参考文档门禁——在任务跟踪初始化后、读取目标文件或源文件、搜索、编辑或分析之前运行。项目文档优先于通用框架假设。

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. 搜索 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 存在） - [ ] 通过证据验证假设 已验证发现修复 + 完整复审循环 — 复审由已验证发现的修复周期触发，而非由轮数触发。审查目的：review → validate findings → fix validated findings → full re-review，直到某一轮的完整审查通过满足退出标准（见下文的严重性门槛）。审查通过后，循环即结束——无需继续进行后续轮次。

又称自审收敛循环。 此名称沿用至今——没有 2 轮上限；“双重往返”仅表示，修复已验证发现后，至少要进行一次全新复审。循环会持续到审查通过，但受下文所述的 3 轮上限约束。

轮数上限 — 最多 3 轮（上限，绝非目标）。 无论在哪一轮（包括第 1 轮）审查通过，循环都会立即结束；上限绝不要求你继续循环。第 3 轮结束时仍有阻塞性发现未解决（应用严重性门槛后）→ 停止，并直接询问用户以升级处理，同时列出仍未解决的发现；达到上限时，绝不可在未告知的情况下给出“够好”的通过结果，也绝不可用上限取代审查通过要求。连续 2 次无进展的阻塞规则仍是更早触发的退出条件——哪个条件先触发，就按哪个条件升级处理。

严重性门槛 — 从第 3 轮起，低严重性发现不再构成阻塞。 退出标准会随轮次逐步收紧，因此循环会围绕后果收敛，而不是在细枝末节上反复打转： 在任何地方都定义同一个谓词：blocking_findings(round, findings) 在第 1–2 轮返回所有已验证的发现，在第 3 轮及之后仅返回已验证的 CRITICAL／HIGH／MEDIUM 发现。只有当所属不变量明确说明时，二元门槛（测试通过、安全问题必须修复、必需产物）才可豁免。

轮次	退出标准——当新一轮完整审查达到以下条件时，循环结束	继续前必须修复
1-2	各严重级别的已验证发现均为零	CRITICAL · HIGH · MEDIUM · LOW
3+	已验证的 CRITICAL／HIGH／MEDIUM 发现为零——仅有 LOW 即为通过	仅 CRITICAL · HIGH · MEDIUM

从第 3 轮开始，LOW 发现不要求修复：如果某轮已验证的发现全部为 LOW，循环立即结束——不要为这些发现开启新一轮。严重级别为 SYNC:severity-rubric（CRITICAL 阻止合并 · HIGH 必须修复 · MEDIUM 应当修复 · LOW 可择机修复）；第 1–2 轮保持不变，因此早期修复容易处理的 LOW 仍然值得。

严重级别下限规则：

• 绝不悄悄丢弃延期处理的 LOW。 所有未修复的 LOW 都必须列在最终报告的 ## Deferred LOW Findings (severity floor, round ≥3) 下，并包含文件、行号和描述，以便负责人安排处理。从报告中删除它们违反协议，不算干净通过。
• 绝不为了触发退出而重新划分发现的严重级别。 将真实的 CRITICAL／HIGH／MEDIUM 降为 LOW，以便结束循环，属于虚假通过。必须先依据后果，按照 SYNC:severity-rubric 确定严重级别，再应用轮次标准——绝不能事后确定，也绝不能受退出目标影响。——原因：如果可以通过重新标记达到下限，那就不是真正的下限。
• 下限约束的是循环，而非标准。 它结束的是_迭代_；它绝不授权发布已知的 CRITICAL／HIGH／MEDIUM，也绝不降低发现最初被纳入时必须满足的发现保留标准。
• 下限绝不适用于硬性门槛。 测试通过门槛（套件必须实际通过）、安全问题必须修复的门槛，以及任何标准是二元判定而非按严重级别评定的门槛，均不受影响——测试失败就是失败，不是 LOW 发现。

通用范围（任何新输出／判断）： 任何新生成的输出或判断都必须经过至少 1 次自审；任何新判断都必须至少经过 1 次 $why-review --validate-findings 验证；任何被标记为需要复查的内容都必须至少复查 1 次——之后才能将该输出视为最终结果。此循环是任何产出工作的技能的默认收敛约定，不仅适用于审查技能。

路由不变量（面向技能编写者）： 验证发现的技能必须通过 $why-review --validate-findings（终端验证器）路由这些发现——绝不另行内联实现发现验证。通过 why-review 路由，才能应用发现保留标准和此循环；verify-review-validate-coverage 传感器会以机械方式强制执行此路由。

第 1 轮： 主会话审查。阅读目标文件，建立理解，记录问题。输出发现和结论（PASS／FAIL）。

第 1 轮后的决策：

• 未发现问题（PASS，零发现） → 审查结束。不要为确认而启动新的子 Agent。
• blocking_findings(round, findings) 非空 → 先运行当前审查技能的发现验证门槛；对于审查技能，默认门槛为 $why-review --validate-findings <report-path>。只修复已验证的发现，然后从头开始执行完整审查协议，并重新拆分任务。

每个修复周期后都要进行全新完整复审： 对当前完整目标重新运行整个审查协议。如果协议包含子 Agent，则调用全新的 spawn_agent——绝不复用之前的 Agent。审查者必须从头重新阅读所有文件，对之前轮次的记忆归零。有关启动机制，请参阅 SYNC:fresh-context-review；有关标准 Agent 提示词模板，请参阅 SYNC:review-protocol-injection。每次全新完整审查都必须发现：

• 上一轮遗漏的跨领域问题
• 已更改文件之间的交互错误
• 规范偏移（新代码与现有模式不一致）
• 应有但缺失的内容
• 上一轮以理由搪塞过去的细微边界情况
• 修复本身引入的回归

循环终止： 每次完整复审后，都根据该轮的退出标准重复同一决策：达到标准 → 结束；仍有阻断性发现 → 验证发现 → 修复 → 从第一个审查阶段重新开始。第 1–2 轮要求各严重级别的发现均为零；从第 3 轮开始，标准是 CRITICAL／HIGH／MEDIUM 为零，因此仅有 LOW 的轮次会结束循环（延期处理的 LOW 应列入报告）。最多 3 轮。在以下情况中先发生的一项出现时，直接向用户请求升级处理：同一已验证发现连续 2 次完整调用都重复且没有进展 · 修复需要产品／负责人提供意见 · 第 3 轮结束时仍有未解决的 CRITICAL／HIGH／MEDIUM。绝不超过 3 轮，也绝不将达到轮数上限判为通过。

规则：

• 第 1 轮审查干净即结束——无需强制进行第 2 轮
• 从第 3 轮开始，如果某轮已验证的发现全部为 LOW，则结束循环——绝不为了只修复 LOW 而开启第 N+1 轮；应将这些 LOW 列为延期处理
• 绝不将 CRITICAL／HIGH／MEDIUM 重新划分为 LOW 来达到第 3 轮的退出标准——必须在应用标准前，依据后果确定严重级别
• 绝不修复未经验证的发现；必须先使用调用方的验证门槛进行验证
• 每个保留的发现还必须满足 why-review 的 Findings Validation Routine 中定义的发现保留标准（该标准刻意高于通用 act-gate——“保留此发现吗？”比“根据这些证据采取行动吗？”要求更严格）；不符合标准的发现应降级或删除，不得保留
• 绝不跳过修复周期后的完整复审（每次修复都会使之前的结论失效）
• 绝不在多轮审查中复用子 Agent——每次使用子 Agent 的迭代都必须启动全新的 Agent 调用
• 主 Agent 必须阅读子 Agent 报告，但不得筛选、重新解释或推翻其中的发现
• 3 轮上限绝不取代审查干净的要求——它限制失控循环，不授权发布未通过干净审查的内容；无论在哪一轮，干净通过都会提前结束循环；达到上限时应升级处理，而非判为通过
• 除重复无进展 2 次的阻断规则外，还必须执行 3 轮上限；两者都是升级处理的触发条件，均非完成标准
• 在对话上下文中跟踪递归调用次数和重复阻断项（限当前会话）
• 最终结论必须综合所有已执行的轮次

报告必须为每个已执行的第 N 轮（N≥2）包含 ## Round N Findings (Fresh Sub-Agent)；如果循环在第 3 轮及之后依据退出标准结束且仍有未解决的 LOW，还必须包含 ## Deferred LOW Findings (severity floor, round ≥3)。 审查协议注入 — 每个新建的子 Agent 审查提示词都必须逐字嵌入 11 个协议块。下方模板已内联展开了全部 11 个正文。运行时，将整个模板复制到 Agent 调用的 prompt 字段中，只替换 Task / Round / Reference Docs / Target Files / Output 部分中的 {placeholders}，并填入特定上下文的值。不要改动嵌入的协议部分。

为何内联展开： 占位符标记会迫使运行时通过间接方式读取文件。间接读取会显著降低 AI 的遵循度（参见 SYNC:shared-protocol-duplication-policy）。因此，模板预先嵌入了全部 11 个协议正文。

子 Agent 类型选择

• code-reviewer — 用于代码审查（审查源文件、git 差异、实现）
• general-purpose — 用于计划 / 文档 / 工件审查（审查 Markdown 计划、文档、规范）

标准 Agent 调用模板（逐字复制）

spawn_agent({
  description: "Fresh Round {N} review",
  agent_type: "code-reviewer",
  prompt: `
## Task
{review-specific task — e.g., "Review all uncommitted changes for code quality" | "Review plan files under {plan-dir}" | "Review integration tests in {path}"}

## Round
Round {N}. You have ZERO memory of prior rounds. Re-read all target files from scratch via your own tool calls. Do NOT trust anything from the main agent beyond this prompt.

## Protocols (follow VERBATIM — these are non-negotiable)

### Spec ↔ Tests ↔ Code Triangulation
DO THIS FIRST — before any per-protocol check below. The review target is the WHOLE PACKAGE, not the diff alone: load the behavior's spec (§3 ACs / §4 BRs / §8 TCs), its tests, and the changed code TOGETHER, and reason about their mutual consistency BEFORE judging any one in isolation.
1. Locate all three faces: the Feature Spec section(s) governing the changed behavior, the tests that guard it, and the production code that implements it. A missing face is itself a finding (SPEC-GAP / TEST-GAP / DEAD-SPEC).
2. Triangulate pairwise — every disagreement is a finding; classify which face is wrong:
   - code vs spec: behavior the code does that no §3/§4/§8 rule describes → CODE-EXTRA or SPEC-STALE; a [HARD] §4 rule or §5 invariant with no enforcing code path → CODE-WRONG.
   - tests vs spec: a §8 TC with no test, or a test asserting behavior no TC/rule names → TEST-GAP or SPEC-SILENT.
   - tests vs code: a changed code path with no covering test → TEST-GAP; a test that still passes against a deliberately broken invariant → WEAK-TEST (apply the mutation thinking in Bug Detection).
3. Hidden-rule capture: any invariant the code enforces but the spec never states (SPEC-SILENT) MUST be surfaced as a finding to add into §3/§4/§8 AND guarded with a test — the enrichment loop, never a silent pass.
4. Only after the three faces agree — or every disagreement is logged as a finding — proceed to the per-protocol checks below; when enrichment adds spec/test content, re-review the package against the enriched spec.
NEVER mark review PASS while any spec/test/code face disagrees without a logged finding. The diff is the entry point; the package is the unit of judgment.

### Evidence-Based Reasoning
Speculation is FORBIDDEN. Every claim needs proof.
1. Cite file:line, grep results, or framework docs for EVERY claim
2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
3. Cross-service validation required for architectural changes
4. "I don't have enough evidence" is valid and expected output
BLOCKED until: Evidence file path (file:line) provided; Grep search performed; 3+ similar patterns found; Confidence level stated.
Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because".
If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]."

### Bug Detection
MUST check categories 1-4 for EVERY review. Never skip.
1. Null Safety: Can params/returns be null? Are they guarded? Optional chaining gaps? .find() returns checked?
2. Boundary Conditions: Off-by-one (< vs <=)? Empty collections handled? Zero/negative values? Max limits?
3. Error Handling: Try-catch scope correct? Silent swallowed exceptions? Error types specific? Cleanup in finally?
4. Resource Management: Connections/streams closed? Subscriptions unsubscribed on destroy? Timers cleared? Memory bounded?
5. Concurrency (if async): Missing await? Race conditions on shared state? Stale closures? Retry storms?
6. Stack-Specific: Check the configured language/runtime pitfalls and framework-specific failure modes discovered from local code.
Classify: CRITICAL (crash/corrupt) → FAIL | HIGH (incorrect behavior) → FAIL | MEDIUM (edge case) → WARN | LOW (defensive) → INFO.

### Design Patterns Quality
Priority checks for every code change:
1. DRY via OOP: Same-suffix classes (*Entity, *Dto, *Service) MUST share base class. 3+ similar patterns → extract to shared abstraction.
2. Right Responsibility: Logic in LOWEST layer (Entity > Domain Service > Application Service > Controller). Never business logic in controllers.
3. SOLID: Single responsibility (one reason to change). Open-closed (extend, don't modify). Liskov (subtypes substitutable). Interface segregation (small interfaces). Dependency inversion (depend on abstractions).
4. After extraction/move/rename: Grep ENTIRE scope for dangling references. Zero tolerance.
5. YAGNI gate: NEVER recommend patterns unless 3+ occurrences exist. Don't extract for hypothetical future use.
Anti-patterns to flag: God Object, Copy-Paste inheritance, Circular Dependency, Leaky Abstraction.

### Logic & Intention Review
Verify WHAT code does matches WHY it was changed.
1. Change Intention Check: Every changed file MUST serve the stated purpose. Flag unrelated changes as scope creep.
2. Happy Path Trace: Walk through one complete success scenario through changed code.
3. Error Path Trace: Walk through one failure/edge case scenario through changed code.
4. Acceptance Mapping: If plan context available, map every acceptance criterion to a code change.
5. Tests Verify Intent: For test/spec changes, verify tests name the protected business rule or invariant and would fail if that intent breaks.
6. Migration Test Exclusion: Do not write tests for migration code. Schema/data migrations are one-time execution paths, not core application logic.
NEVER mark review PASS without completing both traces (happy + error path).

### Test Spec Verification
Map changed code to test specifications.
1. Identify the project's test/spec format from existing docs, test-case files, BDD feature files, or spec folders.
2. Every changed code path MUST map to a corresponding test case/spec (or flag as "needs test case").
3. New functions/endpoints/handlers → flag for test spec creation.
4. Migration files are excluded from test/spec creation; schema/data migrations are one-time execution paths, not core application logic.
5. If spec evidence fields exist, verify they point to actual code (file:line, not stale references).
6. Verify each meaningful test case names the business intent/invariant; flag behavior-only cases that only mirror implementation details.
7. Auth/data changes → verify corresponding authorization and data-state test cases exist.
8. If no specs exist for a changed path → log the gap and recommend the project's test-spec workflow.
NEVER skip test mapping. Untested code paths are the #1 source of production bugs.

### Behavioral Delta Matrix
MANDATORY for any bugfix review. Produce input-state × pre-fix × post-fix × delta table BEFORE writing verdict.
- Minimum 3 rows; include at least one row OUTSIDE the original bug report.
- Any "REGRESSION" delta → review returns FAIL until a preservation test is added.
- Narrative descriptions do NOT substitute for the matrix.
Example rows (external-record sync fix):
| Input                 | Pre-fix | Post-fix                  | Delta      |
| --------------------- | ------- | ------------------------- | ---------- |
| Record exists (valid) | Reused  | Always recreated → orphan | REGRESSION |
| Record missing (404)  | Error   | Recreated                 | Fixed      |

### Fix-Layer Accountability
NEVER fix at the crash site. Trace the full flow, fix at the owning layer. The crash site is a SYMPTOM, not the cause.
MANDATORY before ANY fix:
1. Trace full data flow — Map the complete path from data origin to crash site across ALL layers (storage → backend → API → frontend → UI). Identify where bad state ENTERS, not where it CRASHES.
2. Identify the invariant owner — Which layer's contract guarantees this value is valid? Fix at the LOWEST layer that owns the invariant, not the highest layer that consumes it.
3. One fix, maximum protection — If fix requires touching 3+ files with defensive checks, you are at the wrong layer — go lower.
4. Verify no bypass paths — Confirm all data flows through the fix point. Check for direct construction skipping factories, clone/spread without re-validation, raw data not wrapped in domain models, mutations outside the model layer.
BLOCKED until: Full data flow traced (origin → crash); Invariant owner identified with file:line evidence; All access sites audited (grep count); Fix layer justified (lowest layer that protects most consumers).
Anti-patterns (REJECT): "Fix it where it crashes" (crash site ≠ cause site, trace upstream); "Add defensive checks at every consumer" (scattered defense = wrong layer); "Both fix is safer" (pick ONE authoritative layer).

### Rationalization Prevention
AI skips steps via these evasions. Recognize and reject:
- "Too simple for a plan" → Simple + wrong assumptions = wasted time. Plan anyway.
- "I'll test after" → RED before GREEN. Write/verify test first.
- "Already searched" → Show grep evidence with file:line. No proof = no search.
- "Just do it" → Still need task tracking. Skip depth, never skip tracking.
- "Just a small fix" → Small fix in wrong location cascades. Verify file:line first.
- "Code is self-explanatory" → Future readers need evidence trail. Document anyway.
- "Combine steps to save time" → Combined steps dilute focus. Each step has distinct purpose.

### Graph-Assisted Investigation
MANDATORY when .code-graph/graph.db exists.
HARD-GATE: MUST run at least ONE graph command on key files before concluding any investigation.
Pattern: Grep finds files → trace --direction both reveals full system flow → Grep verifies details.
- Investigation/Scout: trace --direction both on 2-3 entry files
- Fix/Debug: callers_of on buggy function + tests_for
- Feature/Enhancement: connections on files to be modified
- Code Review: tests_for on changed functions
- Blast Radius: trace --direction downstream
CLI: python .claude/scripts/code_graph {command} --json. Use --node-mode file first (10-30x less noise), then --node-mode function for detail.

### Understand Code First
HARD-GATE: Do NOT write, plan, or fix until you READ existing code.
1. Search 3+ similar patterns (grep/glob) — cite file:line evidence.
2. Read existing files in target area — understand structure, base classes, conventions.
3. Run python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists.
4. Map dependencies via connections or callers_of — know what depends on your target.
5. Write investigation to .ai/workspace/analysis/ for non-trivial tasks (3+ files).
6. Re-read analysis file before implementing — never work from memory alone.
7. NEVER invent new patterns when existing ones work — match exactly or document deviation.
BLOCKED until: Read target files; Grep 3+ patterns; Graph trace (if graph.db exists); Assumptions verified with evidence.

## Reference Docs (READ before reviewing)
- `.claude/docs/development-rules.md` — canonical development rules, code-quality guidelines, and pre-commit checklist
- docs/project-reference/code-review-rules.md
- {skill-specific reference docs — e.g., integration-test-reference.md for integration-test-review; backend-patterns-reference.md for backend reviews; frontend-patterns-reference.md for frontend reviews}

## Target Files
{explicit file list OR "run git diff to see uncommitted changes" OR "read all files under {plan-dir}"}

## Output
Write a structured report to plans/reports/{review-type}-round{N}-{date}.md with sections:
- Status: PASS | FAIL
- Issue Count: {number}
- Critical Issues (with file:line evidence)
- High Priority Issues (with file:line evidence)
- Medium / Low Issues
- Cross-cutting findings

Return the report path and status to the main agent.
Every finding MUST have file:line evidence. Speculation is forbidden.
`
})

规则

• 必须完整复制模板 — 包括全部 11 个嵌入的协议部分
• 必须仅替换 Task / Round / Reference Docs / Target Files / Output 部分中的 {placeholders}，并填入特定上下文的内容
• 代码审查必须选择 code-reviewer agent_type，计划 / 文档 / 工件审查必须选择 general-purpose agent_type
• 不得改写、总结或跳过任何协议部分
• 不得以内联方式传递文件内容 — 子 Agent 会通过自己的工具调用读取文件，以获得新鲜的上下文
• 不得通过文件路径或标签名引用协议 — 正文已在上方嵌入
• 不得为协议引入占位符标记 — 协议必须保持完整展开

防止 AI 犯错 — 每项任务都应避免以下失败模式：

上下文变化后重新读取文件。 上下文压缩、恢复或长时间运行的工作都可能导致记忆过时；行动前请核实当前文件。 根据源证据核实生成的内容。 AI 可能会臆造 API、名称、主张和文档事实。记录或引用相关内容前，请检查对应源文件。 删除或重命名前检查下游引用。 删除某个工件可能导致文档、生成的镜像、配置和调用方过时；请先梳理引用关系。 编辑后追踪完整的影响链。 更改定义可能遗漏派生输出和使用方。在宣布完成前，请沿受影响链路逐一检查。 核实所有受影响的输出，而不只是第一个。 一个检查通过不代表所有检查都通过；请验证变更可能影响的每个输出面。 假定现有值是有意设置的——更改或将其标记为缺陷之前，先弄清原因。 在更改或报告常量、限制、标志、阈值、措辞或模式之前，请阅读附近的上下文和历史记录、调用方的执行顺序，以及至少 2 个采用相同约定的同类调用点。文档只说明“是什么”而没有说明“为什么”，意味着缺少依据，而非证明缺少保护条件。 行动前指出歧义——不要默默自行选择。 存在多种有效解释时，必须明确提问，或说明所作假设及其风险。 断言系统自身负责的结果，而非基础设施负责的中间状态。 验证异步工作时，应断言最终业务状态，而绝不要断言由任何并行运行进程都可写入的共享基础设施中的投递 / 重试记录。单独运行时，这类检查可能通过；一旦其他进程共用该基础设施，就会出现间歇性失败。 确保共享指导与接收方角色相关。 通用指导必须对每个接收它的技能或 Agent 都有帮助；代码特定要求只能放在代码专用协议中。 严重性分级标准 — 根据每项发现造成的后果进行分类，而非修复难易程度。所有审查使用同一套分级标准，确保“高”在任何地方都代表相同含义。

严重性	操作	定义
CRITICAL	阻止合并	静默运行时故障、数据损坏、绕过验证、安全漏洞
HIGH	必须修复	行为错误、不变量缺口、架构违规
MEDIUM	应当修复	设计债务、可维护性问题、未来很可能出现的 bug
LOW	修复更好	规范、文档、细微的清晰度问题

基于分数的技能应将其数值等级映射到这些层级——不要另创一套并行术语：

• 0-2 标准评分（例如 production-readiness-review）：0 = CRITICAL/HIGH（未满足标准，阻碍生产就绪），1 = MEDIUM（部分满足，应修复），2 = 通过（无发现）。
• 双轴评分（例如 performance-review、影响 × 可能性）：将结果单元格映射到最接近的层级——高影响 + 高可能性 → CRITICAL/HIGH；低影响或低可能性 → MEDIUM/LOW。

发现的层级决定门槛：在判定 PASS 前，必须解决 CRITICAL/HIGH，或由负责人明确接受；MEDIUM/LOW 可以随版本发布，但需记录后续跟进事项。

目标契约满足循环 — 将用户目标保存在外部文件中，围绕该目标执行，并循环审查/修复，直到所有已保存的必需标准均通过，或阻碍因素升级处理。限定范围的闭环——绝不进行无休止的自主探索。

1. 确定当前目标（按顺序）：当前计划中的 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 根据当前用户请求创建新的目标契约（模板：.claude/templates/goal-contract-template.md）。
2. 必需章节： 原始请求、目的、成功标准（复选框；标明必需项与可选项）、约束、所需证据、迭代日志、目标满足情况矩阵。
3. 开始工作前： 阅读当前目标，并将计划工作映射到已保存的成功标准——执行工作应服务于已保存的标准，绝不能只依赖聊天记忆。
4. 执行/验证后： 追加一条迭代日志——记录结果、证据引用（file:line、命令输出、报告路径）以及剩余差距。
5. 审查门槛： 输出目标满足情况矩阵——| 成功标准 | 证据 | 状态 |，状态为 PASS/FAIL/BLOCKED。只有所有必需标准均为 PASS，总体结果才能为 PASS。
6. 循环规则（重试）： 必需标准为 FAIL → 验证差距确实存在 → 修复 → 仅重新审查受影响的标准。所有必需标准均为 PASS 时，正常停止。
7. 升级规则（停止）： 连续两次迭代都没有任何标准取得进展，或遇到需要用户输入的阻碍因素 → 将该标准标记为 BLOCKED，说明面向用户的原因并升级处理。绝不无限循环。
8. 跳过规则： 微小的对话任务可以跳过目标文件，但必须记录一行理由。用户接受的门槛跳过操作必须在目标文件中记录理由和范围。
9. 安全： 绝不在目标文件中存储机密、令牌、凭据或客户私有数据——只存储证据引用，并对敏感值进行脱敏。

以下条件满足前不得继续： 已确定当前目标（或已记录跳过理由）· 编辑前已阅读已保存的成功标准 · 执行后已追加迭代证据 · 判定任何 PASS 前已输出目标满足情况矩阵。 权衡审问关卡 — 在给出任何判定、评分、发现或建议之前，始终先询问以下三个问题；既要针对审查对象，也要针对你提出的每一项建议。— 原因：只说收益而不说明代价，是背书而非审查；代价最高的权衡，往往是没人记录下来的那些。

1. 是否存在任何权衡？ 说清楚它牺牲了什么。“没有”／“纯粹有利”意味着分析尚未完成，不是答案——若要声称不存在权衡，请说明你检查了哪些维度，以及为什么每个维度都不受影响：未来变更成本 · 复杂性 · 性能／延迟 · 内存／成本 · 耦合 · 可逆性 · 迁移负担 · 运维负荷 · 影响范围 · 安全态势 · 可测试性 · 团队技能／上手时间 · 交付时间 · 用户体验。
2. 是否值得？ 明确权衡收益与牺牲——获得了什么（附指标）· 付出了什么代价 · 谁来承担 · 何时付出——然后给出 值得／不值得／不明确 的结论。没有指标、也没有代价的“更好”，不符合本问题的要求。若结论为不值得 → 撤回或替换该建议，绝不能原样保留。
3. 该权衡是否重要到需要向用户确认？ 重要权衡由用户决定，而不是由你决定。满足以下任意一项即为重要：不可逆／单向门（数据迁移、公开契约、存储格式、供应商锁定）· 将成本转嫁给他人（其他团队、运维／值班人员、未来维护者、最终用户）· 以一种质量属性换取另一种（正确性↔速度、安全性↔便利性、延迟↔成本、简单性↔灵活性）· 跨越边界（客户端↔服务端层、服务契约、事件契约、共享库）· 后果严重的路径（身份验证、资金、数据完整性、破坏性变更、残余风险为高／中）· 值得与否的结论为不明确。

重要 → 停下，并在结论生效前直接询问用户以取得确认——说明该权衡、两个选项、每个选项牺牲什么，以及你的建议。不重要 → 用一句话说明理由并记录在相关内容中，然后继续。

无法询问的执行环境——必须通过交接升级，绝不能默不作声。 直接询问用户只适用于主交互 Agent：子 Agent 无法询问用户，而仅运行终端／仅输出结论的模式则按设计不会提问。在此类环境中运行时，义务应当转交，绝不可免除——必须完成以下所有事项：(a) 正常完成问题 1 和 2；(b) 判断重要性，并在“权衡评估”行中记录 confirmed? = NO — cannot ask from this context；(c) 在返回的摘要／结论中明确指出尚未确认的重要权衡，以便调用方（或父级编排器）代表你直接询问用户并升级处理——仅在磁盘上的报告文件中提及重要权衡，不算交接；(d) 不得给出不带限定条件的 PASS——应标明结论包含尚未确认的重要权衡，让调用方的关卡在用户回答前保持关闭。调用方一旦读到你的返回内容，就承担升级处理的义务。

此例外针对的是可触达性，而非便利性：它仅适用于工具确实无法联系用户的情况（已启动的子 Agent、仅执行验证／输出结论的终端模式、非交互式／无头运行）。它绝不是跳过问题、擅自批准单向门，或因为询问不方便就降低重要性级别的许可——如果你能询问，就必须询问。

对每项审查决策和每项建议，都要输出一行权衡评估：| decision | sacrifices | gain (metric) | who pays, when | WORTH IT/NOT/UNCLEAR | material? | confirmed? |。

以下事项全部完成前，禁止继续： 指明权衡（或给出检查过哪些维度的理由）· 给出是否值得的结论 · 判断重要性 · 每项重要权衡均已向用户确认，或者——在无法询问的环境中——已在返回的结论中交接，供调用方确认。既未确认也未交接的重要权衡，绝不能判为 PASS，也绝不能将其埋没在低严重性备注中。

绝不在未检查的情况下回答“没有权衡”· 替用户默默决定重要权衡· 让趋同／交付压力成为跨过单向门的理由· 将多个重要权衡捆绑成一句含糊的“继续吗？”。

领域实体变更关卡 — 一套协议，约束每个规划、实现或审查涉及领域实体、值对象或聚合的变更的技能或 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 行重复防护规则，则跳过并记录延期说明。——原因：规划者和评审者共用一个协议，才能阻止计划交付一种随后会被评审否决的实体设计。

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

• 强制，重要，必须特别注意：每项声明都要引用 file:line 证据。置信度 >80% 才可采取行动；<60% = 不要建议。

• 强制，重要，必须特别注意：执行评审循环（即自我评审收敛循环）：评审 → 验证发现 → 修复已验证的发现 → 完整复评。一次完整评审通过且零发现时，评审即结束。任何新产出的内容／判断至少要经过 1 次自我评审；任何新判断在被视为最终结论前，至少要通过 1 次 $why-review --validate-findings 验证。

• 强制应用严重级别下限：第 1–2 轮在任何严重级别均无发现时即可结束；**从第 3 轮起，标准为 CRITICAL／HIGH／MEDIUM 级发现为零——LOW 级发现不再要求修复，因此只有 LOW 级发现的轮次即可结束循环。**在报告中列出所有延期处理的 LOW 级发现；绝不可为了达到退出条件而将实际的 CRITICAL／HIGH／MEDIUM 级问题降为 LOW；也绝不可将此下限用于二元门禁（测试通过、安全问题必须修复）。

• 强制遵守最多 3 轮的上限——这是上限，绝非目标：任何轮次（包括第 1 轮）通过后都应立即结束循环；若第 3 轮结束时仍有未解决的 CRITICAL／HIGH／MEDIUM 级问题，→ 停止并升级，直接询问用户，绝不可悄然给出 PASS。连续 2 次无进展的阻断规则属于更早的退出条件——以先触发的条件为准进行升级。绝不可无限循环。

重要，必须特别注意：如果 graph.db 存在，至少对关键文件运行一条图命令。模式：grep → graph trace → grep 验证。

重要，必须特别注意：微服务／事件驱动场景：扫描任务范围内的生产者、消费者、Saga 和契约。对每个触点记录：负责人 · 消息 · 消费者 · 风险（NONE／ADDITIVE／BREAKING）。遗漏消费者 = 无声回归。

• 强制，必须特别注意：估算：自下而上的阶段工时决定 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 的增量变更，SP 上限为 3，除非测试范围 >1.5d。SP 为 13 时应拆分，为 21 时必须拆分。

必须特别注意：运用批判性与顺序思维——每项声明都需要适当且可追溯的证据（仓库／代码声明使用 file:line；研究、产品、内容和文档声明使用来源 URL 或产物章节）；置信度 >80% 才可采取行动；<60% 不要建议。防幻觉：绝不可将猜测当作事实；坦然承认不确定性；独立交叉核验；对自己的信心保持怀疑。

必须特别注意：运用顺序思维——多步骤任务使用 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 继续迭代；反复无进展或遇到阻碍时升级处理。绝 NEVER 在目标文件中存储机密信息。

• 强制要求 根据影响将发现分为 Critical／High／Medium／Low；Critical／High 问题修复或经负责人接受前，不得判定为 PASS。

• 强制要求 基于评分的技能（sre 0-2、perf 双轴）映射到同样的四个等级——不得使用并行的严重程度术语。

提示词增强收尾锚点

重要，务必注意 按照此技能声明的步骤顺序执行；未经用户明确批准，绝 NEVER 跳过、重排或合并步骤 重要，务必注意 对于每个步骤／子技能调用：执行前将状态设为 in_progress，执行后设为 completed 重要，务必注意 每个跳过的步骤都必须注明明确原因；每个已完成的步骤都必须提供简洁证据 重要，务必注意 如果任务工具不可用，维护一份状态同步的逐步计划跟踪表

• 强制要求：必须始终询问这 3 个权衡问题——针对正在审查的事项以及你提出的每项建议：(1) **是否存在任何权衡？**说清楚牺牲了什么（变更成本 · 复杂性 · 性能 · 耦合 · 可逆性 · 迁移 · 运维负担 · 影响范围 · 安全性 · 可测试性 · 交付时间 · 用户体验）——“没有”/“纯收益”意味着分析尚未完成，因此要说明检查了哪些维度；(2) **是否值得？**收益（附带指标）与成本、由谁承担、何时发生 → 给出 WORTH IT / NOT WORTH IT / UNCLEAR 的结论；NOT WORTH IT → 撤回或替换该建议；(3) **是否重要到需要向用户确认？**不可逆/单向门 · 将成本转嫁给其他团队/运维人员/维护者/用户 · 以一种质量属性换取另一种 · 跨越层级/服务/事件/库的边界 · 涉及认证/资金/数据完整性/破坏性变更/高或中风险路径 · 结论为 UNCLEAR → 停止，并在给出结论前直接询问用户确认。
• **强制要求：**未经用户确认的重大权衡绝不能判定为 PASS；绝不能将其掩盖为低严重性备注，绝不能默默替用户做决定，也绝不能让交付或收敛压力为单向门决策背书。——原因：尚未经过权衡、无法撤回的单向门，应由用户决定，而非审查者。
• 强制要求——在无法提问的情境中，必须通过移交升级，绝不能保持沉默。直接询问用户只能触达主交互 Agent：子 Agent 无法询问用户，而仅输出终端结果/结论的模式则按设计不会提问。在这些情境中，责任是转交，而非免除——仍须说明权衡，仍须判断其重要性，记录 confirmed? = NO — cannot ask from this context，在返回的结论/摘要中说明未经确认的重大权衡，以便调用方升级处理（只在磁盘报告中备注不算移交），且绝不能给出无条件的 PASS。仅适用于用户确实无法触达的情况（派生的子 Agent、终端验证模式、无头运行）——如果你能够提问，就必须提问。

并行子 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 中匹配到的正文；正文缺失或格式错误时必须报告，绝不能重构。覆盖规则只能追加（绝不替换此技能自身的规则），且仅为简报，绝不是权限升级；具体程度相同的规则若有矛盾，须告知用户。

收尾提醒

**重要：务必注意目标：**除非计划不存在幻觉（每项关于现有代码的断言都已通过 file:line 证实），且已准备好实施（每个步骤都具体明确，小到可以立即据此编写代码），否则不得让计划进入实施阶段——递归审查，直到完整审查轮次中零项发现。

**重要：务必注意主要步骤（按顺序执行，每项任务各一步）：**阶段 0：检测计划类型 → 步骤 1：阅读 plan.md/goal.md/所有 phase-*.md → 步骤 2：评估 4 组清单（有效性 · 正确性［粒度 + 反幻觉 + 规格/TC 覆盖 + 目标-契约映射］· 最佳实践 · 完整性）+ 11 种对抗性技术 + 反偏见关卡 + 8 个计划维度 + 对每个修改文件进行图追踪 → 步骤 3：评分 PASS/WARN/FAIL → 步骤 4：输出结果 → 步骤 5：递归执行 $why-review 验证 → 修复已验证的发现 → 全面重新审查，直到发现数为零——原因：AI 经常忘记此技能自身的步骤流程；这是“如果什么都不记得，就按此顺序阅读”的内容。

重要：务必注意：当前生效的协议（此技能所包含的 SYNC/共享区块的简明摘要）——每行均指向其上方的规范正文；绝不可将此摘要视为完整区块的替代品，并且始终完整应用以下每项协议：

• **行为差异矩阵：**Bug 修复审查必须在给出结论前提供「输入 × 修复前 × 修复后 × 差异」表。
• **图辅助调查：**当 graph.db 存在时，对关键文件运行一条图命令。
• **跨服务检查：**扫描生产者、消费者、Saga 和契约；缺少消费者会导致静默回归。
• **全新上下文审查：**每轮修复后，启动一个零记忆子 Agent，从头重新阅读。
• **嵌套任务创建：**展开子阶段任务；若为嵌套任务，则关联父工作流行。
• **任务跟踪与外部报告：**初始化任务拆分；将发现逐步写入 plans/reports/。
• **批判性思维：**每项主张都需要可追溯的 file:line 证据；绝不将猜测当作事实。
• **顺序思考：**多步骤思考使用 Thought N/M，并标注 REVISION/BRANCH/HYPOTHESIS，最后给出置信度。
• **项目参考文档：**开始目标工作前，阅读必需的项目参考文档；项目规范优先于通用默认设置。
• **先理解代码：**任何修改前，至少使用 3 种模式进行 grep 并阅读代码。
• **双轮往返审查：**审查 → 验证发现 → 修复 → 完整复审，直至没有问题。
• **审查协议注入：**在每个全新审查提示词中逐字嵌入全部 11 项协议正文。
• **预防 AI 错误：**根据证据核验生成内容，追踪下游引用，验证所有受影响的输出，在上下文丢失后重新阅读，并指出歧义。
• **严重性标准：**按后果划分 Critical/High/Medium/Low；Critical/High 会阻止 PASS。
• **并行子 Agent 派发：**为任务标注 PAR/SEQ，将 PAR 任务按互不重叠的写入集分组为多个波次，在一条消息中启动每个波次，并在进入下一步前设置屏障。 重要，必须注意：以怀疑者而非验证者的角度进行审查——你的任务是找出哪些地方行不通，而不是确认看起来正确的内容；在作出任何结论之前，先运行完整的反偏差关卡（现实检验、假设压力测试、事前验尸、为被否决的替代方案作最有力的辩护、逆向审查）——原因：确认偏误会让结构完善的计划轻易过关。 强制重要，必须注意：反幻觉关卡——计划中每项关于现有源代码的主张都需要 file:line 证据（文件存在、符号已通过 grep 搜索、行为已通过代码追踪）；对现有代码使用“应该”“可能”“通常”之类的表述＝不通过。仅涉及绿地开发的计划 → 通过。 强制重要，必须注意：粒度关卡“足够详细且足够小”——任何超过 5 个文件或 3 小时，或包含规划动词（research/determine/decide/evaluate/explore/investigate）的阶段都不通过；过于模糊 → 补充细节（文件路径、确切的方法名），过于庞大 → 拆分为并列阶段/子计划——原因：无法立即据此编写代码的计划还没有准备好。 强制重要，必须注意：先检测计划类型（Phase 0）——修复缺陷的计划必须包含行为变化矩阵（≥3 行，≥1 行在缺陷报告范围之外；任何 REGRESSION → 不通过，直到有测试覆盖该行为的保留）；安全/性能/重构/契约/基础设施计划各自都要增加对应的审查重点。 强制重要，必须注意：安排 spec-loop——计划必须为每条 [HARD] §4 规则／§5 不变量安排属性/不变量测试规范，并设定 MUTATION-SCORE 质量门槛；若计划设定的是行覆盖率百分比，而非变异分数门槛，则不通过。 强制重要，必须注意：存在任何发现时，必须先运行 $why-review --validate-findings，再编辑任何 plan.md/phase-*.md；仅在最小的责任位置修复经过验证的发现，然后用全新、零记忆的子 Agent 重新开始完整审查；重复此流程，直到干净通过；此关卡通过前绝不编辑计划文件——原因：未经验证的修复会损坏计划并浪费审查轮次。 强制重要，必须注意：轮次上限为 3——这是上限，绝不是目标：任何一轮干净通过，都应立即结束循环；如果同一阻碍在连续 2 次完整重新审查中仍无进展、进行到第 3 轮时仍有未解决的发现，或某项发现需要产品/负责人作出判断，则直接向用户升级询问。绝不超过 3 轮循环，也绝不把达到上限视为通过。 强制重要，必须注意：先建立任务跟踪并拆分任务，再进行读取/grep/编辑（每读取一个文件对应一个任务）；逐步将发现写入 plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md，并从磁盘整合；添加最终审查任务——原因：较长的计划文件会耗尽上下文，报告文件才是事实依据。 强制重要，必须注意：若 .code-graph/graph.db 存在，则对每项“要修改的文件”运行图追踪；将计划中未列出的任何下游文件标记为“可能遗漏”——原因：能发现作者忽略的跨服务/事件处理器影响。 强制重要，必须注意：维度 7——估算偏差：根据最终阶段文件，并遵循所采用的 SYNC:estimation-framework，重新推导 bottom_up_hours = Σ phase_hours，并与 frontmatter 对比。若 |delta| > 20%，frontmatter 必须包含 reestimate_delta_pct 和一行 reestimate_reason；缺少更新则不通过。若 |delta| > 50%，则标记 SHOULD-RESCOPE，并在实施前向用户说明重新界定范围的决定——原因：完成前的估算是基于范围猜测，而锁定阶段才最先显露实际成本。 强制重要，必须注意：维度 8——领域实体设计（有条件）：当计划涉及实体、值对象或聚合时，应用 SYNC:domain-entity-change-gate——即 $plan 编写计划时遵循、$changes-review 审查时遵循的同一套流程。任何未回答、含糊带过或推迟到实施阶段的决策点，都是一项发现，并须附上计划中的 file:line；任务中出现“实体”一词绝不能算作回答。确认范式和子域契合度已在任何实体任务之前明确说明，并且每个触发的行都指出其所属文件。不适用时，说明 No domain-entity surface — Dimension 8 N/A——原因：按数据库表或 UI 屏幕选择聚合边界，是实施后成本最高、最难逆转的决策。 强制重要，必须注意：独立运行结束时，直接向用户展示发现并提供后续选项；仅在工作流内部运行时才可跳过。 强制重要，必须注意：每项发现都要引用 file:line 证据（置信度 >80% 才采取行动，<60% 时不得建议）；只要规范/测试/代码之间存在不一致且未记录为发现，就绝不能标记为通过。 强制重要，必须注意：审查前阅读：.claude/docs/development-rules.md、docs/project-reference/code-review-rules.md、lessons.md，以及特定技能的模式参考资料（backend/frontend/integration-test）。 反合理化：

推托说法	反驳
“计划看起来合理”	结构 ≠ 正确性。用 file:line 证明每一条关于现有代码的说法；看似可信的文字不是证据。
“各阶段定义明确”	有阶段 ≠ 可实施。对每个阶段应用 5 点粒度门槛。
“审查一轮就够了”	仅在完成已验证问题的修复循环后重新审查；一次干净的 COMPLETE 审查即结束循环。
“实施时可以补上空缺”	现在就将含糊的步骤判定为 FAIL——实施是执行计划，而不是凭空编造计划。
“已经考虑过其他方案”	它们是真正的备选方案，还是故意设置的稻草人？请公正有力地阐述被否决方案。
“风险已得到管理”	“密切关注”不是缓解措施。要求明确行动、负责人和触发条件。
“已经追踪过代码”	提供 file:line / grep 证据。没有证据 = 没有追踪。

[TASK-PLANNING] 行动之前，分析任务范围，并使用任务跟踪系统地将任务拆分为小型待办任务和子任务；添加最终审查任务。

---

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

重要，务必注意目标： 阻止任何计划进入实施阶段，除非它既无幻觉（有 file:line 证据），又可直接实施（阶段具体且足够小）——持续循环，直至审查通过。 重要，务必注意： 以怀疑者的态度进行审查——每条关于现有代码的说法都必须有 file:line 证据；含糊或规模过大的阶段一律判定为 FAIL；修复 bug → 行为差异矩阵。 重要，务必注意： 编辑计划文件之前，先通过 $why-review --validate-findings 验证发现的问题；只修复已验证的问题；重新开始完整审查，直到没有任何问题。

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

来源：.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、业务实体、功能规则。泄漏进来后，代码能够编译并运行，因此会悄无声息地通过审查，同时让“可复用”层与某个使用方耦合。保持共享类型与领域无关；通过子类/组合将领域字段/逻辑下放到使用方。——原因：与某个使用方的领域耦合的层不再可复用。