review-changes

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；不要自动运行。

按情况阅读文档：

• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-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 入手，然后只打开与任务相关的文件。

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

[顶部提醒——为什么“审查发现验证门槛”不可妥协]

如果此审查在独立模式下产生了任何发现（严重 / 高 / 中 / 低），在进行任何修复、文档更新、提交或交接之前，必须调用 $why-review 技能，并使用 --validate-findings <report-path>。只有实际调用技能才能通过此门槛——自行重新阅读引用的 file:line、进行“自我验证”或使用任何内联/手动替代方案，都不算通过。

记录首个发现时立即创建待办事项——绝不可依赖记忆： 调用任务跟踪 → [Review Phase 6] Why-review findings validation gate — invoke $why-review，以跟踪此门槛，确保不会跳过。在 $workflow-review-changes 中，报告完成后即停止；验证由父步骤 2 负责。完整流程见阶段 6；文末的结束提醒也有说明。

快速摘要

目标： 审查当前工作树、暂存区、分支或提交中的代码、文档、配置、基础设施及非代码产物差异——通过证据发现正确性错误、缺陷、遗漏的更新、过时文档和规范偏差，确保所有已审查的变更没有缺陷、有证据支撑、符合规范，并在交接前与所需的测试/文档保持同步；如果代码文件发生变更，还要证明代码仍易于修改。

摘要： 只读这一部分即可了解的精简概要——

• 报告驱动，证据为门槛。 每条发现都写入 plans/reports/code-review-{date}-{slug}.md，并提供 file:line 证据；禁止猜测，“看起来没问题”不算结论；代码库惯例（grep 3+ 个示例）优先于教科书规则。
• 发现问题后绝不立即自动修复。 独立模式依次运行 validate（Phase 6 $why-review --validate-findings，实际调用技能）→ fix（Phase 7）→ 从 Phase 0 开始对完整差异重新运行 $review-changes，循环直到一整轮检查零发现。在 $workflow-review-changes 内部，生成报告后即停止，并将发现交给父级。
• 代码有变更时，以下三个委派门禁均为强制要求： Phase 3.5 $code-simplifier（清晰度/可维护性）、Phase 3.7 $integration-test-review Gate-7 覆盖（每项行为变更都必须有覆盖测试 + 规范 TC），以及——针对每项行为变更——Spec Drift Adjudication + Dual-Feedback Ledger（差距同时反馈到规范和测试）。
• docs-update 是无条件的最后一步。 循环收敛且结果干净后，始终对完整变更集运行 Phase 8 $docs-update（在工作流内部则延后交给父级）。

路由边界： 此技能审查的是 git diff——工作树（默认）、暂存区、分支或提交。对于明确指定文件集或 SHA 范围的审查、处理收到的审查反馈，或针对已知范围进行完成前验证门禁，请改用 code-review。

共享引擎（保持同步）： review-changes 和 code-review 共用相同的 review-protocol SYNC: 块。规范来源：.claude/skills/shared/sync-inline-versions.md；策略：SYNC:shared-protocol-duplication-policy。修改某个技能中的共享块时，必须同时更新规范文件和另一个技能，避免二者不一致。这两个技能仅在入口意图（差异 vs 明确范围）和差异专属门禁（integration-test-sync、translation-sync、Phase 3.7 integration-test-review 覆盖门禁）上有所不同，审查质量则没有区别。

工作流：

1. 阶段 0：影响范围 — 如果 .code-graph/graph.db 存在，首先调用 $graph-blast-radius 技能
2. 阶段 0.3：变更类型 — 检测高风险变更类型；创建风险任务
3. 阶段 0.5：计划合规性 — 对照当前有效计划进行验证（有条件执行）
4. 阶段 0.7：范围检测 — AI 对已变更文件进行分类；创建维度任务
5. 阶段 1：收集 — 运行 git status/diff，创建报告文件
6. 阶段 2：文件审查 — 审查每个已变更文件，逐步更新报告
7. 阶段 3：新上下文关卡 — 如果已有发现则跳过；只有在用户、工作流或高风险综合分析明确触发时，才运行第二轮子 Agent
8. 阶段 3.5：Code-Simplifier 优化（代码文件发生变更时必须执行） — 调用 $code-simplifier，范围限定为已变更的代码文件，以发现清晰度、一致性和可维护性方面的简化机会；将其记录为发现，并纳入同一验证/修复循环（仅文档差异时跳过）
9. 阶段 3.7：集成测试审查覆盖率关卡（行为相关代码发生变更时必须执行） — 针对完整差异调用 $integration-test-review；其 7 项质量关卡会审查已变更的测试，且关卡 7（变更覆盖率）会将每个行为发生变化的生产文件映射到一个覆盖它的测试（优先集成测试；使用单元测试作为后备时需说明理由）和一个规范 TC。GAP/SPEC-GAP 结果会作为发现纳入同一验证/修复循环（仅文档差异时跳过；在 $workflow-review-changes 中，推迟到父流程的专属步骤执行）
10. 阶段 4：完成 — 生成关键问题、建议和推荐的提交消息
11. 阶段 5：文档分类 — 记录过时文档相关发现，以纳入验证/修复循环
12. 阶段 6：Why-Review 发现验证（仅独立运行模式；任何独立修复前必须执行） — 每当报告中包含一个或多个发现时，必须调用 $why-review 技能（通过实际的技能调用工具调用），并使用 --validate-findings 验证每项发现是否正确、有证据支持、合理且符合最佳实践，然后才能修复。这必须是真正的技能调用——自己重新阅读引用的行、“自我验证”或任何内联/手动替代方式都不满足此关卡。当此技能作为 $workflow-review-changes 中的步骤 1 执行时，在报告完成后停止；父流程的步骤 2 负责验证发现。
13. 阶段 7：递归修复 + 完整重新审查循环（仅独立运行模式） — 如果独立模式下仍有已验证的发现，则自动修复，然后从阶段 0 重新调用 $review-changes，基于当前完整差异重新进行任务拆分；重复此过程，直到整轮审查没有任何发现。在 $workflow-review-changes 中，父流程的步骤 10–15 负责计划、feature-implement 和重新开始。
14. 阶段 8：强制最终文档更新关卡（必须执行 — 审查/修复循环干净收敛后运行） — 审查发现归零且所有修复均已应用后，始终将针对完整变更集调用 $docs-update 作为最后一步，以确保没有遗漏过时文档。此步骤无条件执行（不以发现已标记问题为前提）——$docs-update 会独立检测审查可能未发现的受影响文档。在 $workflow-review-changes 中，由父工作流的 $docs-update 步骤负责执行；不要在本地运行。

关键规则：

• 以报告为驱动：始终将发现写入 plans/reports/code-review-{date}-{slug}.md
• 开始前必须为所有阶段创建待办任务
• 保持审慎：每项结论都需要 file:line 作为依据
• 指出违规前，先通过 grep 检查至少 3 个现有示例以确认约定
• 主动检查 DRY 违规、YAGNI/KISS 过度设计和正确性 bug
• 当变更文件包含源代码时，运行 Easy-to-Change 门禁：评估未来编辑点、耦合、隐藏状态、重复知识、意图是否清晰，以及抽象边界是否健康
• 当变更文件包含源代码时，对变更的代码文件运行 Phase 3.5 $code-simplifier 优化门禁——其简化机会属于发现，必须进入同一 Phase 6 验证 → Phase 7 修复循环（绝不未经验证自动应用）
• 当变更文件包含承载行为的代码时，对完整 diff 运行 Phase 3.7 $integration-test-review 覆盖率门禁——每项行为变更都必须对应一个覆盖测试（优先集成测试）和一个规范 TC。GAP/SPEC-GAP 判定属于同一 Phase 6 → Phase 7 循环中的发现，绝不允许悄悄记录了事
• 将变更文件与相关文档交叉核对——标记过时的文档、测试规范和 README
• 最终步骤为强制步骤：审核/修复循环收敛至零项发现后，始终对完整变更集运行 Phase 8 $docs-update 扫描——无条件执行，结果干净也不得跳过——原因：即使代码审核结果干净，文档仍可能过时，除非 $docs-update 根据实际变更对其进行核对更新
• 在 Phase 6 的 why-review 验证对当前发现集返回 CLEAN 之前，不得自动修复发现项
• 每轮修复都会使先前的审核结果失效；必须从 Phase 0 重新启动 $review-changes，审核更新后的完整 diff，包括修复内容
• 持续执行审核 → 验证发现项 → 修复 → 完整重新审核，直到一次完整审核没有任何发现；不得仅仅因为存在发现项或修复循环重启了审核，就额外进行一次新上下文审核

强制要求 创建待办任务，发现并阅读项目专属参考文档：

1. 搜索代码规范文档：*code-review*、*patterns*、*conventions*、*style-guide*——阅读找到的所有文档
2. 搜索架构文档：*architecture*、*adr-*、服务/模块根目录下的 README.md
3. 查找涉及变更技术领域（后端、前端、基础设施等）的文档
4. 阅读与变更文件类别最相关的文档

前置条件： 执行前必须阅读：

核心目的： 确保质量——没有缺陷、bug、遗漏的更新或过时内容。核验产物和文档。

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

证据门禁： 强制要求——每项结论、发现和建议都需要 file:line 依据或可追溯的证据，并注明置信度百分比（>80% 才可采取行动，<80% 必须先核验）。

OOP 与 DRY 强制执行： 强制要求——标记应提取到基类、泛型或辅助工具中的重复模式。同一组或具有相同后缀的类必须继承一个共同基类（即使目前为空，也能支持未来共享逻辑和子类重写）。核验项目是否已为所用技术栈配置代码 lint 或分析工具。

代码审核：当前或分支差异

根据项目规范审核当前变更，或用户明确指定的分支/提交差异。

审核范围

目标：默认审核当前工作树中的变更；用户要求比较分支时，则审核明确指定的分支/标签/提交差异。

使用以下来源：

• 当前变更：git status、git diff 和 git diff --cached
• 分支差异：git diff <base>...<head> 加上 git diff --name-only <base>...<head>
• 提交范围：git diff <base>..<head> 加上 git diff --name-only <base>..<head>

评审思维（不可妥协）

保持怀疑。运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度 >80%。

• 阅读实际实现以验证正确性，绝不轻信表面说法
• 每条发现都必须包含 file:line 证据（grep 结果、阅读确认）
• 只有在追踪证据能够证明时才写入报告，否则省略
• 质疑假设：“这真的能用吗？”→ 追踪调用路径以确认
• 质疑完整性：“这些就是全部吗？”→ grep 相关用法
• 验证副作用：“这项改动还会破坏什么？”→ 检查使用方和依赖项
• 没有证据就不要说“看起来没问题”——说明验证了什么以及如何验证

第一原则——易于修改

当差异包含源代码或与代码相关的文件（ .cs、.ts、.html、.scss、.css、测试、脚本、构建/配置即代码）时，应用此准则。 纯文档改动可跳过此准则，除非包含可执行示例或代码片段。

成功指标：未来的修改成本。 DRY、SRP、抽象、设计模式、命名、分层、测试——都服务于一个目标：降低下一次修改的成本。

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

• 拒绝会提高修改成本的“最佳实践”：过早抽象、投机性通用化、泄漏的间接层、没有收益的繁文缛节。
• 在发现中指出真正的问题：耦合、隐藏状态、知识重复、意图不明、过早暴露不可逆的决策。
• 倾向于围绕外部库建立项目自有边界，例如组件/服务的输入输出契约，以便将未来的库变更限制在局部；拒绝增加繁文缛节却不降低修改成本的透传包装器。
• 易于修改的简单设计，胜过不易修改的复杂设计。

在应用下方的具体规则、模式或检查清单之前，先采用这一视角。如果下游规则会提高修改成本，以此原则为准。

---

核心原则（全部执行）

YAGNI — 标记解决假设性未来问题的代码（未使用的参数、投机性接口、过早抽象） KISS — 标记不必要的复杂方案。是否有更简单且满足同一需求的方式？ DRY — 接受新代码前，主动 grep 查找相似/重复代码。出现 3+ 个相似模式 → 建议提取。 Clean Code — 可读性胜于巧妙。名称应体现意图。函数只做一件事。避免深层嵌套。 遵循惯例 — 标记任何模式违规前，先 grep 查找 3+ 个现有示例。代码库惯例优先于教科书规则。 无缺陷/无 Bug — 追踪逻辑路径。验证边界情况（null、空值、边界值）。检查错误处理是否覆盖失败模式。 需要证据 — 每项主张都必须有 file:line 证据或 grep 结果支持。禁止推测。 文档过时 — 将变更文件与相关文档（功能文档、测试规范、README）交叉核对。标记过时或缺失的更新。

对变更文件运行 python .claude/scripts/code_graph batch-query <f1> <f2> --json，检查测试覆盖率和调用方影响。

影响范围预分析（必须首先执行）

重要，必须注意： 每次评审的第一步。先调用 $graph-blast-radius，再进行任何其他评审工作。

如果 .code-graph/graph.db 存在，请在评审变更前运行 graph-blast-radius 分析：

• 调用 $graph-blast-radius 技能（运行 python .claude/scripts/code_graph blast-radius --json）
• 在评审中注明受影响文件数量、未经测试的变更，以及基于影响范围大小评估的风险等级
• 使用结果确定文件评审顺序，优先评审影响最大的文件

借助图谱进行变更评审

针对每个变更文件，追踪完整影响：

1. python .claude/scripts/code_graph trace <changed-file> --direction downstream --json — 列出所有受变更影响的文件
2. 标记任何受影响但未被测试覆盖的文件
3. 捕获简单差异评审容易遗漏的跨服务影响

审查方法（报告驱动的多阶段流程——关键）

必须首先执行：为审查阶段创建待办任务 开始前，使用任务跟踪功能创建以下任务：

• [Review Phase 0] Run $graph-blast-radius to analyze change impact - in_progress (必须首先执行)
• [Review Phase 0.3] Detect high-risk change types, create risk tasks - pending
• [Review Phase 0.7] Categorize changed files, create dimension review tasks - pending
• [Review Phase 0.5] Plan compliance check (skip if no active plan) - pending
• [Review Phase 1] Get changes and create report file - pending
• [Review Phase 2] Review file-by-file and update report - pending
• [Review Phase 3] Evaluate fresh-context gate; skip when findings already exist - pending
• [Review Phase 3.5] Run $code-simplifier on changed code files to optimize code quality - pending (代码文件有变更时必须执行；仅文档差异时跳过)
• [Review Phase 3.7] Run $integration-test-review coverage gate over full diff - pending (行为相关代码有变更时必须执行；仅文档差异时跳过；在 $workflow-review-changes 中推迟到父步骤执行)
• [Review Phase 4] Generate final review findings - pending
• [Review Phase 5] Record stale-doc findings for validation/fix loop - pending
• [Review Phase 6] Why-review findings validation gate before any fix - pending (存在审查发现时必须执行)
• [Review Phase 7] Auto-fix validated findings and restart $review-changes from Phase 0 - pending (仍有已验证的审查发现时必须执行)
• [Review Phase 8] Run $docs-update over full changeset to sync all impacted docs - pending (最终阶段必须执行——审查结果收敛至零项发现后始终执行；绝不跳过)

每个阶段完成后，更新待办任务状态。

注意： 如果阶段 1 发现变更文件达到 10 个或以上，请将阶段 2–4 的任务替换为系统化审查协议任务： [Review Phase 2] Categorize and fire parallel sub-agents、[Review Phase 3] Synchronize and cross-reference、[Review Phase 3.5] Run $code-simplifier on changed code files、[Review Phase 3.7] Run $integration-test-review coverage gate、[Review Phase 4] Generate consolidated report

阶段 0：运行 Graph Blast Radius 分析（必须首先执行）

重要：必须首先执行。 在任何其他审查工作之前，先执行此操作。

• 调用 $graph-blast-radius 技能
• 在报告中记录：变更文件数、受影响文件数、未经测试的变更、风险级别
• 使用影响范围分析结果，确定阶段 2 中需要重点审查的文件
• 如果 .code-graph/graph.db 不存在，请注明“图谱不可用——跳过影响范围分析”，然后继续阶段 0.3

阶段 0.3：变更类型检测与风险任务（必须执行）

目的： 在维度审查前，识别此差异中的高风险变更类型。 对每种检测到的类型创建一个针对性风险任务。变更类型与文件类别相互独立： 同一个文件可能既是迁移变更，也是安全变更——请分别检测所有类型。

步骤 1：检测变更类型

git diff --name-only HEAD       # unstaged
git diff --cached --name-only   # staged
# For branch or commit-range review, use the user-provided diff source:
git diff --name-only <base>...<head>

针对本次差异，评估每种变更类型：

变更类型	检测信号（根据项目的实际约定调整）	条件为 TRUE 时……
DepUpgrade	依赖清单已更改（package.json、*.csproj、Gemfile、go.mod、requirements.txt、Cargo.toml、pom.xml 等）	任一依赖清单中的版本号发生变化
Migration	文件路径或名称表明存在架构变更（包含 migration、schema、alter_table，或符合项目的迁移约定）	差异中出现任何符合迁移约定的文件
BusEvent	新增或修改了事件／消息定义或消费者（根据项目约定推断：消费者命名、消息类型目录）	新增了消费者或事件类，或其契约发生变化
ApiContract	API 定义文件发生更改（控制器、路由处理程序、OpenAPI／GraphQL 架构），且路由或字段存在差异	差异显示新增或移除了路由／操作／字段
SecurityChange	身份验证／权限定义发生更改——根据项目约定推断（身份验证中间件、权限常量、策略定义）	新增、移除或更改了任何身份验证或权限门控
ConfigChange	配置文件发生更改（例如，*.json、*.yaml、*.env*、*Config*、*Options*、*Settings*、*.toml）	出现任何符合配置约定的文件
InfraChange	基础设施定义发生更改（Dockerfile、docker-compose*.yml、CI/CD 管道、k8s 清单、IaC 文件）	出现任何符合基础设施约定的文件

在报告中记录：

## Change Type Analysis
DepUpgrade: [YES/NO] | Migration: [YES/NO] | BusEvent: [YES/NO]
ApiContract: [YES/NO] | SecurityChange: [YES/NO] | ConfigChange: [YES/NO] | InfraChange: [YES/NO]

步骤 2：创建变更类型风险任务（必须在任何审查工作之前完成）

必须： 对每个条件为 TRUE 的信号调用任务跟踪。不要为条件为 FALSE 的信号创建任务。 列出的关注点只是起点——还需运用领域知识进行拓展。 | 条件 | 任务跟踪主题 | 需要调查的关键事项（入手点——结合领域知识进一步扩展） | | ------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DepUpgrade TRUE | [Review-DepUpgrade] 依赖升级 — semver、破坏性变更、安全公告 | 属于主版本、次版本还是修订版本？阅读上游 CHANGELOG，检查是否有破坏性 API 变更。搜索已弃用 API 的使用情况。检查传递依赖的变更。新版本是否有已知安全公告？是否兼容对等依赖？测试是否仍然通过？ | | Migration TRUE | [Review-Migration] 数据库迁移 — 回滚路径、数据量影响、零停机 | 是否有回滚/Down 脚本？估算表大小——大表需要分析锁定情况。非空表中是否有不带默认值的 NOT NULL 列？是否使用无锁选项创建索引？部署顺序如何（在服务部署之前/之后）？重复运行时回填是否具有幂等性？ | | BusEvent TRUE | [Review-BusEvent] 跨服务事件/消息 — 消费者、幂等性、重试、毒丸消息 | 新事件是否有消费者？重试策略是什么：依赖数据尚未同步时，是等待后重试还是直接跳过？处理程序能否安全地运行两次（幂等性）？是否配置了格式错误消息处理/死信队列？与代理保证相关的顺序假设是什么？ | | ApiContract TRUE | [Review-ApiContract] API 契约变更 — 向后兼容性、客户端适配、身份验证 | 是新增内容还是破坏性变更？若为破坏性变更，是否需要版本控制或协调部署？所有调用方（UI、其他服务、测试）是否仍然兼容？新端点是否受到适当保护？是否新增了必需的响应字段，却未更新客户端？ | | SecurityChange TRUE | [Review-SecurityChange] 安全/权限变更 — 覆盖所有路径，不发生权限提升 | 是否覆盖了所有能够到达权限关卡的代码路径？是否有验证未授权访问被拒绝的负向测试？是否可能发生权限提升？是否同时更新了权限执行逻辑和显示控制？权限定义是否集中在唯一的权威位置（避免重复字符串导致不一致）？ | | ConfigChange TRUE | [Review-ConfigChange] 配置/环境变量变更 — 覆盖所有环境，不提交机密 | 所有环境配置中是否都包含新的配置键？是否有硬编码默认值掩盖生产环境配置缺失？差异中是否包含任何机密值？→ 如果是，则为严重问题。是否已在设置指南中记录？配置缺失时应用是否会快速失败？ | | InfraChange TRUE | [Review-InfraChange] 基础设施变更 — 环境一致性、生产环境无开发值、构建可复现 | 变更是否对所有环境产生一致影响？是否有硬编码的开发值（localhost、调试标志、开发凭据）？镜像/依赖版本是否已固定？是否记录了对本地开发的影响？是否记录了 CI/CD 所需的机密/权限？ |

AI-SDD 风险视角： 当变更文件涉及规范、工作流、工具或共享指南时，应用这些视角。

维度	审查重点
Contract/API/routes	公共行为、客户端、生成的规范和回归测试仍保持一致。
Permissions/security-review	执行机制、显示控件、负向测试和权威权限定义保持一致。
Config/flags	所有环境、示例、快速失败行为和文档均为最新状态。
Docs/spec/test drift	规范基准、Section 8 TCs、仪表板和测试代码保持同步，或明确标记为 N/A。
Generated mirrors	共享的技能／工作流／工具链更改已同步到生成的 Agent 界面。
Reference-only artifacts	AI 提取的规范／TCs 在获得所属审查关卡接受前，仍为草稿／参考资料。

步骤 3：在维度审查前完成变更类型任务

对于每个已创建的变更类型任务：

1. 将任务设为 in_progress
2. 处理所有适用的问题——上表仅供参考，并非限制
3. 对每个问题：通过 file:line 引用说明 PASS，或描述 FAIL/WARN 的发现
4. 在报告中的 ## {Task Subject} Findings 下记录发现
5. 将任务设为 completed

**重要：**先完成所有变更类型任务，再进入 Phase 0.7。 如果未检测到变更类型信号，请记录 "No high-risk change types detected" 并继续。

Phase 0.7：变更范围检测 + 动态审查任务（必需）

**目的：**让 AI 根据变更性质对变更进行分类，并据此创建审查任务。 根据项目实际变更文件推导类别，绝不要假设类别集合是固定的。 **思考，而非套用预设分类表。**这一步完全由 AI 负责。

步骤 1：从差异中推导类别

git diff --name-only HEAD        # unstaged
git diff --cached --name-only    # staged
# For branch or commit-range review, use the user-provided diff source:
git diff --name-only <base>...<head>

对于每个变更文件，通过检查以下方面推断其类别：

• **语言／扩展名：**此文件属于哪种技术或领域？
• **目录语义：**此路径在项目中代表哪一层、哪个模块或哪类关注点？
• **变更性质：**这是逻辑、数据架构、配置、文档、基础设施、样式、测试还是工具链？

不要映射到固定类别。推导出符合当前代码库实际结构和术语的类别。

可考虑以下常见类别作为起点（并非详尽列表——请推导适用的类别）：

• 服务端逻辑 — 业务规则、API 处理程序、服务、消费者、事件处理器
• 客户端逻辑 — UI 组件、状态管理、API 集成
• 数据／架构 — 迁移、架构、种子数据、领域模型
• 样式／资源 — CSS/SCSS、设计令牌、图片、字体
• 配置 — 应用设置、环境变量、功能标志
• 基础设施 — Docker、CI/CD、流水线、云清单
• 文档／规范 — Markdown 文档、ADR、功能规范、测试规范
• 测试 — 单元、集成、E2E 测试文件
• 构建／工具链 — 构建脚本、代码检查器、格式化工具、打包工具、Agent 脚本
• 安全 — 身份验证配置、权限定义、证书

在报告中记录：

## Change Surface
{Category name} ({category type}): {N} files
{Category name} ({category type}): {M} files
...

步骤 2：针对每个类别列出问题并创建任务

**此处需要思考，而不是填空。**针对每个类别应用 SYNC:category-review-thinking。

对于每个已识别的类别：

1. **理解领域：**此类别的用途是什么？有哪些不变量约束它？哪些对象依赖它？
2. **阅读项目惯例：**搜索适用于此领域的风格指南、模式文档和 README
3. 从基本原理推导问题——不要受任何固定列表限制；相信你的领域知识
4. 创建跟踪任务的任务，命名为 [Review-{Category}] {brief concern summary}，并列出推导出的问题
5. 选择合适的子 Agent 类型（参见“子 Agent 类型选择”）

始终创建： [Review-General] — 通用质量：正确性、YAGNI/KISS/DRY、文档过时情况、测试覆盖率。无论其他类别如何，均检查所有已更改文件。

子 Agent 类型选择：

类别性质	agent_type
代码逻辑（任何技术栈）	code-reviewer
实现有文档记录的规范/PBI	spec-compliance-reviewer（预检查，在 code-reviewer 之前）
安全、身份验证、权限	security-auditor
性能、查询效率、延迟	performance-optimizer
文档、计划、规范、ADR	general-purpose
基础设施、CI/CD、配置	general-purpose
混合或默认	code-reviewer

规范符合性预检查（当变更集实现了有文档记录的 docs/specs/** 功能或 PBI/故事时）： 首先启动 spec-compliance-reviewer——它会在 code-reviewer 质量检查之前验证实现是否符合规范（发现规范偏差、遗漏要求和额外功能）。如果没有规范/PBI 约束此变更，则跳过（此时 code-reviewer 是唯一的代码检查）。这是 spec-compliance-reviewer 唯一接入的调度位置（sub-agent-selection-guide.md 中的“Spec compliance”行）。

UI/前端维度（由此技能负责）： 当 客户端逻辑 或 样式/资源 类别涉及符合项目已配置前端/UI 文件模式的前端文件时，$review-changes 负责 UI 审查，并将 $review-ui 作为其 UI 维度调用——最好在与其他维度 Agent 相同的并行批次中，启动专用的 ui-ux-designer 子 Agent（如果无法启动子 Agent，则将其检查清单内联）。检查清单：长内容溢出（换行与省略号 + 工具提示）、通过 flex 适配多屏幕、flex-grow 与固定尺寸（优先使用 min/max + flex，而非固定 px）、遵循 z-index 层级规范（不使用原始数字，不使用 !important），以及 SCSS/BEM 质量。在独立运行和工作流上下文中，这一行为相同——$review-ui 不是单独的工作流步骤，而始终在此处运行。如果没有更改前端文件，则完全跳过。

步骤 3：按顺序处理任务

对于每个已创建的任务：

1. 开始前将任务设为 in_progress
2. 仅审查该类别范围内的文件
3. 应用 SYNC:category-review-thinking——结合领域知识，不要局限于其中的示例
4. 将发现写入报告中的 ## {Task Subject} Findings 部分
5. 开始下一个任务前，将当前任务设为 completed

绝不要仅通过扫描就将维度任务标记为已完成。 逐一明确检查每个相关文件。 对于较大的类别（10 个以上文件）：使用系统化审查协议升级为并行子 Agent。

阶段 0.5：计划符合性检查（有条件——仅在存在活动计划时）

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

• 如果为“Plan: none” → 跳过，并记录“无活动计划——跳过计划符合性检查”
• 如果为“Plan: {path}” → 加载计划并验证：

1. 阅读 {plan-path}/plan.md——获取阶段列表和范围
2. 阅读相关阶段文件——提取要修改的文件、测试规范和成功标准
3. 验证（必须注意——以下四项全部检查）：
   • 范围匹配——变更文件是否列在计划阶段中（对计划外文件发出警告）
   • 测试证据——映射到已完成阶段的测试是否有证据（文件:行号），而非“待定”
   • 是否达到成功标准——变更是否满足阶段成功标准
   • 测试意图可追溯性——映射的测试是否指出其保护的业务规则/不变量，而不只是当前行为
4. 在审查报告中添加“计划合规性”章节

阶段 1：获取变更并创建报告文件（必须注意）

• 确认差异来源：当前工作树、已暂存变更、分支比较或提交范围
• 对当前变更运行 git status，或对分支比较运行 git diff --name-only <base>...<head>
• 运行 git diff 或 git diff <base>...<head> 查看实际变更
• 创建 plans/reports/code-review-{date}-{slug}.md
• 初始化报告，添加“范围”、“待审查文件”和“影响范围摘要”章节

阶段 2：逐文件审查（逐步完善报告）

对于每个变更文件，阅读并立即更新报告，记录：

• 文件路径和变更类型（新增/修改/删除）
• 变更摘要：修改或新增的内容
• 目的：变更的原因
• **约定检查：**检索 3 个或更多类似模式——新代码是否遵循现有约定？
• **正确性检查：**追踪逻辑路径——是否处理了空值、空集合、边界值和错误情况？
• **DRY 检查：**检索相似/重复代码——其他位置是否已存在此逻辑？
• **意图检查：**变更是否服务于声明的目的？标记无关修改
• **逻辑追踪：**追踪一条正常路径和一条错误路径。逻辑是否符合要求？
• **语义正确性：**产物是否实现了预期功能？
• 发现的问题：命名、类型、职责、模式、缺陷、过度设计、逻辑错误
• 继续审查下一个文件，并重复以上步骤

阶段 3：新上下文关卡（条件协议——根据发现和阶段 0.7 的表面情况分支）

协议：SYNC:double-round-trip-review + SYNC:fresh-context-review + SYNC:review-protocol-injection（均已内联于上文）。 **不变量：**阶段 3 仅用于审查。可以新增发现，但绝不能修复或验证这些发现。已有发现无需在新上下文中重新审查；任何非零的发现集都应进入阶段 6 的 why-review 验证，然后进入阶段 7 的自动修复 + 从阶段 0 开始完整重启 $review-changes。仅因阶段 7 重启本身并不能触发阶段 3。

进入条件：

1. 如果阶段 2 或任何维度审查已发现问题，跳过阶段 3。记录：因已有发现而跳过新上下文审查；阶段 6 的 why-review 验证是必经的下一关。然后继续阶段 4 汇总和阶段 6 验证。
2. 如果没有任何发现，且不存在明确的独立审查触发条件，跳过阶段 3。记录：因当前审查无问题且不存在第二轮触发条件而跳过新上下文审查。然后继续阶段 4 定稿。
3. 仅当当前发现集为零，且至少存在一个触发条件时，才运行阶段 3：
   • 用户明确要求进行第二轮/新上下文审查；
   • 所选工作流明确要求此次调用由独立审查者进行审查；
   • 高风险的多领域变更需要在给出无问题的结论前进行综合审查。

**避免浪费规则：**不要在阶段 6 之前运行阶段 3 来重新审查已知问题。不要仅因阶段 7 修复后重启审查就运行阶段 3。重启后的审查本身已是所需的完整审查；如果没有发现问题，且不存在上述明确触发条件，就直接以无问题的结论定稿。

如果进入条件允许运行阶段 3，请检查阶段 0.7 中的类别——如果变更涉及多个不同领域（例如服务端 + 客户端），则运行综合模式。否则运行整体模式。

---

[综合模式——变更涉及多个不同领域时] 将 综合 Agent 作为第 2 轮启动。目的：发现各个维度任务无法察觉的跨边界问题。

构造 Agent 调用提示词时：

1. 原样复制 SYNC:review-protocol-injection 模板中的 Agent 调用格式，agent_type: "code-reviewer"

2. 原样嵌入全部 11 个通用 SYNC 区块

3. 将 Task 设置为：

   综合审查 — 仅检查此差异中已更改领域之间的跨边界问题。
   以下是各维度任务的发现，供你参考：{每个维度任务的摘要}。
   通过你自己的工具调用，从头重新读取所有已更改的文件。
   
   仅关注跨边界问题——不要重新审查各领域的内部细节：
   1. 契约对齐：调用方是否符合被调用方暴露的接口？（路由、参数、字段名称、类型）
   2. 数据一致性：跨层边界的字段名称和类型是否一致？
   3. 安全边界：两侧是否都执行了身份验证（执行和显示控制）？
   4. 跨层命名：同一概念在不同层是否使用了不同名称？
   5. 接线缺失：是否有新的生产方却没有使用方？新的使用方却没有生产方？新功能却没有文档？
   6. 文档：文档是否同时反映了两个领域的变更？
   

4. 将 Target Files 设置为 "use the selected diff source from Phase 1"

5. 将报告路径设置为 plans/reports/synthesis-review-{date}.md

子 Agent 返回后：

1. 读取综合审查报告
2. 将发现整合到主报告的 ## Synthesis Round Findings 部分——不要筛选或覆盖
3. **如果有发现：**此处不要修复；标记第 3 阶段已完成，并继续进行第 6 阶段的 why-review 验证
4. **如果没有发现：**作为一次干净的综合审查，继续进行第 4 阶段的最终定稿

---

[整体模式——仅更改单一领域时]

无需进行跨边界综合审查。启动标准的整体第 2 轮审查。

构造 Agent 调用提示词时：

1. 原样复制 SYNC:review-protocol-injection 模板中的 Agent 调用格式
2. 根据该领域的主要关注点选择 agent_type（参见 Sub-Agent Type Selection）
3. 将 Task 设置为："整体审查所选差异。关注全局——整体技术方案的一致性、架构层、逻辑放置位置（最低层）、DRY 违规、YAGNI/KISS、函数复杂度。领域：{第 0.7 阶段的类别}——相应地运用该类别的领域知识。"
4. 将 Target Files 设置为 "use the selected diff source from Phase 1"
5. 将报告路径设置为 plans/reports/code-review-changes-round{N}-{date}.md

子 Agent 返回后：

1. 读取子 Agent 的报告
2. 将发现整合到主报告的 ## Round {N} Findings (Fresh Sub-Agent) 部分——不要筛选或覆盖
3. **如果有发现：**此处不要修复；标记第 3 阶段已完成，并继续进行第 6 阶段的 why-review 验证
4. **如果没有发现：**作为一次干净的整体审查，继续进行第 4 阶段的最终定稿
5. 最终判定必须纳入本次调用中执行的所有审查轮次的发现

以下检查由子 Agent 处理，但可在第 4 阶段进行验证：

清洁代码与过度设计检查：

• 必须关注 YAGNI： 代码是否在解决假设的未来问题？是否存在未使用的参数或推测性的接口？
• 必须关注 KISS： 方案是否不必要地复杂？在满足相同需求的前提下，能否更简单？
• 必须关注 函数复杂度： 方法是否过长？嵌套是否过深？是否承担多项职责？
• 必须关注 可读性： 新团队成员能否在不阅读完整实现的情况下理解代码？

文档过时检查（必需）：

对于每个已更改的文件，识别相关文档：

• 搜索功能文档、架构参考、模块／服务根目录中的 README、API 文档、测试规范和设置指南
• 标记内容已不再与变更后的产物相符的文档
• 标记新功能或组件缺少应有文档的情况
• 在报告中标记具体过时的章节及其变更内容。暂不修复；阶段 6 必须先验证该发现，阶段 7 才能调用 $docs-update 或应用文档编辑。

**规范漂移裁定（行为发生变化时必需）：**应用 SYNC:spec-drift-adjudication。对于每项涉及行为的变更，都要将其与 docs/specs/ 下的规范功能规格进行比较，并将任何差异归类为 CODE-WRONG（变更违反预期的规范规则／AC／不变量 → 阻塞性发现，修复代码／测试）、SPEC-STALE（有意变更行为，而规范未能反映该变更 → 转交 $spec [update] + $spec [mode=tests] [update]）、AMBIGUOUS（在编辑任一方之前直接向用户提问）或 SPEC-SILENT（代码正确地实施了规范产物未提及的不变量 → 补充：通过 $spec [update] + $spec [mode=tests] 添加 §4 BR／§3 AC 和 §8 TC，然后添加守护测试）。逐项记录变更行为的判定结果（没有差异时记录 Spec in sync）。不要仅因代码／测试通过就消除漂移。这是“修复 bug 后检查‘规范是否有误？’”的双向扩展——适用于所有涉及行为变更的评审，而不仅是修复 bug 后的评审。在此标记发现；阶段 6 负责验证，阶段 7 负责修复（CODE-WRONG 修复走修复循环；SPEC-STALE 和 SPEC-SILENT 修复先转交规范更新器，再执行 $docs-update）。

**正确性与 Bug 检测：**应用 SYNC:bug-detection — 空值安全、边界、错误处理、资源清理、并发。

**测试规范验证：**应用 SYNC:test-spec-verification — 定位规范、验证覆盖情况、标记缺口。

**集成测试同步：**应用 SYNC:integration-test-sync-check — 通过直接向用户提问，指出缺失的测试。

**翻译同步：**应用 SYNC:translation-sync-check — 对于多语言 UI 文本变更，要求更新翻译，或明确取得用户对风险的接受。

阶段 3.5：Code-Simplifier 质量优化（代码文件发生变更时必须执行）

目的：正确性评审证明变更有效；此门禁则证明变更后的代码仍然易于阅读、保持一致且易于修改。Bug 查找（阶段 2–3）与简化优化是不同的视角——两者都要执行。$code-simplifier 是清晰度／一致性／可维护性优化的指定负责人，因此本技能将此工作交给它，而不重复其逻辑。

启动条件：

• 当 diff 包含源代码或与代码相关的文件（.cs、.ts、.tsx、.html、.scss、.css、测试、脚本、构建／配置即代码）时执行。
• 仅包含文档／Markdown 的 diff 则跳过。记录：Skipped Phase 3.5 — no code files in diff.

流程：

1. 将 [Review Phase 3.5] 任务设为 in_progress。
2. 调用 $code-simplifier，范围限定为仅变更的代码文件（传入阶段 1 的 diff 来源——工作树、暂存区、分支或提交范围——使其优化相关的变更文件，而不是整个代码库）。要求其指出复用、DRY、KISS/YAGNI、命名、死代码、抽象层次／代码放置位置和可读性方面的简化机会。
3. **记录，不要自动应用。**在评审上下文中，$code-simplifier 以 报告 模式运行：将其建议整合到主报告的 ## Code-Simplifier Optimization Findings 下，并为每项建议提供 file:line 证据和一句理由。这些是发现，不是编辑。
4. 将 [Review Phase 3.5] 任务设为 completed。 流水线集成： Phase 3.5 的发现属于普通发现——它们会在 Phase 4 汇总，在 Phase 6 验证（$why-review --validate-findings 会筛除误报或会增加变更成本的简化建议），只有通过验证的发现才会在 Phase 7 修复。绝不要让 $code-simplifier 在 Phase 6 验证其建议之前修改工作树。

父工作流边界： 当此技能作为步骤 1 在 $workflow-review-changes 中调用时，仍须运行 Phase 3.5（这是一个审查维度，会为报告生成发现），但此处不要修复——应用这些发现由父工作流的 $code-simplifier 自审查和 $feature-implement 修复周期负责。记录这些发现，并将报告交给父工作流的步骤 2。

Phase 3.7：集成测试审查覆盖率关卡（行为代码发生变更时必须执行）

目的： Phase 2-3 证明变更按当前写法正确；此关卡证明变更已覆盖并写入规范。$integration-test-review 是 7 关测试质量审计的指定负责方——其 Gate 7（变更覆盖率）会将差异中的每个行为变更生产文件映射到覆盖它的测试（优先集成测试；使用单元测试作为后备方案时需要明确说明理由）以及一个规范 TC。此技能委托给它，而不是重复实现这套逻辑。SYNC:integration-test-sync-check 仍作为轻量级文件配对检查；此关卡则更深入地检查断言质量、数据状态验证、可重复性，以及整个变更集中的规范↔测试↔代码双向对齐。

准入关卡：

• 当差异中包含承载行为的源代码时运行：处理器、命令、查询、服务、实体、事件消费者、控制器、后台作业或前端逻辑。
• 对仅包含文档 / Markdown / 纯样式资源文件的差异，跳过。记录：Skipped Phase 3.7 — no behavior-bearing code in diff.

流程：

1. 将 [Review Phase 3.7] 任务设为 in_progress。
2. 调用 $integration-test-review，并将范围设为 Phase 1 的差异源（工作树、暂存区、分支或提交范围），使其审计完整变更集——包括变更的生产代码和测试文件，绝不能只审计测试文件。它会运行全部 7 个质量关卡，生成 Gate 7 覆盖率映射表，并双向交叉检查规范 TC。
3. 记录结果，不要自动修复。 将其输出整合到主报告的 ## Integration-Test-Review Findings 下：包括每个关卡的判定、覆盖率映射表，以及所有 GAP / SPEC-GAP / 缺乏正当理由的 COVERED-UNIT（GAP 的严重性至少为 HIGH；对于认证 / 资金 / 数据完整性路径，严重性为 CRITICAL）。
4. 将 [Review Phase 3.7] 任务设为 completed。

流水线集成： Phase 3.7 的发现属于普通发现——它们会在 Phase 4 汇总，在 Phase 6 验证，在 Phase 7 修复。GAP 修复通过 $integration-test 编写缺失的测试；SPEC-GAP 修复则运行 $spec [mode=tests] [update]。之后 Phase 7 会重新审计整个更新后的差异中的覆盖率，包括新增的测试。

父工作流边界： 当此技能作为步骤 1 在 $workflow-review-changes 中调用时，不要在本地运行 Phase 3.7——7 关审计和覆盖率映射由父工作流专门的 $integration-test-review 步骤负责。记录 Phase 3.7 deferred to parent workflow $integration-test-review step.（SYNC:integration-test-sync-check 仍须在本地作为轻量级配对检查执行。）

Phase 4：生成最终审查结果

使用以下最终章节更新报告（必须关注——包含以下所有章节）：

• 总体评估（整体概述）
• 严重问题（合并前必须修复）
• 高优先级（应当修复）
• 架构建议
• 文档过时情况（列出过时文档及其变更内容，或填写“No doc updates needed”）
• 规范偏差判定（针对每个行为变更文件：CODE-WRONG / SPEC-STALE / AMBIGUOUS / SPEC-SILENT / Spec in sync，并注明对应的修复方案；或填写“No behavior change — N/A”）
• 双向反馈记录（必填 — 见下文；或填写“No behavior change — N/A”）
• 正面观察
• 建议的提交信息（根据所做变更）

双向反馈记录（每个行为变更发现必填）。 行为差异必须同时反馈到规范和测试中——不能只修复代码。上面的规范偏差判定行和 Phase 3.7 Gate 7 覆盖行分别只覆盖一个方面；此记录将二者合并为一条“同时更新两者”的断言，避免遗漏。对于每个行为变更发现，输出一行，包含两个单元格：

发现（file:line）	规范反馈	测试反馈
{cite}	{需要对 §8 规范/功能规范进行的更新 — 例如 $spec [update] 然后 $spec [mode=tests]，或 N/A-因为-CODE-WRONG-规范已正确}	{需要的 TC/回归测试 — 例如通过 $spec [mode=tests] 添加新的 §8 回归 TC，或通过 $integration-test 添加覆盖该行为的集成测试}

• 任一方面的单元格为空 = 失败。 不能只写“N/A”——每个 N/A 都必须附带原因（例如：N/A — CODE-WRONG：规范已正确描述预期行为，因此无需修改规范；只需补充回归 TC）。
• CODE-WRONG 发现 → 规范反馈通常为 N/A — 规范正确；必须提供测试反馈（按照 SYNC:spec-drift-adjudication，先添加回归 TC）。
• SPEC-STALE 发现 → 两个单元格均不能填写 N/A：规范反馈 = $spec [update]，然后 $spec [mode=tests]；测试反馈 = 新增/更新 TC + 守护测试。
• SPEC-SILENT 发现（代码正确执行了规范从未声明的不变量）→ 两个单元格均不能填写 N/A：规范反馈 = 添加缺失的 §4 BR / §3 AC（如适用，还需添加 §5 不变量），并通过 $spec [update] + $spec [mode=tests] 添加 §8 TC；测试反馈 = 新增用于守护现已写入规范的不变量的属性测试/回归测试。必须捕获最有价值的内容——绝不能让已发现的不变量只存在于代码或测试中。
• 已有但过时的 TC（由 $integration-test-review 判定为 Gate 7 SPEC-GAP——其 Gate 7 会将仍存在但已无法描述当前行为的 TC 归类为 SPEC-GAP，而非视为覆盖达标）：规范反馈 = 使用 $spec [mode=tests] [update] 修正过时的 §8 TC；测试反馈 = 更新守护测试，使其符合修正后的 TC。
• 此记录本身就是一组普通发现：它会在 Phase 4 汇总，并在 Phase 6 进行验证（$why-review --validate-findings 确认每个行为变更都包含这两个方面），其待完成的规范/测试操作将在 Phase 7 执行。若某行仍有一个方面为空并进入 Phase 7，则评审即为未完成。

阶段 5：文档更新分诊（有条件）

如果阶段 4 的文档过时检查发现了过时文档：

1. 在审查报告中记录受影响的文档以及建议的同步/更新路径
2. 将每项过时文档添加到阶段 6 的发现项验证载荷中
3. 暂勿调用 $docs-update；只有在 $why-review --validate-findings 针对这些发现项返回 CLEAN 后，才在阶段 7 修复过时文档
4. 如果阶段 7 随后应用了文档修复，下一次递归调用 $review-changes 时，必须从阶段 0 开始重新审查更新后的文档

阶段 5 只对审查标记的文档进行分诊。 无论此处是否有任何文档被标记，强制执行的阶段 8 最终 $docs-update 关卡仍会在审查收敛为 clean 后运行；它会独立检测本次分诊可能遗漏的受影响文档。阶段 5 是有条件的；阶段 8 是无条件的。

可读性检查清单（必须认真评估）

批准前，请确认各项产物易于阅读、维护和理解：

• 结构可见性 — 函数是否计算数据结构？应通过注释展示输出形状，避免读者追踪代码
• 不明显的数据流 — 数据是否经过多个步骤转换？应添加简短注释解释处理流程
• 签名自说明 — 参数是否说明其作用？标记未使用的参数
• 魔法值 — 未解释的数字/字符串应改为命名常量，或添加行内说明
• 命名清晰度 — 变量/函数名称应能直接体现意图，无需阅读实现代码

审查检查清单

1. 架构合规性（必须认真评估）

• 遵循项目的层级/模块边界（阅读 docs/project-config.json 或同等文件）
• 存在边界时，不得跨模块/服务直接访问数据
• 将逻辑放在职责最低的层级（而非编排器/顶层类中）

2. 代码质量与整洁代码（必须认真评估）

• 单一职责原则——每个函数/类只做一件事
• 不重复代码（DRY）——搜索类似代码，出现 3 次或更多时应提取
• 按照项目惯例妥善处理错误
• 不使用魔法数字/字符串（提取为命名常量）
• 所有函数均应添加类型注解（语言要求时）
• 使用提前返回/守卫子句
• YAGNI——不添加推测性功能、未使用的参数或过早抽象
• KISS——采用满足需求的最简单方案
• 遵循现有代码库惯例（通过 grep 查找至少 3 个示例进行验证）

2.5. 命名规范（必须认真评估）

• 名称应体现意图（是什么，而非怎么做）
• 使用具体名称，而非通用名称（例如使用 orderRecords 而非 data）
• 布尔值：使用表示状态的动词前缀（isActive、hasPermission、canEdit）
• 不使用晦涩的缩写

3. 项目特定模式（必须认真评估）

• 标记违规前，先阅读项目的模式/惯例参考文档
• 在认定某个模式违规前，先验证至少 3 个现有示例
• 标记偏离项目模式的情况时，提供证据（现有模式所在的 file:line）

4. 安全性（必须认真评估）

• 不得硬编码凭据、令牌或机密信息
• 在所有入口点进行适当的授权检查
• 在系统边界处验证输入（用户输入、外部 API、消息载荷）
• 不存在注入风险（SQL、命令、模板等）

5. 性能（必须认真评估）

• 如果可以实现 O(n) 或 O(1)，则不得使用 O(n²) 复杂度（使用查找结构）
• 不存在 N+1 查询模式（迭代前批量加载相关数据）
• 所有列表查询都应分页（绝不获取无界结果集）
• 对彼此独立的操作进行并行处理（不要强制串行）
• 正确使用 async/await（异步上下文中不得阻塞）
• 查询模式应有适当的索引

6. 常见问题（必须认真评估）

• 未使用的导入或变量
• 不应留在生产环境中的调试/日志语句
• 应通过配置管理的硬编码值
• 缺少 async/await 或 Promise 处理
• 异常处理不正确或缺失
• 边界处缺少验证

6.5 Bugfix 调试器追踪门槛（必须关注）

对于 bugfix、验证失败、过时或错误的最终输出、回归问题或行为变更修复，如果缺少任何必需的证明，则审查不通过：

• Debugger Trace: End -> Start 指明观察到的最终状态以及最终读取方／查询／渲染器／断言
• 通过从读取方 -> 存储／投影／缓存 -> 写入方 -> 消费者／处理器／作业 -> 生产者／来源的反向跳转提供证据
• 列出所有可能写入最终状态的馈入路径，或明确标记为未知
• 假设矩阵将根因分类为主要、促成、排除、潜在或未知
• 论证修复所属层是最低层的共同所有者，而非默认选择症状所在位置
• 正向收敛证明及回归测试／证明映射说明为何最终症状不会持续存在

7. 文档过时（必须关注）

• 对每个已更改文件：找出相关文档（功能文档、架构参考、README）
• 逻辑变更 → 验证相关功能／模块文档仍准确
• 工具变更（脚本、配置、CI）→ 验证设置／入门文档仍准确
• 新增功能／组件 → 标记是否缺少对应文档
• 测试规范应反映变更后的当前行为
• API 变更应体现在相关 API 文档或规范中
• 规范偏差裁定（SYNC:spec-drift-adjudication）：对于每个行为变更文件，判断其与规范性功能规范的偏差属于 CODE-WRONG（变更存在缺陷 — 阻塞，修复代码／测试）、SPEC-STALE（变更符合预期 — 先通过 $spec [update] 更新规范）、AMBIGUOUS（预期行为不明确 — 编辑任一方之前先直接询问用户），还是 SPEC-SILENT（代码正确地强制执行了规范制品未声明的不变量 — 补充：添加 §4 BR／§3 AC + §8 TC + 守护测试）。不要在未说明哪一方具有规范性地位的情况下，将偏差笼统地标记为单方面的“文档过时”。未经裁定的行为与规范之间的偏差判定为不通过；未记录却已强制执行的不变量未纳入文档，同样判定为不通过。

8. M1-M6 合规门禁 — 代码与规范偏离（阻断，必须关注）

**契约：**参见 .claude/skills/shared/sdd-artifact-contract.md → “AI-SDD Mandates (M1-M6)”。对于此变更涉及或应由此变更同步的任何规范/功能文档/PBI/故事/测试规范，本审查均执行 M6。每项检查都应明确指出：此变更是否引入了 M1/M2 叙述性文本泄漏、破坏了逻辑 ID 映射（M3），或造成了 AC/预期结果歧义（M4）？ FAIL 必须注明违反的规范 ID，并引用变更文件及行号。未发现引入的 M1-M5 违规而判定通过，会使本审查本身存在缺陷。

承载字段不受 M1/M2 限制——源标识符在 [Source: ...]、**Evidence**、**IntegrationTest** 字段、YAML frontmatter 和 ```mermaid ``` 代码块中应保持正确。只标记规范/文档叙述性文本中的泄漏。禁用的叙述性文本词元列表：docs/project-reference/spec-principles.md §3.2。此门禁仅适用于变更的制品文件（docs/specs/**、差异中的 PBI/故事/测试规范文件）；若差异未涉及此类制品，则跳过并附上一行说明。

• **M1 — 不在叙述性文本中引入技术泄漏。**如果差异在规范/文档的叙述性文本、标题或 AC 文本中加入框架/产品、语言原生类型或产品/设计模式类名称（禁用列表见 spec-principles.md §3.2），则判定 FAIL。引用变更文件、行号及词元。
• **M2 — 不在叙述性文本中引入源代码。**如果差异使用类/方法/文件路径/命名空间作为名词来表达需求，而非描述业务操作，则判定 FAIL。源标识符只能出现在证据承载字段中。引用变更行。
• **M3 — 保留逻辑 ID 映射。**如果变更新增的需求/规则/TC 没有逻辑 ID（FR-/BR-/OP-/TC-）、移除了逻辑 ID、将逻辑 ID 降级到 [Source:] 证据之后、使用物理代码坐标或仓库根路径，而非可跨技术栈移植的抽象锚点（[Source: namespace/service/id]），或删除了 [Source:] 抽象锚点证据（证据是必需且必须保留的——优先级低于逻辑 ID；仅移动代码不会改变锚点——物理坐标只能出现在溯源 sidecar 中），则判定 FAIL。
• **M4 — 不引入 AC 歧义。**如果变更留下模糊的 AC/预期结果（例如“适当处理”“正常处理”“按需处理”），导致有两种不同实现方式都声称符合要求，或没有可观察的完成状态/明确的错误条件，则判定 FAIL。
• **M5 — 规范仍可重建。**如果变更导致规范/文档必须通过阅读新代码才能理解（缺乏代码库知识的团队无法仅凭制品在不同技术栈上重新实现），则判定 FAIL。引用文件及缺失的细节。

如果任何项目不通过 → 结论为 FAIL；在 Critical Issues 或 High Priority 部分列出每项违规的规范 ID，并引用变更文件/行号。

输出格式

请按以下格式提供反馈：

总结： 简要总体评估

关键问题：（提交前必须修复）

• 问题 1：描述及建议的修复方案

高优先级：（应该修复）

• 问题 1：描述

建议：（锦上添花）

• 建议 1

文档过时情况：（可能需要更新的文档）

• 文档 1：过时内容及原因
• No doc updates needed — 如果没有变更文件对应任何文档

规范偏差裁定：（仅针对行为变更 — 依据 SYNC:spec-drift-adjudication）

• <behavior/file> → CODE-WRONG | SPEC-STALE | AMBIGUOUS | SPEC-SILENT — 裁定 + 后续处理方式（$spec [update]、回归测试用例、直接询问用户，或 enrich-spec：添加 §4 BR/§3 AC + §8 TC + 防护测试）
• Spec in sync — 如果变更行为符合规范特性说明
• No behavior change — N/A — 如果差异仅涉及文档/工具/样式

调试器跟踪缺口：（仅针对缺陷修复/行为变更）

• Trace complete — 如果已提供所需跟踪、馈入路径、假设矩阵、负责人和前向证明
• 缺口 1：跟踪证据缺失或薄弱之处及其阻碍 PASS 的原因

目标达成情况：（任何 PASS 判定前都必须完成 — 按 goal-contract-satisfaction-loop 协议解析当前有效的 Goal Contract：有效计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md；如果不存在，则记录 No active goal — skipped: {one-line reason}）

成功标准	证据	状态
{保存的标准}	{文件:行号、命令输出、报告路径}	PASS/FAIL/BLOCKED

• 只要有任何必需标准为 FAIL，整体 PASS 就会被阻止——代码质量审查通过但未达成已保存目标，不算 PASS。
• BLOCKED 状态必须在矩阵行和目标文件中记录面向用户的升级说明。
• 引用证据；切勿在矩阵或目标文件中复述目标文本或复制机密/敏感内容。
• 判定后，更新目标文件：追加一条 Iteration Log 记录，并同步其 Goal Satisfaction 矩阵。

正面评价：

• 做得好的地方

建议的提交消息：

type(scope): description

- Detail 1
- Detail 2

---

系统化审查协议（针对 10 个及以上变更文件）

当 Phase 1 发现 10 个及以上变更文件时，请应用下文定义的 Systematic Review Batching 协议（map-reduce：设定大小上限的批次 + 分层综合）。

---

工作流建议

**必须遵守——不得例外：**如果当前不在工作流中，必须直接向用户提问。不要判断任务复杂度，也不要决定“任务足够简单，可以跳过”——由用户决定：

1. 启用 workflow-review-changes 工作流（推荐）——从 .claude/workflows.json 运行规范工作流；它会依次执行此技能、发现验证、并行审查者、code-simplifier 自审、修复计划周期、完整重新审查、文档和交接。
2. 直接执行 $review-changes——独立运行此技能

---

架构边界检查

对每个变更文件，验证其没有从禁止的层导入内容：

1. 读取规则：从 docs/project-config.json → architectureRules.layerBoundaries 读取
2. 确定层级：对每个变更文件，将其路径与每条规则的 paths glob 模式匹配
3. 扫描导入：使用 grep 查找文件中的导入语句
4. 检查违规：如果任何导入路径包含 cannotImportFrom 中列出的层名称，则视为违规
5. 排除框架：跳过匹配 architectureRules.excludePatterns 中任意模式的文件
6. 遇到违规时阻止：报告为关键问题："BLOCKED: {layer} layer file {filePath} imports from {forbiddenLayer} layer ({importStatement})"

如果 project-config.json 中不存在 architectureRules，则静默跳过。

---

Phase 6：审查发现验证关卡（修复发现项前必须执行）

目的： 在修复前验证自己的发现。确认每项发现都正确、有证据支持（file:line）、合理且符合惯例。在修改代码或文档前，找出误报、严重性夸大以及遗漏的改进机会。

强制要求： 只要存在发现，就必须创建待办任务。通过任务跟踪将其登记为 [Review Phase 6] Why-review findings validation gate（已列在上方的 Phase 任务列表中）。在此关卡通过且结果为 CLEAN，或进入明确的受阻状态之前，不得修复、更新文档、提交或移交。

触发条件： 产生任何发现（Critical、High、Medium 或 Low）。仅当报告结论为无条件 PASS，且确实没有任何发现时，才可跳过。

必须调用： 只要存在一项发现，就必须在任何修复、文档更新、提交或移交之前，通过技能调用来调用 $why-review 技能。没有内联替代方案——手动重读引用的 file:line、在脑中重新追踪代码，或声称发现“已经验证过”，都不算数。通过此关卡的唯一方式，是实际调用 $why-review --validate-findings 并获得结论。

父工作流边界： 如果此技能作为 $workflow-review-changes 的第 1 步被调用，则不要在本地运行此 Phase 6。完成审查报告后即停止，并将其交给父工作流的第 2 步；父工作流会在任何并行审查者或修复操作开始之前运行 $why-review --validate-findings。

流程（设有次数上限的重做循环）：

1. 读取自己已定稿的报告 plans/reports/{skill}-{date}-{slug}.md
2. 通过技能调用来调用 $why-review 技能（终端的 --validate-findings 模式——在同一个主 Agent 会话中运行，不得启动子 Agent，也不得递归）。“同一个会话”是指 why-review 技能在本次对话中执行——这并不意味着可以用自己的内联重读来替代技能调用。技能必须实际运行。传入参数：--validate-findings plans/reports/{skill}-{date}-{slug}.md，针对每项发现验证：(a) file:line 证据存在且准确；(b) 发现正确（重新追踪所引用的代码）；(c) 严重性合理，没有夸大；(d) 符合项目最佳实践和惯例；对每项被否决的解读进行最有力的论证；并指出审查所遗漏的任何发现或改进机会
3. 读取 why-review 返回的验证结论文件路径，预期为 plans/reports/why-review-validate-{date}.md
4. 对 why-review 的结论进行分类：
   • CLEAN——所有发现均已确认正确、有证据支持、合理且符合最佳实践，且未发现新的问题或改进机会 → 在自己的报告中追加 ## Why-Review Validation 行（“所有 N 项发现均已对照实际代码重新验证；无变更。”），关卡通过；若 N > 0，立即进入 Phase 7。
   • HAS ISSUES——why-review 降低或移除某项发现、指出证据缺失或不准确，或发现新的问题或改进机会 → 转到第 5 步。
5. 协调修订： 更新自己的定稿报告——调整严重性、移除误报、添加发现的问题或改进机会，并添加 ## Why-Review Validation Notes 部分，说明具体改动及原因。
6. 对已更新的报告重新运行 $why-review --validate-findings（返回第 2 步）——只有报告发生变更时才需要重新验证。每次验证都是终端调用（验证模式不会递归）；循环由此处管理，且有次数上限。重复此流程，直到 why-review 返回 CLEAN，或达到最多 2 轮重做（共 3 次验证）。
7. 如果达到上限后仍未 CLEAN： 在 ## Why-Review Validation — Unresolved 下记录未解决事项，并直接向用户提问以升级处理，不要默默陷入循环。

跳过条件（若跳过，必须明确记录原因）：

• Verdict 为无条件 PASS 且没有任何发现 → 记录“已跳过 — 无发现需要验证”，并且不要运行 Phase 7
• $why-review 本身就是当前激活的技能上下文 → 不要递归调用；why-review 会通过自己的终端 --validate-findings 模式重新验证（参见其中的 Findings Validation Gate）

**存在的原因：**AI 报告可能受到确认偏误、误报和严重性夸大的影响。验证可在编辑前确认发现；报告变更后重新验证，则能弥补已修正的发现再未检查的漏洞。

---

Phase 7：递归自动修复 + 全面重新审查循环（有已验证的发现时为必需步骤）

目的：修复会改变审查目标。下一次检查必须从 Phase 0 开始，完整重新调用 $review-changes，不得沿用旧的审查状态继续。

**触发条件：**Phase 6 返回 CLEAN，且已验证的报告仍包含一个或多个发现、薄弱之处、过时文档项、缺失测试项或必需的改进。

**父工作流边界：**当此技能作为步骤 1 在 $workflow-review-changes 中调用时，不要在此处自动修复，也不要重新调用 $review-changes。父工作流的步骤 10-15 负责 $plan、$plan-review、$plan-validate、$why-review、$feature-implement 和完整重启关卡。

协议：

1. 编辑前创建新的修复周期任务：每个已验证的发现对应一个任务，另设一个定向验证任务和一个 $review-changes 重启任务。
2. 在所属层级自动修复已验证的发现。对于过时文档：运行 $docs-update，或仅在验证后编辑权威文档。对于测试/规范：先更新权威产物，再更新派生仪表板。
3. 对修复集运行定向验证：根据具体情况执行测试、lint、文档/规范同步、SDD、图谱或配置检查。
4. 在审查报告中追加 ## Fix Cycle {N}：记录已修复的发现、变更的文件、验证命令/结果，以及附有原因的未解决事项。
5. 在同一个主 Agent 会话中，针对当前完整审查目标重新调用 $review-changes：
   • 为所有阶段创建全新的任务列表
   • 重新运行 Phase 0 影响范围分析、Phase 0.3 风险检测、Phase 0.7 表面分类、Phase 1 差异收集及后续阶段
   • 从头重新读取所有变更文件，包括原始变更和 Phase 7 修复
   • 仅将之前的报告视为历史背景；不得将之前的发现重用于当前结论
6. 重复 Phase 0 → Phase 7，直到一次完整的 $review-changes 调用得出无条件 PASS，且没有任何发现，并跳过 Phase 6，理由为“没有发现需要验证”。

停止条件：

• 如果同一已验证发现连续 3 次完整审查调用中重复出现，且没有明显进展，则停止并请用户决定，不要无限循环。
• 如果某项发现无法在没有产品/负责人输入的情况下安全自动修复，则记录阻塞原因并询问用户。
• 如果所需的验证工具或子技能不可用，则停止并在调整协议前征求用户意见。

不可妥协的规则：

• 绝不要在 $why-review --validate-findings 确认当前发现集之前修复发现。
• 修复后，绝不要在未从 Phase 0 重新运行完整 $review-changes 协议的情况下，将审查标记为干净。
• 修复后，绝不要只审查已修复的文件；要审查当前完整差异，因为修复可能与更早的变更相互影响。
• 重启后，绝不要沿用旧的待办任务；每次递归审查调用都要重新拆分所有阶段。
• 除非输出格式中的目标达成矩阵显示每项必需的已保存标准都为 PASS（或为 BLOCKED 且附有面向用户的升级处理原因），否则绝不要宣布无条件 PASS。必需标准的 FAIL 属于此修复循环中已验证的发现。

---

阶段 8：强制最终文档更新关卡（强制 — 在审查／修复循环收敛且无问题后始终运行）

目的： 确保变更后不会遗留过时文档。阶段 5–7 只修复审查_标记_为问题的文档；此终端关卡会无条件运行 $docs-update，以便将维度审查未发现的受影响文档与实际变更保持一致。代码审查结论无问题，并不意味着文档已是最新。

触发条件： 审查已收敛——一次完整的 $review-changes 检查没有发现任何问题，且所有已验证的修复均已应用。此关卡在独立模式下始终运行；是否发现过时文档问题并非其运行条件。

父工作流边界： 当此技能作为步骤 1 在 $workflow-review-changes 内调用时，不要在本地运行阶段 8——父工作流自身在 $feature-implement 和重启关卡之后执行的 $docs-update 步骤负责最终文档同步。记录 Phase 8 deferred to parent workflow $docs-update step.

流程：

1. 将 [Review Phase 8] 任务设为 in_progress。
2. 调用 $docs-update，覆盖完整变更集（阶段 1 的差异来源以及任何阶段 7 修复）。让它根据变更检测受影响的文档——功能文档、架构参考文档、README、API 文档、测试规范、设置／入门指南。
3. 如果阶段 4 的规范漂移裁定（SYNC:spec-drift-adjudication）返回任何 SPEC-STALE 结论——权威功能规范已不再反映预期行为（包括修复缺陷后规范将缺陷描述为正确行为的情况）——则在 $docs-update 之前运行 $spec [update]，先将规范修正为预期行为。绝不要让 $docs-update 将错误或已被取代的行为写入规范。CODE-WRONG 结论不需要编辑规范——相关问题已在阶段 7 的代码修复循环中修复。任何 SPEC-SILENT 结论——代码已实施某项不变量，但没有任何规范工件对此进行说明——都属于增强：在 $docs-update 之前运行 $spec [update]（添加 §4 BR／§3 AC）和 $spec [mode=tests]（添加 §8 TC），然后确保存在相应的保护性测试；绝不要让已发现的不变量继续没有文档记录。
4. 在审查报告的 ## Phase 8 Docs-Update 下记录已应用的文档更新（或记录 No impacted docs — verified N changed files against related docs）。
5. 将 [Review Phase 8] 任务设为 completed。

终止保证： 区分阶段 8 中的两类编辑。文档正文编辑（叙述性／参考文档文本，不新增规范规则）不会重新触发循环（因为代码行为没有变化）；但必须接受 M1-M6 规范漂移检查（审查清单 §8）和最终回读——从而保证终止。规范内容编辑——新增书面规范规则（将 SPEC-SILENT 不变量纳入 §3／§4／§8，或修正改变既定意图的 SPEC-STALE）——会触发一次有范围限制、限定于模块的复审，针对修订后的规范检查整个软件包（规范 + 测试 + 受影响模块的代码），以确认新写入的规则确实由代码实施并由测试保护，同时查找其他可能被隐藏的规则。除非这次复审本身产生了新的已验证问题（此类问题随后进入常规循环），否则这一次有范围限制的复审即告结束。终止性仍有保证：复审限定于模块范围，每次增强最多运行一次，而不是全面重启阶段 0；复审无问题即结束此技能。这样一来，增强不再是“在末尾触发一次，之后从不复查”，而是“触发后再进行一次收敛检查”，避免审查与文档更新之间无限循环。

强制要求： 阶段 8 运行完毕（或已明确推迟至父工作流）之前，绝不要宣布审查完成或移交工作。跳过文档更新的通过审查属于未完成的审查。

---

后续步骤

强制要求——无一例外 完成本技能后，必须通过直接询问用户来提供选项。不要因为任务看起来“简单”或“显而易见”就跳过——由用户决定：

• "$code-review (推荐)" — 更深入的代码质量审查
• "$watzup" — 收尾会话并审查所有更改
• "跳过，继续手动操作" — 由用户决定

AI Agent 完整性门槛（不可妥协）

完成 ≠ 正确。 在报告任何已完成的工作之前，必须证明：

1. 搜索每个已移除的名称。 提取、重命名或删除操作涉及 N 个文件？通过 grep 确认所有文件类型中都没有残留引用。
2. 更改前先问为什么。 现有值都是有意设置的，除非有证据证明并非如此。没有追溯到依据，就不要“修复”。
3. 验证所有输出。 一个构建通过 ≠ 所有构建都通过。检查每个受影响的技术栈。
4. 评估模式是否适用。 复制附近的代码？验证前提是否相符——范围、生命周期、基类和约束都相同。
5. 新产物 = 已接入的产物。 创建了某个东西？证明它已注册、已导入，并且所有使用方都能访问。

相关技能

技能	关联关系	调用时机
$docs-update	强制终端关卡（Phase 8） — 审查／修复循环收敛后的最终文档同步；也是修复已标记过时内容的主要路径	审查通过后，在 Phase 8 始终调用（独立执行）——无条件；并在 Phase 7 处理已验证的过时问题。若由 $workflow-review-changes 调用，则交由父级处理。
$spec-index	派生索引 — 根据功能规格重新生成分类目录中的 INDEX.md／ERD（绝非事实来源）	规格变更后用于刷新导航辅助内容——不可用于修正规格
$spec [update]	规范规格更新器 — 修正功能文档 §1-8（唯一事实来源）	由 docs-update 内部调用；针对特定内容更新时可直接调用——若发现规格有误，须在调用 docs-update 之前调用
$spec [mode=tests] [update]	测试规格更新器 — 测试用例可能过时的时候调用	由 docs-update 内部调用；针对特定测试用例更新时可直接调用
$integration-test-review	强制覆盖率关卡（Phase 3.7） — 7 项测试质量审计 + 第 7 关变更覆盖映射（每项行为变更 → 对应覆盖测试 + 规格测试用例）	行为相关代码发生变更时，在 Phase 3.7 始终调用（独立执行）；若由 $workflow-review-changes 调用，则交由父级专用步骤处理。仅文档差异可跳过
$review-ui	UI／前端质量关卡 — 溢出、响应式弹性布局、z-index、SCSS/BEM	由此技能负责——当差异包含前端／UI 文件时，作为 UI 维度在内部调用（ui-ux-designer 子 Agent）；不是单独的工作流步骤
$code-simplifier	质量优化维度 — 提高清晰度／一致性／可维护性的简化	由此技能负责——当差异包含代码文件时，在 Phase 3.5 内部调用（报告模式）；其发现的问题经 Phase 6 验证后，在 Phase 7 修复
$code-review	代码质量 — 对变更代码进行更深入的审查	始终在 review-changes 质量检查之后执行

独立调用链

在工作流之外调用时（即用户直接运行 $review-changes）：

review-changes (you are here)
  │
  ├─ Phase 3.5: Code-simplifier optimization (INTERNAL — $code-simplifier over changed code files, report mode)
  │    → Simplification findings feed Phase 6 validation → Phase 7 fix (skip docs-only diffs)
  │
  ├─ Phase 3.7: Integration-test-review coverage gate (INTERNAL — $integration-test-review over the FULL diff, 7 gates)
  │    → Gate 7 maps every behavior-changing production file to a covering test (integration-first) + spec TC
  │    → GAP/SPEC-GAP verdicts feed Phase 6 validation → Phase 7 fix
  │    → GAP fix = WRITE the missing test via $integration-test; SPEC-GAP fix = $spec [mode=tests] [update] (skip docs-only diffs)
  │
  ├─ Follow-on quality checks (review-architecture → code-review → performance)
  │
  ├─ Phase 5: Documentation Staleness Triage
  │    → If stale docs detected: [REQUIRED] include as finding for Phase 6 validation
  │    → If validated in Phase 6: [REQUIRED] fix in Phase 7 via $docs-update or canonical doc edit
  │    → Then recursively restart $review-changes from Phase 0
  │
  ├─ Integration test check (SYNC:integration-test-sync-check):
  │    → If logic changes touch tested areas: [REQUIRED] → $integration-test [from-changes]
  │    → Then: $integration-test-review → $integration-test-verify
  │
  ├─ Translation sync check (SYNC:translation-sync-check):
  │    → If multilingual UI text changes lack locale updates: [REQUIRED] ask the user directly + explicit decision
  │
  ├─ Spec drift adjudication (SYNC:spec-drift-adjudication) — ALL behavior-changing reviews:
  │    For every behavior-bearing change diverging from the canonical Feature Spec, classify:
  │    → CODE-WRONG (change violates an intended spec rule/AC/invariant) → [REQUIRED] BLOCKING finding; fix code/test (regression TC first)
  │    → SPEC-STALE (intentional new behavior the spec no longer reflects) → [REQUIRED] $spec [update] BEFORE $docs-update, then $spec [mode=tests] [update]
  │    → AMBIGUOUS → [REQUIRED] ask the user directly (or canonical spec owner) before editing either side
  │    → SPEC-SILENT (code enforces a correct invariant the spec never states) → [REQUIRED] enrich: $spec [update] add §4 BR/§3 AC + $spec [mode=tests] add §8 TC, then guarding test
  │    Bugfix sub-case: if post-bugfix AND spec documents the bug as expected behavior → SPEC-STALE; never let $docs-update codify broken behavior.
  │    Never normalize drift just because code/tests are green.
  │
  ├─ Phase 6 + Phase 7 recursive loop
  │    → If ANY findings exist: $why-review --validate-findings
  │    → If validated findings remain: auto-fix, verify, then restart $review-changes from Phase 0
  │    → Repeat until a full review invocation has zero findings
  │
  ├─ Phase 8: [MANDATORY FINAL after zero findings] → $docs-update over the full changeset
  │    → ALWAYS runs (unconditional) — syncs every impacted doc so none stay stale
  │    → docs PROSE edits (no new spec rule); M1-M6 check + read-back, NO full code re-review (guarantees termination)
  │    → SPEC-CONTENT edits (a newly written spec rule — SPEC-SILENT promoted to §3/§4/§8, or a SPEC-STALE correction changing documented intent) → exactly ONE bounded, module-scoped re-review of the affected module's package (spec + tests + code) to confirm the new rule is enforced in code + guarded by a test; that single pass terminates unless it itself yields a new validated finding (then normal loop). At most once per enrichment, never a full Phase-0 restart.
  │    → A passing review with skipped docs-update is an INCOMPLETE review
  │
  └─ [RECOMMENDED after Phase 8] → $watzup
        Summary of all review findings, doc changes, and test coverage status.

[CRITICAL — TOP 3 RULES]

1. MUST ATTENTION 首先检查 Phase 0 图的影响范围 — 绝不能跳过；这将决定整个审查顺序
2. 发现问题后，执行验证 → 修复 → 完整重启。 运行 $why-review --validate-findings，修复已验证的问题，然后从 Phase 0 重新运行 $review-changes，直到完整检查通过且没有发现任何问题。
3. MUST ATTENTION 在开始前跟踪所有阶段的任务；缺失的测试 MUST 通过直接询问用户来揭示，不能悄悄记录

[IMPORTANT] 使用任务跟踪，在开始前将所有工作拆分成小任务——包括每个文件的读取任务。这样可以防止因文件过长而丢失上下文。对于简单任务，AI MUST ATTENTION 询问用户是否要跳过。 系统化评审分批处理（map-reduce） — 变更集较大时，切勿逐个评审文件。将文件划分为有大小上限的批次，为每个批次并行启动一个专门的子 Agent，然后进行归并。这样可以限制每个上下文的大小——包括每个批次 Agent 和协调者的上下文——因此即使文件数量增加，也能保持完整覆盖。

触发阶梯（按顺序逐级升级，不是相互竞争的阈值）：

1. 变更文件 < 10 个 → 逐个文件顺序评审（默认方式；不分批）。
2. 变更文件 ≥ 10 个 → 切换到系统化并行模式。宣布："Detected {N} changed files. Switching to systematic parallel review protocol." 然后：分类 → 按大小限制分批 → 扁平归并。
3. 类别 > 6 个或文件 > 40 个 → 另外加入分层综合环节（见下文）。第 2 级的所有步骤仍然适用。

步骤 1 — 分类。 根据项目的实际结构（而非强行套用）将变更文件分为逻辑类别。类别是_关注轴_；可参考以下示例，并据此确定适合该代码库的类别：

类别类型	分组示例
Agent/工具链	AI 脚本、钩子、技能定义、工作流配置、lint 规则
根目录配置/文档	根目录 README、项目配置、CI/CD 流水线配置
参考文档	架构文档、模式参考、设置指南
功能/领域文档	业务功能文档、规格文件、ADR
后端逻辑	服务/处理器/控制器源代码（根据项目结构推断）
前端逻辑	UI 组件/状态/API 源代码（根据项目结构推断）
数据/Schema	迁移文件、Schema 文件、种子数据
测试	单元、集成、E2E 测试文件
基础设施	Docker、k8s、CI/CD、云端清单

步骤 2 — 按大小限制分批。 每批次 ≤8 个文件或 ≤2000 行差异，以先达到的限制为准；每个批次启动一个子 Agent。类别仍然是关注轴，但任何超出上限的类别都要拆分成多个符合大小限制的批次（30 个后端文件 → 4 个批次）。设置大小上限而非类别上限，才能安全处理“大量文件”：仅限制类别数量，可能导致某个类别过大，使单个 Agent 的上下文不堪重负。

步骤 2a — 为每个批次选择子 Agent 类型（匹配该批次的主要关注点）：

• 代码逻辑（任何技术栈）→ code-reviewer
• 涉及安全的变更 → security-auditor
• 性能关键路径 → performance-optimizer
• 文档、计划、规格、配置、基础设施 → general-purpose

每个批次子 Agent 都会收到：完整的文件列表；作为主要思考模型的 SYNC:category-review-thinking——从第一性原理推导每个类别的关注点，而非使用固定清单（如果调用方技能不包含该区块，则直接采用以类别为先的思考方式）；与其关注点相关的项目参考文档（通过 *patterns*、*conventions*、*style-guide* 发现）；交叉引用核验说明（数量、表格、链接）。所有批次 Agent 并行运行，并将发现写入 plans/reports/（遵循 SYNC:task-tracking-external-report）；归并者从磁盘读取报告，绝不依赖记忆。

步骤 3 — 归并。

• 扁平归并（第 2 级：类别 ≤6 个且文件 ≤40 个）： 协调者收集每份批次报告，跨批次交叉核对数量/表格/契约，发现只有跨类别才能看出的缺口（代码中有功能但文档缺失；新增 API 端点却没有客户端调用），并整理为一份按类别划分的整体报告。
• 分层归并（第 3 级：类别 > 6 个或文件 > 40 个）： 插入中间层——每个关注领域由一个综合 Agent 负责，它只读取本领域的批次报告，并输出一份综合结果。协调者读取的是关注领域综合结果（约 5 份），而非原始批次报告——使归并者的上下文复杂度为 O(#关注领域)，而非 O(#文件)。
  • 跨关注领域交互检查（第 3 级强制执行——弥补综合层盲点）： 按关注领域分开综合，可能遗漏横跨两个关注领域和两个批次的交互（数据层/批次 7 中的受污染源 → api/批次 3 中的汇）。因此：(a) 每个关注领域综合 Agent 必须明确列出**“跨关注领域交互候选项”——它处理过且可能与其他关注领域关联的实体/符号/契约（共享 DTO、事件名称、表/集合名称、导出符号）；(b) 在得出结论前，协调者必须**针对所有关注领域综合结果中的这些候选项执行步骤 3 的交叉引用/缺口检查，而不能只在批次内检查。缺少此步骤，就会在其所针对的大型差异中，以限制上下文为代价牺牲完整性。

步骤 4 — 整体评估。 综合所有发现后，评估：作为统一意图的整体一致性；跨类别同步情况（文档是否与代码一致？契约是否与调用方一致？）；类别交互处的风险区域；变更产物是否缺少相应的文档/规格更新。

不得静默截断。 如果任何上限导致抽样，或因预算限制而丢弃某个批次，必须明确宣布被丢弃/抽样的范围——有限覆盖绝不能被误认为完整覆盖。 从末端到起点的调试追踪 — 对于复杂 bug、验证失败、回归修复、会改变行为的代码或不清晰的代码流程，在提出修复方案前，先从观察到的最终状态开始反向追踪。

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

以下内容完成前，禁止继续： 明确最终状态 · 写出反向追踪 · 列举所有输入路径 · 完成假设矩阵 · 论证负责修复的层 · 将正向收敛证明对应到测试。

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

批判性思维模式 — 运用批判性思维和顺序思维。每项主张都需要可追溯的证据；只有置信度 >80% 才能采取行动。 防止幻觉： 绝不把猜测当作事实——为每项主张引用来源，坦然承认不确定性，自行检查输出中的错误，独立交叉验证，并对自己的判断保持怀疑——缺乏证据的确定性是一切幻觉的根源。 顺序思考协议 — 为复杂或模糊的工作提供结构化的多步骤推理。在规划、审查、调试或完善想法时使用；对于这类工作，一次性推理并不安全。

在以下情况触发： 复杂问题分解 · 需要修订的自适应计划 · 需要纠正方向的分析 · 范围不明确或逐渐显现 · 多步骤解决方案 · 基于假设的调试 · 跨领域权衡评估。

格式（显式模式 — 可见的思考过程）：

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

必须包含的结尾内容： 说明置信度百分比 · 列出假设 · 提出未决问题 · 明确具体的下一步行动。

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

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

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

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

1. 搜索 3+ 个相似模式（grep／glob）——引用 file:line 作为依据
2. 阅读目标区域内的现有文件——理解其结构、基类和惯例
3. 当 .code-graph/graph.db 存在时，运行 python .claude/scripts/code_graph trace <file> --direction both --json
4. 通过 connections 或 callers_of 梳理依赖关系——了解哪些内容依赖目标
5. 对于非简单任务（涉及 3+ 个文件），将调查结果写入 .ai/workspace/analysis/
6. 实施前重新阅读分析文件——绝不能只凭记忆开展工作。——原因：上下文过长会导致偏离文件内容；文件才是事实依据
7. 现有模式可用时，绝不能另创模式——完全遵循现有模式，或记录偏离原因。——原因：模式不一致会割裂代码库，拖慢每位后续读者的工作

在以下事项完成前，禁止继续： - [ ] 已阅读目标文件 - [ ] 已搜索 3+ 个模式 - [ ] 已进行图追踪（若 graph.db 存在） - [ ] 已通过证据验证假设 设计模式质量 — 每次代码更改都要进行的优先检查：

1. 通过 OOP 实现 DRY： 找出用途、命名模式或生命周期相同的类／模块。运用你对项目语言／框架的了解，确定符合惯用方式的抽象（基类、混入、trait、协议、装饰器）。存在 3 个或更多相似模式时 → 提取为共享抽象。
2. 职责恰当： 将逻辑放在最低层（实体 > 领域服务 > 应用服务 > 控制器）。绝不在控制器中编写业务逻辑。
3. SOLID： 单一职责（只有一个变更原因）。开闭原则（扩展，而非修改）。里氏替换（子类型可替换）。接口隔离（接口应小而精）。依赖倒置（依赖抽象）。
4. 提取／移动／重命名后： 使用 Grep 检查整个范围内是否存在悬空引用。绝不容忍遗漏。
5. YAGNI 门槛： 除非存在 3 个或更多实例，否则绝不推荐设计模式。不要为了假设的未来用途进行提取。

需要标记的反模式： 上帝对象、复制粘贴式继承、循环依赖、抽象泄漏。

通过串行检查关注设计质量 — 每次只检查一个质量维度（分轮检查），不要一次检查所有问题。——原因：注意力分散会漏掉单一焦点检查能够发现的问题。

1. 确定适用维度 — 根据代码的语言、领域和模式，判断适用哪些质量维度：DRY、SOLID 原则（SRP／OCP／LSP／ISP／DIP）、OOP 惯用方式、内聚／耦合、GRASP、迪米特法则、CQRS 不变量等。维度列表并非固定，应根据代码的实际功能推导。

2. 针对每个维度进行一次专注检查 — 按顺序逐一专注检查每个维度。不要在不同轮次中混合检查事项。

3. 门槛：3 个或更多相似模式 = 必须提取 — 这不是可选建议，而是必须采取行动的结构性修复。

4. 同类违规达到 2 个或更多 = 结构性发现 — 将其报告为需要通过架构解决的“模式问题”，而不是列出各个单独实例。 复杂度预防（Ousterhout）——必须遵守。以变更成本衡量代码：一项业务变更应对应一处代码变更。审查时标记以下所有问题：

5. 变更放大——小型业务变更迫使你在 >3 处修改代码 → 结构性缺陷。针对一个合理的未来变更（添加变体、添加字段、添加授权），统计编辑位置。>3 处 = 拒绝。

6. 认知负担——读者必须记住过多上下文才能安全地修改代码。标记深层继承、过长的参数列表、布尔陷阱、隐式顺序依赖。

7. 入口处的横切重复——在每个控制器/处理器/路由中重新实现日志记录、错误处理、验证、身份验证、事务处理。提取到中间件 / 拦截器 / 过滤器 / 装饰器 / 切面。

8. 泄漏实现技术——仓储向调用方返回 IQueryable/QuerySet/Criteria/原始游标/ORM 实体。返回已完成的结果和能明确表达意图的方法（GetActiveVipUsers()，而不是 Query()）。

9. 类型判断分散——在 >1 处通过 switch/if 链判断枚举/判别符。新增变体 = 新增一个文件，而不是修改 N 处。边界处有一个工厂/注册表 switch 可以接受；分散的 switch = 拒绝。

10. 贫血模型——领域对象只有 getter/setter，逻辑散落在服务中。将不变量/行为移到对象上（order.Checkout()，而不是 order.Status = ...）。

11. 基本类型痴迷——账户号码、电子邮件、金额、百分比、日期范围使用原始 string/int/decimal，并在每个入口重复验证。使用值对象 / 记录 / 结构体封装，并在构造时验证一次。

12. 内联横切关注点——在每个处理器顶部手写授权/租户隔离/审计/净化逻辑。使用声明式标记表达意图（@RequirePermission("Order.Delete")），并在中心位置统一执行。

13. 浅层模块——小类、大接口（许多公共方法、许多标志、许多构造函数参数），但封装的逻辑很少。如果一个小接口隐藏了大量实现，那么这个模块就是深的。如果学习接口所需的成本 ≈ 学习实现的成本 → 内联。

14. 重复组件/处理器生命周期缺少基类——3 个或更多表单/CRUD 处理器/列表视图重复实现加载/脏状态/提交/分页逻辑 → 提取为基类 / 钩子 / 可组合对象 / 混入 / 特征。

15. 过早或延迟抽象——遵循三次法则。第一次出现：直接编写。第二次：注意到重复。第三次：提取。不要在出现真实差异前构建通用框架；也不要复制粘贴到第 4 次。

16. 未将内嵌工具逻辑提取为辅助函数——内联分页循环（while (hasMore) { skip += take; ... }）、临时日期时间运算、字符串解析/格式化、集合分区、重试/退避循环、URL/查询字符串构建。如果算法非平凡且与业务无关、可跨栈复用，就提取到 util/helper/extensions，让调用方用一行代码调用。内联重复 → 扩大重复缺陷的影响范围。

17. 逻辑位于错误的（更高）层——下移至被调用方——当被调用方拥有数据时，调用方却编写业务/派生逻辑。默认情况：应该属于应用服务的控制器代码；应该属于领域服务或实体的应用服务代码；应该属于视图模型/存储的组件代码/服务。调用方深入被调用方的数据结构来进行计算 → 将计算移至被调用方上明确表达意图的方法中。由最低的合适层负责（实体 > 领域服务 > 应用服务 > 控制器 · 模型/VM > 存储 > 组件）。将逻辑放在更高层 = 当同级调用方需要相同逻辑时产生重复。

18. 规则归其所有者——首次编写时就提取——如果调用方内联了从另一类型的数据派生、规范化、验证或计算而来的逻辑，就将它移到拥有该数据的类型中。即使只使用一次也足够——触发条件是职责错误，而非重复。同级调用方总会出现；内联副本会悄然偏离，既不会导致编译错误，也没有可搜索的名称。常见问题：后端——应用层处理器 / 命令 / 查询 / 服务 / 控制器中的内联规则，实际应属于领域实体 / 值对象 / 领域服务。前端——组件中的内联派生逻辑 / 格式化 / 验证，实际应属于模型 / 存储 / 视图模型 / API 服务。**修复方法：**在拥有该规则的类型上将其命名为一个方法（静态或实例方法）；调用方按名称调用。未来出现变体时 → 在所有者上新增第二个命名方法，绝不编写近似的内联副本。先明确职责；复用是随之而来的结果。

提取目标——命名规则应放在哪里：

规则形式	应放在
对实体自身数据执行的纯函数	实体上的静态方法
修改 / 保护实体状态的行为	实体上的实例方法
对基本类型值始终成立的不变量	值对象构造函数
需要 DI（仓储 / 设置 / 时钟）	在 DI 中注册的辅助类
跨类型复用且与领域无关的算法	util / 扩展方法
纯粹的形状 / 投影转换	DTO 映射

提交前编辑位置测试（如果答案是“很多”，则拒绝）：

变更场景	应修改
添加新变体（客户类型、支付方式）	1 个新文件
更改 HTTP 错误响应格式	1 个中间件/过滤器
为每个持久化实体添加时间戳字段	1 个基实体/拦截器
为新端点添加授权	1 个声明式标记
更换数据库/ORM	仅数据层
更改业务计算规则	所属实体上的 1 个方法
为表单添加加载指示器模式	1 个基组件/钩子
为领域基本类型添加验证规则	1 个值对象构造函数
更改分页/重试/日期时间算法	1 个辅助函数/util 函数
更改实体数据的派生逻辑	实体上的 1 个方法

操作准则：

• 先编写调用点。
• 针对合理的未来变更统计编辑位置。
• 优先删除代码，而不是添加代码。
• 在边界处显式呈现假设，在内部隐藏细节。
• 复用前扫描——编写非平凡代码块之前，先搜索类似算法（while.*skip、DateTime.*Add、split/join 链、分页循环、重试循环）。找到匹配的现有辅助函数 → 调用它。如果没有，但模式与业务无关、可跨栈复用 → 在出现第二个调用方之前提取到 util。
• 层级放置测试——问自己：“如果明天有同级调用方需要这个逻辑，他们是否会重新推导？”如果会，那么逻辑就位于错误的层级。将其下移。
• 为未来复用预留空间——如果审查者发现某个代码块很可能出现在另一项功能中（与领域无关的算法、共享生命周期、重复出现的派生逻辑），不要用纯粹的 YAGNI 来合理化。要么现在提取（如果成本低），要么创建一条待跟踪的 TODO，明确写出提取目标，以免第二个调用方悄然复制。悄然重复是默认的失败模式。
• 犹豫不决时，问：“如果需求发生变化，需要修改什么？”

衡量好代码的标准是变更成本。 不是最短。不是最巧妙。不是抽象最多。读过一小部分局部代码后，能够以最低成本安全修改。 经验证问题修复 + 完整重新审查循环——由经验证的问题修复周期触发重新审查，而非由轮次编号触发。审查目的：review → validate findings → fix validated findings → full re-review，直到一次完整审查通过且未发现问题。审查通过即结束循环——无需再进行其他轮次。

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

第 1 轮后的决策：

• 未发现问题（PASS，零条问题发现） → 审查结束。不要启动新的子 Agent 进行确认。
• 发现问题（FAIL，或问题发现数量非零） → 首先运行当前审查技能的问题发现验证关卡；对于审查技能，默认关卡为 $why-review --validate-findings <report-path>。只修复已验证的问题，然后从头开始重新执行完整审查流程，并重新拆分任务。

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

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

**循环终止：**每次完整重新审查后，重复相同的决策：无问题 → 结束；有问题 → 验证问题发现 → 修复 → 从第一个审查阶段重新开始。持续进行，直到一次完整审查通过且未发现任何问题。如果同一个已验证问题连续 3 次完整调用都重复出现且没有进展，或修复需要产品/负责人提供意见，则直接向用户提问并升级处理。

规则：

• 第 1 轮审查通过即结束——无需强制进行第 2 轮
• 绝不修复未经验证的问题发现；必须先使用调用方的验证关卡进行验证
• 修复周期后绝不跳过完整重新审查（每次修复都会使先前的判定失效）
• 绝不跨轮次复用子 Agent——每次使用子 Agent 的迭代都必须启动新的 Agent 调用
• 主 Agent 阅读子 Agent 的报告，但不得筛除、重新解释或推翻其中的问题发现
• 不得以任意的子 Agent 轮次数上限取代审查通过的要求；仅使用重复 3 次且无进展的阻塞规则来避免无限循环
• 在对话上下文中跟踪递归调用次数和重复出现的阻塞项（仅限当前会话）
• 最终判定必须纳入已执行的所有轮次

报告必须为已执行的每个 N≥2 的轮次包含 ## Round N Findings (Fresh Sub-Agent)。 全新上下文重新审查 — 修复后，通过在适用时启动隔离的子 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 调用
• 持续审查，直到一次完整审查未发现任何问题；如果同一个阻塞问题连续 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 必须通过自己的工具调用读取文件，以获得全新上下文
• 不得通过文件路径或标签名引用协议——正文已在上方嵌入
• 不得为协议引入占位符标记——协议必须保持完整展开状态

逻辑与意图审查 — 验证代码的实际行为是否符合修改原因。

1. 修改意图检查： 每个修改过的文件都必须确实服务于所述目的。将无关修改标记为范围蔓延。
2. 成功路径追踪： 沿着修改后的代码，完整追踪一个成功场景。
3. 错误路径追踪： 沿着修改后的代码，追踪一个失败或边界情况场景。
4. 验收条件映射： 如果有计划上下文，将每项验收条件映射到对应的代码修改。
5. 测试验证意图： 对于测试或规范的修改，验证测试是否命名了受保护的业务规则或不变量，以及当该意图遭到破坏时测试是否会失败。
6. 排除迁移测试： 不要为迁移代码编写测试。架构和数据迁移是一次性执行路径，而非核心应用逻辑。

在完成成功路径和错误路径追踪之前，绝不可将审查标记为 PASS。

缺陷检测 — 每次审查都必须检查类别 1–4。绝不可跳过。

1. 空值安全： 参数或返回值是否可能为 null？是否进行了保护？可选链是否存在遗漏？是否检查了 .find() 的返回值？
2. 边界条件： 是否存在差一错误（< 与 <=）？是否处理了空集合？零值或负值？最大限制？
3. 错误处理： try-catch 范围是否正确？是否静默吞掉异常？错误类型是否具体？是否在 finally 中清理？
4. 资源管理： 连接或流是否已关闭？销毁时是否取消订阅？是否清除了计时器？内存是否有上限？
5. 并发（如有异步）： 是否缺少 await？共享状态是否存在竞态条件？闭包是否过期？是否会引发重试风暴？
6. 技术栈专属检查： 检查根据本地代码发现的已配置语言、运行时的常见陷阱和框架专属故障模式。

分类： CRITICAL（崩溃或数据损坏）→ FAIL | HIGH（行为错误）→ FAIL | MEDIUM（边界情况）→ WARN | LOW（防御性问题）→ INFO

测试规范验证 — 将修改过的代码映射到测试规范。

1. 根据现有文档、测试用例文件、BDD 功能文件或规范目录，识别项目的测试或规范格式。
2. 每条修改过的代码路径都必须映射到对应的测试用例或规范（否则标记为“需要测试用例”）。
3. 新函数、端点或处理程序 → 标记为需要创建测试规范。
4. 排除迁移文件的测试用例/测试创建；架构和数据迁移是一次性执行路径，而非核心应用逻辑。
5. 如果存在规范证据字段，验证其是否指向实际代码（file:line，而非过时的引用）。
6. 验证每个有意义的测试用例是否命名了业务意图或不变量；将只反映实现细节的行为测试用例标记出来。
7. 涉及身份验证或数据的修改 → 验证是否存在相应的授权和数据状态测试用例。
8. 如果修改过的代码路径没有对应规范 → 记录缺口，并建议使用项目的测试规范工作流。

绝不可跳过测试映射。 未经测试的代码路径是生产环境缺陷的头号来源。 集成测试同步检查 — 验证已更改的业务逻辑文件是否有对应的测试。

1. 从已更改的文件中 → 识别业务逻辑文件：处理器、命令、查询、服务、控制器、解析器、事件处理器。不同技术栈的命名各不相同 — 根据项目约定推断（例如 *Service.*、*Handler.*、*Controller.*、*Command.*、*Query.*、*Resolver.*）。排除迁移文件：架构／数据迁移是一次性执行路径，并非核心应用逻辑。
2. 对于每个已识别的文件 → 搜索对应的测试文件。根据项目中现有测试推断测试命名方式（例如 *.test.ts、*Tests.java、*_test.py、*.spec.js、*Tests.cs）。检查标准测试目录（tests/、spec/、__tests__/）或相邻的测试项目／软件包。
3. 如果测试存在 → 检查测试方法是否覆盖已更改的行为（新方法／参数／逻辑路径）
4. 如果测试缺失 → 必须：直接向用户提问：“业务逻辑文件 {file} 没有集成测试 — 请先运行 $integration-test，或确认测试已编写？”选项：“先运行 $integration-test”（推荐）|“测试已编写／更新 — 继续”
5. 严重性：高 — 必须向用户指出已更改的业务逻辑缺少测试；不得悄悄标记后继续

对于每项缺少测试覆盖的业务逻辑更改，都必须明确向用户提问并由用户决定 — 绝不悄悄跳过。— 原因：悄悄跳过会导致未经测试的业务逻辑被部署到生产环境。

翻译同步检查 — 验证多语言 UI 更改是否包含翻译更新。

1. 根据项目配置判断是否为多语言模式：localization.enabled === true 且 supportedLocales.length > 1
2. 通过扩展名／路径模式检测面向 UI 的文件是否已更改（.ts、.tsx、.html、.css、.scss，以及配置时使用的 localization.uiPathPatterns）
3. 对于多语言 UI 更改，验证是否存在翻译资源差异（配置时使用 localization.translationFilePatterns）
4. 如果缺少翻译更新 → 必须：直接向用户提问：“多语言项目中的 UI 文本已更改，但未检测到翻译更新。现在运行翻译同步，还是在明确接受风险后继续？”选项：“先运行翻译同步”（推荐）|“明确接受风险后继续”
5. 严重性：高 — 多语言 UI 文本更改必须由用户明确决定是否同步翻译，不得悄然放行

不得悄悄跳过。多语言 UI 文本更改必须明确确认是否同步翻译。 类别审查思路 — 用于审查任意类别变更文件的思考框架。它不是固定检查清单——应根据领域知识推导关注点；示例仅供参考。你对该类别的了解胜过此处的任何清单——请相信自己的判断。

步骤 1 — 了解类别的作用。 该类别在整个系统中负责什么？必须维护哪些不变量？它有哪些使用方契约（谁依赖它，他们有何预期）？

步骤 2 — 阅读该类别的项目约定。 搜索该领域的参考文档、风格指南、ADR 或 README。使用 grep 查找 3 个或更多类似文件——总结命名约定、结构模式和共享基类。如果没有文档，请根据现有代码归纳约定。

步骤 3 — 从基本原理推导关注点。 应用所有相关项，并根据实际类别扩展此列表：

• 正确性： 逻辑是否符合预期？追踪正常路径和错误路径。
• 边界契约： 是否遵循接口/API/事件/协议？是否引入隐式耦合？
• 项目约定： 新代码是否遵循步骤 2 中找到的模式？应有证据佐证，而非凭空假设。
• 安全性： 每个入口点都强制执行身份验证吗？是否在边界处验证输入？差异中是否包含机密信息？
• 性能： 是否存在无界操作？N+1 模式？异步上下文中的阻塞调用？未建立索引的查询？
• 可维护性： 是否遵循 DRY？是否遵循单一职责原则？复杂度是否合理？名称是否能体现意图？
• 测试覆盖率： 变更路径是否有测试覆盖？变更后现有测试是否仍然有效？
• 文档： 相关文档、规范或 README 是否反映了这些变更？

步骤 4 — 创建子任务并执行。 针对每个已识别的关注点，创建一个用于跟踪任务的子任务，附上 file:line 证据逐项处理，并标记为完成。没有证据，不报告问题。

按类别类型列举的关注点示例（并非详尽无遗——请相信自己的判断，考虑列表以外的事项）：

• 服务端逻辑： handler/service 结构约定、验证层位置、副作用隔离、跨服务边界约束、数据访问层分离、错误传播策略
• 客户端逻辑： 组件生命周期管理、资源清理（订阅、监听器、计时器）、状态管理模式、API 集成层分离、响应式流组合
• 数据/Schema： 迁移是否可逆（回滚脚本）、锁对表数据量的影响、回填是否幂等、索引是否覆盖查询模式、部署顺序
• 配置： 是否存在于所有环境？差异中是否包含机密信息？配置缺失时，应用是否会快速失败（而非静默返回 null）？是否在设置指南中有所说明？
• 基础设施： 开发环境与生产环境是否一致？是否存在硬编码的开发环境值（localhost、调试标记）？镜像/依赖版本是否固定？是否记录了 CI/CD 所需的机密信息？
• 样式/资源： 是否遵循项目命名约定？是否使用设计变量/令牌（而非硬编码的魔法值）？作用范围是否正确（组件样式是否造成全局副作用）？
• 文档： 是否准确？链接是否有效？示例是否仍与当前代码/行为一致？是否涵盖新场景？
• 测试： 断言是否验证特定结果（而不只是“没有异常”）？是否幂等（可重复执行 N 次）？是否覆盖边缘情况，而不只是正常路径？
• 安全相关产物： 所有代码路径是否都经过安全关卡？是否有负向测试（拒绝未授权访问）？强制执行逻辑和展示控制是否都已更新？
• 构建/工具： 规则变更是否一致生效？是否有会静默忽略违规的例外？是否记录了对 CI 运行时间的影响？ 图辅助调查——当 .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 查看细节。

嵌套任务扩展约定——对于工作流步骤调用，[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-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。
3. 阅读所有必需文档。如果 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；不要自动运行。
4. 开始目标工作前，说明：Reference docs read: ... | Not applicable: ...。

**就绪条件：**已评估范围、已检查/阅读必需文档或已完成设置流程、已确认 lessons.md、已给出引用。 任务跟踪与外部报告持久化——执行前先完成初始化；然后在处理目标文件或源码之前，预先获取项目参考文档。

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

**解除阻塞的条件：**任务分解已创建；计划或审查工作已声明报告路径；下一项发现出现前，首项发现已持久化。

源码/测试偏差检查。 对于编码、修复、调试、调查、测试或审查工作：源码行为发生变化时，检查受影响的单元、集成和端到端测试，并根据证据判断测试是否应调整以匹配预期行为，或源码变更是否属于需要修复的意外缺陷。不要为迁移代码编写测试；模式或数据迁移是一次性执行路径，不属于核心应用逻辑。

规范偏差裁定（代码错误还是规范过时）。 每当变更后的行为偏离规范性功能规范（业务规则、验收标准、流程、状态转换，或 docs/specs/ 下的 §8 TC）时，MUST NOT 默默选择一方。依据 shared/sdd-artifact-contract.md → Drift Gates 进行裁定：

1. 检测——将变更与规范中记录的意图进行比较。若无偏差，则记录 Spec in sync 并继续。
2. 分类偏差：
   • CODE-WRONG——规范正确描述了预期行为，而变更违反了该行为 → 阻塞性发现；依据预期行为修复代码/测试（先编写或调整回归 TC）。
   • SPEC-STALE——变更代表新的预期行为，而规范仍记录着旧的/错误的行为 → 先通过 $spec [mode=update] 更新规范，然后同步 $spec [mode=tests] + $spec [mode=sync]。
   • AMBIGUOUS——预期行为不明确 → 在编辑任一方之前，直接询问用户（或规范负责人）。
   • SPEC-SILENT——代码正确地执行了某项不变量/行为，但没有任何规范性规范产物（§3 AC、§4 BR、§5 不变量、§8 TC）对此作出说明 → 这不是偏差，而是审查中发现的未编写规则。通过 不变量梳理流程完善规范（$spec [mode=sync] direction=harvest → spec/references/sync.md）：证明该规则始终成立（至少有两个执行点，或有拒绝性守卫），将其表述为全称量化属性，然后将规则添加到 §4（或 §3/§5）以及 §8 TC 中，使用 $spec [update] + $spec [mode=tests]，并添加守卫测试。发现的不变量若只留在代码中（或只留在测试中），即为不完整——这是价值最高的记录，因为它捕捉到了那条无人写下的规则。
3. 绝不要仅因为代码/测试通过就将偏差视为正常——通过可能恰恰体现了偏差本身。必须回归规范性意图，而不能以当前通过的一方为准。

行为发生变化的审查/实现若未裁定规范偏差，即为不完整；发现已执行但未写明的不变量却未将其纳入规范（无 §4/§8 条目），同样是不完整的。 AI 错误预防 — 每项任务都要避免的失败模式：

上下文变化后重新阅读文件。 上下文压缩、恢复任务或长时间运行的工作都可能导致记忆过时；行动前请核实当前文件。 依据源证据核实生成的内容。 AI 会幻觉出 API、名称、主张和文档事实。记录或引用之前，请检查相关源文件。 删除或重命名前检查下游引用。 移除某项内容可能导致文档、生成的镜像、配置和调用方过时；先梳理引用。 编辑后追踪完整影响链。 更改定义可能会遗漏派生输出和使用方。宣布完成前，请追踪受影响的链路。 核实所有受影响的输出，而不只是第一个。 一项检查通过不代表所有检查都通过；请验证更改可能影响的每个输出面。 假设现有值都是有意设置的——更改前先问“为什么”。 更改常量、限制、标志、措辞或模式前，请阅读附近的上下文和历史记录。 行动前明确指出歧义——不要默默自行选择。 存在多种有效解释时，必须明确提问，或说明假设及其风险。 确保共享指导与角色相关。 通用指导必须对每个接收它的技能或 Agent 都有帮助；代码专属义务只应放在代码专属规范中。

严重性分级标准 — 根据后果对每项发现进行分类，而不是根据修复难易程度。所有评审使用同一套标准，确保“高”在任何地方都代表相同含义。

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

基于评分的技能应将数值等级映射到这些级别，不要另创一套术语：

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

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

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

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

重要：必须注意 检查 DRY 原则，运用 OOP，确保职责层级正确并遵循 SOLID。移动代码后，使用 Grep 查找悬空引用。

重要：必须注意 做好复杂度预防——一次业务变更对应一次代码变更。标记变更放大（未来每次变更需改动超过 3 处）、分散的类型分支、贫血模型、基本类型偏执、抽象泄漏技术细节、浅模块、未提取的工具逻辑（分页/日期时间/字符串/重试 → helpers），以及放错在更高层的逻辑（下移至被调用方/实体/VM）。不要用纯粹的 YAGNI 为隐性重复开脱。

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

重要：必须注意 核实代码的实际行为是否符合变更原因。追踪正常路径和错误路径。 重要，务必注意 每次审查都要检查空值安全、边界、错误处理和资源管理。

重要，务必注意 将变更的代码路径映射到测试用例。标记未经测试的路径。

重要，务必注意 检查变更的逻辑文件是否有对应测试。通过直接向用户提问指出缺失的测试——这是强制要求，不是建议。

重要，务必注意 对于多语言 UI 文本变更，请验证是否更新了翻译。如果没有更新，必须通过直接向用户提问的方式要求其明确决定。

务必注意 运用批判性思维和顺序思维——每项结论都需要适当的可追溯证据（关于代码库/代码的结论需提供 file:line；关于研究、产品、内容和文档的结论需提供来源 URL 或资料章节）；置信度 >80% 时才能采取行动，<60% 时不要提出建议。防止幻觉：绝不把猜测说成事实，坦诚承认不确定性，独立交叉验证，并对自己的判断保持审慎。

务必注意 运用顺序思维——标记多步骤思考 Thought N/M、REVISION/BRANCH/HYPOTHESIS，并在接近结论时标注置信度百分比；参见 $sequential-thinking 技能。

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

• 强制要求 在处理目标任务前启动任务跟踪；一次只转换一个任务的状态。

• 强制要求 将计划/审查结果增量保存到 plans/reports/，并基于磁盘上的内容综合整理。

• 强制要求 完成任务跟踪初始化后、开始处理目标/源内容前，阅读必需的项目参考文档，并注明 Reference docs read: ...。

• 强制要求 始终包含 lessons.md；项目约定优先于通用默认规则。

• 强制要求 如果项目配置、根目录指令文件或任何必需的参考文档缺失或过时，则在开展常规项目专属工作前，自动运行 $project-init 或更精简的下级流程。

重要，务必注意 调试器跟踪门槛：对于非简单的错误/修复/调查/审查任务，从观察到的最终输出开始，反向追踪 reader → storage/projection → writer → consumer/job → producer/trigger。列出所有输入路径和假设后再修复。在跟踪、假设矩阵、负责修复的层级以及正向收敛证明齐备之前，禁止继续。

• 强制要求 父工作流条目不能替代子阶段跟踪；嵌套时须展开阶段，并关联父项。

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

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

• 强制要求 执行后追加迭代证据；报告 PASS 前输出目标满足度矩阵（PASS/FAIL/BLOCKED）；对经过验证的 FAIL 进行循环处理；遇到反复无进展或阻塞时升级处理。绝不要在目标文件中存储机密。

• 强制要求 大型变更集 → 按大小上限分批（≤8 个文件或 ≤2000 行差异），每批安排一个并行子 Agent；绝不要逐个审查大量文件。

• 强制要求 超过 6 个类别或 40 个文件时，增加分层综合环节；每位关注点综合人员都要提出跨关注点交互候选项，编排器须在结束前执行跨关注点评审。

• 强制要求 按影响程度将发现分类为 Critical/High/Medium/Low；修复或由负责人接受前，Critical/High 项会阻止 PASS。

• 强制要求 基于评分的技能（SRE 0–2 分、性能双轴）映射到相同的四个等级——不得并行使用其他严重性分类体系。

• 强制要求 根据文件语言、目录语义和变更性质推导审查类别；每个类别创建一个子任务。

• 强制要求 从第一性原理推导每个类别的关注点，并提供 file:line 证据——绝不使用固定检查清单。

收尾提醒

重要，务必注意目标： 确保每项已审查的变更都没有缺陷、有证据支撑、符合约定，并且在交接前与所需测试和文档保持同步；当代码文件发生变更时，还要证明代码仍然易于修改。

重要，务必注意——当前生效的协议（本技能携带的 SYNC/共享区块的简明摘要；每行均指向上文的规范正文——务必注意遵守完整区块，绝不可仅凭摘要采取行动）：

• 系统化批处理： 文件数 ≥10 → 按大小限制进行并行批处理。
• 调试器追踪： bug/修复 → 通过从终点到起点的反向追踪门槛。
• 批判性思维： 每项结论都要追溯；置信度 >80% 才采取行动。
• 顺序思考： 多步骤任务使用 Thought N/M 标记。
• 先理解代码： 至少 grep 3 次，变更前先阅读代码。
• 设计模式质量： 遵循 DRY/SOLID，在恰当的职责层处理。
• 复杂度预防： 一项业务变更 = 一项代码变更。
• 双轮往返审查： 验证 → 修复 → 完整重新审查，直到无问题。
• 新鲜上下文审查： 修复后由全新、零记忆的子 Agent 重新审查。
• 审查协议注入： 在子 Agent 提示词中逐字嵌入 11 项协议。
• 逻辑与意图审查： 代码实际执行的操作要符合变更原因。
• 缺陷检测： 空值、边界、错误处理、资源清理。
• 测试规范验证： 将变更路径映射到测试用例。
• 集成测试同步： 通过直接询问用户，指出缺失的测试。
• 翻译同步： 多语言 UI 文本变更需要同步更新翻译。
• 类别审查思维： 根据文件和变更性质推导类别。
• 图辅助调查： 对关键文件运行图追踪。
• 嵌套任务创建： 扩展子阶段，并关联父任务。
• 项目参考文档： 阅读必需文档，包括 lessons.md。
• 任务跟踪与报告： 初始化任务，并逐步持久化发现。
• 源代码/测试偏移： 行为变更 → 调整相关测试。
• 规范偏移： 分类为 CODE-WRONG/SPEC-STALE/AMBIGUOUS/SPEC-SILENT，并指派相应修复。
• AI 错误预防： 根据证据验证生成内容，追踪下游引用，验证所有受影响的输出，在上下文丢失后重新阅读，并指出歧义。
• 严重性标准： 根据后果划分为 Critical/High/Medium/Low。

[CRITICAL — 重申三大规则]

1. 务必注意：首先执行第 0 阶段图分析，评估影响范围——绝不可跳过；它决定整个审查的优先级顺序。
2. 务必注意：发现项必须遵循当前的责任边界。 独立模式下，执行第 6 阶段验证 → 第 7 阶段修复 → 从头重启完整的 $review-changes；在 $workflow-review-changes 内部时，报告后即停止，并将发现交给父步骤 2，然后由父步骤 10-15 负责规划、feature-implement 和重启。
3. 务必注意：开始前跟踪所有阶段的任务；必须通过直接询问用户指出缺失的测试。

• MANDATORY 嵌套任务扩展契约 — 在工作流中调用时，仍须通过任务跟踪展开内部阶段，并使用 [N.M] $review-changes — phase 前缀和 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 关联。工作流行是容器，不能替代内部阶段。
• MANDATORY 开始前，使用任务跟踪将工作拆分为小型待办任务
• MANDATORY 通过直接向用户提问来验证决策 — 绝不自动决定
• MANDATORY 添加最终审查待办任务以验证工作质量
• MANDATORY 开始前，查找并阅读项目专属参考文档
• MANDATORY Phase 0 图谱影响范围分析必须是第一步 — 绝不跳过
• MANDATORY 任何发现都必须在修复前验证；独立模式调用 $why-review --validate-findings，而 $workflow-review-changes 父级模式在报告后停止，并将验证交由父级步骤 2 处理
• MANDATORY 独立模式下修复已验证的发现后，必须从 Phase 0 递归调用 $review-changes，使用全新的任务拆分，并审查完整的当前差异，而不只是已修复文件；父级模式下，父级步骤 10-15 负责修复计划、feature-implement 和完整重启
• MANDATORY 持续执行验证 → 修复 → 完整重启，直到某次完整审查调用没有任何发现；独立模式在本地执行此循环，父级模式将发现报告给 $workflow-review-changes 以执行循环
• MANDATORY 每次审查都必须检查文档是否过时 — 即使不自动修复，也要标记过时文档
• MANDATORY 当审查／修复循环收敛到零项发现后，必须运行 Phase 8 最终 $docs-update 门禁 — 始终执行，无条件，不得因审查结果良好而跳过（仅在 $workflow-review-changes 内延后至父级的 docs-update 步骤）— 原因：代码审查通过后，文档仍可能过时，直到 docs-update 根据实际变更逐一核对所有受影响文档；审查结果良好却跳过 docs-update，意味着流程未完成
• MANDATORY 当差异包含代码文件时，必须运行 Phase 3.5 Code-Simplifier 优化门禁 — 对变更的代码文件调用 $code-simplifier（报告模式），在报告中记录其清晰度、一致性和可维护性方面的发现，并通过 Phase 6 验证 → Phase 7 修复处理；仅文档差异可跳过（须记录跳过原因）— 原因：正确性审查证明代码能正常工作，简化器门禁则证明代码易于修改；没有明确提醒时，这一步很容易被悄然省略
• MANDATORY 当差异包含承载行为的代码时，必须运行 Phase 3.7 Integration-Test-Review 覆盖率门禁 — 对完整变更集（生产代码和测试）调用 $integration-test-review；其 Gate 7 必须将每项行为变更对应到覆盖该行为的测试（优先集成测试；若使用单元测试则须说明理由）和一个 spec TC；每个 GAP／SPEC-GAP 都必须作为发现交由 Phase 6 验证 → Phase 7 修复（修复 GAP 即编写缺失的测试）；仅文档差异可跳过，并须记录原因；在 $workflow-review-changes 内则延后至父级专门的 $integration-test-review 步骤 — 原因：看似正确的变更若没有覆盖测试或规范已过时，就会让行为在缺乏保护的情况下发布；配对检查只能证明文件名对应，不能证明覆盖情况
• MANDATORY 缺少变更业务逻辑的测试时，必须通过直接向用户提问的方式告知用户 — 不得只在内部记录
• MANDATORY 独立模式下，只要存在任何发现，就必须运行 Phase 6 Why-Review 发现验证门禁 — 通过技能调用调用 $why-review 技能，并使用 --validate-findings（终端模式，同一会话；必须实际调用技能 — 自行重读引用行或进行任何内联／手动自我验证，都不满足此门禁）。记录首条发现时，立即通过任务跟踪登记 [Review Phase 6] Why-review findings validation gate — invoke $why-review，以免遗忘。验证每项发现是否正确、有证据支持、合理且符合最佳实践；只有发现问题或改进机会时才重新执行，最多重新执行 2 次，之后通过直接向用户提问升级处理；随后 Phase 7 修复已验证的发现并重启此技能。在 $workflow-review-changes 内，不得在本地运行 Phase 6／7；这些门禁由父级步骤 2 和步骤 10-15 负责。
• MANDATORY 遵循声明的步骤顺序；未经用户明确批准，绝不跳过、重排或合并步骤
• MANDATORY 每个跳过的步骤都须说明明确理由；每个已完成的步骤都须提供简洁的证据
• MANDATORY 以报告为驱动 — 在审查每个文件／维度时，逐步将每项发现写入 plans/reports/code-review-{date}-{slug}.md，而不是最后一次性汇总 — 原因：报告既是外部记忆，也是交付物；只保留在上下文中的发现会在上下文压缩时丢失
• MANDATORY 证据门禁 — 每项主张、发现和建议都必须有 file:line 证据或可追溯的调用链，并给出置信度评估（>80% 可执行，60-80% 先验证，<60% 不得建议）；禁止输出推测；“证据不足”是有效结论 — 原因：未经证明的发现会浪费作者时间，并损害他们对整份报告的信任
• MANDATORY 先查惯例再标记 — 标记任何模式、命名或风格违规前，先 grep 3 个以上现有示例；代码库惯例优先于教科书规则 — 原因：依据项目从未采用的规则进行标记，会制造误报
• MANDATORY 对变更代码执行 YAGNI / KISS / DRY / Clean Code 原则 — 标记臆测性泛化、不必要的复杂性和重复知识；3 个以上相似模式 = 必须提取，2 个以上同类违规 = 结构性发现（不是单独的琐碎问题）— 原因：这些是“易于修改”成功指标在日常工作中的具体体现
• MANDATORY 每次行为变更审查都必须进行规范偏差裁定（不只限于 Bug 修复后）— 将每处差异归类为 CODE-WRONG / SPEC-STALE / AMBIGUOUS / SPEC-SILENT，并按要求处理修复（CODE-WRONG → 修复代码 + 回归 TC；SPEC-STALE／SPEC-SILENT → $spec [update] + $spec [mode=tests]；AMBIGUOUS → 直接向用户提问）；若无差异，则记录 Spec in sync — 原因：代码和测试通过，仍可能悄然将规范违规常态化
• MANDATORY 双反馈台账 — 每项行为变更发现都必须同时反馈到规范和测试；任一轴的单元格为空或只写“N/A”都算失败（每个 N/A 都须在单元格内说明理由）— 原因：只修复代码会让规范或其 TC 过时，导致问题在下次变更时再次出现
• MANDATORY Bugfix Debugger Trace Gate（§6.5）— 对 Bug 修复／回归／验证失败／输出过时／行为变更修复，若缺少完整的 End→Start 调试器追踪、枚举的输入路径、假设矩阵、最低责任修复层的理由，以及前向收敛和回归测试证据，则审查失败 — 原因：没有追踪的修复只会处理症状所在的位置，Bug 还会再次发生
• MANDATORY 新鲜上下文门禁（Phase 3）仅用于审查 — 可以新增发现，但绝不修复或验证发现，绝不重新审查已知发现，也不得仅因 Phase 7 重启而运行；任何非零发现集都直接进入 Phase 6 — 原因：重复审查已知发现会消耗上下文，却不会增加有效信号
• MANDATORY 将子 Agent 和综合审查的发现原样整合到主报告中 — 阅读这些发现，绝不筛选、弱化或推翻 — 原因：主 Agent 会为自己的错误找理由；零记忆子 Agent 的存在，正是为了发现这些错误
• MANDATORY 当差异包含前端／UI 文件时，$review-changes 负责 UI 维度 — 运行 $review-ui（优先在同一并行批次中使用 ui-ux-designer 子 Agent）：长内容溢出、响应式 flex 尺寸、z-index 规范、SCSS／BEM 质量；仅在没有前端文件变更时跳过 — 原因：$review-ui 从来不是单独的工作流步骤，因此跳过 UI 审查会导致 UI 缺陷未经审查就发布
• MANDATORY 对变更触及或应同步的任何 spec／feature-doc／PBI／story／test-spec，执行 M1-M6 Code-to-Spec 偏差门禁（§8，阻断性）— 若引入技术泄漏（M1）／将源代码用作叙述文本（M2）／逻辑 ID 映射损坏（M3）／AC 含糊（M4）／规范无法再仅凭产物重建（M5），则审查失败；失败时必须指出违规的 mandate ID 和变更文件的 file:line；载体（[Source:]、**Evidence**、frontmatter、mermaid）不受此限制 — 原因：放行新引入的 M1-M5 违规，会使审查本身有缺陷
• MANDATORY 架构边界检查 — 对每个变更文件，读取 docs/project-config.json 中的 architectureRules.layerBoundaries，匹配该文件所属层，并 grep 其导入项；若导入来自 cannotImportFrom 层，则按 Critical 阻断；若不存在 architectureRules，则静默跳过 — 原因：层边界违规可以在不报错的情况下编译并发布，逐渐侵蚀架构
• MANDATORY 在报告任何已完成工作前，必须通过 AI Agent 完整性门禁 — grep 每个已移除的名称（所有文件类型中不得有任何悬空引用），修改现有值前先问 WHY，验证所有受影响的输出（一个通过 ≠ 全部通过），复制附近代码前评估模式是否匹配（范围／生命周期／基类／约束相同），并证明每项新产物都已接入（已注册、已导入、可访问）— 原因：完成不等于正确，未经验证的“完成”只是未经检验的假设
• MANDATORY 大型变更集（≥10 个变更文件）→ 系统化分批审查 — 分类，并限制每批规模（≤8 个文件或 ≤2000 行差异）；每批启动一个并行子 Agent，然后汇总；超过 6 个类别或超过 40 个文件时，增加分层综合阶段，并执行跨关注点交互检查；任何被丢弃／抽样的范围都必须明确告知 — 绝不要逐个审查大量文件，也绝不能让有限覆盖看起来像完整审查 — 原因：大型差异会悄然耗尽单个 Agent 的上下文，导致部分文件未经审查

【底部提醒——WHY-REVIEW 发现验证关卡绝不可省略】

与顶部提醒规则相同，重复强调以便在长上下文中仍能记住：独立模式下的任何发现 → 在进行任何修复、文档更新、提交或交接之前，必须调用 $why-review 技能（技能调用，--validate-findings <report-path>）。内联／手动自我验证不能替代实际的技能调用。task tracking 在出现首个发现时立即记录 [Review Phase 6] 关卡，以免遗忘。在 $workflow-review-changes 内部，遵循父步骤 2。

反合理化：

规避说法	反驳
“对于图谱爆炸半径来说太简单”	Phase 0 图谱检查会确定风险顺序；运行该检查，或记录图谱不可用。
“没有发现问题，跳过文档／测试”	即使结论为无问题，也仍需证明已检查文档／测试，或明确说明它们不相关。
“发现的问题很明显，现在就修复”	先调用 $why-review 技能（--validate-findings）——必须是真正的技能调用，而不是内联自我验证；未经验证的发现不能作为修复依据。
“我自己已经重新检查过这些行了”	内联重新阅读无法通过 Phase 6。门禁要求实际调用 $why-review 技能并返回结论。
“只重新检查修复过的文件”	修复可能与先前的改动相互影响；从 Phase 0 开始，对完整差异重新运行 $review-changes。
“子 Agent 已经审查过了”	主报告必须整合原始发现，不得覆盖或筛除它们。
“已经查过项目惯例了”	提供至少 3 个 file:line 示例。没有证据就等于没有搜索。
“DRY／SOLID 要求进行这种抽象”	证明它能降低未来的修改成本；否则这只是形式主义，而非质量。
“审查没有发现 Bug，跳过简化”	找 Bug ≠ 做简化。仍需对已更改的代码文件运行 Phase 3.5 $code-simplifier。
“测试文件没有改动，跳过测试审查”	审查对象是改动，而非测试文件。Phase 3.7 Gate 7 会将每项行为改动对应到覆盖它的测试和规范 TC。
“存在同名测试文件”	名称对应 ≠ 覆盖。Phase 3.7 $integration-test-review 用于证明测试在断言层面覆盖了已更改的行为。
“审查结果干净，文档肯定没问题”	代码干净 ≠ 文档是最新的。交接前必须运行 Phase 8 $docs-update 全面检查——这是强制要求，并非视情况而定。
“行为改了，但规范和测试都通过了”	通过 ≠ 保持同步。运行 Spec Drift Adjudication 和 Dual-Feedback Ledger；对差异分类，并安排应完成的规范／测试修复。
“Bug 已修复，可以发布了”	如果缺少 §6.5 的 End→Start 追踪、馈入项枚举、假设矩阵和回归证明，Bug 修复审查就会失败。
“我足够有把握，不用引用依据”	置信度低于 80% 时先核实；没有 file:line 就是在猜测，而这是禁止的输出。说明你追踪了什么以及如何追踪。
“读起来没问题，看上去正确”	“看上去没问题”不是证据。称其正确之前，先追踪一条正常路径和一条错误路径，并引用对应行。
“只是前端调整，跳过 UI 审查”	$review-changes 负责 UI 维度——差异中只要有前端文件，就必须触发 $review-ui；这绝不是可以延后的独立步骤。
“附近代码就是这么写的，照着抄”	最近的示例 ≠ 前提条件匹配。复制之前，先证明新上下文具有相同的作用域、生命周期、基类和约束。
“规范正文提到了类名，没什么问题”	在规范叙述中引入技术／来源描述属于 M1/M2 FAIL（§8）。注明强制要求 ID 和已更改文件的行号；载体是唯一例外。
“导入能编译，分层就没问题”	能编译 ≠ 允许。检查 architectureRules.layerBoundaries；违反 cannotImportFrom 属于阻塞级 Critical，而非风格问题。
“文件很多，我全读一遍就行”	大型差异会导致单个上下文被静默截断。文件数 ≥10 时，采用有大小上限的并行批次并缩减范围；声明任何被省略／抽样检查的范围。
[TASK-PLANNING] 行动前先将范围拆分为较小的待办任务；保持一个任务处于 in_progress 状态；添加最终审查待办项。

---

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

重要，务必注意：当 .code-graph/graph.db 存在时，必须先运行图谱影响范围分析。 重要，务必注意：每项主张都必须有 file:line 证据；对过时文档/测试的每项决策都必须有依据。 重要，务必注意目标：确保每项经审查的变更没有缺陷、有证据支持、符合约定，并在交接前与所需的测试/文档保持同步；如果更改了代码文件，还必须证明代码仍易于修改。

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

来源：.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/ 中查明。应用共享 AI-SDD 中的 shared/sdd-artifact-contract.md。读取 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. 执行： 按照上下文指令中的工作流步骤推进与并行阶段规则推进——由模型驱动；子 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 错误预防（系统经验）

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