code-review-standards

代码审查标准

目的

此技能定义了 code-critic Agent 在代码生产流程的第 4 阶段采用的结构化检查清单。清单按严重程度标记，让 PM 和工程师都能明确了解哪些问题会阻碍交付，哪些仅供参考。工程师可以在请求审查之前加载此技能进行自查。

设立此清单，是因为多 Agent 系统中的非结构化代码审查会产生不一致的信号：一次审查可能指出命名问题，另一次可能指出安全问题，但两者指出的问题并不相同。严重程度标记可以让不同审查的结果保持一致。

按严重程度标记的检查清单

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 行文件限制）

Verdict 格式

Critic 输出必须以 verdict 作为第一行，接着是发现项表格，最后是总结段落。

第一行格式：

VERDICT: APPROVE

或

VERDICT: WARN

或

VERDICT: BLOCK

发现项表格格式：

严重程度	文件	行	问题	必要修复
CRITICAL	auth.py	47	硬编码的 API 密钥 sk-...	移至环境变量；添加到 .env.example
HIGH	fetcher.py	23	在 async def 中调用了 requests.get()	替换为 await httpx.AsyncClient().get()
MEDIUM	parser.py	88	函数有 34 行	提取 _parse_headers() 辅助函数

Verdict 定义：

Verdict	条件	PM 操作
APPROVE	没有 CRITICAL 或 HIGH 发现项	进入第 5 阶段（安全审查）
WARN	没有 CRITICAL 发现项，但有一个或多个 HIGH 发现项	进入第 5 阶段，并将发现项记录到文档交接内容中
BLOCK	存在任意 CRITICAL 发现项（一个或多个）	暂停流水线；向用户展示发现项；等待用户指示

APPROVE 表示实现已准备好进行安全审查。APPROVE 审查中的 MEDIUM 和 LOW 发现项会作为备注传递给 Documentation Agent——它们不会阻碍交付，但会保留以供日后参考。

WARN 表示实现存在结构性问题，应予以修复，但不构成可利用的缺陷或正确性故障。PM 继续进行安全审查，并将 WARN 发现项表格附加到文档交接消息中。PM 还会记录这些发现项（知识库条目或待办事项），以免它们被悄然遗漏。

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、命名规范）
• Verdict 协议：针对每种 verdict 的完整 PM 行为、失败循环模板

效率和可迁移性标准源自 CAST Highlight 代码 质量指标（https://doc.casthighlight.com/），并以改写后的原创 示例呈现。