---
name: pre-commit-quality-review
description: 大量代码合并主干分支前的质量自查：功能逻辑内聚、代码分层、可维护性三问走查整个待合并批次；当用户要求合并主干前查质量、提测/发版/特性分支大批量合入前走查、自查内聚/分层/可维护性时使用。
---

<!-- nuwa-sdlc-kit v1.3.1 · content — 播种一次，本地所有（升级不覆盖）
SDLC Stage 3.5 · 大量代码合并主干分支前质量自查（writer 侧）。三问清单安装后按仓库实际维护：
分层文档路径、质量门命令登记在本节，检查项可增删。 -->

# 合并主干前质量自查（Pre-Merge Quality Review）

> 适用时机：**大量代码合并主干分支前**必做（提测、发版、特性分支大批量合入等场景）——对整个待合并批次做一轮实现质量走查；
> 日常小 commit（样式微调、文案、单点修复）可跳过。本自查是 writer 侧质量门，
> 不替代 PR 评审（`REVIEW.md` 五遍清单；writer 不自批）。
>
> 承接「**先功能后重构**」的开发节奏：功能先跑通 → 重构收敛（内聚/分层/可维护）→ 本自查作重构完成后的**验收门**——三问发现的问题当场修复、修完复查，全过 + 质量门绿才可合并交付。

## 目标

回答三个问题，每个结论都带证据（文件:行号）：

1. 功能逻辑是否内聚？
2. 代码分层是否正确？
3. 后续是否便于维护？

## 工作方式

1. 以**待合并批次**为单位走查：`git diff <主干分支>...HEAD` 加工作区未提交改动圈定改动面（新增文件读全文），不逐行复读未改代码。
2. 逐问检查，发现问题当场修复（属重构收敛的一部分），修完复查该问，不带着已知问题进主干。
3. 走查后跑质量门：有分域快速门先跑分域，再按需跑全量（`pnpm exec vitest run`），贴结论数字。
4. 回报结论：可合并 / 需修改（列问题清单与位置）。

## 三问清单

### 一、功能逻辑内聚

- 该功能的知识（状态、缓存失效、副作用与清理）是否收在属主模块内，还是散落在多个调用方？
- 同一不变量是否只有一处维护点？兜底/防御逻辑是否跟着属主走？
- 组件或函数是否只服务一类使用者？混入的无关职责是否拆出去了？

### 二、代码分层

- 依赖方向是否单向（页面 → 组件 → hooks/services → utils）？有无越层 import？
- 对外契约（props/参数/接口）是否最小？调用方是否无须了解实现细节即可正确使用？
- 新代码落点是否符合本仓分层约定？（本仓：docs/engineering-conventions.md，含分层依赖禁令与命名/I18n 规范）

### 三、便于维护

- 注释是否解释「为什么」（约束、坑、边界），而非复述代码？
- 命名是否与既有代码同族？魔法数字是否收敛为具名常量？
- 后续接手者能否凭接入注释独立使用/扩展？易错点是否有防呆（防御 guard、cleanup 配对）？

## 判定口径

- 三问全过 + 质量门绿 → 可合并。
- Important（会错、会泄漏、破坏分层约束）→ 必须先修再合并。
- Nit（风格/更优雅写法）≤ 5 条，记录不阻塞；格式化工具已覆盖的不算。

## 参考

- slash command：`/quality-review` 可直接点名本流程。
- PR 评审清单：根目录 `REVIEW.md`（评审侧五遍清单）。
- 「错两次进规则」：同类问题第二次被抓，纠正写入 AGENTS.md。