# QA Code Reviewer

> QA 流程倒数第二步的独立审查环节。在 qa-test-runner 执行完成后，以独立视角审查代码本身——检查架构、安全、并发正确性、数据一致性、 回归风险、测试覆盖缺口——不受执行方结论的影响。产出 code-review.json（含 severity 分级发现和 readiness 约束）， 和 assert-code-review 门禁一起构成代码审查证据，交给 qa-report-generator 汇入最终报告。P0/P1 安全问题、资金逻辑缺陷、权限漏洞、数据不一致风险标记为 blocking。 不适用：生成用例、执行测试、修改产品代码（除非用户明确要求）、报告生成。

- Skill: `mingdui/qa-code-reviewer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add mingdui/qa-code-reviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mingdui/qa-code-reviewer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: mingdui (https://skillmd.com/u/mingdui)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/mingdui/qa-code-reviewer

---


# 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 命令

```powershell
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`：

```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`。

然后跑门禁：

```bash
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 缺陷"。明确说明你审了什么、没审到什么。