review-post-task

Codex 兼容性说明：

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

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

Codex 不会接收基于 Claude Hooks 注入的文档。 进行编码、规划、调试、测试或审查时，请按照以下路由显式打开项目文档。

始终阅读：

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

根据情况阅读：

• 后端／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
• 规格／测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实现／审查：integration-test-reference.md
• E2E 测试实现／审查：e2e-test-reference.md
• 代码审查／审计工作：code-review-rules.md，并根据变更文件阅读相关领域文档

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

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

快速摘要

目标： 任务完成后进行两轮代码审查，在提交前发现问题。

工作流：

1. 第一轮：逐文件审查 — 分别审查每个变更文件
2. 第二轮：整体审查 — 评估总体方案、架构和一致性
3. 报告 — 总结关键问题和建议

关键规则：

• 确保质量：不得存在缺陷、错误、遗漏的更新或过时内容
• 检查代码和文档是否完整
• 基于证据提出发现，并注明 file:line 引用

完成代码变更后，执行强制性的两轮审查协议。 重点：$ARGUMENTS

激活 code-review 技能，并遵循其工作流和任务完成后的两轮审查协议：

审查思维（不可妥协）

保持怀疑。运用批判性思维和顺序思维。每项声明都必须有可追溯的证据和置信度百分比（想法的置信度应高于 80%）。

• 不要想当然地认为代码正确——应阅读实际实现并加以验证
• 每项发现都必须附带 file:line 证据（grep 结果、阅读确认）
• 只报告能通过代码追踪证明的声明——没有证据支持的声明一律舍弃
• 质疑假设：“这真的能用吗？”→ 追踪调用路径予以确认
• 挑战完整性：“这就是全部吗？”→ 在各服务中 grep 相关用法
• 验证副作用：“这还会造成什么问题？”→ 检查调用方和依赖项
• 没有证据就不要说“看起来没问题”——说明你验证了什么，以及如何验证

第一原则——易于修改

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

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

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

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

---

核心原则（全部执行）

YAGNI——标记解决假设性未来问题的代码（未使用的参数、推测性接口、过早抽象） KISS——标记不必要的复杂方案。要问：“有没有更简单的办法？” DRY——在整个代码库中 grep 相似或重复代码。如果存在 3 个或更多相似模式，应标记并提议抽取。 Clean Code——可读性胜过巧妙。名称应体现意图。函数各司其职。避免深层嵌套（≤3 层）。方法少于 30 行。 遵循惯例——标记任何模式违规之前，先 grep 查找 3 个或更多现有示例。代码库惯例优先。 无缺陷、无 Bug——追踪逻辑路径。验证边界情况（null、空值、边界）。检查错误处理。 必须提供证据——每项声明都必须有 file:line 证据或 grep 结果支持。禁止推测。 文档过时——将变更的文件与相关文档（功能文档、测试规范、README）交叉核对。标记所有过时的文档，或未更新以反映当前代码变更的文档。

可读性检查清单（必须重点评估）

批准之前，确认代码易读、易维护、易理解：

• 结构可见性——如果函数计算出一种数据结构（对象、映射、配置），注释应展示其输出形态，以免读者必须追踪代码才能了解
• 不明显的数据流——如果数据经过多个步骤转换（A → B → C），应使用简短注释说明处理流程
• 自解释的签名——函数参数应说明其用途；标记未使用的参数
• 魔法值——未作解释的数字或字符串应定义为命名常量，或附带行内说明
• 命名清晰度——变量和函数的名称应能体现意图，无需阅读实现

协议

第 1 轮： 收集变更（git diff），应用项目审查清单：

• 后端：平台仓库、验证、事件、DTO
• 后端：在数据播种器中添加种子数据（而非迁移）——如果数据库重置后数据必须存在，就应使用播种器
• 前端：基类、存储、untilDestroyed、BEM
• 架构：分层位置、服务边界
• 约定： 使用 grep 搜索 3 个或更多类似模式，以确认代码遵循代码库约定
• 正确性： 跟踪逻辑路径，检查边界情况（null、空值、边界值）
• DRY： 使用 grep 搜索代码库中的重复或相似代码
• YAGNI/KISS： 标记过度设计、不必要的抽象和推测性功能
• 文档过时： 将变更文件与 docs/business-features/、测试规范、README 交叉核对，并标记过时文档

[IMPORTANT] 数据库性能协议（强制执行）：

1. 必须分页 —— 所有列表/集合查询都必须使用分页。绝不能将所有记录加载到内存中。验证：不存在未分页的 GetAll()、ToList() 或 Find()；必须使用 Skip/Take 或基于游标的分页。
2. 必须建立索引 —— 所有查询筛选字段、外键和排序列都必须配置数据库索引。验证：实体表达式中的字段顺序与索引字段顺序一致，数据库集合具有索引管理方法，迁移中为 WHERE/JOIN/ORDER BY 列包含索引。

修复发现的问题。

第 2 轮（强制执行——使用全新的子 Agent 进行第 2 轮审查）：

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

使用 SYNC:review-protocol-injection 上文中的规范 Agent 模板，启动一个全新的 code-reviewer 子 Agent 进行第 2 轮审查。该子 Agent 对第 1 轮发现的问题或修复内容毫无记忆。构造 Agent 调用提示词时：

1. 逐字复制 SYNC:review-protocol-injection 模板中的 Agent 调用格式
2. 嵌入以下 9 个 SYNC 区块的完整原文（均已在本技能文件上文中内嵌）：SYNC:evidence-based-reasoning、SYNC:bug-detection、SYNC:design-patterns-quality、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. 将任务设为 "Review ALL uncommitted changes holistically. Focus on cross-cutting concerns, interaction bugs, convention drift, missing pieces, subtle edge cases (null/empty/boundary/off-by-one), over-engineering, naming inconsistencies, logic errors, test spec gaps."
4. 将目标文件设为 "run git diff to see all uncommitted changes"
5. 将报告路径设为 plans/reports/review-post-task-round{N}-{date}.md

子 Agent 返回后：

1. 阅读子 Agent 的报告
2. 在主报告中以 ## Round {N} Findings (Fresh Sub-Agent) 的形式整合发现——不要筛选或覆盖
3. 如果失败： 修复问题，然后启动一个新的第 N+1 轮全新子 Agent（发起新的 Agent 调用——绝不能重复使用第 2 轮的 Agent）
4. 最多进行 3 轮全新审查——如果 3 轮后仍未通过，直接向用户提问并升级处理
5. 最终结论必须纳入所有轮次的发现

最终报告： 任务描述、第 1/2 轮结果、变更摘要、已修复问题、遗留问题。

集成说明

• 由工作流编排在 $cook、$fix、$code 后自动触发
• 可使用 $review-post-task 手动调用
• PR 审查请使用 $code-review
• 复杂审查请使用 code-reviewer 子 Agent

---

系统化审查协议（适用于变更文件数 ≥ 10）

变更集较大（10 个或更多文件）时，按关注点对文件分类，为每个类别并行启动 code-reviewer 子 Agent，然后将发现汇总为一份整体报告。 完整的 4 步协议（分类 → 并行子 Agent → 汇总 → 整体评估）请参阅 review-changes/SKILL.md § “Systematic Review Protocol”。

---

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

完成 ≠ 正确。 在报告任何工作已完成之前，先提供证据：

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

[IMPORTANT] 使用任务跟踪，在开始前将所有工作拆分成小任务——包括为每个要读取的文件创建任务。这可以避免因长文件而丢失上下文。对于简单任务，AI 必须 ATTENTION 询问用户是否要跳过。

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

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

强制要求：重要，必须 ATTENTION 制定 ToDo 任务，阅读以下项目专属参考文档：

• docs/project-reference/code-review-rules.md — 反模式、审查清单、质量标准 （优先阅读）（相关时直接阅读；不要依赖钩子注入的对话文本）
• docs/project-reference/integration-test-reference.md — 集成测试模式、夹具设置、Seeder 约定、经验教训（审查或编写集成测试前必须阅读）
• project-structure-reference.md — 服务列表、目录树、约定

如果未找到这些文件，请搜索：项目文档、编码标准、架构文档。

OOP 和 DRY 执行要求：强制要求，重要，必须 ATTENTION——标记应提取到基类、泛型或辅助工具中的重复模式。同一组或具有相同后缀（例如 *Entity、*Dto、*Service 等）的类必须 ATTENTION 继承同一个基类（即使目前基类为空，也能为未来的共享逻辑和子类重写做好准备）。确认项目已为对应技术栈配置代码 lint 或分析工具。

嵌套任务扩展约定——对于工作流步骤调用，[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-docs-reference.md；架构/新领域需要 project-structure-reference.md。
3. 阅读所有存在的必需文档；不存在的文档视为不适用并跳过。不要相信对话中的 [Injected: <path>] 等文本能证明当前上下文包含该文档。
4. 开始目标工作前，说明：Reference docs read: ... | Missing/not applicable: ...。

解除阻塞的条件： 已评估范围、已检查/阅读所需文档、已确认 lessons.md、已给出引用。

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

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

解除阻塞的条件： 已创建任务拆分；计划/审查工作已声明报告路径；在发现下一个问题之前，已持久化首个发现。

批判性思维 — 运用批判性思维和顺序思维。每项主张都需要可追溯的证据，置信度 >80% 才能采取行动。 防止幻觉： 切勿将猜测当作事实陈述——为每项主张引用来源，坦诚承认不确定性，自行检查输出是否有误，独立交叉核对，始终对自己的判断保持怀疑——缺乏证据的确定性是所有幻觉的根源。

基于证据的推理 — 禁止推测。每项主张都需要证据。

1. 为每项主张引用 file:line、grep 结果或框架文档。
2. 声明置信度：>80% 可直接行动；60-80% 先核实；<60% 不要给出建议。
3. 架构变更必须进行跨服务验证。
4. “我没有足够的证据”是有效且符合预期的回答。

解除阻塞的条件： 提供证据文件路径（file:line）；已执行 Grep 搜索；找到 3 个或更多相似模式；已说明置信度。

无证据时禁止使用： “显而易见”“我认为”“应该是”“可能是”“这是因为”。

如果未完成 → 输出： “证据不足。已核实：[…]. 未核实：[…].” 先理解代码 — 硬性门槛：在阅读现有代码之前，禁止编写、规划或修复。

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： 找出用途、命名模式或生命周期相同的类／模块。运用对项目语言／框架的了解，判断符合惯例的抽象方式（基类、混入、特征、协议、装饰器）。存在 3 个以上类似模式时，提取为共享抽象。
2. 职责适当： 将逻辑放在最低层（实体 > 领域服务 > 应用服务 > 控制器）。绝不在控制器中放置业务逻辑。
3. SOLID： 单一职责（只有一个变更原因）。开闭原则（扩展而非修改）。里氏替换（子类型可相互替换）。接口隔离（小型接口）。依赖倒置（依赖抽象）。
4. 提取／移动／重命名后： 在整个范围内搜索悬空引用。零容忍。
5. YAGNI 门槛： 如果某种模式未出现 3 次以上，绝不建议使用。不要为了假设的未来用途进行提取。

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

通过串行审查确保设计质量 — 一次扫描一个质量维度（分轮审查），而不是同时考虑所有问题。——原因：注意力分散会漏掉单独专注审查时能发现的违规问题。

1. 确定适用的维度 — 根据代码的语言、领域和模式，判断适用的质量维度：DRY、SOLID 原则（SRP／OCP／LSP／ISP／DIP）、OOP 惯用法、内聚与耦合、GRASP、迪米特法则、CQRS 不变量等。列表并非固定——应根据代码的实际功能推导。
2. 每个维度单独进行专注审查 — 依次专注审查每个维度。不同轮次之间不要混合考虑问题。
3. 阈值：3 个以上类似模式 = 必须提取 — 不是可选建议。应将其标记为必须采取行动的结构性修复。
4. 同类违规达到 2 个以上 = 结构性问题 — 应报告为需要通过架构解决的“模式问题”，而不是逐项列出实例。 由修复触发的重新审查循环 — 重新审查由修复周期触发，而非由轮次编号触发。审查流程：review → if issues → fix → re-review，直至某一轮未发现问题。审查通过后循环即结束——无需进行后续轮次。

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

第 1 轮后的决策：

• 未发现问题（PASS，发现数为零） → 审查结束。不要启动新的子 Agent 进行确认。
• 发现问题（FAIL，或发现数不为零） → 修复问题，然后启动新的子 Agent 进行第 2 轮重新审查。

由新的子 Agent 重新审查（每次修复周期之后）： 启动一次新的 spawn_agent 工具调用——绝不重复使用之前的 Agent。子 Agent 从头重新阅读所有文件，不保留此前各轮的任何记忆。启动机制请参见 SYNC:fresh-context-review，标准 Agent 提示词模板请参见 SYNC:review-protocol-injection。每一轮新的审查都必须发现：

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

循环终止： 每轮新的审查结束后，重复相同决策：无问题 → 结束；有问题 → 修复 → 进入下一轮新的审查。持续执行，直到某一轮发现数为零，或达到最多 3 轮新的子 Agent 审查，然后通过直接向用户提问来升级处理。

规则：

• 第 1 轮审查通过即结束——无需强制进行第 2 轮
• 修复周期后绝不跳过新的子 Agent 重新审查（每次修复都会使之前的结论失效）
• 各轮之间绝不重复使用子 Agent——每次迭代都要启动一次新的 Agent 调用
• 主 Agent 必须阅读子 Agent 报告，但不得筛选、重新解读或否定其中的发现
• 每次审查最多进行 3 轮新的子 Agent 审查——如果仍为 FAIL，则通过直接向用户提问来升级处理（不得默默继续循环）
• 在对话上下文中跟踪轮次计数（仅限当前会话）
• 最终结论必须纳入所有已执行轮次的结果

报告必须包含每个已执行的第 N 轮（N≥2）的 ## Round N Findings (Fresh Sub-Agent)。 全新子 Agent 复审 — 通过隔离的子 Agent，消除编排器的确认偏误。

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

时机： 仅在修复周期之后进行。如果某轮审查未发现问题，则循环结束——不要启动确认性子 Agent。如果某轮审查发现问题，则触发：修复 → 全新子 Agent 复审。

方法：

1. 启动一次全新的 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——每次修复都会使此前的结论失效
• 绝不在不同轮次重复使用同一个子 Agent——每一轮全新审查都要启动一次全新的 spawn_agent 调用
• 每次审查最多进行 3 轮全新子 Agent 审查——如果仍未通过，则通过直接提问用户来升级处理；不要静默循环，也不要回退到任何先前的协议
• 在对话上下文中跟踪迭代次数（仅限会话，不使用持久化文件）

审查协议注入 — 每个全新的子 Agent 审查提示词都必须逐字包含 10 个协议块。下方模板已将全部 10 个协议正文展开内嵌。运行时，将整个模板原样复制到 Agent 调用的 prompt 字段中，仅替换 Task／Round／Reference Docs／Target Files／Output 部分中的 {placeholders}，填入与具体上下文相关的值。不要改动内嵌的协议部分。

为何要内联展开： 占位符标记会导致运行时通过文件读取进行间接引用。经由间接引用会显著降低 AI 的遵循度（见 SYNC:shared-protocol-duplication-policy）。因此，模板预先内嵌了全部 10 个协议正文。

子 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)

### 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: JS: === vs ==, typeof null. C#: async void, missing using, LINQ deferred execution.
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)
- 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.
`
})

规则

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

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

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

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

未完成两种追踪（成功路径和错误路径）之前，绝不可将审查标记为通过。

Bug 检测 — 每次审查都必须检查第 1-4 类。绝不可跳过。

1. 空值安全： 参数或返回值是否可能为空？是否有防护？是否存在可选链漏洞？是否检查了 .find() 的返回值？
2. 边界条件： 是否存在差一错误（< 与 <=）？是否处理空集合？零值或负值？最大限制？
3. 错误处理： try-catch 范围是否正确？是否静默吞掉异常？错误类型是否具体？是否在 finally 中清理？
4. 资源管理： 是否关闭连接或流？销毁时是否取消订阅？是否清除计时器？内存是否有界？
5. 并发（如为异步）： 是否缺少 await？共享状态是否存在竞态条件？闭包是否过时？是否出现重试风暴？
6. 特定语言栈： JS：=== 与 ==，typeof null。C#：async void、缺少 using、LINQ 延迟执行。

分类： CRITICAL（崩溃/损坏）→ FAIL | HIGH（行为不正确）→ FAIL | MEDIUM（边界情况）→ WARN | LOW（防御性问题）→ INFO

测试规格验证 — 将已更改代码映射到测试规格。

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

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

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

删除前检查下游引用。 删除组件会导致文档和代码连锁过时。移除前，先梳理所有引用该组件的文件。 根据实际代码验证 AI 生成的内容。 AI 会捏造 API、类名和方法签名。记录或引用前，务必使用 grep 确认它们确实存在。 编辑后追踪完整依赖链。 修改定义时，容易遗漏由此衍生的下游变量和使用方。务必追踪完整依赖链。 验证正确性时追踪所有代码路径。 确认代码存在，不等于确认代码会执行。务必追踪提前退出、错误分支和条件跳过，不要只检查正常路径。 调试时，先问“谁负责？”再修复。 追踪问题究竟出在调用方（数据错误）还是被调用方（处理错误）。在负责的层级修复，绝不要只修补症状出现的位置。 假定现有值是有意设置的——修改前先问“为什么”。 修改任何常量、限制、标志或模式前：阅读注释、查看 git blame，并检查周围代码。 验证所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改必须验证每一项输出。一个检查通过不代表全部检查都通过。 整体优先调试——警惕注意力就近偏差。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐项根据证据进行验证，然后再提出任何代码层面的假设。 精准修改——应用差异测试。 修复 Bug 时，每一行更改都必须能直接对应到该 Bug。不要顺手重新调整样式或改进相邻代码。增强任务：实现改进，并明确说明。 编码前明确歧义——不要默默自行选择。 如果请求有多种解释，逐一列出并估算工作量，然后询问。绝不要擅自假定需要处理所有记录、采用基于文件的方案或使用更复杂的路径。

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

重要，务必注意：通过 OOP 检查 DRY 原则、职责层是否正确以及 SOLID 原则。移动代码后使用 grep 搜索悬空引用。

重要，务必注意：执行审查循环：审查 → 如发现问题 → 修复 → 由新的子 Agent 重新审查。某轮审查若未发现问题，则结束审查。

重要，务必注意：对已更改的文件运行图影响分析。计算差集：受影响项减去已更改项 = 可能过时的项。

重要，务必注意：验证代码的实际行为是否符合此次更改的原因。追踪正常路径和错误路径。

重要，务必注意：每次审查都检查空值安全、边界条件、错误处理和资源管理。

重要，务必注意：将已更改的代码路径映射到 TC-{FEATURE}-{NNN}。标记未测试的路径。

务必注意：运用批判性思维——每项主张都需要可追溯的证据，行动前置信度须高于 80%。防幻觉：绝不要把猜测说成事实。

务必注意：落实防止 AI 犯错的要求——整体优先调试、在负责的层级修复、编码前明确歧义，并在上下文压缩后重新阅读文件。

• 必须在开展目标工作前初始化任务跟踪；一次只推进一个任务。

• 必须逐步将计划和审查结果写入 plans/reports/，并根据磁盘上的内容综合整理。

• 必须在任务跟踪初始化完成后、开始处理目标或源文件之前，阅读必需的项目参考文档，并注明 Reference docs read: ...。

• 必须始终包含 lessons.md；项目约定优先于通用默认做法。

• 必须注意，父工作流行不能替代子阶段跟踪；嵌套时应展开各阶段并关联父项。

• 必须注意，编排器应在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵循同一时间只有一个任务处于 in_progress 的原则。

Prompt-Enhance 收尾锚点

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

收尾提醒

重要：务必注意开始前，使用任务跟踪将工作拆分为小型待办任务 重要：务必注意创建新代码前，在代码库中搜索 3 个或更多类似模式 重要：务必注意为每项主张提供 file:line 证据（置信度 >80% 才采取行动） 重要：务必注意添加最终审核待办任务，以验证工作质量 重要：务必注意执行审核循环：审核 → 如有问题 → 修复 → 由新的子 Agent 重新审核。如果某一轮未发现问题，则审核结束。 强制：重要，务必注意开始前阅读以下文件：

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

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

---

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

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

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制、重要、必须、关键。无论出于何种原因，都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应与项目无关；从 docs/project-config.json 和 docs/project-reference/ 中查找项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，采用以下结构；除非用户明确调用了某个工作流／技能，且本地协议将明确调用视为确认：
   • 问题："你想启用哪个工作流？"
   • 选项 1："启用 [最佳匹配工作流]（推荐）"
   • 选项 2："启用自定义工作流：[步骤 1 → 步骤 2 → ...]"（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤按顺序手动执行
5. 创建任务： 跟踪工作流的所有步骤
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项声明都必须有可追溯的证据；置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实；每项声明都要引用来源；坦率承认不确定性；自行检查输出是否有误；独立交叉核对；对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 AI 注意力原则（首因－近因效应）： 对于较长的提示词／协议，将最关键的 3 条规则同时放在开头和结尾，以确保指令在较长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，循环执行直至验证通过，并且只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图被破坏时失败，而不能只照搬当前行为。

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

开始前将工作拆分为小任务并进行跟踪。添加最终任务："分析 AI 错误与经验教训"。

提取经验教训——仅限根本原因，不处理表面症状：

1. 指明失败模式（推理／假设失误），而非症状——例如“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，就再抽象一层。
3. 将其写成通用规则——去除项目特定的名称／路径／类。该规则应适用于任何代码库。
4. 合并：多个错误若有相同的失败模式 → 总结为一条经验教训。
5. 重复发生检查：“如果没有这条提醒，未来会话中还会发生这种情况吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review／$code-simplifier／$security／$lint 能否发现此问题？”——能 → 改进相应的审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。