why-review

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会将旧版 Claude /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 Spec
• 集成测试实现／审查：integration-test-reference.md
• E2E 测试实现／审查：e2e-test-reference.md
• 代码审查／审计：code-review-rules.md 以及根据变更文件选择的领域文档

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

[目标提醒 — 必须高度重视]

确保每个审查目标都合理、正确、有证据支持，并符合最佳实践。 始终提出 3 个权衡问题（针对你做出的每一项决策和每一条建议）：（1）是否存在权衡？——指出牺牲了什么；回答“没有”意味着分析尚未完成，不能算作答案；（2）是否值得？——比较收益与成本，明确由谁承担、何时承担 → 值得 / 不值得 / 不明确；（3）权衡是否重大到需要向用户确认？——不可逆、成本转嫁给他人、以一种质量属性换取另一种、越过边界、高后果路径，或情况不明确 → 停止，并在给出结论前直接询问用户。绝不能默默决定重大权衡。——原因：只说出好处却不提代价，是在背书，而不是审查；单向门是否迈入，应由用户决定，而不是由你决定。 **强制第二轮（完整模式）：**只要第一轮产生任何发现，就必须再次调用 $why-review --validate-findings，对这些发现进行确认，确保每一项都正确合理，然后才能移交。绝不能跳过，也绝不能为逃避验证而压下、降级或少报发现。作为完整模式的首个动作，必须启动自递归审查循环——主要通过协议循环（不依赖宿主），并在可用时辅以 /goal Stop-hook 门禁——阻止流程在发现通过验证前结束。——原因：未经验证的发现只是未经证实的主张；第二次自我审查可以发现第一轮自圆其说后产生的误读和夸大。

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

快速摘要

**目标：**解决用户要求的审查目标，并采用相应的对抗性审查路径（计划 / PBI 理由、代码变更、文档 / 规范 / 报告、发现或明确指定的工件），确保决策、发现和计划经得起对抗性理由审查，然后再开展后续工作。

摘要：（速读版——概述此技能的用途和全部主要步骤）

• 目的——担任对抗性理由审查者：每项计划／PBI／差异／文档／规范／报告／发现都必须在后续工作开始前通过 SKEPTIC 审查；成功指标是易于更改（降低未来的更改成本，或予以拒绝）。每项发现都必须附有 file:line、严重性和置信度。
• 步骤 1——先检测模式（递归控制）：--validate-findings 是终端模式——绝不重新调用 $why-review，绝不运行门禁，也绝不生成子 Agent；完整模式可以在 validate-findings 模式下调用自身一次。这是不可妥协的防护措施。——原因：在终端模式下执行其中任何操作都会导致无限循环。
• 步骤 2——完整模式的首要操作 → 绑定自递归审查循环：协议循环是主要且与宿主无关的绑定方式（自行驱动审查 → 验证 → 协调 → 完整复审，直到 CLEAN 且没有新发现；最多返工 2 次，然后升级处理）；/goal 门禁是在可用时调用的可选加速器（缺少它绝不会削弱循环）——绝不在终端模式下绑定它；“自行修复”=协调本次审查的自身发现集，而不是代码。然后执行任务引导：创建阶段任务 + 必须包含的“发现验证门禁”收尾任务。
• 步骤 3——审查前确定目标类型（提交／PR／差异 → 代码变更；PBI／规范／文档 → 产物；“没有活动计划”仅适用于尚未解决的计划理由请求——绝不悄然转换），读取活动目标契约，然后按关注点路由（code-reviewer / security-auditor / performance-optimizer / general-purpose）。目标中包含集成测试时 → 应用集成测试审查关联机制（读取 $integration-test-review 的 8 项门禁，或在独立完整模式下委派）——在其 4 行递归防护条件下跳过。
• 步骤 4——以 SKEPTIC 身份审查 → 完成全部 7 项反偏见门禁（为被否决的替代方案构建最强论据 · 未考虑过的替代方案 · 反方论据 · 对假设施压 · 事前验尸 · 正反优缺点对称分析 · 权衡审问门禁）+ 验证清单（检查存在性和质量深度）+ 第 2 轮复审；交叉核对规范↔测试↔代码——任何不一致的一方都是一项发现；存在本身绝不代表通过。
• 权衡门禁——对每项决策和每条建议都必须提问：（1）**是否存在任何权衡？**说清楚牺牲了什么——“没有”意味着分析尚未完成，因此要说明检查过哪些维度；（2）**是否值得？**比较收益与成本、由谁承担、何时承担 → 值得／不值得／尚不明确；（3）**影响是否重大到需要向用户确认？**不可逆 · 成本转嫁至别处 · 牺牲质量属性 · 越过边界 · 高后果路径 · 尚不明确 → 停止，并在给出结论前直接询问用户以确认。输出 Trade-Off Assessment 表格；重大权衡未经确认 = 绝不通过。
• 步骤 5——对自身发现运行发现验证门禁（任何严重性均适用）：重新调用终端模式 --validate-findings，进行协调，并重新执行完整审查，直到 CLEAN 且没有新发现（最多 2 次），然后直接询问用户下一步（+ 视条件调用 $llm-council）。双重反馈：会改变行为的发现必须同时包含规范偏离结论（CODE-WRONG / SPEC-STALE / AMBIGUOUS / SPEC-SILENT / in-sync）和测试反馈操作；SPEC-SILENT 还必须补充 §4 BR／§3 AC + §8 TC——缺少任何一项都属于 HAS-ISSUES，绝不能标记为 clean。

**工作流：**检测模式／目标 →（仅完整模式）绑定自递归审查循环（协议优先；可用时选用 /goal 加速器）→ 路由路径／文档／图／子 Agent 关注点 → 审查维度／对抗性门禁／易于更改 → 通过终端模式 --validate-findings 验证发现 → 协调 + 全面完整复审，直到 CLEAN 且没有新发现（最多返工 2 次）→ 在完整模式下询问下一步。 关键规则： 必须先确定目标类型，再进行审查。每条发现都必须包含 file:line、严重性、置信度和最佳实践依据。每次做出决定和提出建议时，都必须询问 3 个权衡问题（是否存在权衡？是否值得？影响是否重大 → 向用户确认）；绝不能未经审视就接受“没有权衡”，绝不能默默决定重大权衡。除非用户要求说明尚未解决的计划理由，否则绝不能说“没有进行中的计划”。绝不能从 validate-findings 调用 $why-review。必须依据易于更改原则进行判断：降低未来更改成本，否则就否决。

你的任务

$ARGUMENTS

审查模式（先检测——控制递归）

在进行任何审查工作之前，根据 $ARGUMENTS 检测模式：

模式	$ARGUMENTS 中的触发条件	执行内容	递归
full（默认）	不包含 validate-findings 标记	完整的设计理由审查（下方的验证清单 + 对抗性轮次），然后执行发现验证关卡收尾任务——该任务会以 validate-findings 模式重新调用本技能，审查其自身的发现。	可在同一会话中以 validate-findings 模式调用自身一次。
validate-findings	$ARGUMENTS 包含 --validate-findings / mode=validate-findings / validate findings in	仅针对所提供的发现/报告执行发现验证流程——验证每条发现是否正确、有证据支持、合理且符合最佳实践；指出遗漏的改进项；给出 CLEAN / HAS-ISSUES 结论。	**终止模式——绝不调用 $why-review，绝不运行关卡，绝不启动子 Agent。**停止递归。

递归保护（不可协商）： validate-findings 模式会终止。不得调用 $why-review 或验证关卡——以防止无限递归。返工循环由调用方负责，最多返工 2 次，在同一主 Agent 会话中进行，绝不启动子 Agent。

在 validate-findings 模式下：跳过完整验证清单、对抗性轮次、任务初始化和后续步骤评审关卡。直接跳转到发现验证流程，输出结论并返回调用方。

绑定自递归审查循环（完整模式 — 模式检测后的首要操作；协议优先，/goal 可选）

务必注意： 仅在完整模式下，模式检测后的首要操作 — 在任务初始化之前、任何审查工作之前 — 都必须绑定此技能的自递归审查循环，确保在本次审查的所有发现都经过验证，且整体重新审查未发现新问题（或触发有界升级）之前，不能停止。循环由两层绑定：协议循环（主要层，不依赖宿主）和可选的 /goal 加速器。正确性由协议循环保障 — 项目规则规定，钩子和命令仅为加速器，因此缺少 /goal 绝不会削弱循环。

入口条件：

• 在完整模式下运行（不含 validate-findings 标记）。
• 在 validate-findings 终止模式下跳过 — 此模式只向调用方返回判定，不得绑定循环、安装目标、创建收尾任务或循环（递归保护）。不记录任何内容。

1. 协议循环 — 始终绑定（不依赖钩子/命令）。 作为正在运行的 Agent，你有责任确保自己不会停止，直到循环收敛或触发有界升级。无论 /goal 是否存在，这项要求对 Claude、Codex 和 Copilot 一视同仁：

对整个目标运行完整的对抗式审查（验证清单 + 两轮对抗审查）→ 对发现运行 $why-review --validate-findings → 调和（删除未证实/夸大的发现，补齐证据缺口，添加新发现/改进项）→ 将调和后的发现与整个目标结合起来，重新运行完整审查（而非仅重新检查有变动的发现）→ 持续循环，直到完整一轮审查未产生任何新发现，且验证结果为 CLEAN；或有界阻碍触发升级。最多进行 2 轮返工，之后直接询问用户以升级处理。若仍有发现未验证，或重新审查可能产生新发现，则不得停止。

在「发现验证关卡」处，将此视为必须持续遵守的义务，并重新阅读 — 不要把它当作一次性说明，在首次审查后就自行找理由放弃。

2. /goal 命令 — 可用时作为加速器调用。 如果存在 /goal 命令，且允许你在此环境中运行，则还必须调用它（实际执行命令，不能仅改述，也不能用 Goal Contract 文件替代），并传入能体现此技能自递归循环的条件，让会话 Stop 钩子以机械方式强制执行：

/goal why-review self-recursive loop: run the full adversarial review (Validation Checklist + both Adversarial Rounds) over the whole target → run $why-review --validate-findings on the findings → reconcile (drop unproven/inflated findings, fix proof gaps, ADD surfaced findings/enhancements) → re-run the FULL review over the WHOLE target combined with the reconciled findings (not just re-checking the changed findings) → loop until a complete pass yields zero new findings and validation returns CLEAN, or a bounded blocker escalates. Max 2 re-do rounds, then escalate by asking the user directly. Do not stop while a finding is unvalidated or a re-review would surface new findings.

/goal Stop 钩子会阻止停止，直到满足条件，并在条件满足时自动清除 — 不要让用户清除它。

如果 /goal 不可用、未注册或不允许使用（例如 Codex/Copilot，或未配置该命令的 Claude 运行环境）：不要报错、不要阻塞，也不要虚构替代关卡。在记录审查情况的位置添加一行（收尾的「发现验证关卡」任务，或现有的 Goal Contract）：/goal accelerator unavailable — review loop bound by protocol (above)，然后继续。协议循环本身就是关卡，由纪律而非钩子来强制执行。

why-review 修正的是自身的发现集合，而非代码。 此处的「自我修正」是指调和发现报告，确保所有保留的发现均正确、有证据支持、合理且符合最佳实践，并且没有遗漏 — 这与「发现验证关卡」运行的循环相同，现在由目标关卡确保无法放弃。代码/规格/测试的修正仍由调用方负责；此技能仅用于审查。

任务初始化（完整模式 — 在技能开始时执行）

开始审查前，创建任务跟踪阶段任务和必需的收尾任务：

• [Why-Review] 绑定自递归审查循环 — 以协议为主；可用时可选用 /goal 加速器（仅完整模式） — 进行中 （强制首项任务 — 在 validate-findings 模式下跳过）
• [Why-Review] 发现验证关卡 — 如果存在任何发现，对其运行 $why-review --validate-findings；重复执行，直到结果为 CLEAN（最多 2 次） — 待处理 （强制收尾任务）

在开始时创建。将收尾任务保持为 pending，直到存在发现；然后在技能完成前执行。在 validate-findings 模式下，不要创建这两个任务。

首要原则 — 易于变更

成功指标：未来的变更成本。 DRY、SRP、抽象、设计模式、命名、分层和测试，都是为了降低下一次变更的成本。

审查代码、重构、测试或抽象时，思考：这会让下一次变更更便宜还是更昂贵？

• 否决那些会提高变更成本的“最佳实践”：过早抽象、推测性泛化、泄漏的间接层、没有收益的繁文缛节。
• 在发现中指出真正的问题：耦合、隐藏状态、重复知识、意图不明、过早暴露的不可逆决策。
• 优先选择简单、易于变更的设计，而不是复杂、难以变更的设计。

在应用以下任何规则或清单之前，先遵循此原则；如果下游规则会提高变更成本，以此原则为准。

---

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

默认立场：质疑，而非验证。你的任务是找出问题，而不是确认正确之处。

确认偏误陷阱： 阅读一份连贯的计划后，AI 会自然地寻找赞同的理由。当前上下文（计划之后、修复之后）会加剧这一点——你已经看过其中的推理，也已经为其合理化。本节旨在打破这种循环。——原因：已经认可过某种推理的审查者，若不强制重置，就无法同时对其保持怀疑。

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

技巧	思考
钢人论证	为被否决的方案辩护。拥有 10 年领域经验的资深人士会选择它吗？如果会，否决它就需要更有力的证据。
为什么不选？	对每个“因为 Y 而选择 X”，都要问 X 有哪些取舍。
假设压力测试	列出最重要的 3 项假设；如果假设错误，会有什么影响？强有力的计划即使 3 项中有 2 项不成立，也能站得住脚。
事前验尸	假设 3 个月后生产环境发生故障；写出一个合理的情景。
未考虑的替代方案	找出 1–2 种未提及的方案；如果没有解释为何排除这些方案，说明覆盖不足。
利弊对称性	统计所选方案的优缺点。优点与缺点之比超过 2:1，通常意味着存在偏见。
逆向审查	在给出发现或结论前，用 2 句话论证相反结论；选择论据更有力的一方。
权衡审问	提出以下 3 个问题：是否存在权衡？·是否值得？·是否重要到需要向用户确认？

禁止模式

禁止模式	必须进行的修正
“看起来不错，因为……”	先说明挑战。
有就是好	检验质量深度；考察真实替代方案和因果依据。
理由含糊	要求提供指标和成本：在哪些方面更好，代价是什么？
权衡分析不对称	将 3 个优点 / 1 个缺点视为分析不完整。
“看起来没问题”	提供对抗性挑战的证据。
“没有权衡” / “纯粹是利好”	说清楚检查了哪些维度，以及为什么每个维度都不受影响；未检查不等于不存在。
重大权衡被悄然决定	直接询问用户，将决定升级给用户；绝不能擅自跨过单向门。

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

撰写最终结论前，完成全部 7 项检查（必须注意）：

• 为至少一个被否决的替代方案提出最有力的论据（论证其可取之处）
• 找出至少 1 个计划中未包含的替代方案
• 列出 2-3 条反对所选方案的论据
• 揭示 2-3 个隐藏假设，并进行压力测试
• 进行事前验尸（设想一个具体的失败场景）
• 检查优缺点是否对称
• 进行下方的 权衡审问关卡（明确权衡 · 判断是否值得 · 决定是否需要因其重要性升级处理）

任何一项检查未完成 → 对抗性审查尚未完成。返回并继续。

权衡审查关卡（强制要求——未经此步骤，不得给出结论、发现或建议）

[BLOCKING] 每次都要问这三个问题——既针对正在审查的决策，也针对你提出的每一项建议。——原因：只提好处、不提代价的审查是在背书，而不是审查；最大的权衡往往正是没人写下来的那些。

1. 是否存在权衡？ 说清楚这项决策／建议牺牲了什么。每个选择都必然以某些东西换取另一些东西。“没有”不是可接受的答案——这代表分析尚未完成。若要声称不存在实质性权衡，请说明你检查了哪些维度，以及为什么每个维度都不受影响：

未来变更成本 · 复杂性 · 性能／延迟 · 内存／成本 · 耦合 · 可逆性 · 迁移负担 · 运维负担 · 影响范围 · 安全态势 · 可测试性 · 团队技能／上手时间 · 交付时间 · 用户体验。

2. 值得吗？ 明确权衡收益与牺牲——获得什么 · 付出什么代价 · 谁来承担 · 代价何时到来——然后给出一个结论：值得 / 不值得 / 不明确。以易于变更为准则：凡是会提高未来变更成本的权衡，都需要相称且明确的回报，不能含糊其辞。没有指标和成本的“更好”无法通过此项审查。

3. 这项权衡是否足够重大，需要向用户确认？ 重大权衡应由用户决定，而不是由你决定。符合下表中任意一项时，即为重大：

权衡满足以下条件时视为重大	示例
不可逆——单向门	数据迁移、公共 API／契约形式、存储格式、框架／供应商锁定
将成本转嫁给他人	其他团队、运维／值班人员、未来的维护者、最终用户
以一种质量属性换取另一种质量属性	正确性↔速度、安全性↔便利性、延迟↔成本、简单性↔灵活性
跨越边界	客户端↔服务端层边界、服务契约、事件契约、共享库
位于后果严重的路径上	身份验证、资金、数据完整性、破坏性变更、高／中残余风险
无法提供证据（“是否值得”的结论 = 不明确）	根据现有证据无法量化收益或成本

• 重大 → 停止，并直接询问用户以确认，之后才能确定结论：说明这项权衡、两个选项、各自的牺牲，以及你的建议。绝不能代替用户悄悄解决重大权衡，也绝不能将其埋在低严重性备注中。
• 不重大 → 在“权衡评估”表格中就地记录，并用一句话说明理由后继续；无需升级处理。
• 在 validate-findings 终端模式下：进行评估并记录，但不要升级处理——该模式不提出问题（参见“后续步骤”豁免条款）；在结论中标出未升级处理的重大权衡，以便调用方升级处理。

输出： 每次审查都必须包含 Trade-Off Assessment 表格（参见“输出格式”）——每项受审查的决策和你提出的每项建议各占一行。若存在发现但表格为空，则审查不完整。

目标解析（请在评审前完成）

分析用户请求，而不只是看其字面参数形式。确定目标，然后选择匹配的路径。

用户请求／证据	评审路径	必须执行的目标工作
明确指定计划目录、plan.md、阶段文件	计划依据评审	阅读 plan.md 和所有 phase-*.md 文件。
PBI／故事／规格规划产物、要求评估依据	PBI／产物依据评审	阅读指定产物及相关的验收／设计／风险部分；若其中引用了计划文件，也要阅读这些文件。
提交 SHA、Commit: ...、PR／合并提交、git diff	代码变更评审	确定差异范围，阅读已更改的文件，在可用时运行图影响分析，并遵循代码评审／对抗性评审协议。
分支比较或未提交的更改	代码变更评审	使用请求指定的分支／差异或 git diff；阅读已更改的文件，以及差异涉及的测试／文档。
文档／规格／报告／发现项路径	产物评审	阅读目标产物，并根据源证据核实其中的说法；仅当产物是计划／PBI 时，才使用依据检查清单。
请求含糊不清	根据证据推断；若不安全则提问	优先根据请求和代码库证据选择合理目标。只有当两条合理的评审路径会导致不同工作时，才提问。

重要默认规则：

1. 提交哈希／Commit: ... 区块 => 代码变更评审，而不是“未找到有效计划”。
2. PBI 文件 => 评审该 PBI／产物；无需套用 plans/**/plan.md。
3. “未找到有效计划。请先运行 $plan。”仅适用于尚未确定目标的计划依据评审请求。
4. 必须记录目标类型、证据和置信度；绝不能悄然转换目标类型。

主动目标读取（评判依据前）： 按照 goal-contract-satisfaction-loop 协议解析有效的 Goal Contract（有效计划中的 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md）。存在时，应根据已保存的 Original Request、Purpose、Success Criteria 评审产物的依据——标出那些为已保存目标从未要求的工作辩护的理由，以及产物的论证未涵盖的已保存必需条件。不存在时，记录 No active goal — rationale reviewed against the current request only. 仅限完整模式；--validate-findings 终端模式跳过此读取。

审查重点路由

检测到的问题	主要重点／子 Agent 路由
源代码／差异	code-reviewer + 内嵌的代码审查协议。
目标中的集成／端到端测试，或代码变更涉及有集成测试覆盖的行为	应用下方的 集成测试审查关联 — $integration-test-review 负责 8 项测试质量关卡；本技能读取其协议（模式 A）或委派给它（模式 B），绝不重新推导这些关卡。
身份验证、密钥、权限、数据	如有 security-auditor，则使用；否则由 code-reviewer 明确执行安全审查。
延迟、规模、内存、查询	如有 performance-optimizer，则使用；否则由 code-reviewer 明确执行性能审查。
计划／PBI／文档／规范	使用 general-purpose，并说明理由／产物维度。
混合目标	按问题拆分为有针对性的审查；所有审查完成后汇总发现。

代码变更审查路径

当目标是代码变更时：

1. 确定差异来源：
   • 提交 SHA：使用 git show --name-status，并与其第一个父提交进行差异比较。
   • 合并提交：默认与第一个父提交进行差异比较，除非用户指定其他父提交／范围。
   • 分支／范围：使用用户提供的范围。
   • 未提交的变更：使用 git diff，并在相关时纳入暂存区差异。
2. 理解变更上下文 + 跟踪跨越 BOTH 边界的完整流程（代码变更目标必须执行；纯计划／PBI／文档目标不适用）。 在深入评判文件之前，先写一行变更上下文（内容 · 意图 · 起始层级 · 主要受影响流程），然后应用下面内嵌的 BOTH 个代码块：SYNC:cross-stack-impact-trace 用于客户端↔服务器层级边界（BE→FE 正向，FE→BE 反向），SYNC:cross-service-check 用于微服务／事件／外部／松耦合边界。将每个边界／接触点归类为 NONE / ADDITIVE / BREAKING；若某个 BREAKING 边界的另一侧消费者未在同一差异中更新，则属于 HIGH-min 发现。若不存在跨边界，则注明 Single-tier / monolith — N/A。
3. 阅读变更文件，以及证明行为所需的附近测试／文档。
4. 集成测试检测（有条件）。 如果目标包含集成／E2E 测试文件，或变更了有集成测试覆盖的行为代码，则在评判 Test/spec/doc sync 维度之前，运行下面的 Integration-Test-Review Linkage。如果两种情况都不成立，则注明 No integration tests in target — linkage N/A。
5. 根据变更的文件类型，阅读项目参考文档，然后再评判模式。
6. 如果 .code-graph/graph.db 存在，则在得出结论之前，对关键变更文件运行图影响范围分析或跟踪。
7. 按顺序进行专注审查，应用内嵌的代码审查协议：错误检测、设计模式质量、逻辑／意图、测试／规范验证、图分析、易于修改性。
8. 优先输出发现，附上 file:line 证据、严重性、置信度，以及测试／文档缺口。

集成测试审查关联（有条件 — 仅供参考，设有防护）

目的： 此技能的 Test/spec/doc sync 维度会询问 “测试／规范／文档是否提供证据，证明预期不变量受到保护？” — 但回答此问题的 8 道关卡（断言价值 · 数据状态 · 可重复性 · 领域逻辑 · 规范可追溯性 · 三方同步 · 变更覆盖 · 场景真实性）属于 $integration-test-review。请转交给该负责方；切勿在此重新推导出一个较弱的副本。—原因：仅凭阅读理由来评判测试质量的审查，会认可从未经过变异测试验证的断言。

递归防护 — 任意一行成立时，完全跳过。 记录延期处理说明，然后继续；切勿调用或读取：

抑制上下文	依据	需记录的推迟说明
模式为 validate-findings	终止模式——完全不调用子技能	Linkage N/A — validate-findings is terminal.
由 $integration-test-review 第 9 阶段调用	它在 integration-test-review/SKILL.md:429-431 调用此技能，并在 :438 对反向边进行防护	Linkage deferred — invoked by $integration-test-review Phase 9.
在任意阶段由 changes-review 调用——包括 0.8 并行理由维度、6 validate-findings 或 7.5 整体审查——或在 $workflow-review-changes 内部调用	changes-review/SKILL.md:395（第 0.8 阶段，其中将此推迟说明列为对子 Agent 的约束），:867（第 6 阶段），:938（第 7.5 阶段）；其第 3.7 阶段（:608-626）已负责此关卡	Linkage deferred to changes-review Phase 3.7 / parent workflow step.
由 $debug-investigate 的根因验证关卡调用	debug-investigate/SKILL.md:151；在 integration-test-verify-loop 内部，该关卡会在已运行 $integration-test-review 的轮次中触发（integration-test-verify-loop/SKILL.md:98,110,495）	Linkage deferred — debug-investigate gate; the verify loop owns the audit.

— 原因：若不加防护，此边会形成循环（why-review → integration-test-review → 第 9 阶段 → why-review），并重新引入 integration-test-verify-loop/SKILL.md:31 已修复的重复归属缺陷。

模式 A — 阅读协议（默认）。 阅读 .claude/skills/integration-test-review/SKILL.md 中的 §"The 8 Quality Gates"；将关卡 1-8 作为审查目标测试的视角。成本低——不会递归，也不会调用子技能。发现会连同 file:line 依据和严重级别，一并纳入本次审查的常规发现集。

模式 B — 委派给 $integration-test-review（升级）。 仅在以下条件全部满足时调用：未触发任何防护行 · 独立的完整模式审查 · 目标差异本身包含集成测试文件。其 GAP / SPEC-GAP 判定将作为普通发现，交由本次审查的发现验证关卡处理。

仅供参考，绝不阻断——符合此技能的 Enforcement: Advisory 范围；强制覆盖由 changes-review 第 3.7 阶段负责。— 原因：缺少此关联时，独立的理由审查会在不知不觉中跳过测试质量审查。

理由说明 / 产物审查维度

针对每个适用维度，分别进行一次重点审查；不要同时扫描所有维度。

维度	思考
目标契合度	我们是否基于证据和信心，解决了用户的要求？
目标一致性	理由说明是否服务于已保存的目标契约所规定的目的和成功标准，还是偏离了这些要求？
理由深度	备选方案是否真实、因果关系是否清晰、是否对称、是否考虑了各种假设？
权衡诚实度	这会牺牲什么，是否值得？这种权衡是否重要到需要向用户确认？未评估代价的收益说明理由存在缺口。
行为风险	在正常、错误、边缘和回滚路径中，哪些内容会失效？
跨边界影响	契约变更是否会影响另一客户端↔服务端层级（BE↔FE）的使用方，或松耦合的外部服务或事件使用方？（层级交界处 + 服务/事件）
测试/规范/文档同步	证据是否证明测试/规范/文档能够保护预期不变量，并避免过时的说法？
未来变更成本	建议是否减少了耦合、隐藏状态、重复内容和意图不明的情况？

验证清单

对于计划/PBI/产物理由审查，先阅读已明确的目标。如果是计划目录，请阅读 plan.md 和所有 phase-*.md 文件。检查是否存在，以及质量深度如何。

对于代码变更审查，请使用代码变更审查路径，而不要强行套用计划清单。仍须纳入对抗性分析、事前剖析、假设、证据和调查结果验证。

规则： 仅仅存在并不代表通过。某个章节即使存在，但其中的论证薄弱、不对称或未经验证，也无法通过质量深度检查。

必需章节（在 plan.md 或阶段文件中）

#	章节	是否存在检查	质量深度检查（对抗性）
1	问题陈述	用 2-3 句话描述问题	问题的范围是否界定得当？是否可以用不同方式表述，从而引出不同的解决方案？是否把症状误认为了根本原因？
2	考虑过的替代方案	至少列出 2 个替代方案及其优缺点	替代方案是否切实可行（而非稻草人论证）？领域专家是否会认真考虑每个方案？是否列出了所选方案的缺点，而不仅是其他方案的缺点？
3	设计依据	明确说明决策与权衡之间的关联	推理是否体现因果关系（X 导致 Y），还是仅作描述（X 更好）？是否揭示了隐藏假设？是否考虑了失效模式，而不仅是成功模式？
4	风险评估	每个阶段至少列出 1 项风险	风险是否按严重程度分级？缓解措施是具体行动，还是模糊意向（“密切关注”）？是否至少有一项关于方案本身（而非仅执行过程）的风险？
5	负责人	明确合并后由谁维护代码	隐式注明也可以（由作者负责），明确注明更好

剩余风险门槛

• 质疑范围过宽、被否决的替代方案论证不足，以及任何高/中风险。
• 高/中风险必须修复、降低，或由用户/负责人明确接受后才能通过。
• AI 提取的规范/测试用例不能作为有效证据，除非规范所有者/审核门槛已接受这些内容。

可选（缺失时标记，不判失败）

#	章节	适用条件	质量深度检查
6	运维影响	服务层或 API 变更	是否定义了回滚步骤？回退后会导致什么故障？
7	跨服务影响	涉及多个微服务的变更	是否确定了所有下游使用方？需要通知谁？
8	迁移策略	数据库架构或数据变更	是否有回滚方案？是否已用数据样本进行测试？

输出格式

## Why-Review Results

**Plan:** {plan path}
**Target Type:** {plan/PBI/code changes/docs/spec/report/artifact}
**Target:** {path, commit, branch range, or artifact}
**Date:** {date}
**Verdict:** PASS / NEEDS WORK

### Checklist

| #   | Check                   | Presence  | Quality Depth | Notes                                                                |
| --- | ----------------------- | --------- | ------------- | -------------------------------------------------------------------- |
| 1   | Problem Statement       | ✅/❌     | ✅/⚠️/❌      | {what's strong / what's weak}                                        |
| 2   | Alternatives Considered | ✅/❌     | ✅/⚠️/❌      | {are they real or strawmen?}                                         |
| 3   | Design Rationale        | ✅/❌     | ✅/⚠️/❌      | {causal or just descriptive?}                                        |
| 4   | Risk Assessment         | ✅/❌     | ✅/⚠️/❌      | {concrete mitigations or vague?}                                     |
| 5   | Ownership               | ✅/❌     | ✅/⚠️/❌      | {details}                                                            |
| 6   | Bugfix Debugger Trace   | ✅/❌/N/A | ✅/⚠️/❌      | {final state, feeder paths, hypothesis matrix, owner, forward proof} |
| 7   | Trade-Off Gate          | ✅/❌     | ✅/⚠️/❌      | {trade-off named? worth-it verdict? material → user confirmed?}      |

> ✅ Strong ⚠️ Weak/Partial ❌ Missing

### Adversarial Analysis

**Strongest arguments AGAINST the chosen approach:**

1. {argument 1 — cite specific plan text that weakens under this pressure}
2. {argument 2}
3. {argument 3 if applicable}

**Unexamined alternatives** (not mentioned in the plan):

- {alternative A} — why it might be worth considering
- {alternative B if applicable}

**Weakest assumptions** (if wrong, the plan breaks):

1. {assumption} — impact if false: {consequence}
2. {assumption} — impact if false: {consequence}

**Bugfix trace challenge** (required for bugfix, failed verification, stale/incorrect final output, regression, or behavior-changing fix plans):

- Observed final state and final reader proven? {yes/no/N/A}
- All feeder paths enumerated or explicitly bounded? {yes/no/N/A}
- Hypothesis matrix includes ruled-out and latent causes, not only the chosen cause? {yes/no/N/A}
- Owning fix layer protects all downstream consumers? {yes/no/N/A}
- Forward convergence proof and tests/proof mapping make the symptom impossible or detect recurrence? {yes/no/N/A}

**Pre-mortem** (assume it ships and fails in 3 months):

> {One concrete, plausible failure scenario based on the plan's approach}

**Pros/Cons symmetry:** Pros listed: {N} | Cons listed: {N} | Bias: {balanced / leans toward pros / leans toward cons}

### Trade-Off Assessment (MANDATORY — one row per reviewed decision AND per recommendation you make)

| #   | Decision / recommendation       | Trade-off — what it sacrifices                       | Gain (metric)   | Who pays, when     | Worth it?                         | Material?                          | Confirmed with user?       |
| --- | ------------------------------- | ---------------------------------------------------- | --------------- | ------------------ | --------------------------------- | ---------------------------------- | -------------------------- |
| 1   | {decision or my recommendation} | {sacrifice — or dimensions checked + why unaffected} | {gain + metric} | {payer / when due} | WORTH IT / NOT WORTH IT / UNCLEAR | YES / NO ({which materiality row}) | asked / N/A (not material) |

> Material trade-off with `Confirmed with user? = no` → verdict CANNOT be PASS. Escalate by asking the user directly first.

**Cross-Boundary Impact:** (code-change targets) {per client↔server seam AND per service/event/external touchpoint: NONE / ADDITIVE / BREAKING with routed fix; or `Single-tier / monolith — N/A`}

### Missing Items (if any)

- {specific item to add before implementation}

### Recommendation

{Proceed to $feature-implement | Add missing sections first | Add adversarial analysis to plan/PBI | Fix code findings | Update docs/specs | Continue manually}

第 2 轮：对抗性复审（强制）

协议： 深度多轮审查（通过上文中的 SYNC:double-round-trip-review 内联）

第 1 轮后，执行第二轮完整对抗性审查：

1. 假设第 1 轮错了——以“第 1 轮漏掉了某些内容。找出来。”开头。
2. 质疑第 1 轮中的每个 PASS 项——针对每项至少提出 2 句话，论证相反观点。
3. 完成反偏见关卡（对抗性审查思维模式部分中的全部 7 个方框，包括权衡审问关卡）。
4. 填写对抗性分析——必须包含：
   • 至少 2 条反对所选方案的论据
   • 至少 1 个未经审视的替代方案
   • 至少 2 个隐含假设及其失效后果
   • 事前验尸分析
   • 优缺点对称性计数
   • 权衡评估表——列出每项决策和每条建议：明确说明权衡、判断是否值得、决定其重要性；针对第 1 轮称为“无”的任何权衡，重新回答那 3 个问题：原因：第 1 轮最常见的疏漏是没有量化收益。
5. 聚焦第 1 轮的疏漏：
   • 容易被否定的替代方案（过于容易驳倒）
   • 表述含糊且缺少具体缓解措施的风险
   • 问题陈述本身隐含的假设
   • 伪装成“相关改进”的范围蔓延
6. 如果第 2 轮发现了新问题，更新结论。
7. 最终结论须兼顾两轮审查和对抗性分析。

范围

• 适用范围： 功能、重构、架构变更、提交/差异/代码变更、文档/规范/报告审查
• 仅对计划理由审查豁免： 微小配置变更，或在当前工作流允许记录跳过时的单文件微小调整
• 执行方式： 建议性（软性警告）——不会阻止实施

重要说明

• 仅审查——不要修改目标文件或实施变更
• 保持简洁——确保内容可在不到 2 分钟内执行
• 简单计划仍须通过反偏见关卡；审查结果可以简短，但不能跳过该关卡

---

发现验证关卡（完整模式 — 存在发现项时的强制收尾任务）

目的： 交接前，重新验证本次审查的所有发现项：是否正确、有证据支持、合理且符合最佳实践。发现问题并找出遗漏的改进项。

触发条件： 完整模式下，存在任何发现项、弱点、缺失项或 NEEDS WORK 结论时触发——无论严重程度如何（Critical、High、Medium 或 Low）。Medium 或 Low 严重程度绝不会让发现项免于验证；即使只有一条低严重程度的细微问题，也会触发此关卡。只有在结论为无条件 PASS，且发现项集合确实为空（不存在任何严重程度的发现项或缺失项）时，才能跳过；并记录跳过原因。绝不能在 validate-findings 模式下运行。——原因：“这只是 Low”本身就是一项严重程度声明，必须由验证环节确认，不能作为跳过的理由。

调用方的重新执行循环（有次数限制 — 由此处负责，而非 validate 模式）：

1. 确保将发现项写入报告（plans/reports/why-review-{date}.md）。
2. 在同一个主 Agent 会话中调用 $why-review --validate-findings plans/reports/why-review-{date}.md，不得使用子 Agent。每次调用均会结束。
3. CLEAN → 在报告中追加 ## Findings Validation 一行（“已重新验证全部 N 条发现项；它们均正确、有证据支持、合理且符合最佳实践；无需更改。”），关卡通过，退出循环。
4. HAS ISSUES → 协调处理：删除或降低缺乏证据支持或被夸大的发现项（包括任何未达到**≥85% 发现项留存率门槛**的发现项——参见 Findings Validation Routine 的 Confidence 门槛），补齐证据缺口，添加新发现项或改进项，重新推导结论，并记录 ## Findings Validation Notes，说明更改内容及原因。
5. 全面重新执行——由于协调后的发现项改变了整体情况，因此要基于协调后的发现项，对整个目标重新执行完整审查（Validation Checklist + 两轮对抗式审查），而不只是单独重新验证更改过的发现项；随后在更新后的报告上再次调用 $why-review --validate-findings。重复此过程，直到结果为 CLEAN 且未发现新问题，或达到最多 2 轮重新执行的上限。仍未达到 CLEAN → 记录未解决状态，标记为目标关卡阻塞项，并在 ## Next Steps 中直接询问用户以升级处理。

发现验证流程（validate-findings 模式正文 — 终止）

仅在 validate-findings 模式下执行。**终止：不要调用 $why-review，不要运行 gate，不要启动子 Agent，不要创建收尾任务。**验证、输出判定结果，然后返回。

读取提供的发现/报告（路径来自 $ARGUMENTS）。对每条发现、弱点、遗漏项、对抗性论点和假设，验证以下全部四项：

• 正确 — 重新追溯引用的计划文本 / file:line；该发现确实成立（不是误读或过期引用）。
• 有证据支撑 — 存在具体的 file:line 或引用的计划/报告章节；拒绝“可能 / 应该 / 我认为”。
• 合理 — 严重性/权重适度，不夸大；对反方观点作最有力的论证后，该问题依然成立。
• 符合最佳实践 — 建议符合项目惯例和易变更性指标（降低未来变更成本），而非个人偏好或推测性的泛化。
• 权衡已衡量 — 该发现的建议明确说明其牺牲了什么，给出“值得 / 不值得 / 尚不明确”的判定，并根据 Trade-Off Interrogation Gate 确定其重要性。将建议说成纯收益，或在没有经过各维度检查的论证时标注 Trade-off: none，均属验证失败——标记为 HAS-ISSUES，并指出未衡量权衡的建议。未与用户确认的重大权衡属于 HAS-ISSUES：指出该权衡，由 CALLER 升级处理（终止模式只评估，绝不提问）。判定为不值得 → 删除该发现或替换其建议，绝不能原样保留。——原因：修复成本高于所消除问题的修复方案，是评审本应撤回的发现。
• 双重反馈（仅适用于行为变更类发现） — 如果任何发现会改变可观察行为，确认该发现同时具备反馈的两个部分：(1) 规格偏差判定——CODE-WRONG / SPEC-STALE / AMBIGUOUS / SPEC-SILENT / in-sync（依据 SYNC:spec-drift-adjudication）——以及 (2) 具体的测试反馈操作（通过 $spec [mode=tests] 编写回归/保留 TC，或通过 $integration-test 编写覆盖测试）。缺少任一部分的行为变更类发现均属验证失败——标记为 HAS-ISSUES，并指出缺失的维度（spec verdict absent 或 test feedback absent）。判定为 SPEC-SILENT（代码正确强制执行了任何规格产物都未说明的不变量）时，规格维度必须采取规格补充操作——通过 $spec [update] + $spec [mode=tests] 添加 §4 BR / §3 AC 和 §8 TC；没有规格补充操作的 SPEC-SILENT 发现属于 HAS-ISSUES，与双重反馈维度为空相同。没有规格判定且无需补充 TC 的纯代码修复属于不完整发现，而非无问题发现。
• 置信度门槛（有别于 >80% 的行动门槛） — 只有当某条发现明确陈述的“该问题确实存在”置信度**≥85%时，才能保留。此门槛高于通用的 >80% 行动门槛，且所问的问题不同**：行动门槛问“我能否依据这些证据采取行动？”；此门槛问“这条报告的发现是否足够有力，值得保留？”置信度为 80-84% 的发现应降级或删除，不得保留。≥85% 的置信度必须基于上述有证据支撑的检查（引用 file:line + 追溯得到的失败路径）；仅凭推断得出的置信度低于此门槛。

然后查漏——再次应用 Adversarial Techniques：是否存在未审视的替代方案、隐藏假设或增强机会？

输出判定结果至 plans/reports/why-review-validate-{date}.md：

• CLEAN — 每条发现都通过上述所有检查，且没有发现新问题。
• HAS ISSUES — 列出每条应删除/降级/修复的发现（原因 + file:line），以及每条新发现/增强项（file:line）。

返回判定结果路径 + 状态。由 Caller 负责协调并进行有界的返工；此流程不会修改 Caller 的报告，也不会循环执行。

---

后续步骤

**在 validate-findings 模式下豁免：**终端模式会返回判定；跳过 ## 后续步骤，直接询问用户，进入 council gate。

**强制 — FULL MODE：**评审后，直接询问用户；后续步骤由用户决定。

**[阻塞] 重大权衡确认必须先进行。**Trade-Off Interrogation Gate 标记为 MATERIAL 的任何权衡（不可逆 · 将成本转嫁给他人 · 以一种质量属性换取另一种 · 跨越边界 · 高后果路径 · 是否值得尚不明确）都必须通过单独的直接提问向用户确认——说明权衡、两个选项、各自的牺牲，以及你的建议——且必须在后续步骤问题和任何 PASS 判定之前进行。若有多个重大权衡，先询问后果最严重的（每次调用最多 3 个问题），绝不要把它们捆在一个含糊的“继续吗？”问题里。——原因：未经确认就迈过的单向门无法退回，而只有用户有权做出这个决定。

• “$feature-implement (Recommended)” — 设计依据通过验证后开始实施
• “$plan-execute” — 如果要实现的是较简单的变更
• “Skip, continue manually” — 由用户决定

此外 — 按条件升级到 $llm-council

提出第一个后续步骤问题后，评估 gate：

1. **先检查工作流抑制条件：**读取 plans/.workflow-state.json 或等效的 workflowId。对于 workflow-refactor、workflow-bugfix 和 test-*，抑制 council。原因：council 需要 11 次 LLM 调用；这些工作流足够常规、可逆或仅涉及测试，适合使用 $why-review。这与 .claude/skills/llm-council/SKILL.md 中的“Workflow Integration”一致。
2. **Frontmatter gate：**读取有效的 plan.md 或 PBI frontmatter。符合以下任一条件时触发：cross_service_impact != NONE；breaking_changes；complexity in {high, critical} 或 story_points >= 13；new_framework；irreversible；security_critical；performance_critical；cost_high。
3. **覆盖项/默认值：**缺失字段默认不触发；council_suppress: true 会跳过提示并记录原因。

如果已抑制或未触发，不要提及 $llm-council。如果 gate 触发，提出一个单独的第二个后续问题：

• “升级到 $llm-council (Recommended)” — Gate 已触发（检测到高风险信号）。运行由 11 个子 Agent 组成的 council（5 位顾问 + 5 位评审者 + 主席）。当 $why-review 单独使用不足以应对时使用。此时，更便宜的替代方案已用尽：$plan-validate 是前一级方案。
• “跳过 — 不使用 council 继续” — 确认 gate 已触发；仍按当前决定继续。

[阻塞 — 仅限 full mode] 完成前必须主动提出至少一个用户问题。validate-findings 不提问，因为它只返回判定。 [重要] 工作前使用任务跟踪，包括读取文件的任务；简单任务必须记录跳过决定。 **关键目的：**确保质量：没有缺陷、错误、遗漏的更新或过时内容。验证代码和文档。 **外部记忆：**长时间评审应将中间结果和最终结果写入 plans/reports/。 **证据门槛：**每项声明、发现和建议都必须有 file:line 证明或追踪记录，这是强制要求，并标注置信度（>80% 采取行动，<80% 进行验证）。 **OOP 和 DRY 执行要求：**强制标记 3 处或更多重复模式以便提取；同组/同后缀类（*Entity、*Dto、*Service）在降低未来变更成本时应共享基类。 从结果回溯的调试追踪 — 对于复杂 Bug、验证失败、回归修复、会改变行为的代码或不清晰的代码流程，在提出修复方案前，先从观察到的最终状态开始向前回溯。

1. 帧 0：观察到的最终状态 — 明确指出用户可见的输出、失败断言、日志行、持久化值、API 响应、渲染的 UI 或聚合桶。记录生成该结果的读取器／查询／渲染器，并提供 file:line 证据。
2. 每次向前追溯一跳 — 追踪最终读取器 -> 投影／缓存／存储 -> 写入器 -> 消费者／处理器／任务 -> 生产者／调用方 -> 原始触发因素。每一跳都记录：输入、转换、输出、所属方和证据。
3. 列举所有上游路径 — 找出每个可能写入最终路径的上游生产者／调用方／事件／任务，包括重试、异步、缓存、后台和备用 UI/API 路径。将每条路径标记为已验证、已排除或仍未知。
4. 构建假设矩阵 — 对每个可能的原因，列出支持证据、反对证据、复现／验证方法、影响范围和状态（primary、contributing、ruled out、latent）。在明确解决或界定其他可能原因之前，不要修复。
5. 选择负责修复的层 — 找出不变量的所属方，以及能保护所有下游消费者的最低共享层。除非症状位置负责该不变量，否则不得在症状位置修复。
6. 正向证明收敛 — 选择修复方案后，再次从起点走到终点，说明修正后的状态如何到达观察到的最终输出。将每个根因对应到修复部分，并将每个修复部分对应到测试／证明。

完成以下事项前处于阻塞状态： 指明最终状态 · 写出回溯追踪 · 列出所有上游路径 · 完成假设矩阵 · 说明负责修复的层 · 将正向收敛证明对应到测试。

绝不允许： 从第一个可疑代码路径开始。将多个生产者合并成一条“流程”。未经证明读取模型，就把重复症状当作重复记录。跳过已排除的假设。

行为差异矩阵 — Bug 修复评审中必须提供。请在给出通过／失败判定前先生成此表。叙述性描述不能替代此表。

输入状态	修复前行为	修复后行为	差异
{condition}	{current behavior}	{fixed behavior}	已保留 ✓ / 已修复 ✓ / 回归 ✗

规则： ≥3 行 · 至少 1 行涉及 Bug 报告中未提及的情况 · 若差异为回归 → 判定失败，直到有覆盖该情况的保留行为测试（spec-tests-template.md#preservation-tests-mandatory-for-bugfix-specs）

完成以下事项前处于阻塞状态： ≥3 行 · 至少 1 行涉及 Bug 报告之外的情况 · 没有未缓解的回归

嵌套任务展开约定 — 对于工作流步骤调用，[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。 项目参考文档门禁 — 在任务跟踪初始化之后、读取目标文件或源文件、使用 grep、编辑或分析之前运行。项目文档优先于通用框架假设。

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/ 下的源 Feature Specs；架构/新领域需要 project-structure-reference.md。
4. 阅读所有必需文档，然后在开展目标工作前说明：Reference docs read: ... | Not applicable: ...。

准备就绪的条件： 已评估范围、已查阅 docs/project-config.json、已检查/阅读必需文档或完成设置流程、已确认 lessons.md，并已给出引用。 跨技术栈影响追踪 — 首要审查操作：先全面理解变更，再判断文件。每次审查差异时：记录变更背景，端到端追踪主要受影响区域的完整流程，跨越客户端↔服务端边界，确保一端的变更绝不会悄无声息地破坏另一端。（这不同于负责服务间／事件边界的 SYNC:cross-service-check；本项负责同一应用内部客户端↔服务端的技术栈边界；两者结合可覆盖完整流程。）

1. 先理解背景 — 逐个文件审查之前，先写一条简短的变更背景说明：变更内容、意图（原因）、变更发起层（前端／后端／共享／基础设施）以及主要受影响的功能／流程。必须在指出任何问题之前完成。
2. 识别跨技术栈边界 — 针对主要受影响区域，找出客户端与服务端之间的契约边界：API 路由／端点及方法、请求／响应 DTO 或负载结构、共享类型／模式、事件／消息契约、查询／路由参数。根据 docs/project-config.json 和项目惯例推断技术栈布局。
3. 沿变更方向端到端追踪完整流程：
   • 后端变更 → 向前追踪所有前端使用方： 处理器／控制器 → 响应 DTO／序列化器 → API 客户端／服务 → 存储／状态 → 组件／模板的渲染或提交。
   • 前端变更 → 向后追踪至后端契约： 组件／表单 → API 客户端调用 → 路由／端点 → 请求 DTO／验证 → 处理器／领域逻辑。
   • 当 .code-graph/graph.db 存在时，使用 $graph-connect-api 和 python .claude/scripts/code_graph trace <file> --direction both --json 映射关联；否则，在两端都搜索路由路径、DTO／类型名称以及每个字段名。
4. 确认两端仍然一致 — 对每个变更的边界，确认另一端相符：路由路径和方法、字段名和类型、可空性／可选性、必需与可选参数、枚举值、身份验证／权限、错误／状态结构。任何不一致都属于 BREAKING 问题（后端变更破坏前端使用方，或前端现在发送了后端会拒绝的内容）。
5. 对每个边界分类： NONE（无契约变更）／ADDITIVE（向后兼容）／BREAKING（另一端的使用方也必须变更）。若 BREAKING 边界的另一端使用方未在同一差异中更新，严重性至少为 HIGH（涉及身份验证／资金／数据完整性路径时为 CRITICAL）。

仅在变更不存在跨层边界时跳过 — 纯文档、无数据契约的纯样式变更，或单层工具。明确说明：Single-tier change — no cross-stack seam。仅涉及后端或仅有单层的代码库仍须追踪内部使用方（服务／事件边界使用 SYNC:cross-service-check）。

完成以下事项前不得通过： 已记录变更背景 · 已识别边界或明确标注 N/A · 已沿变更方向追踪完整流程 · 已将每个变更的边界分类为 NONE／ADDITIVE／BREAKING。 跨服务检查 — 微服务／事件驱动架构：在结束调查、计划、规范或功能文档前，必须执行。遗漏下游消费者会导致静默回归。

边界	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 · 已审查契约 · 已标记破坏性变更风险

任务跟踪与外部报告持久化 — 执行前先完成初始化；然后在处理目标／源文件前，预先读取项目引用文档。

1. 在读取目标文件、Grep 搜索、编辑或分析前，创建简要任务拆分。上下文丢失时，先检查当前任务列表。
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 设计、调试、架构）、进阶技巧（螺旋式完善、假设检验、收敛）和元策略（不确定性处理、修订级联）。

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

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

1. 每项主张都引用 file:line、grep 结果或框架文档
2. 声明置信度：>80% 可自由采取行动，60-80% 先核实，<60% 请勿推荐
3. 架构变更必须进行跨服务验证
4. “我没有足够的证据”是有效且预期的输出

以下事项完成前一律阻止： - [ ] 证据文件路径（file:line）- [ ] 已执行 grep 搜索 - [ ] 已找到 3 个以上相似模式 - [ ] 已声明置信度

无证据时禁止使用： “显然”“我认为”“应该是”“可能是”“这是因为” 如果信息不完整 → 输出："证据不足。已验证：[...]。未验证：[...]。"

已验证发现的修复与完整重新审查循环 — 由已验证发现的修复周期触发重新审查，而非由轮次数触发。审查目的：审查 → 验证发现 → 修复已验证的发现 → 完整重新审查，持续进行，直到某一轮完整审查通过退出标准（见下文的 严重性下限）。审查通过即结束循环——无需继续后续轮次。

又称 自我审查收敛循环。 该名称源于历史——没有两轮上限；“双轮往返”仅表示，修复已验证的发现后必须至少重新审查一次。循环将持续到审查通过，并受下文的 3 轮上限约束。

轮次上限——最多 3 轮（是上限，绝不是目标）。 无论在哪一轮（包括第 1 轮），审查通过都应立即结束循环；上限不会要求你继续循环。若到第 3 轮仍有阻塞性发现未解决（应用严重性下限后）→ 停止并直接询问用户以升级处理，列出仍未解决的发现；绝不能因达到上限而悄然给出“差不多就行”的 PASS，也绝不能让上限取代审查通过的要求。连续两次无进展即阻塞的规则仍是更早的退出条件——哪个条件先触发，就按哪个条件升级处理。

严重性下限——从第 3 轮起，LOW 不再构成阻塞。 退出标准会逐轮收紧，因此循环会聚焦于影响，而不是在表面修饰上反复打转： 在任何地方都定义同一个谓词：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，消除编排者的确认偏误。

原因： 主 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 次重复出现且没有进展，则直接向用户升级反馈
• 在对话上下文中跟踪迭代次数和重复出现的阻塞问题（仅限会话，不写入持久化文件）

审查协议注入 — 每个全新子 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
• 不得改述、总结或跳过任何协议部分
• 不得以内联方式传递文件内容——子代理会通过自己的工具调用读取文件，因此能获得全新的上下文
• 不得通过文件路径或标签名称引用协议——协议正文已嵌入上方
• 不得为协议引入占位符标记——协议正文必须保持展开后的原样

图谱影响分析 — 当 .code-graph/graph.db 存在时，运行 blast-radius --json，检测所有受变更影响的文件（7 种边类型：CALLS、MESSAGE_BUS、API_ENDPOINT、TRIGGERS_EVENT、PRODUCES_EVENT、TRIGGERS_COMMAND_EVENT、INHERITS）。计算差值：受影响文件 - 已变更文件 = 可能过时的文件。风险：<5 为低，5-20 为中，>20 为高。对于影响较大的文件，使用 trace --direction downstream 深入追踪依赖链。

严重性准则 — 根据后果对每项发现进行分类，而非依据修复难易程度。所有审查采用同一量表，因此“高”在任何地方都表示相同严重程度。

严重性	处理方式	定义
CRITICAL	阻止合并	静默运行时故障、数据损坏、绕过验证、安全漏洞
HIGH	必须修复	行为错误、不变量缺失、架构违规
MEDIUM	应当修复	设计债务、可维护性问题、可能导致未来错误
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，也绝不能将其埋没在低严重性备注中。

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

• MANDATORY 在开始目标工作前，先初始化任务跟踪；每次只转换一个任务的状态。

• MANDATORY 将计划和审查发现逐步保存到 plans/reports/，并从磁盘上的内容综合整理。

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

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

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

MUST ATTENTION 首项审查操作——记录变更背景，并全面追踪主要受影响区域的完整链路，贯穿客户端与服务端的交界处（BE→FE 正向，FE→BE 反向）。验证两端在路由/DTO/字段/类型/可空性/授权方面仍保持一致；任何不一致都属于 BREAKING 级发现。仅单层或仅文档变更可跳过（需说明）。

IMPORTANT MUST ATTENTION 微服务/事件驱动：扫描任务范围内的生产者、消费者、Saga 和契约。对每个接触点，记录：所有者 · 消息 · 消费者 · 风险（NONE/ADDITIVE/BREAKING）。遗漏消费者会导致静默回归。

IMPORTANT MUST ATTENTION 调试器追踪门禁：对于非简单的错误、修复、调查或审查工作，从观察到的最终输出开始，反向追踪 reader → storage/projection → writer → consumer/job → producer/trigger。修复前列出所有供给路径和假设。在具备追踪、假设矩阵、负责修复的层，以及正向收敛证明之前，工作不得继续。

• MANDATORY 父工作流中的条目不能替代子阶段跟踪；存在嵌套时，需展开阶段并关联父项。

• MANDATORY 编排器必须在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵守同一时间仅有一个 in_progress 的规则。

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

• MANDATORY 执行后追加迭代证据；报告 PASS 前，输出目标满足度矩阵（PASS/FAIL/BLOCKED）；对经验证的 FAIL 进行迭代；多次无进展或遇到阻碍时升级处理。绝 NEVER 在目标文件中存储机密信息。

• MANDATORY 按后果将发现分为 Critical/High/Medium/Low；Critical/High 级发现必须先修复或经负责人接受，才能判定为 PASS。

• MANDATORY 基于评分的技能（SRE 0-2、性能双轴）必须映射到相同的四个级别，不得使用另一套严重性术语。

Prompt-Enhance 收尾锚点

• IMPORTANT MUST ATTENTION 遵循此技能声明的步骤顺序；未经用户明确批准，绝 NEVER 跳过、调换或合并步骤

• IMPORTANT MUST ATTENTION 对每个步骤/子技能调用：执行前设为 in_progress，执行后设为 completed

• IMPORTANT MUST ATTENTION 每个跳过的步骤都必须明确说明原因；每个已完成的步骤都必须提供简要证据

• IMPORTANT MUST ATTENTION 如果 Task 工具不可用，则维护一个状态同步的等效逐步计划跟踪器

• 强制重要必须注意 执行审查循环（即 自审收敛循环）：审查 → 验证发现的问题 → 修复已验证的问题 → 完整重新审查。完整审查一轮且没有发现问题，即结束审查。任何新生成的输出／判断都至少要经过 1 次自审；任何新判断都必须至少经过 1 次 $why-review --validate-findings，验证后才能视为最终结果。

• 强制 执行 严重性下限：第 1–2 轮在任何严重性等级均无发现时即可结束；从第 3 轮起，标准为没有严重／高／中严重性问题——低严重性问题不再必须修复，因此仅有低严重性问题的一轮即可结束循环。 在报告中列出每一项延期处理的低严重性问题；绝 NEVER 不要为了达到退出条件而将实际的严重／高／中严重性问题降为低严重性，也绝 NEVER 不要将此下限用于二元门槛（测试通过、安全方面必须修复的问题）。

• 强制 执行 最多 3 轮的上限——这是上限，绝不是目标：任何一轮（包括第 1 轮）通过审查后没有问题，就立即结束循环；如果第 3 轮结束时仍有未解决的严重／高／中严重性问题 → 停止并升级处理，直接询问用户，绝不能默默给出通过结论。连续 2 次没有进展的阻断规则是更早的退出条件——哪个条件先触发，就在那一轮升级处理。绝 NEVER 无限循环。

• 强制必须注意，始终询问 3 个权衡问题——针对正在审查的事项以及你提出的每项建议：(1) 是否存在任何权衡？ 说清楚牺牲了什么（变更成本 · 复杂性 · 性能 · 耦合 · 可逆性 · 迁移 · 运维负担 · 影响范围 · 安全性 · 可测试性 · 交付时间 · 用户体验）——说“没有”／“纯收益”代表分析未完成，因此要说明已检查哪些维度；(2) 是否值得？ 将收益（附带指标）与成本进行比较，说明由谁承担、何时承担 → 给出 值得／不值得／不明确 的结论；不值得 → 撤回或替换该建议；(3) 其影响是否重大到需要向用户确认？ 不可逆／单向决策 · 将成本转嫁给其他团队／运维人员／维护者／用户 · 以一种质量属性换取另一种 · 跨越层级／服务／事件／库的边界 · 涉及身份验证／资金／数据完整性／破坏性变更／高或中风险路径 · 结论不明确 → 停止，并在给出结论前直接询问用户确认。

• 强制 未经用户确认的重大权衡绝不能判定为通过；绝 NEVER 将其隐藏为低严重性备注，绝 NEVER 默默做出决定，也绝 NEVER 让交付或收敛压力成为授权单向决策的理由。——原因：无法撤回的单向决策应由用户决定，而不是审查者。

• 强制——无法询问用户的情境必须通过交接升级，绝不能保持沉默。 直接询问用户只能由主交互 Agent 执行：子 Agent 无法询问用户，且仅输出终端结果／结论的模式按设计不会询问。在这些情境中，职责是转交而非免除——仍须指出权衡，仍须判断其重大程度，记录 confirmed? = NO — cannot ask from this context，在返回的结论／摘要中说明未经确认的重大权衡，以便调用方升级处理（只在磁盘报告中备注不算交接），且绝不输出无条件的通过结论。此规则仅适用于用户确实无法触达的情况（已生成的子 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 中匹配到的正文；缺失或格式错误的正文必须报告，绝不可重建。覆盖规则只能附加（绝不替换此技能自身的规则），并且只是简报，绝非权限升级；具体程度相同的规则若相互矛盾，必须提交给用户处理。

收尾提醒

**重要，务必注意目标：**确定请求的审查目标，并采用相应的对抗式审查路径（计划/PBI 理由、代码更改、文档/规范/报告、发现项或明确的产物），确保决策、发现项和计划经得起对抗式理由审查，再继续后续工作。

重要，务必注意主要步骤（完整模式）——技能 AI 总会忘记：（1）检测模式——--validate-findings 为终止模式；（2）绑定自递归审查循环——以协议循环为主（与宿主无关），在可用时可选用 /goal 关卡——加上任务引导（阶段任务 + 收尾发现项验证关卡任务）；（3）确定目标类型 + 阅读当前 Goal Contract + 按关注点路由；（4）以怀疑者立场审查——7 个反偏见检查项（包括权衡审问关卡：是否存在权衡？是否值得？是否重要？→ 与用户确认）+ 验证清单（检查是否存在且质量深度是否足够）+ 第 2 轮复审 + 规范↔测试↔代码三角验证；（5）发现项验证关卡——重新调用终止模式 --validate-findings，协调差异，并完整重做复审直至结果干净（最多 2 次），然后直接询问用户下一步。未经用户明确批准，绝不可跳过、调整顺序或合并任何步骤。——原因：这些步骤构成审查的完整性；删去任何一步，都会导致发布未经证实的结论。

**生效中的协议（所含 SYNC/共享区块的简要摘要）：**这些只是指引——上文的规范正文才具有约束力；务必遵守每一项，绝不可将摘要中的一行视为完整规则。

• 从终点到起点的调试跟踪： 对于复杂 Bug，从观察到的最终状态反向追踪到触发原因。
• 行为差异矩阵： 判定是否修复 Bug 时，必须提供至少包含 3 行的修复前后差异表，其中一行来自报告之外。
• 嵌套任务创建： 工作流中的任务行仍需展开为子阶段任务；存在嵌套关系时，链接到父任务。
• 项目参考文档： 在评判约定之前，先阅读适用范围内的项目文档（始终包括 lessons.md）。
• 任务跟踪与外部报告： 初始化任务；长时间审查的发现要逐步保存到 plans/reports/。
• 批判性思维： 每项主张都要追溯并有证据支持；只有置信度超过 80% 才采取行动，并始终保持自我质疑。
• 顺序思维： 多步骤思考须标记为 Thought N/M，并使用 REVISION/BRANCH/HYPOTHESIS 标记及置信度收尾。
• 防止 AI 出错： 根据证据核验生成的内容，追踪下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并明确指出歧义。
• 基于证据的推理： 每项主张都须引用 file:line、grep 结果或文档；没有证据，就不提出建议。
• 双轮往返审查： 审查 → 验证 → 修复已验证的问题 → 全面重新审查，直至无问题后结束循环。
• 全新上下文审查： 每轮修复后，使用记忆清零的全新子 Agent 重新开始完整审查。
• 审查协议注入： 将全部 11 个协议正文原样嵌入每个全新子 Agent 的提示中。
• 图谱影响分析： 存在 graph.db 时，运行影响范围分析；受影响但未更改的文件即为过时文件。
• 严重程度标准： 根据后果将发现分为 Critical/High/Medium/Low；Critical/High 会阻止判定为 PASS。
• 权衡质询关卡： 始终询问——有何权衡？值得吗？若影响重大，须在判定为 PASS 前向用户确认。
• 并行子 Agent 调度： 将任务标记为 PAR/SEQ，将 PAR 任务按互不重叠的写入集合分组，每波在一条消息中启动，并在进入下一波前设置屏障。

重要：必须注意 默认立场应为 SKEPTIC，而非验证者——在作出任何判定前，必须完成全部 7 项反偏见关卡：为至少 1 个被否决的备选方案提出最有力的论据；指出至少 1 个尚未考虑的备选方案；列出 2 至 3 条反对所选方案的论据；对 2 至 3 个隐藏假设进行压力测试；进行事前验尸；检查正反两方论据是否对称；运行权衡质询关卡。——原因：列出章节本身绝不等于通过；已经认可该推理的审查者需要被强制重置，才能发现其中的问题。 重要：务必始终询问这 3 个权衡问题——针对正在审查的决策，以及你自己提出的每一项建议：(1) 是否存在权衡？ 指出它在未来变更成本 · 复杂性 · 性能 · 耦合 · 可逆性 · 迁移 · 运维负担 · 影响范围 · 安全性 · 可测试性 · 团队技能 · 交付时间 · 用户体验方面牺牲了什么——“没有权衡”／“纯收益”意味着分析尚未完成，因此要说明检查了哪些维度，以及每个维度为何不受影响；(2) 值得吗？ 明确权衡收益与牺牲——获得了什么（用指标衡量），代价是什么、由谁承担、何时付出 → 给出 值得／不值得／尚不明确 的结论；不值得 → 撤回或替换该建议，绝不能保留；(3) 这项权衡是否重要到需要向用户确认？ 满足以下任一情况即为重要：不可逆（单向门） · 将成本转嫁给其他团队／运维人员／维护者／用户 · 以一种质量属性换取另一种 · 跨越层级／服务／事件／库的边界 · 涉及身份验证／资金／数据完整性／破坏性变更／高或中风险路径 · 或结论尚不明确 → 停止，并在下一个步骤问题之前、任何通过结论之前，单独直接询问用户确认，说明这项权衡、两个选项、各自的牺牲，以及你的建议。每次审查都要输出 Trade-Off Assessment 表；重要权衡未经用户确认，绝不能判定为通过，也绝不能将其埋在低严重性备注中。在 validate-findings 终止模式中：评估并记录，但不要提问——标记出来，交由调用方升级处理。——原因：只说收益不说代价，是在背书而非审查；没有标明代价的修复可能比它消除的缺陷更昂贵；而单向门应由用户决定是否跨过，绝不是审查者的决定。 重要：务必注意，审查之前先确定目标类型：计划／PBI 理由、代码变更、文档／规范／报告、发现项，或其他产物。提交／PR／差异输入默认按代码变更审查；只有在计划理由请求尚未解决时才说“没有活动计划”，绝不能悄悄转换目标类型。——原因：目标类型错误会导致用错误的清单审查错误的产物。 重要：务必注意，递归防护不可妥协：完整模式最多只能调用一次 $why-review --validate-findings；validate-findings 模式为终止模式——绝不能重新调用 why-review、运行门禁或启动子 Agent。——原因：终止模式执行以上任何操作都会导致无限递归。 重要，必须注意：每条发现都必须引用 file:line 证据，并注明严重程度和置信度（>80% 才采取行动，<60% 则不得提出建议）；拒绝使用“可能 / 应该是 / 我认为”——原因：未经证实的发现是猜测，不是审查结果。 重要，必须注意：以易于修改为评判标准——每条发现、测试、重构和抽象都必须降低未来的修改成本；指出真正的敌人（耦合、隐藏状态、重复知识、意图不明、过早做出的不可逆决策），否则就驳回建议。——原因：这项指标优先于任何会提高修改成本的下游“最佳实践”。 重要，必须注意：评判约定前，先搜索至少 3 个现有模式并阅读目标文件；将附近模式标记为“错误”之前，先评估其是否适用（最接近的示例 ≠ 满足相同前提）。——原因：本地约定优先于通用框架默认值；不结合上下文进行模式匹配会凭空制造错误发现。 重要，必须注意：开始前，通过任务跟踪将工作拆分为小型待办任务；完整模式下，在技能启动时（任务初始化阶段）创建 发现验证关卡收尾任务，并在存在发现时运行该关卡——重新调用 $why-review --validate-findings（终端模式，同一会话），确认每条发现都正确、有证据支撑、合理且符合最佳实践；只有出现已指出的发现问题或改进项时才重新执行（最多重新执行 2 次，之后直接询问用户）。——原因：该关卡能在交付前发现夸大、误读或未经证实的发现。 重要，必须注意：执行审查循环：审查 → 验证发现 → 修复已验证的发现 → 完整重新审查；一次完整审查未发现任何问题，即结束审查。绝不修复未经验证的发现；不同轮次绝不复用子 Agent（每次都调用新的 spawn_agent）；主 Agent 阅读子 Agent 报告，但不得筛选或推翻报告结论。——原因：每次修复都会使先前结论失效，而编排者的确认偏误会掩盖回归问题，新启动且没有历史记忆的审查者则能发现这些问题。 重要，必须注意：评判整个软件包，而非仅看差异——一并加载行为规格（§3 AC / §4 BR / §8 TC）、其测试和变更代码，进行交叉核对；任何一方缺失或彼此不一致，本身就是一条发现（CODE-WRONG / SPEC-STALE / TEST-GAP / SPEC-SILENT）。只要任何一方存在分歧且未记录为发现，就绝不能标记为 PASS。——原因：差异只是审查入口，整个软件包才是评判单位。 重要，必须注意：如果目标包含集成/E2E 测试，或变更了有集成测试覆盖的行为，则应用集成测试审查衔接：$integration-test-review 负责 8 项测试质量关卡，因此应阅读其协议（默认模式 A），或将审查委托给它（模式 B，仅适用于独立完整模式），而不是凭目测评判断言质量。符合以下任一 4 条豁免条件时跳过，并记录延后处理说明：验证发现模式；由 $integration-test-review 第 9 阶段调用；由 changes-review 在任意阶段（0.8、6 或 7.5）或 $workflow-review-changes 调用；由 $debug-investigate 的根因关卡调用。——原因：本技能的 Test/spec/doc sync 维度声称能证明测试保护了不变量，但只有这些关卡才能判断这一点；而无豁免条件的调用会形成 why-review → integration-test-review → why-review 循环。 重要，必须注意：每条改变行为的发现都必须同时包含规格偏移判定（CODE-WRONG / SPEC-STALE / AMBIGUOUS / SPEC-SILENT / in-sync）和具体的测试反馈措施；若判定为 SPEC-SILENT，还必须采取规格补充措施（§4 BR/§3 AC + §8 TC）。缺少任一方面都应判为 HAS-ISSUES，绝不能视为干净的发现。——原因：只修代码会悄然丢失规格中的不变量，使其失去保障。 重要，必须注意：对于缺陷修复 / 回归 / 行为变更审查，在给出结论前，按从结果到原因的顺序逐步调试（观察最终状态 → 逆向追踪 → 找出上游路径 → 假设矩阵 → 责任层 → 正向收敛证明），并生成行为差异矩阵（至少 3 行，至少 1 行涉及缺陷报告之外的内容）；任何回归差异都必须判定为 FAIL，直到有保护性测试覆盖。——原因：文字叙述会掩盖回归问题，而从症状着手修复则会忽略矩阵和追踪所能揭示的问题。 重要，必须注意：修复必须放在负责该不变量的层级——拥有该不变量的最低层级——绝不能放在症状/崩溃发生处；如果修复涉及 3 个或更多文件且包含防御性检查，则表明层级选错，应继续向下寻找。——原因：在症状处打补丁会让所有其他调用方继续暴露于问题之中。 重要，必须注意：PASS 前，必须修复或降低高中风险，或由用户/负责人明确接受这些风险；未经权威负责人/审查关卡认可，AI 提取的规格/测试用例不得作为证据。——原因：无人负责的残余风险只是延期发生的故障，不是通过审查。 重要，必须注意：发现 3 个或更多重复模式时，应提议提取为可复用模式；对于后缀相同的类（*Entity/*Dto/*Service），如果提取共享基类能降低未来修改成本，也应提议提取；绝不推荐出现次数少于 3 次的模式（YAGNI）。——原因：过度抽象和抽象不足都会提高未来的修改成本。 重要，必须注意：阅读 Project Reference Docs Gate 选出的参考文档（始终包含 docs/project-reference/lessons.md）；长期审查的发现应逐步保存到 plans/reports/；在完整模式下，直接询问用户以验证下一步——绝不自动继续。——原因：项目文档优先于通用假设，外部记忆能在上下文压缩后保留，而审查关卡由用户负责。 重要，必须注意：添加最终审查待办任务，以验证工作质量。 必须注意：运用批判性和顺序性思维——每项结论都需要适当的可追溯证据（关于仓库/代码的结论需提供 file:line；关于研究、产品、内容和文档的结论需提供来源 URL 或材料章节）；置信度 >80% 才采取行动，<60% 时不要提出建议。防止幻觉：绝不把猜测说成事实，坦然承认不确定性，独立交叉核实，始终对自己的判断保持怀疑。

必须注意：运用顺序性思维——采用多步骤 Thought N/M、REVISION/BRANCH/HYPOTHESIS 标记，明确标注置信度百分比；参见 $sequential-thinking 技能。

必须注意：防止 AI 出错——根据证据核实生成的内容，删除或重命名前追溯下游引用，核实所有受影响的输出，上下文丢失后重新阅读文件，并在采取行动前指出歧义。

[IMPORTANT] 开始前分析任务规模，并系统地将任务拆分为许多小的待办事项——这非常重要。

[GOAL REMINDER — MUST ATTENTION CRITICAL]

确保每个审查目标都合理、正确、有证据支撑，并符合最佳实践。 每次作出决策和提出建议时，始终询问这 3 个权衡问题：（1）是否存在权衡？——指出牺牲了什么；回答“没有”意味着分析尚未完成；（2）是否值得？——权衡收益与成本、由谁承担、何时承担 → 值得 / 不值得 / 不明确；（3）该权衡是否重大到需要向用户确认？——如果涉及不可逆操作、将成本转嫁给他人、以一种质量属性换取另一种、跨越边界、高后果路径，或情况不明确 → 停止并向用户确认，直接提问后再作结论。绝不默默替用户决定重大权衡。——原因：只说好处却不提代价是背书，而是否踏上一条单行道应由用户决定，绝非由你决定。 强制二次审查（完整模式）：只要第一轮得出任何发现，就必须对这些发现再次调用 $why-review --validate-findings，确认每项发现正确且合理后才能交接。绝不跳过；绝不为了规避二次审查而压下、降级或少报发现。自递归审查循环——主要是协议循环（与宿主无关），并在可用时由 /goal Stop-hook gate 把关——阻止在发现通过验证前停止。——原因：未经验证的发现就是未经证实的主张，第二次自审可发现第一轮合理化后遗漏的误读和夸大。

防止合理化：

规避说法	反驳
“没有有效计划”	仅适用于尚未解决的计划理由请求；提交、差异、PBI 和文档都是目标。
“只是代码审查”	仍需确定目标、阅读文档、运行图谱，并梳理测试／规范／文档。
“问题看起来很明显”	通过终端 --validate-findings 验证每一项问题。
“第一轮就够了”	完整模式下，只要有任何问题，就必须运行第二次 --validate-findings；协议审查循环（以及可用时的 /goal Stop hook）会阻止在完成这一步之前停止。
“报告零项问题，跳过关卡”	为逃避验证而压下或降低问题等级，正是 SKEPTIC 立场所禁止的偏见；先列出问题，再进行验证。
“直接在文中验证，不要重新调用”	第二次验证必须实际在终端调用 $why-review --validate-findings，并针对已写好的报告执行；不能只在脑中快速检查一遍。
“一次检查所有维度”	每个维度各进行一轮有重点的检查；分散注意力更容易漏掉问题。
“之后再问”	完整模式会在结束前询问用户下一步怎么做。
“看起来不错／各方意见一致”	默认采用 SKEPTIC 立场；完成全部 7 个反偏见检查项；交叉核对规范↔测试↔代码——任何一方不一致都是一项问题。
“这里没有权衡／只有好处”	未检查不等于不存在。明确列出已检查的维度（变更成本、复杂度、性能、耦合、可逆性、运维、安全、交付），并说明每项为何不受影响。
“权衡显而易见，没问题”	明确给出“值得／不值得／不确定”的结论，并说明收益、成本、由谁承担、何时承担。“显而易见”不是结论。
“我会在报告中注明权衡，而不是询问用户”	重大权衡必须单独直接询问用户，并在任何 PASS 之前获得答复——埋在报告中的备注不算确认。
“只是审查，升级与否不由我决定”	将重大权衡提请用户决策本就是审查职责；保持沉默等于把决定交给了无人。
“行为有变化，但不影响规范”	给出规范偏差结论及测试反馈操作；SPEC-SILENT 需要补充 §4 BR／§3 AC 和 §8 TC。
“在崩溃处修复”	在负责该不变量的层级修复（最低的不变量责任层）；崩溃位置是症状，不是原因。
“风险很高，但还是发布”	PASS 之前，必须修复、降低或由负责人接受高／中残余风险。

---

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

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

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