code-review-standards

用途

该技能定义了 code-critic 智能体在代码生产流水线第 4 阶段所应用的结构化审查清单。清单带有严重级别标签，使项目经理（PM）和工程师都能明确知道哪些发现会阻断交付、哪些只是建议。工程师也可以在请求 critic 审查之前加载此技能进行自审。

该清单的存在是因为多智能体系统中的非结构化代码审查会产生不一致的信号：一次 critic 调度标记命名问题，另一次标记安全问题，两者都没有标记相同的内容。严重级别标签使审查在不同调度之间具有确定性。

严重级别标签清单

CRITICAL（必须修复，阻断交付）

没有硬编码的密钥、API 密钥或凭据
没有 SQL 注入向量（仅使用参数化查询）
没有任意代码执行路径（不使用 eval、exec、不受限制的 pickle.loads）
认证/授权不可绕过
没有无退出条件的无限循环

HIGH（必须修复，阻断交付）

所有公共函数和类都有类型提示
mypy --strict 零错误通过
pytest 零失败通过
新代码测试覆盖率 >= 90%
没有裸 except 子句
没有可变默认参数
没有全局可变状态
异步函数内没有同步 I/O
没有 N+1 查询模式
错误情况被显式处理（不被静默吞掉）

MEDIUM（标记，记录在报告中，继续）

函数 <= 20 行（优先 <= 10）
没有可用哈希映射降低复杂度的嵌套循环
在相关处将 list.pop(0) 替换为 deque.popleft()
asyncio.gather 在适当处使用 return_exceptions=True
异步操作有显式超时
公共方法有文档字符串（Google 或 NumPy 风格）
生产代码路径中没有 Any 类型

效率（参见 criteria-efficiency.md）：

没有对两个集合的嵌套循环，本应是哈希映射查找（O(n*m) → O(n+m)）
没有逐次迭代的 I/O（循环内的查询/RPC/获取）——在循环外批量处理（热路径上为 HIGH；参见“没有 N+1 查询模式”）
重复的深层属性/选择器解析缓存在局部变量中（没有贪婪数据访问）
循环中的字符串累积使用 list+join / StringBuilder，而不是 +=
生产查询路径中没有 SELECT * / 过度获取

可迁移性（参见 criteria-transferability.md）：

没有死代码/不可达代码（无条件 return/break/raise 之后的语句；未被调用的私有成员）
长 if/else if 链（对同一键有 3 个以上分支）替换为 switch/match 或分派映射
没有嵌套 switch/match——将内部 switch 提取为命名函数
没有主动误导性的名称（名称与其持有的值相矛盾）

LOW（仅提示）

PEP 8 合规（black + isort 自动处理）
变量命名清晰且具有描述性
没有留下注释掉的代码
导入顺序整洁
变更中的命名一致性（同一概念，同一名称；大小写一致）
没有文件管理过多职责（参见 800 行文件限制）

裁决格式

Critic 输出必须以第一行的裁决开始，随后是发现表格，最后是总结段落。

第一行格式：

VERDICT: APPROVE

或

VERDICT: WARN

或

VERDICT: BLOCK

发现表格格式：

Severity | File | Line | Issue | Required Fix

示例：

CRITICAL | auth.py | 47 | Hardcoded API key sk-... | Move to env var; add to .env.example

HIGH | fetcher.py | 23 | requests.get() called inside async def | Replace with await httpx.AsyncClient().get()

MEDIUM | parser.py | 88 | Function is 34 lines | Extract _parse_headers() helper

裁决定义：

Verdict	Condition	PM Action
APPROVE	零 CRITICAL，零 HIGH 发现	进入第 5 阶段（安全）
WARN	零 CRITICAL，一个或多个 HIGH 发现	进入第 5 阶段，发现记录到文档交接
BLOCK	任何 CRITICAL 发现（一个或多个）	暂停流水线；向用户呈现发现；等待用户指示

APPROVE 意味着实现已准备好进行安全审查。APPROVE 审查中的 MEDIUM 和 LOW 发现作为备注传递给文档智能体——它们不阻断交付，但保留供将来参考。

WARN 意味着实现存在应修复的结构性问题，但不代表可利用的缺陷或正确性失败。PM 继续安全审查，并将 WARN 发现表附加到文档交接消息中。PM 还记录发现（KB 条目或待办事项），以免它们被静默丢弃。

BLOCK 意味着实现至少有一个缺陷，如果发布，会造成安全漏洞、数据丢失风险或静默失败模式。PM 立即暂停流水线，将 critic 发现表逐字呈现给用户，并等待明确指示。PM 不得在无用户输入的情况下自动重试工程师。

80% 置信度过滤

干净的审查是有效的审查。不要制造发现。

只报告有 >80% 置信度是真实问题的议题。不要标记：

将风格偏好标记为 HIGH 或 CRITICAL
“这在边缘情况下理论上可能是个问题”而没有具体证据
看起来不寻常但可能是有意且正确的模式
不在范围内的缺失功能（检查第 1 阶段规范）

当置信度低于 80% 时，将关注点作为总结段落中的问题记录，而不是表格中的发现。示例：“process_batch() 函数似乎没有处理空输入——请验证调用方是否保证非空批次。”

此过滤器防止 critic 成为噪音生成器，从而训练 PM 忽略发现。表格中的每个发现都应是可操作的：工程师阅读后，确切知道要修复什么，并且无需请求澄清即可完成。

CRITICAL 标准：每个 CRITICAL 项的详细解释和示例
HIGH 标准：每个 HIGH 项的详细解释和示例
MEDIUM 标准：每个 MEDIUM 项的详细解释和示例
LOW 标准：每个 LOW 项的详细解释和示例
效率标准：算法/数据访问模式（嵌套循环、循环内获取、贪婪访问、循环拼接、过度获取）
可迁移性标准：可维护性模式（死代码、长 if/else-if 链、嵌套 switch、命名卫生）
裁决协议：每个裁决的完整 PM 行为、失败循环模板

效率和可迁移性标准源自 CAST Highlight 代码质量指标（https://doc.casthighlight.com/），经改写并附有原始示例。

技能介绍

用途