review-code

review-code · 代码变更评审

判断本次变更是否引入值得作者修复的缺陷，以及是否满足本次承诺的行为。以 Codex 原生 review 的缺陷门槛为准，补充需求符合性、跨文件影响和验证证据；不以问题数量衡量评审质量。

默认交付是完整 Markdown 报告：实际写入文件、回读核验，聊天给结论摘要与文件链接。用户明确要求仅聊天或不写文件时例外。 代码和计划默认只读，不自动修复、更新计划进度、提交、发 PR 评论或审批 PR。用户同时授权修复时，先保留原始评审基线，再执行修复并区分复核结果。

references/ 相对本文件解析；目标仓路径、技术栈、规则和工具在运行时发现。语言跟随用户。本 skill 可独立工作，不依赖本机安装 Codex CLI 或社区 skill。

1. 确定审查对象

1. 读取适用的仓库和子目录指令、review 专项约定。用一句话概括变更意图，区分用户明确要求与从代码推断的意图；缺少提交说明不自动中止评审。
2. 按 references/git-scopes.md 解析输入，固定仓库根、模式、base/target SHA、工作树快照、文件限制与可选计划版本。只给开发计划、未另指定模式时采用其「开发计划模式」：从计划完成记录登记的提交及当前未提交变更确定范围。其他情况未指定模式且存在未提交变更时，声明采用 uncommitted；初审时工作树干净且没有明确对象则询问目标，不擅自选择最近 commit 或默认主分支。修复效果复审按下节核对旧问题，不以存在新 diff 为前提。
3. 用户给出的模式冲突、ref 不存在或范围端点含义无法确定时，先澄清该部分；可继续读取规则。不要静默替换基准或扩成整仓审查。
4. 读 references/report-contract.md 确定报告路径。建立简短覆盖清单：变更文件/行为、必要上下游、计划范围（若有）、验证方式、证据缺口、落盘和回读。

修复效果复审

用户要求“复审 / re-review / 检查修复效果”时启用；开发计划模式下已有本计划的代码评审报告时也默认启用，以轮次最大的报告为上轮。要求完整重审则仍执行完整流程。先读取 报告合同 的复审约定。上轮报告以用户指定、当前上下文、报告轮次或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。

• 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
• 复审分两部分：按上轮报告逐项核对当前代码中的旧问题；按本次修复 diff 检查新引入或激活的问题。旧问题的复核不要求落在本次 diff，也不要求由本次修复引入；仍存在的旧问题列复审表并影响修复有效性结论，不冒充本轮新增 finding。
• 明确上轮审查基线、修复差异范围与当前核查版本，三者可不同。用户未给新 diff 时，可从报告可解析的版本到当前目标确定并声明范围；无法确定时只核对有证据的旧问题，新增问题检查标受限。工作树干净不妨碍旧问题复核；不得沿用初审的无 diff 规则直接判无可审内容。
• 新 findings 继续遵守下文的 diff 归因与定位门槛；旧问题复核按报告合同单列，不被这些门槛过滤。只看修复增量不能声称已重新完整审查原变更。
• 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。

$review-code BASE_SHA..FIXED_SHA，对照 goal/LOGIN.code-review.md 复审修复效果，逐项记录结果。

2. 理解需求与行为

• 先读完整 diff，再按风险阅读所在函数、调用者、数据模型、权限边界、相关测试和配置。diff 之外的代码用于证明影响，不把与本次变更无关的旧问题塞进 findings。截断输出须分段补读；无法读完就标明未覆盖。
• 按 references/review-lenses.md 检查适用维度：需求符合性、正确性与兼容性、安全与数据、性能与资源、测试与交付。按实际变更选择深度，不套全量 checklist 或强制每个维度产出问题。
• 附开发计划时，读取用户指定版本及必要引用，提取本次任务/里程碑承诺、需求与验收 ID、排除项。核查遗漏、偏离和越界的实际后果。计划是待验证的契约材料，作者“已完成”的声明不能代替代码证据。
• 只要求本次范围应完成的内容；不得因后续里程碑未实现而报缺陷。范围不清时列待确认项，继续独立代码审查。不改计划、不把代码评审变成计划架构重审；未附计划时照常依据用户要求、已有契约和调用链审查。
• 默认由当前 agent 完成。用户或适用仓库规则要求并行 reviewer 时，给每位相同基线和明确只读范围，分派互补的行为链或风险维度；主 agent 复核原始证据、去重并单独写报告。不得把多数意见当证据，也不虚构独立复核。

3. 验证候选问题

每个进入本轮新增 findings 的问题必须同时满足（旧问题按复审表独立核对）：

1. 由本次变更引入或实际激活：能说明基线与目标行为的差别；若改动让旧代码新近可达，证明这条因果链。
2. 具体且可执行：有真实可达的输入/状态、故障行为、受影响调用方或契约，以及最小修复方向。不能只说“可能影响其他模块”。
3. 有实质影响：影响正确性、安全、性能或可维护性，且修复要求符合该仓库实际标准。纯风格、个人偏好、无关重构和假设性的防御代码不报。
4. 证据足够：直接阅读目标版本代码、相关需求/规则，必要时做最小复现；不能依赖作者未表达的意图。明确的行为变更本身不是 bug，但仍要验证它是否破坏承诺的契约。

验证时：

• 先检查现有校验、类型约束、上游过滤、事务或补偿是否已处理该场景；不因局部缺少 try/catch、空值判断或缓存就推断故障。
• 选择能验证该行为的现有测试、类型检查或最小实验，先读命令及相关配置，避免自动修复、快照更新、迁移、部署或访问真实业务数据。需要写临时复现时使用隔离临时目录；不向目标代码库添加测试或修复。
• 实际执行才记为“通过”；写明命令、所测版本、结果和限制。无法运行时保留充分的静态证据或列待核实项，不强制运行无关全量测试，也不用测试通过替代需求检查。
• 历史 commit/范围的运行验证必须使用对应目标快照；当前 checkout 的测试不能证明另一 commit。对原有失败与新增失败做必要的基线比较。
• 技术结论依赖外部接口或版本且本地无法确证时，查对应版本的官方资料并引用；不可访问时说明证据缺口。性能问题说明实际数据规模/复杂度，安全问题说明输入可控性与可达路径，不把模式匹配当漏洞结论。
• 对每条候选做反证复核。按根因和修复动作合并重复，保留所有独立有效问题；不设数量指标，不只留最严重几条。证据不足移入待核实项，不能降为 P3 混入 findings。

4. 裁定、落盘与交付

1. 按报告合同写精确短定位、单段问题说明、P0–P3 和置信度。新增 findings 的主定位须与所审 diff 重叠；旧问题复审及支持证据可在 diff 之外。规则对结论有实质贡献时，附该规则的文件和最小行范围。
2. 核对覆盖清单以及版本是否发生变化。相关文件或计划变动时重审受影响结论；不能收敛时保留快照版本与缺口。报告新文件不纳入本轮审查对象。
3. 完整报告先写评审对象，再列确认问题、待核实项、覆盖与验证、可选计划符合性、总体结论和修复顺序。默认采用 patch is correct / patch is incorrect / inconclusive；最后一项是本 skill 为证据不足增加的状态，不伪称原生 Codex JSON 值。总体结论首行写验收判定。
4. 写入并回读报告，检查问题、证据、基线、限制和结论完整，链接指向实际文件。空 findings 或无法充分验证也要保存；写入失败如实说明未落盘，聊天交付完整内容，不能宣称完成保存。

5. 验收判定与下一步

计划实施完成后，代码评审是验收守门：「评审 → 修复 → 复审」循环，直到通过验收或用户明确本期放过。最终回复先给一行验收判定（定义见报告合同的「验收判定」），再给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex $apply-code-review、Claude Code /apply-code-review），路径填实际文件。

验收判定	下一步
需要修改	apply-code-review <本报告路径>；修复后再用本技能复审
通过验收 / 用户豁免通过	变更涉及界面、且还没有覆盖当前版本的 UI 验收通过时，可选 review-ui <计划路径> 做 UI/UX 验收；计划来自 PRD 时，可选 review-prd-dev-gaps <计划路径> 核对该期 PRD 覆盖；都不适用时说明本计划代码验收完成
需补证	列出所缺证据或验证及获取方式，补齐后再次 review-code <计划路径或原范围>

• 计划是否来自 PRD 以计划顶部「需求来源」为准；旧计划没有该行时，账本来源明确指向 PRD 的也算。未附计划时不提示差异核查。
• 通过验收但仍有 P3 时，可选用 apply-code-review <本报告路径> 处理，处理后照常复审。
• 用户在评审后或调用时明确表示本期放过剩余问题，按报告合同在本轮报告追加豁免记录并回读，再按通过给下一步；不把豁免写成已修复。
• 只给出建议命令，不自行启动修复、复审、UI 验收或差异核查。

调用示例（自然语言参数，不要求专用解析器）：

使用 $review-code goal/LOGIN.md
使用 $review-code 审查当前未提交变更。
使用 $review-code 审查未提交的 src/auth.ts 和 tests/auth.test.ts。
使用 $review-code 审查 commit abc1234，参考 docs/plan/login.md 的 M2。
使用 $review-code 审查 a1b2c3d..d4e5f6a，报告写到 docs/reviews/login.code-review.md。
使用 $review-code 审查相对 origin/main 的差异。
使用 $review-code 审查相对 main 的已提交差异，仅聊天输出。

项目状态回写

若仓库已登记状态台账，或存在仓根 .xgent-ai/sdlc/protocol.md（兼容已有 docs/project-status/protocol.md；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

每次实际评审登记独立评审 ID、精确 base/target 或工作树指纹、范围、结论和报告路径；计划关联以实际输入为准，允许没有计划的评审。复审关联前轮，不覆盖旧结论；不把 patch is correct 登记为已验收、已合并或已发布。