requesting-code-review git:20260919.361331bA

Immutable. This exact content never changes and is served at /api/v1/blob/ce17c9be222ba298.

---
name: requesting-code-review
description: 用户要求审查当前代码差异或 PR 时使用，默认只读；处理已收到的评审意见用 receiving-code-review。
compatibility: 本地差异审查需要 git。读取 GitHub PR 或发布评审需要可用的 GitHub 连接器或已认证的 gh CLI。
---

# 系统性代码审查

## 边界

- 审查当前本地差异或指定 GitHub PR，默认只分析和报告。
- `receiving-code-review` 处理别人已经给出的意见。
- 审查阶段不修改文件、不提交、不推送；用户已明确授权后续工作时，审查完成后继续对应步骤。
- 发布远端评审仍须用户明确要求；同一范围内已有授权时不重复请求。
- 不要求特定客户端插件。GitHub 连接器可用时优先使用，否则回退 `gh`；两者都不可用时仍可审查本地差异，远端操作明确报告未执行。

## 1. 固定审查快照

先确认仓库、工作区和审查范围：

```bash
git rev-parse --git-dir
git status --short
git branch --show-current
git log --oneline -10
```

PR 模式通过当前可用的 GitHub 能力读取编号、基准分支和来源分支、状态、更新时间、完整差异和检查。本地模式读取 `git diff HEAD` 或明确的 `<base>...HEAD`。记录实际范围，不基于旧差异或截断差异块下结论。

完整差异、逐文件覆盖、可信上下文、行号定位和反证规则遵循 [评审证据协议](references/evidence-protocol.md)。标准或深入审查先执行 [范围与完整性预判](references/review-preflight.md)。

## 1.1 场景契约与验收范围

如果变更目录或目标项目已有 `test-scenarios.md`，在深入审查前读取它，把它当作本次行为范围和验收标准的输入，而不是把测试数量当作覆盖证明。

检查：

- 每个受影响的行为是否能映射到场景 ID；
- `covered` 场景是否有真实测试命令、日志、运行结果或其他证据；
- `skipped` 场景是否说明原因、影响和后续动作；
- P0/P1、错误路径、兼容性、权限和人工 E2E 场景是否被遗漏；
- 实现、测试和场景契约之间是否出现互相矛盾的预期。

没有场景契约时，不要为了补文档而擅自创建文件。对于非平凡或行为变化的差异，在摘要中记录 `scenario contract: none`，将其作为覆盖与验收缺口，而不是自动判定为代码缺陷。

审查仍然是只读流程；场景状态和证据的补充由实现者或用户授权的后续步骤完成。

## 2. 确定深度与专项

- 快速：100 行以内且 1-5 个文件
- 标准：100-500 行，或 6-10 个文件
- 深入：500 行以上、10 个以上文件，或涉及认证、支付、数据写入等高风险路径

只根据本轮变更加载专项：

- 通用正确性、边界、错误处理、测试与复杂度：[代码质量](references/code-quality.md)
- 明确热点、I/O/网络放大、锁或分配风险：[性能](references/performance.md)
- 信任边界、鉴权、输入或密钥风险：[安全](references/security.md)
- 行为、API、配置或示例变化：[文档](references/documentation.md)
- `.go` / `go.mod`：[Go](references/go-specialist.md)
- `.java`：[Java](references/java.md)
- `.py`：[Python](references/python.md)
- CI、YAML/JSON 配置或依赖清单：[CI 与配置](references/ci-config.md)

TS/JS 变更执行轻量语言检查，不因仓库存在某语言就加载无关清单。

## 3. 架构分路

用户明确要求架构评审，或差异改变模块分层、公共接口、适配器或中间件、状态或任务生命周期、存储、跨服务调用、权限、错误体系、并发与资源管理时，加载 [架构审查](references/architecture.md)。

架构结论必须基于当前差异和必要相邻实现。区分必须修复与可选优化，不把理想化分层、个人偏好或未触及历史问题包装成缺陷。

## 3.1 结构与变更风险

标准或深入审查增加以下检查，但只对当前差异和其必要上下文下结论：

- 先寻找能删除概念、分支、状态或中间层的重构，再提出局部整理；仅移动复杂度而没有降低读者负担，不算结构改善。
- 对新增的特殊分支、临时布尔值、可选模式、重复条件和一次性 wrapper 保持怀疑；如果逻辑已经属于某个 canonical helper、包或层，应移回其所有权边界。
- 文件因本次变更从 1000 行以下增长到 1000 行以上时，视为强烈的拆分信号；只有有明确结构理由且仍易读时才接受。
- 检查独立的异步工作是否被无理由串行化，以及相关更新是否可能留下半完成状态；只在能降低复杂度或确实改善一致性时提出并行或原子化建议。
- 类型、错误和权限边界应表达真实不变量；不要用 `any`、cast、静默 fallback 或过宽 optional 参数掩盖边界不清。
- 外部输入、配置、网络和持久化数据应在系统边界完成解析、校验和类型收窄；内部逻辑应信任已经建立的不变量，不要把重复 nil 检查和 transport/storage 类型泄漏到业务层。
- 如果状态由多个布尔值、阶段字段或散落条件共同表达，检查是否应改为状态机、判别联合、registry 或其他能消除矛盾状态的领域结构；不要为了抽象而抽象。
- 只保留能解释不变量、兼容性或非显然取舍的注释；删除模板化注释、异常防御分支、仅为绕过类型检查的 cast 和会掩盖根因的 try/catch。保持行为不变，不把主观格式偏好当成问题。

## 4. 证据过滤与汇总

对每个候选 finding：

1. 读取定义、调用方、配置和测试等必要上下文；差异块不足时查真实代码。
2. 找能推翻关键事实的反证，有直接反证就删除。
3. 确认问题由当前变更引入或暴露，并定位到当前快照最小连续范围。
4. 内部评估置信度：`80+` 才作为问题；`50-79` 放入待确认；低于 50 不输出。
5. 按文件和根因去重，再按 P0/P1/P2 排序。

对影响范围较大的变更，找出“该变更安全所依赖的一个关键事实”，并尽量用真实代码、最小脚本或针对性测试证明它。只能从源码推理或无法运行验证时，明确标为待确认，不把未证明的安全假设写成结论。

对可能改变开发者或既有功能使用方式的差异，额外检查环境变量和 secret 读取、端口与网络、必需脚本、构建入口、feature gate 和内部权限条件。预期的破坏只有在目标和范围明确时才忽略；否则按回归报告。研究尚未完成时保留未确认项，不用条件猜测替代对后端、调用方或 PR 讨论的核实。

测试相关差异额外检查：

- 关键主流程、失败路径、边界输入、兼容性、权限和并发/异步状态是否有与风险匹配的验证；
- 新增或修复的 bug 是否有可复现的回归场景，而不是只增加无关覆盖率；
- 测试是否依赖执行顺序、共享状态、未提交事务、固定资源名或外部环境；
- 删除、收缩或改写测试时，原有关键约束是否仍被保留；
- 单元测试使用 mock/fake 时，集成/E2E 是否仍覆盖真实协议、数据和最终状态；
- 测试通过、编译通过或中间资源状态是否被错误地报告成完整运行面验证。

严重度：

- P0：确定的正确性、安全或严重并发缺陷
- P1：健壮性、关键测试缺口或明确性能退化
- P2：有实际维护成本的设计、文档或规范问题

不为凑数量报告问题。默认检查是否存在可删除的抽象、依赖和配置层，但安全校验、错误处理、数据保护、可访问性和用户明确需求不算无效复杂度。

## 5. 发布评审

只有用户明确要求把结果发布到 GitHub 时：

1. 完成所有适用检查和去重后再发布，避免中途制造多次通知。
2. 使用当前可用的连接器；不支持写入时回退 `gh api`。
3. 只发布一次不阻塞合并的 `COMMENT`，不擅自使用 `REQUEST_CHANGES`。
4. 发布后读回评审，验证目标 PR、正文和事件类型。
5. 没有远端写能力时输出完整评审正文和人工执行说明，不声称已经发布。

## 输出

```text
## 问题
[P0/P1/P2] <标题> - <文件:行> [置信度: 90]
证据: <触发条件、当前代码和影响>
建议: <最小可执行修复>

## 待确认问题
- <缺少的关键证据>

## 摘要
- diff 快照：<range>
- 文件覆盖：<已审查 / 上下文 / 跳过 / 失败>
- 范围与需求：<结论>
- 场景契约：<path / none>; 覆盖：<结论>
- 可拆分性与文档债务：<结论>
- 架构专项：<未执行或基于证据的结论>
- 发布：<未请求 / connector / gh / 未执行>

## 统一约束

- 验收标准：遵循 `skills/_shared/common-acceptance.md`
- 场景契约只作为审查输入；没有用户授权，不在审查流程中创建或修改它。
```

问题最多 15 条。没有高置信问题时明确写“未发现明确问题”，并说明验证和上下文边界。