code-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 Specs
• 集成测试实现/审查：integration-test-reference.md
• E2E 测试实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及根据变更文件确定的领域文档

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

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

快速摘要

目标： 在验收或交接之前，确保已审查的代码正确、易于修改、符合规范且有验证依据——通过在反馈中提供验证（而非敷衍认同）、通过 code-reviewer 子 Agent 请求有针对性的系统审查，并在声称完成之前强制执行验证门槛。

路由边界： 如果用户要求审查当前更改、未提交的工作、已暂存／未暂存的差异，或分支之间的差异，请改用 changes-review。

共享引擎（保持同步）： code-review 和 changes-review 共用相同的 review-protocol SYNC: 块。规范来源：.claude/skills/shared/sync-inline-versions.md；策略：SYNC:shared-protocol-duplication-policy。在一项技能中更改共享块时，请同时更新规范文件和配套技能，确保二者始终保持一致。两项技能仅在入口意图上有所区别（明确范围／反馈／完成门槛 与 git diff）——审查质量并无差异。

强制要求： 审查前，搜索项目专属的参考文档：

编码规范 — 搜索：code-review-rules、coding-standards、style-guide、contributing 架构 — 搜索：patterns-reference、architecture、adr 测试约定 — 搜索：integration-test-reference、test-guide、test-conventions 设计系统 — 搜索：design-system、design-tokens、component-library

阅读找到的文档后再进行审查。若未找到任何文档，则依据文件扩展名／目录结构推断技术栈并运用相关知识。

工作流：

1. 创建审查报告 — 初始化 plans/reports/code-review-{date}-{slug}.md
2. 阶段 0：影响范围 — 如果存在 .code-graph/graph.db，先运行图分析
3. 阶段 0.1：更改上下文与全流程影响追踪（强制优先理解） — 记录更改上下文，然后全面追踪主要受影响区域的完整流程，涵盖两个边界——客户端↔服务端层（FE↔BE）以及服务／事件／外部边界——并将每个接缝／触点归类为 NONE／ADDITIVE／BREAKING（单层或单体架构须明确标记为 N/A）
4. 阶段 0.3：风险检测 — 检测依赖项、迁移、总线／事件、API、安全、配置和基础设施风险
5. 阶段 0.5：计划符合度 — 存在有效计划时，核对更改文件和测试是否符合计划
6. 阶段 0.7：表面分类 — 根据语言、目录语义和更改性质对文件分类，并路由至子 Agent；存在前端／UI 文件时调用 $ui-review
7. 阶段 1：逐文件审查 — 审查每个文件，并在报告中更新正确性、规范、DRY、意图、测试和文档检查结果
8. 阶段 2：整体审查 — 重新阅读累积的报告，评估整体方案、架构、重复代码和跨边界行为
9. 阶段 3：最终结果 — 在报告中更新整体评估、关键问题、建议、文档过时情况和测试缺口
10. 修复循环：验证 → 修复 → 完整复审 — 存在审查发现时，先验证这些发现，仅修复已验证的问题，然后在修复周期结束后重新开始完整审查

关键规则：

• 以报告为驱动： 逐步完善报告；重新阅读以把握全局
• 先检测： 有条件时先运行图分析评估影响范围，然后在审查前对更改类型和文件表面进行分类
• 代码应易于修改： 将未来的修改成本作为首要代码质量指标；只有在 DRY、SOLID、抽象和模式能减少修改放大效应时才采用它们
• 拒绝敷衍认同： 只进行技术评估（禁止说“你说得对！”）
• 验证门槛： 声称完成之前必须提供证据
• 在其他位置审查当前差异： 当前更改、已暂存／未暂存的差异和分支差异应使用 changes-review
• 审查通过即结束。 不要在新的上下文中先复审已知问题再进行验证／修复；只有修复改变了审查对象后才重新审查。

代码审查

三项实践：以严谨的技术态度接收反馈；通过 code-reviewer 子 Agent 请求系统性审查；在声称完成之前执行验证关卡。

对已更改的函数运行 python .claude/scripts/code_graph query tests_for <function> --json，以标记覆盖缺口。

审查心态（不可妥协）

保持怀疑。每项主张都需要可追溯的证据 file:line。置信度 >80% 才采取行动。

• 绝不想当然地接受代码正确性——追踪调用路径
• 绝不提出缺少 file:line 证据（grep 结果、阅读确认）的发现
• 始终追问：“这真的可行吗？”→ 追踪验证。“这就是全部吗？”→ 跨服务 grep
• 始终验证副作用：批准前检查调用方和依赖方

首要原则——易于更改

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

评估代码、重构、测试或抽象时，请问： 这会让下一次更改成本更低，还是更高？

• 拒绝会增加更改成本的“最佳实践”（过早抽象、 推测性通用化、泄漏式间接层、没有收益的繁琐流程）。
• 在发现中明确指出真正的问题：耦合、隐藏状态、重复 知识、意图不清、过早暴露且不可逆的决策。
• 优先采用项目自有的边界来封装外部库，例如 组件／服务的输入输出契约，前提是它能将未来的库变更 限定在局部；拒绝那些增加繁琐流程却未降低 更改成本的透传包装器。
• 易于更改的简单设计，胜过难以更改的复杂设计。

在应用下方任何具体规则、模式或检查清单之前，先采用这一视角——如果下游规则会增加更改成本，就以此原则为准。

---

核心原则（全部执行）

原则	规则
YAGNI	标记用于解决假设性问题的代码（未使用的参数、推测性接口）
KISS	标记不必要的复杂性。“有没有更简单的办法？”
DRY	grep 相似／重复代码。出现 3 种或更多相似模式 → 标记并提取
Clean Code	可读性 > 取巧。名称应体现意图。函数只做一件事。嵌套 <=3 层。方法 <30 行
Convention	标记违规前，必须 grep 至少 3 个现有示例。代码库惯例优先于教科书
No Bugs	追踪逻辑路径。验证边界情况（null、空值、边界）。检查错误处理
Proof Required	每项主张都必须有 file:line 证据支持。禁止推测
Doc Staleness	将更改文件与相关文档交叉核对。标记过时或缺失的更新

技术正确性高于社交舒适度。 实施前先验证，提出主张前先取得证据。

图增强审查（如果存在 graph.db，则推荐）

1. python .claude/scripts/code_graph graph-blast-radius --json — 按影响范围对文件排序（依赖项最多的优先）
2. python .claude/scripts/code_graph query tests_for <function_name> --json — 标记未经测试的已更改函数
3. python .claude/scripts/code_graph trace <file> --direction downstream --json — 下游影响（事件、总线、跨服务）
4. python .claude/scripts/code_graph trace <file> --direction both --json — 控制器/命令/处理程序的完整流程上下文
5. 影响范围较广（受影响节点超过 20 个）= 高风险。在报告中标记。

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

必须首先：创建待办任务

Task	Status
[Review] Create report file	in_progress
[Review Phase 0] Run graph blast-radius if available	pending
[Review Phase 0.1] Note change context + holistic full-pipeline trace across BOTH boundaries — client↔server tier (FE↔BE) AND service/event/external — classify each seam/touchpoint NONE/ADDITIVE/BREAKING (MANDATORY comprehension-first; N/A for single-tier/monolith)	pending
[Review Phase 0.3] Detect high-risk change types	pending
[Review Phase 0.5] Plan compliance check (skip if no active plan)	pending
[Review Phase 0.7] Detect categories + route sub-agents	pending
[Review Phase 0.7b] $ui-review sub-review — skip if no frontend/UI files in changeset	pending
[Review Phase 1] File-by-file review + update report	pending
[Review Phase 2] Holistic assessment	pending
[Review Phase 3] Final findings, docs triage, and test sync findings	pending
[Review Fix Loop] Validate findings, fix validated issues, and full re-review if fixes are applied	pending
[Review Final] Consolidate all rounds	pending

步骤 0：创建报告文件

创建 plans/reports/code-review-{date}-{slug}.md，并添加「范围」和「待审查文件」部分。

阶段 0：图谱爆炸半径分析（可用时优先执行）

如果 .code-graph/graph.db 存在，请在审查前运行图谱影响分析：

• python .claude/scripts/code_graph graph-blast-radius --json，或项目中的等效命令
• 在报告中记录受影响文件数量、未经测试的变更函数，以及风险等级
• 在阶段 1 优先审查影响较大的文件

如果图谱数据不可用，请记录“图谱不可用 — 跳过爆炸半径分析”，然后继续执行阶段 0.1。

阶段 0.1：理解变更上下文并追踪完整流水线影响（强制 — 优先理解）

重要，必须注意： 这是第一个_理解_步骤 — 必须先于任何逐文件或维度审查。爆炸半径分析（阶段 0）收集影响数据；此处需要全面理解变更，并追踪主要受影响区域跨越每个边界的完整流水线。应用跨栈影响追踪和跨服务检查协议（正文见下方的 SYNC 部分）。这份全面的首轮映射为后续阶段 0.3 的变更类型风险任务和阶段 2 的全面跨边界评估提供依据 — 但不能取代它们。

撰写一段变更上下文说明（变更内容 · 目的 · 起始层级 · 主要受影响的功能/流程），然后按照跨栈影响追踪和跨服务检查协议（下方的 SYNC 区块）执行两项追踪。

阶段 0.3：检测高风险变更类型

审查文件前，检查目标差异或明确指定的文件集，识别以下情况：

• Bug 修复、验证失败、过时/不正确的最终输出、回归问题或改变行为的修复 — 要求提供 Debugger Trace: End -> Start、所有输入路径、假设矩阵、负责修复的层，以及向前收敛的证明；缺少追踪证据属于高危/严重审查发现
• 依赖项升级 — 语义化版本、破坏性变更、安全公告、对等依赖兼容性
• 迁移或架构变更 — 回滚、锁/卷影响、零停机部署、幂等回填
• 总线事件/消息 — 消费者是否存在、幂等性、重试、毒消息/死信处理
• API 契约变更 — 向后兼容性、调用方一致性、身份验证、必需的响应字段
• 安全变更 — 强制执行覆盖范围、权限提升、负向测试、重复的权限字符串
• 配置/环境变量变更 — 覆盖所有环境、不包含机密、快速失败行为、设置文档
• 基础设施变更 — 开发/生产环境一致性、固定版本、CI/CD 权限、可复现构建

为每个确实存在的信号创建有针对性的审查任务，并在维度审查前完成。

阶段 0.5：计划符合性检查（有条件）

如果存在有效计划上下文，请在审查文件前根据计划核实范围、测试证据和成功标准；否则记录跳过原因。

目标契约映射（有条件 — 存在有效目标时）： 按照目标契约满足循环协议，解析有效的目标契约（有效计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md）。找到后，在报告中将审查的变更映射到已保存的成功标准 — 指明此变更集推进了哪些标准（提供 file:line 证据）、哪些标准未受影响，以及任何不符合已保存标准的变更（若无正当理由，则标记为范围偏离）。若不存在有效目标，请记录 No active goal — mapping skipped.；不得在审查过程中创建目标文件。

阶段 0.7：检测审查类别

开始审查前，对变更集分类并安排子 Agent：

变更文件中的特征	路由至
认证／权限／令牌／加密文件	security-auditor
查询文件、缓存、批处理	performance-optimizer
源代码（逻辑、处理程序、服务）	code-reviewer
前端／UI 文件（组件、模板、.html／.scss／.css、design-system）	$ui-review 技能（参见 Phase 0.7b）
文档、计划、规格说明、Markdown	general-purpose
同时包含安全／性能文件的混合变更集	先启动专用子 Agent，再启动 code-reviewer

Phase 0.7b：前端／UI 子审查（有条件 — $ui-review）

如果变更集中包含符合项目已配置 UI 模式的任意前端／UI 文件（组件、模板、.html／.scss／.css、design-system 令牌），则调用 $ui-review 技能进行子审查，确保覆盖 UI 特定问题——长内容溢出（换行还是省略号+工具提示）、响应式多屏 flex、使用 flex-grow 配合 min/max 而非固定 px、语义化 z-index 规范（不使用原始数字、不使用 !important），以及所有模板元素均使用 BEM 类。将其发现纳入本报告的 Phase 3 结果。

跳过（记录原因）：如果变更集中没有前端／UI 文件，则记录“已跳过 Phase 0.7b — 变更集中没有前端／UI 文件”。

Phase 0.8：推导审查类别

按以下维度对变更文件分组：文件语言（扩展名）、目录语义（路径）、变更性质（新实体、架构、配置、UI、测试）。

对每个类别：命名、创建子任务，并使用 SYNC:category-review-thinking 推导关注点（基于第一性原理，而非固定检查清单）。

类别列表 = Phase 1 工作拆分。每个类别对应报告中的独立章节。

Phase 1：逐文件审查（构建报告）

对每个文件，立即更新报告：

• 文件路径、变更摘要、用途、发现的问题
• **规范检查：**搜索 3 个以上相似模式——新代码是否遵循现有规范？
• **正确性检查：**追踪逻辑——是否处理了 null、空值、边界和错误情况？
• **DRY 检查：**搜索相似／重复代码——此逻辑是否已存在于其他位置？
• **意图检查：**变更是否服务于既定目的？标记无关修改
• **测试检查：**变更行为是否有相应的测试／规格说明覆盖，或记录了缺失项？
• **文档检查：**相关文档／规格说明／README 是否仍与变更后的行为一致？

Phase 2：整体审查（重新阅读报告）

审查完所有文件后，重新阅读已累积的报告：

• 技术方案：整体方案是否连贯统一？
• 职责划分：逻辑是否位于最底层？业务逻辑是否未放在控制器中？
• 数据所有权：常量／配置是否放在模型／实体中，而不是控制器／组件中？
• 重复代码：使用 Grep 验证——变更中是否有重复逻辑？
• 架构：是否遵循整洁架构？是否遵守服务边界？
• 计划遵循情况：若有活动计划 → 检查 ## Plan Context：实现是否符合要求，TC 是否有代码证据（而非“待定”），是否有未满足的要求
• 设计模式：是否有应用模式的机会（switch→Strategy）？是否存在反模式（上帝对象、复制粘贴、循环依赖）？是否通过基类实现 DRY？
• 跨边界行为：调用方／被调用方是否一致？API／事件契约是否一致？新增连接是否可达？
• 测试同步：业务逻辑变更是否有对应测试，或明确说明面向用户的缺口
• 翻译同步：多语言 UI 文本变更是否同步更新翻译，或明确接受风险
• Bug 修复追踪完整性：若 diff 是 Bug 修复或行为变更修复，审查报告必须说明最终状态追踪、馈入路径、假设矩阵、修复所属层、正向收敛证明，以及测试／证明映射是否完整

必须重点检查——Spec-Loop 测试纪律（核心逻辑变更）：除上述正常／错误路径追踪外，对变更的核心逻辑采用难以伪造的严格标准。采用 MUTATION-SCORE 门槛——存活的变异体意味着存在缺失的不变量，因此必须要求能杀死该变异体的测试；不得将行覆盖率百分比视为测试强度的证明。若任何 [HARD]／§5 不变量仅由示例测试覆盖，且没有普遍量化的属性 TC（以及边界反例），则将其标记为 HIGH 级发现。每项行为变更发现都必须有一行 Dual-Feedback（是否反馈到规范？是否反馈到测试？任一轴为空即为不完整）——在报告中记录。依据 SYNC:spec-drift-adjudication 判定任何规范偏差（CODE-WRONG / SPEC-STALE / AMBIGUOUS / SPEC-SILENT）；对于 SPEC-SILENT 发现——代码正确强制执行了规范制品中未提及的不变量——两个反馈轴都不得为 N/A：规范反馈 = 使用 $spec [update] + $spec [mode=tests] 添加缺失的 §4 BR／§3 AC（如适用，还需添加 §5 不变量）和 §8 TC；测试反馈 = 新增用于保护现已写入规范的不变量的属性／回归测试；绝不能让已发现的不变量只存在于代码或测试中。审查整个软件包（规范 + 测试 + 代码），而不只是 diff，以丰富规范，而非仅修补代码。

**必须重点检查——整洁代码：**YAGNI（未使用的参数、推测性接口）？KISS（是否存在更简单的方案）？方法是否超过 30 行或嵌套超过 3 层？

**必须重点检查——正确性：**是否处理空值／空集合／边界情况？是否捕获错误路径？是否存在异步竞态？追踪正常与错误路径。

文档过时检查：

对于每个变更文件，使用 grep 在 docs/ 和 AI 工具目录中搜索文件名／模块。行为变更 → 标记过时文档（具体章节 + 变更内容）。仅标记过时情况——切勿在此处自动修复文档。

常见过时模式：计数／限制变更 → 文档中嵌入了该数值 | API／契约变更 → API 使用文档 | 新增／移除 hook／skill → 目录／README | schema 变更 → 实体参考文档。

阶段 3：最终审查结果

更新报告：总体评估、严重问题、高优先级、架构建议、跨边界影响（来自阶段 0.1——分别针对每个客户端↔服务端边界和每个服务／事件／外部触点，标注 NONE / ADDITIVE / BREAKING 及相应的修复路径；或明确注明“单层／单体 — 不适用”）、文档过时情况、正面观察。

若发现文档过时，建议使用 docs-update 并列出准确的过时章节；不得默默放过过时文档。

已验证修复 + 完整重新审查（发现问题得到修复时为强制要求）

第 3 阶段后，不要仅为了重新审查同一组发现问题而启动新的审查者。请先验证发现问题，再仅修复已验证的问题。由于修复会改变审查目标，修复周期结束后必须重新开始完整审查。如果重新启动的审查流程使用子 Agent，请按照 SYNC:review-protocol-injection 中的规范模板构造每个 Agent 调用：

1. 原样复制 SYNC:review-protocol-injection 中的 Agent 调用格式
2. 嵌入全部 11 个 SYNC 块的完整原文：SYNC:spec-tests-code-triangulation、SYNC:evidence-based-reasoning、SYNC:bug-detection、SYNC:design-patterns-quality、SYNC:complexity-prevention、SYNC:logic-and-intention-review、SYNC:test-spec-verification、SYNC:fix-layer-accountability、SYNC:rationalization-prevention、SYNC:graph-assisted-investigation、SYNC:understand-code-first
3. 任务："Run a full fresh code-review pass over the current assigned scope after validated fixes were applied. Focus: cross-cutting concerns, interaction bugs, convention drift, missing pieces, subtle edge cases, logic errors, test spec gaps, and regressions introduced by the fixes."
4. 目标文件："use the explicit files, plan scope, or reviewer-provided target range"
5. 报告：plans/reports/code-review-rerun{N}-{date}.md

子 Agent 返回后：

1. 读取 plans/reports/code-review-rerun{N}-{date}.md 中的报告
2. 将发现问题整合为 ## Re-Review {N} Findings ——不得筛选或覆盖
3. **如果仍有发现问题：**在进行任何其他修复前，先验证这组新发现问题
4. **仅在另一个修复周期后重复：**应用已验证的修复后，再次重新开始完整审查；如果同一阻断问题在连续 2 次完整审查中反复出现且毫无进展，请直接向用户升级处理

清洁代码规则（必须检查）

#	规则	详情
1	禁止魔法值	所有字面值 → 命名常量
2	类型注解	所有函数都要显式标注参数和返回值类型
3	单一职责	每个方法/类只处理一个关注点。事件处理器/消费者：一个处理器 = 一个关注点。切勿捆绑——框架事件分发器可能会静默吞掉处理器异常
4	DRY	不要重复；提取共享逻辑
5	命名	使用明确的名称（orderRecords，而非 data）、动词+名词的方法名、is/has/can/should 布尔值；不要使用缩写
6	性能	不要使用 O(n²)（改用字典）。在查询中投影（不要加载全部数据）。始终分页。按 ID 批处理（避免 N+1）
7	实体索引	集合：索引管理方法。EF Core：复合索引。表达式字段顺序与索引顺序一致。文本搜索 → 文本索引

数据生命周期规则（必须认真审阅）

判断标准： “删除数据库并重新开始——这些数据还需要存在吗？” 需要 → Seeder/fixture。不需要 → Migration。

类型	包含内容	绝不包含
Seeder / Fixture	默认记录、系统配置、参考数据（幂等——每次启动时运行都安全）	Schema 变更
Migration	Schema 变更、添加或移除列、数据转换、索引变更	默认记录、权限种子数据、系统配置

遵循项目的语言/框架约定。原则具有普适性——具体实现因项目而异。

遵循旧模式

审查包含旧模式和现代模式的文件时：

1. 检测旧模式信号——搜索 project-config.json、package.json 或同类文件，查找 "legacy"、版本标记、功能注释
2. 了解“旧模式”的含义——grep 至少 3 个旧模式文件，了解其模式约束与现代文件的区别
3. 推导合规规则——对于此技术栈，旧模式/现代模式在生命周期/内存管理方面有哪些区别？
4. 运用技术栈知识，标记反模式

绝不要假设任何特定框架的生命周期。应从代码库证据中推导。

何时使用此技能

实践	触发条件	必须认真阅读
接收反馈	收到审查意见、反馈不清楚/有疑问、与现有决策冲突	references/code-review-reception.md
请求审查	每项子 Agent 任务完成后、主要功能完成后、针对特定范围的审查、复杂 Bug 修复后	references/requesting-code-review.md
验证关卡	在声称完成、提交、推送或创建 PR 之前。任何关于成功/满意的表述	references/verification-before-completion.md

快速决策树

SITUATION?
│
├─ Received feedback
│  ├─ Unclear items? → STOP, ask for clarification first
│  ├─ From human partner? → Understand, then implement
│  └─ From external reviewer? → Verify technically before implementing
│
├─ Completed work
│  ├─ Major feature/task? → Request code-reviewer subagent review
│  └─ Before merge? → Request code-reviewer subagent review
│
└─ About to claim status
   ├─ Have fresh verification? → State claim WITH evidence
   └─ No fresh verification? → RUN verification command first

接收反馈流程

模式： 阅读 → 理解 → 验证 → 评估 → 回复 → 实施

• 绝不要使用流于形式的赞同语（“你说得对！”、“好观点！”、“谢谢……”）
• 验证前绝不要实施
• 必须复述需求、提出问题，或给出技术理由进行反驳
• 开始前，必须就所有不明确的事项请求澄清
• 实施建议的“恰当”功能前，先 grep 确认其使用情况（YAGNI 检查）

来源处理： 人类协作者 → 理解后实施。外部审查者 → 进行技术验证，如有错误则提出异议。

完整流程： references/code-review-reception.md

请求审查流程

1. 获取 Git SHA：BASE_SHA=$(git rev-parse HEAD~1) 和 HEAD_SHA=$(git rev-parse HEAD)
2. 向 code-reviewer 子 Agent 分派任务，并提供：WHAT_WAS_IMPLEMENTED、PLAN_OR_REQUIREMENTS、BASE_SHA、HEAD_SHA、DESCRIPTION
3. 处理反馈：关键问题 → 立即修复。重要问题 → 继续前修复。次要问题 → 记录下来以便之后处理。

完整流程： references/requesting-code-review.md

验证门禁协议

铁律：没有最新的验证证据，绝不声称已完成

门禁： 确定命令 → 运行命令 → 阅读输出 → 验证输出是否支持该声明 → 然后再声明。跳过任何一步 = 撒谎。

声明	所需证据
测试通过	测试输出显示 0 个失败
构建成功	构建命令退出码为 0
Bug 已修复	原始症状测试通过
满足要求	逐行核对清单并验证

危险信号——立即停止：“应该”“大概”“似乎”等说法、验证前就满意、未经验证就提交、相信 Agent 的报告。

完整协议： references/verification-before-completion.md

相关内容

• code-simplifier
• debug-investigate
• refactoring

---

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

当阶段 1 发现 10 个以上变更文件时，请应用下文定义的系统化审查分批协议（Map-Reduce：限制批次大小 + 分层综合）。

---

工作流建议

必须遵循——无例外： 如果当前尚未处于工作流中，请直接询问用户：

1. 启用 workflow-review-changes 工作流（推荐）——完整审查 → 验证修复流程 → 持续重新审查，直到没有问题
2. 直接执行 $code-review——单独运行

---

架构边界检查

对于每个变更文件，验证其未导入禁止的层：

1. 从 docs/project-config.json → architectureRules.layerBoundaries 中读取规则
2. 确定层级——将文件路径与每条规则的 paths glob 模式匹配
3. 扫描导入——使用 grep 搜索所配置语言的 import/include 语句
4. 检查违规——导入路径包含禁止的层名称 → 违规
5. 排除框架——跳过匹配 architectureRules.excludePatterns 的文件
6. 存在违规时阻止——"BLOCKED: {layer} layer file {filePath} imports from {forbiddenLayer} ({importStatement})"

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

---

阶段 4：Why-Review 自我验证门禁（存在发现项时必须执行）

目的： 在交接前对自己的发现进行对抗性验证。在问题向下游传递之前，及时发现过度标记的高严重性问题、误报和严重性夸大。

触发条件： 产生任何发现项（严重、高、中或低）。仅当报告结论为无条件 PASS 且确实没有任何发现项时才跳过。

协议：

1. 从 plans/reports/{skill}-{date}-{slug}.md 读取自己最终定稿的报告
2. 使用参数调用 $why-review 技能：validate findings in plans/reports/{skill}-{date}-{slug}.md — verify each finding has file:line proof, steel-man each rejected interpretation, and stress-test severity classifications
3. 读取 why-review 返回的验证结论路径，预期为 plans/reports/why-review-validate-{date}.md
4. 如果 why-review 降低或移除任何发现项： 更新自己最终定稿的报告，修订严重性、移除误报，并添加 ## Why-Review 验证说明 一节，说明变更内容及原因
5. 如果 why-review 确认所有发现项： 在自己的报告中追加 ## Why-Review 验证 一行，写明“所有 N 个发现项均已根据实际代码重新验证；严重性未作调整。”

跳过条件（跳过时须记录明确原因）：

• 结论为无条件 PASS 且没有任何发现项 → 记录“已跳过——没有需要验证的发现项”
• why-review 技能本身是当前上下文（避免递归）

设立此规则的原因： AI 子 Agent 的报告会受到确认偏误影响——协调器会将严重性声明当作既定事实。2026-05-09 的审查事件产生了 5 个高严重性问题；对抗性验证将其中 3 个降级。将此规则纳入标准实践。

---

后续步骤

强制要求——无一例外：完成后，直接询问用户：

• "$fix（推荐）"——审查发现需要修复的问题
• "$watzup"——审查无问题，结束会话
• "跳过，继续手动处理"——由用户决定

AI Agent 完整性关卡（不可妥协）

完成 ≠ 正确。 在报告任何已完成的工作之前：

1. 对每个已移除的名称执行 grep。 提取、重命名或删除后，执行 grep，确认所有文件类型中都没有残留引用。
2. 修改之前先问为什么。 现有值应视为有意设置，除非有证据证明并非如此。
3. 验证所有输出。 一个构建通过，不代表所有构建都通过。
4. 评估模式是否适用。 复制附近代码时，验证前置条件是否匹配——作用域、生命周期、基类和约束。
5. 新建产物 = 已接入的产物。 创建了内容？证明它已注册、已导入，且所有使用方都能访问。

---

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

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

**外部记忆：**复杂工作 → 将发现逐步写入 plans/reports/——防止上下文丢失，并作为交付物。

**证据关卡：**强制要求——每项声明、发现和建议都必须提供 file:line 证据及置信度百分比（>80% 时采取行动，<80% 时先验证）。

**OOP 与 DRY：**强制要求——标记可提取到基类／泛型／辅助项中的模式。后缀、生命周期或职责相同的类应共享公共基类。根据项目使用的语言，采用符合惯例的抽象方式（基类、mixin、trait、protocol）。验证是否已配置 lint 或分析器。 跨技术栈影响追踪 — 首要审查操作：先全面理解变更，再判断文件。每次审查差异时：记录变更背景，端到端追踪主要受影响区域的完整流程，跨越客户端↔服务端边界，确保一端的变更绝不会悄无声息地破坏另一端。（这不同于负责服务间／事件边界的 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 · 已审查契约 · 已标记不兼容变更风险 系统化评审分批处理（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. 正向验证汇合 — 选定修复方案后，再次从起点向终点追踪，说明修正后的状态如何到达观察到的最终输出。将每个根因对应到修复部分，并将每个修复部分对应到测试／证明。

满足以下条件前必须阻止继续： 已明确最终状态 · 已写出反向追踪 · 已枚举所有供给路径 · 已完成假设矩阵 · 已论证负责修复的层 · 已将正向汇合证明对应到测试。

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

借助图进行调查 — 存在 .code-graph/graph.db 时必须执行。

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

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

任务	最低图操作
调查／侦察	在 2-3 个入口文件上运行 trace --direction both
修复／调试	对 Bug 函数运行 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 查看细节。 类别审查思路 — 用于审查任意类别变更文件的思考框架。它不是固定检查清单——应根据领域知识推导关注点；示例仅供参考。你对该类别的了解胜过此处的任何清单——请相信自己的判断。

步骤 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 运行时间的影响？ 子 Agent 返回契约 — 此技能启动子 Agent 时，子 Agent MUST 仅返回以下结构。主 Agent 只读取此摘要 — NEVER 在行内请求子 Agent 的完整输出。

## 子 Agent 结果：[skill-name]

状态：✅ PASS | ⚠️ PARTIAL | ❌ FAIL
置信度：[0-100]%

### 发现（仅限严重/高优先级 — 最多 10 条）

- [严重程度] [文件:行号] [发现]

### 已采取的行动

- [已更改的文件] [更改内容]

### 阻碍（如有）

- [阻碍说明]

完整报告：plans/reports/[skill-name]-[date]-[slug].md

主 Agent 仅在以下情况读取 Full report 文件：(a) 解决具体阻碍，或 (b) 制定修复计划。 子 Agent 按 SYNC:incremental-persistence 的要求逐步写入完整报告 — 不将其留在内存中。

上下文预算 — 返回内容是摘要，不是对话记录：最多 10 条发现，不在行内粘贴原始文件内容、完整差异或逐字日志，也不重新粘贴源内容。摘要以外的所有内容都保存在磁盘上的 Full report 中。若子 Agent 返回内容将超出摘要格式，MUST 将详细信息写入报告，并仅返回报告路径 — 整个 map-reduce 机制所保护的稀缺资源是编排器的上下文。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

基于证据的推理 — 禁止猜测。每项声明都必须有证据。

1. 为每项声明引用 file:line、grep 结果或框架文档
2. 声明置信度：>80% 可直接采取行动，60-80% 先验证，<60% 不得给出建议
3. 架构变更必须进行跨服务验证
4. “证据不足”是合理且符合预期的输出

以下条件满足前不得继续： - [ ] 证据文件路径（file:line）- [ ] 已执行 grep 搜索 - [ ] 找到 3 个或更多类似模式 - [ ] 已说明置信度

未经证实不得使用： “显然”“我认为”“应该是”“很可能”“这是因为” 若信息不完整 → 输出："证据不足。已验证：[...]。未验证：[...]。" 设计模式质量 — 每次代码更改都要进行的优先检查：

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，持续执行，直到某一轮完整审查通过，达到该轮的退出标准（见下文的 严重性下限）。审查通过即结束循环——无需再进行后续轮次。

又称 自我审查收敛循环。 这个名称沿用至今——没有 2 轮上限；“双轮往返”仅表示已验证问题的修复周期至少会触发一次全新审查。循环会持续到审查通过，但最多不超过下文所述的 3 轮上限。

轮次上限——最多 3 轮（上限，绝非目标）。 无论在哪一轮，只要审查通过，循环就立即结束——包括第 1 轮；上限绝不意味着必须继续进行审查。如果到第 3 轮时仍有阻塞问题未解决（按严重性下限判定）→ 停止并直接询问用户，以升级处理，并列出仍未解决的问题；达到上限时，绝不能默默给出“够好”的通过结论，也绝不能用上限替代审查通过要求。连续 2 次无进展的阻塞规则仍是更早的退出条件——哪个条件先触发，就按哪个条件升级处理。

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

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

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

严重级别下限规则：

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

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

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

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

第 1 轮后的决策：

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

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

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

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

规则：

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

报告必须为每个已执行的第 N 轮（N≥2）包含 ## Round N Findings (Fresh Sub-Agent)；如果循环在第 3 轮及之后依据退出标准结束且仍有未解决的 LOW，还必须包含 ## Deferred LOW Findings (severity floor, round ≥3)。 全新上下文重新审查 — 修复后，通过在适用时启动独立的子 Agent，消除协调者的确认偏误，重新开始完整审查。

原因： 主 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
• 不得改写、总结或跳过任何协议部分
• 不得以内联方式传递文件内容——子 Agent 会通过自己的工具调用读取文件，因此拥有新鲜的上下文
• 不得通过文件路径或标签名称引用协议——正文已嵌入在上方
• 不得为协议引入占位符标记——协议必须保持展开后的原文

防止合理化 — AI 会通过以下借口跳过步骤。请识别并拒绝：

借口	反驳
“计划太简单了”	简单的任务加上错误的假设 = 浪费时间。无论如何都要先制定计划。
“之后再测试”	先 RED，再 GREEN。先编写 / 验证测试。
“已经搜索过了”	提供包含 file:line 的 grep 证据。没有证据 = 没有搜索。
“直接做吧”	仍然需要任务跟踪。可以省略深度分析，绝不能省略跟踪。
“只是一个小修复”	在错误位置进行的小修复会引发连锁问题。先核实 file:line。
“代码不言自明”	后续读者需要证据链。仍然要记录。
“合并步骤以节省时间”	合并步骤会分散注意力。每个步骤都有独特的目的。

逻辑与意图审查 — 核实代码的实际行为与修改原因相符。

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

未完成这两种路径（成功路径 + 错误路径）的追踪，绝不应将审查标记为 PASS。

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

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

分类： 严重（崩溃 / 数据损坏）→ FAIL | 高（行为错误）→ FAIL | 中（边缘情况）→ WARN | 低（防御性问题）→ INFO 测试规范验证 — 将变更的代码映射到测试规范。

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

绝不能跳过测试映射。 未经测试的代码路径是生产环境 Bug 的头号来源。

修复层级责任制 — 绝不能在崩溃点修复。追踪完整流程，并在负责的层级修复。

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

进行任何修复之前，必须：

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

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

反模式（拒绝）：

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

源码/测试漂移检查。 对于编码、修复、调试、调查、测试或审查工作：当源码行为发生变化时，应检查受影响的单元/集成/E2E 测试，并根据证据判断是应调整测试以符合预期行为，还是源码变更属于意外 Bug、需要修复。不要为迁移代码编写测试；架构/数据迁移是一次性执行路径，不属于核心应用逻辑。 AI 错误预防 — 每项任务都应避免的失败模式：

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

严重级别评定标准 — 根据后果对每项发现分类，而不是根据修复难度。在所有评审中使用同一套标准，确保“高”在各处含义一致。

严重级别	处理方式	定义
CRITICAL	阻止合并	运行时静默失败、数据损坏、绕过验证、安全漏洞
HIGH	必须修复	行为错误、不变量缺口、架构违规
MEDIUM	应当修复	设计负担、可维护性问题、可能导致未来缺陷
LOW	有空可修	惯例、文档、轻微的清晰度问题

基于评分的技能应将数值量表映射到这些级别——不要另造一套术语：

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

发现的级别决定了准入条件：通过前必须解决 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，也绝不能将其埋没在低严重性备注中。

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

• MUST ATTENTION（强制） 每项结论都必须引用 file:line 证据。置信度 >80% 才采取行动；<60% = 不要提出建议。

• MUST ATTENTION（强制） 通过 OOP 检查 DRY（后缀相同 → 基类）、职责是否放在正确位置（最低层）以及 SOLID。更改后搜索悬空引用。

• MUST ATTENTION（强制） 防止复杂度累积——一次业务变更 = 一次代码变更。标记变更放大（未来变更需要修改 >3 处）、分散的类型判断、贫血模型、基本类型偏执、抽象泄漏技术细节、浅层模块、未提取的实用逻辑（分页／日期时间／字符串／重试 → 辅助函数），以及放错在较高层的逻辑（下移至被调用方／实体／VM）。不要用纯粹的 YAGNI 为悄无声息的重复代码找借口。

• MUST ATTENTION（强制且重要） 执行审查循环（又称 自审收敛循环）：审查 → 验证发现 → 修复已验证的发现 → 完整复审。一次完整审查通过且零发现时，结束审查。任何新生成的输出／判断都至少要经过 1 次自审；任何新判断在被视为最终结果前，都至少要经过 1 次 $why-review --validate-findings 验证。

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

• MUST（强制） 遵守最多 3 轮的上限——这是上限，绝非目标：任何一轮（包括第 1 轮）审查通过，都应立即结束循环；第 3 轮结束时仍有未解决的 CRITICAL／HIGH／MEDIUM 级问题 → 停止并升级处理，直接询问用户，绝不能默默判定通过。如果连续 2 次没有进展的阻止规则先触发，则在触发时立即升级处理。绝不能无休止地循环。

• MUST ATTENTION（强制） 无论任务看起来多简单，都要完成所有步骤。“太简单，不值得规划”是逃避，不是理由。

• MUST ATTENTION（强制） 如果存在 graph.db，至少对关键文件运行一条图谱命令。模式：grep → 图谱追踪 → grep 验证。

• MUST ATTENTION（强制） 确认每个更改的文件都服务于既定目的。追踪正常流程和错误流程。标记范围蔓延。

• MUST ATTENTION（强制） 每次审查都要检查空值安全、边界条件、错误处理和资源管理。

• MUST ATTENTION（强制） 将每个更改的函数／端点对应到一项测试。在更改文件附近查找项目的测试规范格式。标记覆盖缺口，并建议创建测试。

• MUST ATTENTION（强制） 对于多语言前端／UI 文本更改，在判定通过前，确认已更新译文（或用户明确接受相关风险）。

MUST ATTENTION（强制） 首项审查操作——记录更改上下文，并从整体上追踪主要受影响区域的完整流程，贯穿客户端↔服务端边界（BE→FE 正向，FE→BE 反向）。确认两端在路由／DTO／字段／类型／可空性／认证方面仍保持一致；任何不一致都属于 BREAKING 级问题。仅对单层或仅文档更改可跳过（需说明）。

IMPORTANT MUST ATTENTION（重要且强制） 微服务／事件驱动：扫描任务范围内的生产者、消费者、saga 和契约。对每个触点记录：所有者 · 消息 · 消费者 · 风险（NONE／ADDITIVE／BREAKING）。缺少消费者会导致无声回归。

IMPORTANT MUST ATTENTION（重要且强制） 追踪完整数据流，并在责任所属层修复，而不是在崩溃点修复。添加 ?. 前审查所有访问位置。 务必注意：应用批判性与循序思考——每项声明都需要适当的可追溯证据（关于代码库/代码的声明须提供 file:line；关于研究、产品、内容和文档的声明须提供源 URL 或资料章节）；置信度 >80% 才能采取行动，<60% 时不得提出建议。防止幻觉：绝不把猜测说成事实，坦然承认不确定性，独立交叉核对，并对自己的信心保持怀疑。

务必注意：应用循序思考——使用多步骤 Thought N/M、REVISION/BRANCH/HYPOTHESIS 标记，并尽可能给出置信度百分比；参见 $sequential-thinking 技能。

务必注意：应用 AI 错误预防措施——根据证据核实生成的内容；删除或重命名前追踪下游引用；核实所有受影响的输出；上下文丢失后重新阅读文件；采取行动前明确指出歧义。

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

• 强制要求：从第一原则出发，基于 file:line 证据推导每个类别的关注点——绝不使用固定清单。

• 强制要求：开始目标工作前先建立任务跟踪；每次只转换一个任务的状态。

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

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

• 强制要求：始终包含 lessons.md；项目配置和约定优先于通用框架默认值。

• 强制要求：如果项目配置、根目录指令文件或任何必需参考文档缺失或过时，须自动运行 $project-init，或采用更窄范围的下级流程，然后再开展常规项目专属工作。

重要，务必注意：调试器追踪门槛：对于非琐碎的 Bug、修复、调查或审查工作，从观察到的最终输出开始，反向追踪 reader → storage/projection → writer → consumer/job → producer/trigger。列出所有馈入路径和假设后才能修复。在以下各项完成前不得继续：追踪、假设矩阵、负责修复的层级，以及正向收敛证明。

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

• 强制要求：编排器须在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵守同一时间只有一个任务处于 in_progress 状态的规则。

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

• 强制要求：执行后追加迭代证据；报告 PASS 前输出 Goal Satisfaction 矩阵（PASS/FAIL/BLOCKED）；针对已验证的 FAIL 循环处理；反复没有进展或遇到阻碍时升级处理。绝不得在目标文件中存储机密信息。

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

• 强制要求：> 6 个类别或 > 40 个文件 → 增加分层综合层；每个关注点综合器须提出跨关注点交互候选项，并由编排器在结束前执行跨关注点检查。

• 强制要求：按后果将发现分为 Critical/High/Medium/Low；除非已修复或经负责人接受，否则 Critical/High 会阻止 PASS。

• 强制要求：基于评分的技能（SRE 0-2、性能双轴）映射到相同的四个级别——不得采用另一套严重程度术语。

提示词增强收尾锚点

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

• 务必始终提出 3 个权衡问题——针对正在审查的事项以及你提出的每项建议：(1) 是否存在任何权衡？ 说明牺牲了什么（变更成本 · 复杂性 · 性能 · 耦合 · 可逆性 · 迁移 · 运维负担 · 影响范围 · 安全性 · 可测试性 · 交付时间 · 用户体验）——“没有”／“纯收益”都意味着分析尚未完成，因此要说明检查了哪些维度；(2) 是否值得？ 比较收益（含指标）与成本，说明由谁承担、何时承担 → 给出 值得／不值得／不明确 的结论；不值得 → 撤回或替换建议；(3) 影响是否重大到需要向用户确认？ 不可逆／单向门 · 成本转嫁给其他团队／运维人员／维护者／用户 · 以一种质量属性换取另一种 · 跨越层级／服务／事件／库的边界 · 身份验证／资金／数据完整性／破坏性变更／高风险或中风险路径 · 结论为“不明确” → 停止，并在给出结论前直接向用户确认。
• 强制要求：未经用户确认的重大权衡绝不能判为通过；绝不能将其埋在低严重性备注中，绝不能擅自决定，也绝不能让交付或收敛压力替单向门决策。——原因：未经充分讨论、无法撤回的单向门，应由用户而非审查者决定。
• 强制要求——在无法提问的情境中，必须通过交接升级，绝不能默不作声。 直接向用户提问只能由主交互 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 绝不进一步扇出。

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

叠加规则只能添加内容：它们只能在此技能自身协议的基础上添加规则，绝不能替换、覆盖、禁用或重新解释其中已有规则——移除所有叠加规则后，此技能应恢复为与文档所述完全一致的行为。叠加规则是简要补充，不是权限升级：绝不能豁免工作流门槛、Git 规范、审查门槛或用户确认门槛。若叠加规则与技能本身确实冲突，或两个具体程度相同的叠加规则直接矛盾 -> 将两者都告知用户；绝不能悄然自行裁决。

务必注意：执行前，必须先解析此技能的项目协议叠加规则——只采用最具体的匹配级别（精确名称 > glob > *；此优先级仅用于排列叠加规则之间的顺序，绝不能用于对抗此技能本身），且只读取 <protocols-dir>/<Name>.md 中匹配项的正文；正文缺失或格式错误时需报告，绝不能重建。叠加规则只能添加内容（绝不能替换此技能自身的规则），且只是简要补充，绝不是权限升级；具体程度相同的规则若相互矛盾，须交由用户处理。

收尾提醒

**重要目标：**在验收或交接之前，确保代码已审查、正确、易于修改、符合规范，并有验证结果作为依据。

务必注意：生效中的协议（此技能包含的 SYNC/共享内容块的简明摘要——每行都指向上文对应的规范正文；以正文为准）：绝不能仅依据摘要采取行动；当引用的规范内容块触发时，必须始终阅读该内容块。

• 系统化分批处理： 大型变更集 → 拆分为有大小上限的并行批次，再缩减。

• 从结果端反向追踪调试： 修复前，从观察到的最终状态反向追踪。

• 借助图谱开展调查： 首先对关键文件运行图谱命令。

• 按类别审查： 从基本原理推导各类别的关注点。

• 子 Agent 返回约定： 子 Agent 仅返回摘要，报告保存在磁盘上。

• 创建嵌套任务： 在工作流行下展开子阶段。

• 项目参考文档指南： 开始目标工作前，先阅读项目文档。

• 外部任务跟踪报告： 初始化任务；逐步持久化调查结果。

• 批判性思维： 每项主张都要有可追溯的证据；绝不猜测。

• 顺序思考协议： 使用多步 Thought N/M，并在结尾给出置信度。

• 基于证据的推理： 引用 file:line；置信度 >80% 时才采取行动。

• 设计模式质量： 通过 OOP 实现 DRY，置于最低层，并遵循 SOLID。

• 预防复杂化： 一项业务变更 = 一项代码变更。

• 双轮审查： 审查 → 验证 → 修复 → 重新审查，直至无问题。

• 使用新上下文审查： 修复后，通过拥有全新记忆的子 Agent 重新审查。

• 审查协议注入： 原样嵌入全部 11 项协议正文。

• 防止自我合理化： 拒绝跳过步骤的托辞；提供证据。

• 逻辑与意图审查： 确保变更的代码符合所述目的。

• Bug 检测： 每次审查都检查 null、边界、错误和资源问题。

• 测试规范验证： 将每条变更路径对应到一个测试。

• 修复层级问责： 在负责的层级修复，而不是在崩溃点修复。

• 源代码与测试漂移检查： 源代码变更 → 对受影响的测试进行调整。

• 防止 AI 出错： 根据证据验证生成内容，追踪下游引用，验证所有受影响的输出，在上下文丢失后重新阅读，并明确指出歧义。

• 严重性评估标准： 按后果分类；Critical/High 会阻止 PASS。

• 强制要求 嵌套任务展开约定 — 在工作流中调用时，仍须通过任务跟踪展开内部阶段，前缀格式为 [N.M] $skill-name — phase，并使用 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 建立关联。工作流行是容器，不可替代子任务。

• 强制要求 开始前使用任务跟踪将工作拆分为小型待办任务

• 强制要求 直接询问用户以验证决策 — 绝不自动决定

• 强制要求 添加最终审查任务以验证工作质量

• 强制注意 审查前搜索项目专属参考文档（编码规范、架构、测试约定）

• 强制注意 阶段 0：首先检测变更类型 — 将 auth/perf 文件交由专门的子 Agent 处理，再进行常规审查

• 强制注意 完成本次审查后运行 $why-review，以验证设计理由、已考虑的替代方案和风险评估

• 并行子 Agent 调度： 为任务标记 PAR/SEQ，将 PAR 任务分组为写入集合互不相交的批次，每个批次在一条消息中启动，进入下一批次前设置屏障。

[TASK-PLANNING] 开始行动前，分析任务范围，并使用任务跟踪系统地将任务拆分为小型待办任务和子任务。

---

结束提醒 — 易于变更是成功指标。 每项发现、 测试、重构和抽象都必须回答一个问题：这会让 下一次变更的成本更低，还是更高？ 如果不能降低未来的 变更成本，就应拒绝它。耦合、隐藏状态、重复知识和 意图不清才是真正的敌人——要明确点名指出。 防止自我合理化： | 规避说法 | 反驳 | | -------------------------------- | ----------------------------------------------------------------------------- | | “目的很明显” | 仍然要锚定目标——首因/近因效应能让结果在长提示词中持续保持活跃。 | | “现有提醒已经足够” | 在结束提醒中重申目标——底部锚定可防止偏离。 | | “修改提示词时可以跳过证据” | 引用已更改文件的证据，并确认没有遗留过时的协议文本。 |

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