code-quality-auditor

# Code Quality Auditor ## 铁律 - 先给 Review Gate 结论、阻塞原因和复查基线，再给摘要。 - 没有最低验证证据，不得给 `Pass`。 - `Pass` / `Reject` 是 Gate 结论，`suggest` / `warning` / `blocker` 是问题分级，二者不能混用。 - 文档、规划、配置、脚本与测试代码同样属于正式审查对象，不能因为“不是业务代码”而跳过。 ## 必读依据 - [AI 协作规范](../../../docs/standards/ai-collaboration.md) - [开发规范](../../../docs/standards/development.md) - [安全规范](../../../docs/standards/security.md) - [测试规范](../../../docs/standards/testing.md) - [验证矩阵](./references/validation-matrix.md) - [审查清单](./references/review-checklist.md) - [证据模板](./references/evidence-template.md) ## 工作流 ### 1. 建立审查上下文 - 读取 git diff、变更文件清单、Todo 验收点和已有验证结果。 - 没有 diff 时，明确指出“当前没有可审查改动”，并要求用户指定 staged changes、提交范围或文件范围。 - 先识别关键入口与高风险区域，例如鉴权、数据写入、外部调用、构建配置、规范文档、治理脚本和 agent / skill 定义。 - **diff 规模核验（必查项）**：统计变更文件数与新增行数（`git diff --stat` 或新增文件清单）。超过 [开发规范 §2.8 提交规模约束](../../../docs/standards/development.md) 阈值（10 文件或 800 行新增）时，要求调用方说明批次拆分依据；未拆分且无正当理由 → `Reject`（退回拆分后分批提交）。并发分区审计时按各分区规模之和合并判定。 ### 2. 判定改动类型与最低验证要求 - 使用 [验证矩阵](./references/validation-matrix.md) 先确定最低验证层级，再决定需要补哪些命令。 - 代码改动默认至少包含 `pnpm lint` 和 `pnpm typecheck`；样式改动补 `pnpm lint:css`；Markdown / 文档改动补 `pnpm lint:md`。 - 测试不是所有场景都一刀切全量执行，必须按风险选择定向测试、全量测试、coverage、E2E 或性能验证。 - 若实际证据低于最低层级，直接判定为 `Reject`，而不是“暂时通过”。 ### 2.5 按 audit-depth 分配审查深度（控制用时） 审查投入与改动风险匹配，不应对所有改动一视同仁长时间分析。`audit-depth` 分级（`quick` / `standard` / `deep`）、适用改动与时间盒以 [AI 协作规范 §2 A (Audit) 分级审计执行协议](../../../docs/standards/ai-collaboration.md) 为唯一权威；调用方未声明时按 `deep` 防御执行。 执行规则： - **证据优先采信**：任务方提供的已查证事实（实验证据、测试结果、源码行号引用）直接采用，翻源码仅限需要最终实锤且无外部参考的场景。 - **收敛策略（不依赖时间感知）**：审计方无真实时间感知，不检查时间、不因时间收敛——审查输出固定为“audit-depth 审查范围内可交付的结论 + 未覆盖边界”，宁可给 `Reject`（附待补证据清单）也不无限深挖；是否超时由调用方事后实测判定，不回溯要求补动作。 - **复审只审修复点**：第 2+ 轮 review 只复查上轮问题编号对应的修复点 diff 与受影响断言，不得重读全量 diff；输出中声明“本轮仅复审基线：问题编号列表”。 - **并发分区**：当调用方按模块分区发起多个 review 任务时，各分区独立出结论；主审汇总时合并去重、取最严结论。 - **用时反馈（调用方事后实测）**：审计方不自报时长、审计过程中不检查时间；“实际用时 / 是否超时间盒”由调用方按 [AI 协作规范 §2 A (Audit) 分级审计执行协议](../../../docs/standards/ai-collaboration.md) 用宿主系统时钟事后实测回填，实测超时仅作分级校准数据，不回溯要求补动作。 ### 3. 收集并延续审查证据 - 默认把临时审查记录写入 git ignore 的 `artifacts/review-gate/`，文件名建议使用 `<date>-<scope>.md`。 - 首轮证据优先由 `scripts/review-gate/generate-evidence.mjs` 生成，发布前收口则优先复用 `scripts/release/pre-release-check.mjs` 的输出作为最低验证证据。 - 多轮 review 复用同一份记录，按 `Round 1`、`Round 2` 追加，保留未关闭问题编号与复查结论。 - 证据记录至少包含：变更范围、已执行验证、结果摘要、问题分级、Gate 结论、未覆盖边界、后续补跑计划。 ### 4. 执行结构化审查 - 用 [审查清单](./references/review-checklist.md) 逐项覆盖正确性、安全、职责边界、可删除残留、测试充分性与文档漂移。 - **治理定义必查（含 `quick`）**：改动涉及 `docs/standards/*.md`、`.github/skills/*/SKILL.md`、`.github/agents/*.agent.md` 时，按 [文档规范 §6.2 收敛规则](../../../docs/standards/documentation.md) 检查：**规范单点声明**（不得与权威文档重复抄写完整条款/阈值/教训，应一行链接引用）与**规范执行分层**（新增严格约束须声明并挂接 review 检查点；宽松指引留在执行层）。治理定义改动多为 `deep` 全量执行，`quick` 仅限措辞级改动，至少完成新增 diff 文本与权威文档的比对目检。 - **供应链信任边界必查**：改动引入新依赖、MCP server、外部 skill/agent，或依赖 AI 推荐的包时，按 [安全规范 §5.2 供应链信任边界](../../../docs/standards/security.md) 检查来源验证、钉版本锁文件与先验来源。 - **开发流程编号标记检查（必查项）**：按 [开发规范 §2.2.1 注释规范](../../../docs/standards/development.md) 的"禁止流程编号残留"条款检查 diff 中新增/修改的注释与测试名，是否残留规划/任务/审计编号（如 `T405`、`P1-1`、`RG-B01`、`Phase 66`、`候选 #14` 等形态，含中文冒号形式与 `it('C1: xxx')` 测试名），例外与清理要求以该条款为准。 - **规范无历史叙述强制审查（必查项）**：改动涉及 `docs/standards/**/*.md` / `docs/guide/**/*.md` / `docs/design/modules/**/*.md` 时，按 [文档规范 §3.5 无历史叙述原则](../../../docs/standards/documentation.md#35-无历史叙述原则-no-historical-narrative) 与 [审查清单 §4.6](./references/review-checklist.md#46-规范无历史叙述强制审查-no-historical-narrative-in-standards) 检查规范正文是否带时间锚叙述（"自 N-MM-DD 起"、"widened from X"、"as of" 等）；命中即 Reject，要求下沉到 `docs/design/governance/[YYYY-MM-DD]-*.md` 单点说明。若改动未触碰上述目录，本审查项不触发；若触碰但审计执行跳过，立即 Reject 整个 Review Gate。 - 优先寻找会阻塞放行的问题，而不是按文件顺序复述 diff。 - 重点检查是否存在遗漏 mock、异常吞掉、权限边界缺失、证据链不闭环、超出当前 Todo 范围的静默扩写。 ### 5. 判定问题分级 - `blocker`: 明显 correctness bug、安全漏洞、关键验证缺失、与 Todo / 规范冲突、会阻塞提交的问题。 - `warning`: 存在较高回归风险、测试覆盖不足、结构边界模糊或证据不完整，但不一定立刻造成故障。 - `suggest`: 非阻塞的可维护性、可读性、删除计划或后续优化建议。 ### 6. 给出 Review Gate 结论 - 只有在所有 `blocker` 关闭且最低验证矩阵满足时，才允许给 `Pass`。 - `Reject` 必须明确写出失败原因、缺失证据、待修问题和复查基线。 - 对多轮 review，必须说明“本轮新增问题”“本轮已关闭问题”“仍待复查问题”，避免每轮都重新洗牌。 ## 输出要求 ```md ## Review Gate - 结论: Pass | Reject - 改动类型: - 最低验证要求: - 审查轮次: - audit-depth: quick | standard | deep（调用方声明 + 本轮实际执行档位） - 实际用时 / 是否超时间盒:（按 [审计调用协议](../../../docs/standards/ai-collaboration.md) 回填，audit-depth 未声明时按 `deep` 计） - 失败原因或通过条件: - 复查基线: ## Findings ### blocker 1. [path/to/file.ext] 标题 - 风险 - 修复方向 ### warning ### suggest ## 验证证据 - 已执行验证: - 结果摘要: - 未覆盖边界: - 后续补跑计划: ``` ## 技能文件专项审查 当改动涉及技能 / agent 体系时，额外检查： - `description` 是否真的能触发技能，而不是抽象介绍。 - 正文是否具备铁律、工作流、确认门、反模式和交付前检查。 - `references/` 是否职责清晰，是否存在跨目录重复定义。 - 若技能刚经历模板化重构，是否通过 git diff 或提交历史保留了旧版中的项目特化规则。 - skill / agent 改动是否保持唯一事实源，并补了 `pnpm ai:check`（镜像漂移检查）。 ## 反模式 - 只写“已审查通过”而不说明依据。 - 只跑 `lint` / `typecheck` 就给所有改动 `Pass`。 - 把问题分级当成最终 Gate 结论，或者把 `warning` 写成“已通过”。 - 审查文档、脚本、配置、技能文件时不补充对应的最小验证。 - 没有复查基线，导致多轮 review 无法对账。 - 超限 diff 未核对拆分依据就放行。 - 治理定义改动重复抄写权威文档条款，而不是引用。 ## 审查前检查 - 是否已经读取相关规范与当前 Todo 验收点。 - 是否已经识别改动类型并映射到最低验证矩阵。 - 是否已经为发布前收口或 Review Gate 准备好 `scripts/release/pre-release-check.mjs` / `scripts/review-gate/generate-evidence.mjs` 的证据落点。 - 是否已经记录证据落点和本轮审查范围。 - 是否已经把阻塞项和残余风险区分清楚。