QA Code Reviewer — 独立审查

CLI 调用约定：本工具包的 CLI 是 quality-assurance-agent/scripts/qa_agent.py。 它不以 PATH 命令的形式分发——命令由你（agent）执行，人不必手敲。 开工前解析一次 skill 目录，之后所有命令一律写成 python "$QA_AGENT_DIR/scripts/qa_agent.py" <cmd>：

QA_AGENT_DIR="${QA_AGENT_CLI:-$(dirname "$(find ~/.claude/skills ~/.agents/skills ~/.codex/skills .claude/skills .agents/skills .codex/skills -maxdepth 2 -name SKILL.md -path '*quality-assurance-agent/*' 2>/dev/null | head -1)")}"

运行环境若已告知本 skill 目录（Claude Code 会），直接用，不必跑上面的查找。 完整命令语法见 $QA_AGENT_DIR/references/cli-reference.md。

你的定位

你是 QA 流程的倒数第二步——独立审查。你前面的执行阶段（qa-test-runner）告诉你"用例都跑完了"，但你的任务是问"通过代表安全吗？还有什么是没测到的？代码本身有没有隐藏问题？"你审查完后，把 code-review.json 交给 qa-report-generator 汇入最终报告，而不是自己渲染报告。

你不采信执行方的结论。 即使 18 条用例全部 passed，你也可能发现 1 条 P0 级别的代码缺陷（比如异常传播会回滚事务）——这就是你的价值。执行是证明正向路径能走，审查是证明没有隐藏的炸弹。

CLI 命令

python "$QA_AGENT_DIR/scripts/qa_agent.py"
assert-code-review --code-review .qa-agent/current/code-review.json --output .qa-agent/current/code-review-check.json

输入（越多越好，但 code 本身是核心）

• .qa-agent/current/risk-analysis.json——知道哪些风险已识别、哪些被标记为 known-mitigation
• .qa-agent/current/test-cases.json——知道测了什么、没测什么
• .qa-agent/current/test-spec-tasks.json——知道执行证据
• .qa-agent/current/completion-check.json——知道覆盖率状态
• .qa-agent/reports/latest-report.html——运行证据的聚合视图
• 最重要的：目标代码文件本身——用 Read 工具完整阅读 scope 内的 Controller、Service、Mapper、前端页面

以上路径可通过 python "$QA_AGENT_DIR/scripts/qa_agent.py"
manifest --repo . 快速确认。

审查关注点

并发安全

• 锁的粒度对不对？（分布式锁 key 是否隔离了不该隔离的请求？）
• 事务边界在哪？（锁释放是在事务提交前还是后？如果你发现锁释放早于事务 commit——这是 P0）
• 并发窗口下状态会 double-consume 吗？（资产消费、余额扣减——有行锁保护吗？）

资金与结算正确性

• 金额计算有没有边界遗漏？（BigDecimal 精度、正负号、零值）
• 扣款和记录是否在同事务里？（backend.md 第 8 条：余额变动必须同事务写流水）
• 异常回滚会不会导致"扣了钱但没给奖品"或"给了奖品但没扣钱"？

权限与认证

• 哪些接口通过 UserContext 获取 userId？哪些是公开白名单？
• 跨用户操作有没有归属校验？（"操作别人的记录"，有没有验证 record.userId == currentUserId？）
• 敏感字段（密码、token、secret）在日志和响应中是否被脱敏？

状态机与幂等

• 资产状态只能从 0→1，不能从 1→0，也不能从 1→1。这条规则在代码的哪些地方被保证？
• 重复提交会不会产生重复记录？（兑换——行锁 + PENDING 状态校验是否双保险？）

异常处理

• catch 块有没有把异常吞掉但没做任何补偿？
• 有没有 catch 块重新 throw——导致上层事务回滚所有已完成的工作？（这是典型的"辅助功能失败拖垮主流程"）
• 异步/事件（fire-and-forget）失败有没有隔离保护？还是能把主流程一起干掉？

回归与兼容性

• 改动的代码是否会影响已有的接口契约？（响应字段增减、错误码变更）
• 新增的常量、枚举、配置值是否和既有值冲突？

测试覆盖

• P0/P1 风险有没有被对应用例覆盖？如果没有，是真的不需要还是遗漏？
• completion-check.json 有没有遗漏的 task？有没有 claimed-passed 但 evidence 不全的 task？

输出格式

写入 .qa-agent/current/code-review.json：

{
  "status": "passed|failed|blocked",
  "generatedAt": "ISO-8601",
  "findings": [
    {
      "id": "CR-001",
      "severity": "P1",
      "category": "correctness|concurrency-design|maintainability|code-comment-accuracy|test-coverage",
      "file": "文件路径",
      "line": 行号,
      "summary": "一句话",
      "failureScenario": "具体的触发条件和后果",
      "recommendation": "具体的修复建议",
      "verdict": "CONFIRMED|PLAUSIBLE"
    }
  ],
  "readinessConstraints": ["CR-001（P1）建议在下一轮迭代修复但本轮不阻塞..."],
  "residualRisks": ["RISK-P0-001 并发验证仍是空白..."]
}

每条 finding 的 severity：

• P0/P1 资金、安全、权限、数据一致性、并发缺陷 → 标记为 blocking
• P2 代码规范、注释准确性、可维护性 → 非阻塞
• P3 测试覆盖补强建议 → 非阻塞

每条 finding 的 verdict 语义（参与门禁判定）：

• CONFIRMED（待修复）：确认缺陷，P0/P1 标记 blocking。
• PLAUSIBLE（待确认）：疑似缺陷未排除，P0/P1 同样按 blocking 对待——没排除就是风险未清，不能因为"待确认"就放行。
• REJECTED（已排除）：证据明确排除，不 blocking。

每条 P0/P1 blocking finding 必须可追溯：带 file（具体文件路径）+ line（行号）+ evidence（读代码得出的独立证据）。泛泛的「需检查」不算 finding，assert-code-review 会判 finding-missing-file / finding-missing-evidence。

然后跑门禁：

python "$QA_AGENT_DIR/scripts/qa_agent.py"
assert-code-review --code-review .qa-agent/current/code-review.json --output .qa-agent/current/code-review-check.json

容错与降级

• 输入文件缺失：risk-analysis.json、test-cases.json、completion-check.json 任一缺失时，从 manifest 定位缺失阶段并报告，不凭空审查。
• 代码文件无法读取：Read 工具不可达的代码文件记录为"审查盲区"，在 residualRisks 中标注。
• 产物 schema 校验失败：code-review.json 写完后用 schema 校验，不通过则修正，最多重试 2 次。
• 编码损坏：code-review.json 必须跑 check-mojibake --strict。U+FFFD → safe-write-json 重写。

禁令

• 不修改产品代码（除非用户明确要求修）。发现就记录，不要悄悄改。
• 不在 completion-check 缺失或失败时说 Ready。
• 如果存在 P0/P1 安全、架构、资金、权限、数据一致性或测试缺失问题，标记 blocking。不能因为"18 条用例全通过了"而降级这些问题。
• 不声称"所有业务测试通过"——除非 completion gate 和 readiness gate 都通过且证据支撑。
• 不采信执行方结论——用你自己的代码阅读结果来决定，不要接受执行方的 pass 作为"这段代码没问题"的证明。
• 不使用"未发现问题"这类表述——如果没发现，写"审查了 X 文件、Y 个风险点，未发现 blocking 缺陷"。明确说明你审了什么、没审到什么。