发布前打磨

仓库当前状态：

git rev-parse --abbrev-ref HEAD
git status --short
git diff --stat 2>/dev/null | tail -1

基础 ref 参数（可选）：$ARGUMENTS

规则

• 审阅前必须完整阅读每一个被修改的文件——绝不能评估你尚未打开的代码
• 仅标记真实问题，不标记已被格式化工具（formatter）覆盖的风格偏好项
• 切勿向原本没有注释、文档字符串或类型注解的代码中添加 comments、docstrings 或 type annotations
• 区分合法的运行时日志（logger.info、logger.error）与遗留调试语句（console.log、console.debug）
• 修复时仅做最小、精准的编辑——不得重构周边已有代码
• 仅在变更/新增行中识别问题，不审查既存代码
• 复用建议必须指向代码库中**已存在的具体函数/工具**，而非假设性的“你可以提取这段逻辑”
• 不对冷路径（cold paths）、一次性初始化代码或仅运行一次的脚本进行性能效率审查

阶段 1：自动化检查

运行项目的 lint + 类型检查命令。查阅 CLAUDE.md 获取正确的验证命令（常见如 pnpm check、just check、cargo clippy、uv run ruff check 等）。

若检查失败：

1. 修复所有报错
2. 重新运行检查直至通过
3. 然后进入阶段 2

若 CLAUDE.md 中未找到验证命令，请向用户询问应执行的命令。

阶段 2：差异分析

确定哪些内容发生了变更：

1. 检查是否存在未提交的变更：git diff + git diff --cached
2. 检查 git status --short 中的未跟踪文件（标记为 ??）。将新加入的未跟踪源文件纳入审阅范围。若某次暂存变更引用了未跟踪文件（例如新建模块、基准测试目标或测试用例），该引用本身即为一项发现：若该变更合入而对应文件缺失，将导致全新克隆和 CI 因引用丢失而失败
3. 若传入了 base ref 参数，则基于该 ref 进行比对：git diff ...HEAD
4. 若无未提交变更且未指定 base ref，则默认与 main 分支比对：git diff main...HEAD。若当前待审阅工作已在本会话中提交，应将审阅范围限定为本次会话内的提交，而非整条分支
5. 若完全无变更，报告“无可审阅内容”并终止流程

从审阅中排除锁文件与生成文件（Cargo.lock、pnpm-lock.yaml、package-lock.json、*.snap、自动生成的 bindings 等）——它们属于构建产物，而非人工编写的源码。

逐行通读所有变更文件，理解每处修改的作用及其原因。

当某次变更涉及既有代码路径的迁移或重写（如文件移动、处理器拆分为中间件、函数重命名/替换），需打开其原始版本——即移动前的文件，或对已删除/重命名文件使用 git show : —— 并对比行为（而非仅比对行文本）。注意是否遗漏了输入校验、副作用顺序是否改变、防护逻辑（guards）是否被移除；将上述问题传递给各 agent。

阶段 3：并行审阅

将 diff 写入临时草稿文件。使用 Agent 工具，在单条消息中并发启动全部四个 agent。向每个 agent 传入该 diff 文件路径及变更文件列表，确保其拥有完整上下文——切勿将大型 diff 内联至四个 prompt 中。

为每个 agent 的 prompt 补充以下信息：

• 来自 CLAUDE.md 的相关项目约束（性能假设、日志规范、平台特性等），以确保发现的问题符合领域实际
• diff 中已知为有意为之的模式（例如测试跳过路径中按项目惯例保留的 console.log），避免 agent 返回已知误报

小 diff 快速路径：若 diff 极小（大致少于 50 行变更），跳过 agent 并行分发，由你本人直接完成下述四项视角的审阅，且须逐行通读全部变更。后续所有阶段仍需执行。

Agent 1：整洁性（Cleanliness）

快速、机械、高置信度。聚焦应被移除的冗余内容。

• 调试残留：开发期间添加的 console.log、console.debug、console.warn；临时调试变量；硬编码的测试值。不包括结构化日志调用（logger.info、logger.error、c.var.logger）
• AI 垃圾信息：解释显而易见代码的注释（如 "// increment counter"、"// return the result"）——即使该行代码已在其他类别中标记，也需单独标记每处此类注释；非公开 API 的内部/私有函数上的 JSDoc；简单辅助函数上冗长的 docstring；Claude 留下的（非用户所留）TODO/FIXME/HACK 标记；语言能正确推断类型时不必要的类型注解；代码或注释中的 emoji（除非项目明确使用）
• 非 ASCII 标点符号：变更行中引入的破折号（em-dash）、智能引号等 Unicode 标点（除非项目允许使用）。纯文本 grep 可能遗漏多字节字符——需以字节感知方式扫描变更文件，例如：rg -n '[x{2010}-x{2015}x{2018}-x{201F}]'
• 死代码：未被引用的函数、变量、类型；被注释掉的代码块（git 已保留历史）；未被使用的函数参数（接口/回调签名必需者除外）
• 未使用导入：新增但从未被引用的 import；重构后遗留的 import（linter 能捕获大部分——请验证边界情况）
• 硬编码值：应置于常量中的魔法数字或字符串；应位于配置中的 URL、价格、限制等。不包括明显常量，如 0、1、true、HTTP 状态码

Agent 2：设计与复用（Design & Reuse）

需超出 diff 范围探索整个代码库。聚焦结构性与设计层面问题。

• 复用机会：在整个代码库中搜索已有的工具函数、辅助函数与共享模块，判断是否可替代新编写的逻辑。重点关注 utility 目录、共享模块，以及与变更文件相邻的文件。对已有工具可覆盖的场景（字符串处理、路径操作、类型守卫、环境检测等）却手写逻辑的情况进行标记
• 过度工程：仅被调用一次的辅助函数（应内联）；仅封装单次调用且无额外价值的抽象；未增加实质价值的 try/catch（如原样重新抛出错误、捕获不可能发生的异常）；已在路由入口完成校验的内部数据重复校验；为本可直接编码的功能添加特性开关或配置；为刚编写的新代码添加向后兼容 shim
• 冗余状态：与现有状态重复的状态；可通过计算派生的缓存值；本可改为直接调用的 observer/effect
• 参数泛滥：向函数新增参数，而非对现有参数进行泛化或重构
• 带微小差异的复制粘贴：高度相似、应统一的代码块
• 泄漏的抽象：暴露本应封装的内部细节，或破坏既有抽象边界
• 字符串化编码（Stringly-typed code）：代码库中已存在常量、枚举或 branded types 的场景下，仍使用原始字符串
• 结构性问题：因本次变更导致函数过长（>50 行，考虑拆分）；命名与代码库既有规范不一致
• 迁移代码的行为偏移：当 diff 移动或重写了既有逻辑路径时，请对照其替换的原始代码（参见阶段 2）进行比对。标记被移除的输入校验、被删减的防护逻辑或早期返回、以及错误语义的变化（状态码、返回结构等）。即使每行代码都看似干净，任何改变了 行为 的重构本质上都是回归缺陷。

Agent 3：效率（Efficiency）

聚焦运行时性能与资源问题。

• 冗余工作：冗余计算、重复文件读取、重复网络/API 调用、N+1 模式
• 错失并发机会：本可并行执行的独立操作被串行执行
• 热路径膨胀：向启动过程或每个请求/每次渲染的热路径中新增阻塞型工作
• 无变更更新（No-op updates）：在无变更检测机制的轮询循环、定时器或无条件触发的事件处理器中更新状态/store；亦包括接收 updater/reducer 回调但未遵循相同引用返回语义的包装函数
• TOCTOU 反模式：在操作前预先检查文件/资源是否存在——应直接操作并捕获相应错误
• 内存问题：无界数据结构、缺少清理逻辑、事件监听器泄漏
• 过于宽泛的操作：仅需部分数据却读取整个文件；仅需过滤一个条目却加载全部数据
• 未校验的系统边界：fetch/HTTP 调用未检查响应状态（r.ok）；对外部调用的 Promise 拒绝未作处理；I/O 边界处缺少错误处理

Agent 4：副作用闸控（Side-Effect Gating）

封闭范围的正确性检查。用于发现那些在预期闸控检查之前就已执行的高成本或不可逆副作用。它 **不评判业务逻辑是否正确**——那是 /review 的职责。

• 清点副作用：列出 diff 中引入或迁移的所有高成本或不可逆副作用——支付/扣款、数据库写入/删除、对外部服务的可变调用、文件写入、通知/邮件发送、不可逆状态变更
• 清点闸控条件：针对每个副作用，列出其前置必需检查项——输入校验（结构/类型/范围）、认证、授权、前提条件/存在性检查、幂等性/去重校验
• 交叉验证执行顺序：标记任意一条控制流路径上，闸控检查位于副作用之后、或根本未执行的情况。追踪需跨越中间件/处理器边界——在调用 next() 之前触发副作用的中间件是首要嫌疑对象；本应闸控它的校验逻辑通常位于下游处理器中
• 缺少回滚机制：标记已提交的副作用，但同一请求后续步骤仍可能失败（例如：已扣款，但请求最终报错）
• 超出范围 —— 转交至 /review：业务逻辑是否正确、定价计算、算法正确性、任何缺乏明确不变量（invariant）的问题

每一项发现均须注明副作用所在行、其所对应的闸控条件（或标注为“无闸控”），以及完整的控制流路径。缺少两个行号引用的发现无效。

阶段 4：发现项验证

在呈现任何结果前，须依据实际代码逐一验证所有 agent 提出的发现项。无法通过验证的发现项应直接丢弃。

对每一项发现：

• 精确定位所引文件与行号 —— 确认代码确实存在且与描述一致。若行号错误或代码内容不符，直接丢弃该发现
• 死代码 / 未使用导入 —— 在整个代码库中全局 grep 引用。若该符号在任何位置（import、调用、类型使用）被引用，丢弃该发现
• 复用建议 —— 确认所建议的工具函数/模块确实在声称路径下存在。若不存在，丢弃该发现
• 调试残留 —— 确认被标记行确实是调试产物，而非结构化日志（logger.*、c.var.logger.*）
• 效率 / 设计类主张 —— 阅读上下文代码，确认所述模式真实存在。剔除在完整上下文中不成立的推测性发现
• 副作用闸控 / 行为偏移类主张 —— 通过阅读实际控制流确认：副作用所在行、闸控条件所在行、二者之间的路径（含下游处理器与中间件执行顺序）。对迁移/重写导致的回归，须与 被替换的原始代码 对比验证，而非与可能同样存在问题的兄弟路径对比。绝不以“这是行为决策”或“超出范围”为由忽略——若其成立，则属最高严重等级的发现
• 重写或迁移路径 —— 当发现落在重写/迁移后的代码上时，需核查该缺陷是否已在 HEAD（或迁移前版本）中存在。若已存在，予以保留但标注为“既有缺陷延续”，而非新增回归。同时单独标记随旧路径一并删除、且未被新路径覆盖的测试用例

仅通过验证的发现项方可进入最终报告。

阶段 5：报告

将已验证的发现项整合为一份去重后的单一报告。若多个 agent 标记了同一处代码，合并为一项发现。按类别分组：

## 审阅发现

### 正确性（N 项问题）
1. `path/to/file.ts:55` - chargeUser() 在请求体校验前执行（处理器在校验逻辑 :78 处执行，且在 next() 之后）；畸形请求将被扣款，随后返回 400 错误
2. ...

### 整洁性（N 项问题）
1. `path/to/file.ts:42` - console.log("debug response")
2. ...

### 设计（N 项问题）
1. `path/to/file.ts:15-18` - 手动拼接路径，应复用 shared/utils 中已有的 `resolveAssetPath`
2. ...

### 效率（N 项问题）
1. `path/to/file.ts:30-45` - 独立 API 调用被顺序 await，应改用 Promise.all
2. ...

### 观察项（非阻塞性）
1. `path/to/file.ts:88` - flock 回退机制捕获了所有锁错误，而不仅限于文件系统不支持的情况——此为行为说明，非缺陷；由你决定是否调整

### 验证后丢弃项
1. `path/to/view.py:12` - 每次 mousemove 都调用 getBoundingClientRect —— 元素为 CSS fixed 定位，因此 rect 已缓存，不会触发布局刷新

**总计：X 个问题，分布于 Y 个类别**

**建议：** 修复正确性 #1、整洁性 #1-2、效率 #1；跳过设计 #2（边际收益低）。

**等待批准后，再执行修复。**

始终将 正确性 类别列于首位（包括 (0 issues) 的情况），因为该数字为零本身即是重要信号——表明已对副作用执行顺序进行了检查。正确性为零时，必须明确说明已追踪的具体副作用及其覆盖的闸控条件，而不仅给出数量统计。该类别绝不可与样式类问题一同批量批准。

观察项 是经验证的行为说明，不属于缺陷——由用户自行判断，永不阻塞流程。验证后丢弃项 列出阶段 4 中被否决的 agent 发现及其原因，用以佐证报告中的统计数字。任一子节为空时可省略。

报告结尾需附上逐项 建议：明确指出你计划修复哪些项、跳过哪些项，以便用户可按编号快速批准。

若未发现任何问题，报告“洁净 —— 未发现任何问题”，并说明正确性为零的具体验证过程（追踪了哪些副作用、为何判定为洁净），同时提供下一步建议——例如：直接提交、或交由用户自行审阅——然后终止流程。

报告末尾必须包含如下语句：“等待批准后，再执行修复。”（或前述“洁净”情形下的对应表述）。在用户明确批准前，不得进入阶段 6。

阶段 6：修复与验证

获得用户批准后：

1. 以最小、精准的编辑修复所有报告的问题
2. 重新运行项目的验证命令
3. 若出现新错误，继续修复
4. 输出摘要：已修复内容、最终检查状态
5. 若被审阅的工作已提交，请询问修复应作为 amend 还是新提交——默认采用新提交