| name | code-review |
| description | Review code changes for correctness, regressions, edge cases, style issues, and unnecessary churn. Use when checking diffs, reviewing pull-request-like changes, or doing independent quality review. Triggers on "review this", "check my changes", "code review", "代码审查". |
code-review
独立的代码审查技能。读 diff(或一组改动文件),按结构化清单评估,输出按严重度分组的发现。不修改任何代码——只产出报告供用户决策。
触发条件
- 用户说"帮我 review"、"检查改动"、"code review"、"代码审查"
- 用户分享 PR / 一段 diff
- workflow
/review-changes 或 /verify-result 路由到本技能
safe-refactor 完成阶段性改动后自动调用(互补关系:refactor 做改,review 验改)
前置条件
- 工作区里有未提交改动 或 给定明确的 commit range / file list
- 如果是 PR review,先
gh pr diff 或 git diff 拿到改动集
执行步骤
Step 1: 确定 review 范围
- 如果用户没指定,默认对当前未提交改动 (
git status + git diff) 做 review
- 如果指定了 commit / branch / PR,明确范围并向用户复述确认
- 大改动(>500 行 diff)先拆分:按文件 / 按职责分批
Step 2: 加载上下文
- 读完整的被改动文件(不只是 diff 中显示的几行)——
Read 工具读整文件,至少看清楚函数边界
- 读引用方:用
Grep 找谁调用了被改函数 / 谁导入了被改模块
- 读测试:被改代码是否有测试?测试是否被同步更新?
Step 3: 按 6 维清单审查
按以下顺序检查,每条记录具体 file:line 引用:
- Correctness(正确性): 代码是否做了它声称的事?看 docstring / commit message 是否与实际逻辑匹配
- Regressions(回归风险): 已有功能是否可能被破坏?特别看:
- 被改函数的所有调用方是否还能用
- 公开 API(schema、CLI args、env vars)是否保持向后兼容
- 共享状态 / 全局变量 / 单例
- Edge Cases(边界): 异常输入、空集合、None、并发、I/O 失败是否处理
- Interface Risk(接口风险): public 或 internal contract 是否被无意改动(rename、参数顺序、返回类型)
- Test Coverage(测试覆盖): 改动是否有对应测试?新 branch / new error path 是否被测
- Churn(多余改动): 有没有可以简化 / 删除的部分?有没有偏题改动应该单独 commit
Step 4: 生成报告
输出格式:
# Code Review: {scope}
## Critical (must fix before merge)
- [file:line] {issue}: {why it's critical}
## Important (should fix)
- [file:line] {issue}: {recommended fix}
## Nit (style / minor)
- [file:line] {issue}
## Suggested next checks
- {what to verify next, e.g. "run integration tests on stage X"}
按严重度排序。每条必须带 file:line 锚点(markdown link 格式 [file.py:42](file.py#L42)),不写笼统"some code smells"。
输出契约
返回 markdown 报告(向用户终端打印)。不落盘到 artifacts/——code-review 是即时反馈,不进入 evidence_graph。如果用户后续要 fix,由用户决定是否调 safe-refactor / systematic-debugging。
失败处理
- diff 过大(>1000 行)→ 先警告用户,建议拆分 PR 后再 review
- 无法访问被引用的外部依赖(例如改动调了未安装的库)→ 报告 "[BLOCKED] unable to verify X because Y",不编造判断
- 改动跨多个 unrelated 子系统 → 拆分报告(按子系统分节)
与其他技能的关系
- systematic-debugging: review 找到 bug → debug 定位 root cause → fix
- safe-refactor: refactor 做改动 → review 验证保留语义
- test-author: review 标出"缺测试" → test-author 补
- verification-runner: review 标出"应该跑 X 测试" → verification 实际执行
遵守规则
.agents/rules/repo-architecture.md: 不允许 review 时建议跨模块违规修改
.agents/rules/evidence-discipline.md: review 报告中的 claim 必须有 file:line 证据
Severity-blocking review(强制 severity 协议)
"建议性" review 是噪声。NeXus 的 review 必须把每条评论钉死在 4 级 severity 上,让作者 一眼看出"必须改 vs 可选改"。
没标 severity 的评论视为 NIT,但不允许这样写——所有评论都必须显式标级。
四级 severity 定义
| Severity | 含义 | Merge 影响 |
|---|
| CRITICAL | 会导致正确性 / 安全 / 数据丢失 / 公开契约违反 | 阻断 merge,必须修后重新 review |
| IMPORTANT | 不立刻坏,但显著放大未来 bug 风险(缺测试覆盖、错误处理缺失、回归风险、文档与代码不一致) | 必须 address——修、或给出 reviewer 同意的 defer 理由 |
| NIT | 风格 / 命名 / 局部可读性 / 微优化 | 建议性,作者可拒绝且无需解释 |
| PRAISE | 优秀实践 / 正确的设计判断 | 正向反馈,鼓励同类做法被复用 |
每级的强制结构
每条 review comment 必须在 file:line 之后立刻打 [CRITICAL] / [IMPORTANT] / [NIT] / [PRAISE] 标签,并满足该级的"必填字段":
- CRITICAL 必填两项:
- 为什么 block:具体说出"会引发什么样的错误"——不能写"this looks wrong",要写"input X 会触发 ZeroDivisionError,调用方未捕获"
- 怎么修:给出可执行的修法(patch 思路 / 替换代码 / 调用替代 API),让作者无需再追问
- IMPORTANT 必填一项:
- 修改后预期结果:明确"改完之后我期望看到 X"(例:新增 test case 覆盖 None 分支、错误码统一为 ValueError、log 改为 warning 级)
- NIT 必填:
- 只需指出位置 + 建议,不需要解释影响(因为本来就可拒绝)
- PRAISE 必填:
- 指出做对了什么 + 为什么这是好实践(让读者能复用此判断,不是空洞的 "nice")
不允许的 ambiguous 评论
下列写法在 NeXus review 报告里禁止出现——它们既不阻断也不可执行,纯属噪声:
- ❌ "could be better"、"maybe consider"、"feels off"——没有 severity,也没有 actionable 建议
- ❌ "this is a bit complex"——没说复杂在哪、对应哪一级、要怎么改
- ❌ "I'd probably do it differently"——表达偏好不是 review
- ❌ 只给 severity 不给"为什么 block / 修改后预期"(CRITICAL/IMPORTANT 的必填字段缺失)
- ❌ 标了 CRITICAL 但实际只是风格问题 —— 滥用 CRITICAL 等同噪声,会被作者降权所有 critical 标签
若一条评论确实拿不准 severity,默认降为 NIT 并加一句"为什么没标 IMPORTANT 的判断依据"——宁可漏报也不滥报。
报告输出补强
报告第一行必须给出 severity 直方图:CRITICAL=N, IMPORTANT=N, NIT=N, PRAISE=N,让作者 / merger 一眼定位 review 结论:
CRITICAL ≥ 1 → 不允许 merge,必须修
CRITICAL = 0, IMPORTANT ≥ 1 → 可 merge 但需作者明确处理意见(修 / defer with reason)
CRITICAL = 0, IMPORTANT = 0 → 通过,NIT 可选采纳