231 lines
21 KiB
Markdown
231 lines
21 KiB
Markdown
审查项目代码质量，基于仓库规则、实际代码、测试、配置、依赖和文档证据，识别架构、实现、复用、测试覆盖、三方库使用和工程质量风险。默认只输出审查结论和建议，不修改任何文件；只有当用户明确要求制定修复计划或执行修复时，才进入计划和执行阶段。
|
||
|
||
## 约束
|
||
|
||
- 先审查再修复；未经用户确认，不修改代码、测试、配置、依赖或文档
|
||
- 不得虚构已执行的命令、已读取的文件、subagent 结论、测试结果或用户确认；所有结论必须能追溯到实际读取内容、命令输出，或明确标记为假设、观察建议或信息不足
|
||
- 优先遵守仓库已定义的开发规范、质量门禁、架构边界、包管理器规则、测试规则和文档同步规则
|
||
- 不进行全仓库无差别逐文件精读；先建立目录、依赖、脚本、测试和变更范围索引，再定向读取高风险、高复杂度、核心链路和近期改动相关文件
|
||
- 不以代码现状作为唯一真相；代码必须同时对照 README、开发文档、配置、测试、脚本、实际运行入口、近期提交和用户确认过的约束
|
||
- 不因发现问题就自动新增依赖、重写架构、迁移技术栈或扩大功能范围；此类动作必须单独列为候选方案并获得用户确认
|
||
- 质量审查默认不创建提交、不推送、不变更分支、不执行 destructive git 操作
|
||
- 每批修复执行前必须获得用户明确确认；若环境提供提问工具，优先使用提问工具，否则以普通对话确认
|
||
- 删除、重写、批量迁移、大范围格式化、依赖变更、数据库/配置 schema 变更、构建产物变更前必须单独确认；若环境提供提问工具，优先使用提问工具，否则以普通对话确认；若存在 git 仓库，不创建 `.bak` 备份文件，改用当前 `git status` / `git diff` 作为回退依据；仅在无版本控制或用户明确要求时，才将备份放到代码目录外的用户确认路径
|
||
- 若修复影响用户可见行为、配置、部署、运行行为、架构边界、开发流程、测试方式或构建发布流程，必须同步更新对应文档
|
||
- 若环境限制导致验证命令无法执行，记录未执行项、原因和残留风险，不得声称已验证
|
||
- 审查阶段不得运行会格式化、修复、生成、迁移、安装、删除、写入受版本控制路径或修改工作区的命令；如不确定命令是否只读，先询问用户
|
||
- 若环境支持 subagent，可仅用于收集和只读分析；若不支持 subagent，由主 agent 按相同分工顺序串行执行最小必要分析；任何 subagent 都不得修改代码、测试、配置、依赖或文档，不得提交、推送、切换分支、安装依赖或执行 destructive git 操作；所有修复必须由主 agent 在用户确认后执行
|
||
|
||
## 1. 收集
|
||
|
||
读取约束：
|
||
|
||
- 优先使用当前会话信息、仓库文档、配置文件、脚本、测试和版本控制状态
|
||
- 可并行读取互不依赖的文件、命令结果和 subagent 只读分析结果；并行前先划分范围，避免重复读取、结论冲突和上下文膨胀；不支持并行时按同样范围串行执行
|
||
- 不原样输出大段文件内容，仅在审查报告和收尾中输出必要结论
|
||
|
||
并行或分工分析策略：
|
||
|
||
- 当审查范围较大、文件类型明显分层、多个分析维度互不依赖，或需要同时核对代码、测试、配置、文档和依赖证据时，优先使用可用的并行能力或 subagent 只读分析
|
||
- 范围较小、问题集中、需要连续推理、需要用户确认、需要修改文件或存在高风险命令时，不使用 subagent，避免额外协调成本；若环境不支持 subagent，则由主 agent 串行执行并说明未使用原因
|
||
- 适合拆分为架构边界、正确性/安全、前端专项、后端专项、测试验证、依赖与包管理、脚本/构建、文档闭环等子任务
|
||
- 先由主 agent 建立共享基线，包括仓库规则、用户指定范围、目录结构、脚本、质量门禁、git 状态和候选高风险区域
|
||
- 每个 subagent 只接收最小必要上下文，明确任务目标、允许读取范围、禁止操作、输出格式和必须引用的证据类型
|
||
- 每个文件或目录默认只分配给一个主责 subagent；确需交叉复核时，明确一个为主责、一个只做抽样或专项核验
|
||
- subagent 不重复读取共享基线文件，除非需要核对具体证据；共享基线由主 agent 统一读取并摘要分发
|
||
- subagent 不输出大段源码，只输出文件路径、行号、问题摘要、证据、影响、建议、风险等级、建议验证方式和不确定项
|
||
- 无 subagent 环境的降级方式：主 agent 先建立共享基线，再按架构边界、正确性/安全、前端、后端、测试验证、依赖与包管理、脚本/构建、文档闭环的顺序串行抽查；每轮只读取当前问题所需的最小文件集合，避免一次性展开全仓库
|
||
|
||
分步收集：
|
||
|
||
a) 先读取项目规则和入口，确定审查范围：
|
||
|
||
- 先读取最小必要规则入口：根 README、文档路由或仓库说明中明确指向的开发规范；只有发现审查对象涉及对应领域时，再读取架构、前端、后端、发布等专题文档
|
||
- 包管理和脚本配置，例如 `package.json`、锁文件、构建配置、测试配置、lint/format/typecheck 配置
|
||
- OpenSpec 或仓库级工程规则，例如存在时读取 `openspec/config.yaml`
|
||
- 若用户指定了审查范围、模块、分支、PR、change 或文件列表，以用户指定范围为主；否则默认采用标准审查：读取仓库规则、目标范围入口、相关测试和配置，并抽查核心链路，不声称覆盖全仓库
|
||
- 若审查对象是 PR、分支、change 或近期改动，先确定审查基线：base 分支、head 提交、变更文件、变更类型和受影响入口；发现问题时区分“本次引入问题”和“既有问题被触发/暴露”
|
||
|
||
b) 建立项目索引，先确认而不是假设：
|
||
|
||
- 目录结构、主要入口、前后端边界、共享类型、脚本目录、测试目录和文档目录
|
||
- 运行脚本、质量门禁脚本、构建脚本、测试脚本和生成脚本
|
||
- 依赖清单、直接依赖用途、devDependencies 用途、成熟工具库能力、统一 UI 框架及项目已有组件封装、锁文件状态和是否存在多包管理器痕迹
|
||
- 版本控制状态、当前工作区改动、近期提交或用户指定 diff 范围
|
||
|
||
c) 定向读取代码和测试：
|
||
|
||
- 核心业务链路、应用入口、路由/API、状态管理、数据访问、配置加载、错误处理、日志、权限/安全边界、构建集成点
|
||
- 近期改动文件、复杂度明显偏高文件、重复实现、跨层 import、公共工具、共享类型、测试薄弱或失败相关文件
|
||
- 与用户指定问题、模块、PR、change 或质量目标直接相关的代码、测试和文档
|
||
|
||
d) 收集验证证据：
|
||
|
||
- 先识别已定义的 typecheck、lint、format check、test、build、schema check、verify 等质量命令；只在命令明确只读、不会安装依赖、不会写入数据库/远端资源/受版本控制路径且预计成本可接受时执行；可能修改文件、生成产物、访问外部服务、耗时较长或副作用不明的命令，必须先说明影响并获得用户确认
|
||
- 当前已执行过的验证结果、失败日志、跳过原因和未验证范围
|
||
- 测试目录结构、测试覆盖的关键行为、边界条件、异常路径和回归场景
|
||
|
||
e) 若无法确定范围或规则：
|
||
|
||
- 先确认审查对象、审查深度和是否允许执行验证命令；若环境提供提问工具，优先使用提问工具，否则以普通对话确认
|
||
- 若仍无法确认，降级为“仓库规则 + 代码静态审查 + 可定位测试审查”，并明确不做未读取范围的结论
|
||
|
||
## 2. 分析
|
||
|
||
按以下维度检查；维度编号只表示检查顺序，不代表问题严重度，每个发现必须单独按“阻断/高/中/低”评级：
|
||
|
||
| 检查顺序 | 维度 | 检查点 |
|
||
| -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| D0 | 正确性与安全风险 | 是否存在会导致数据丢失、权限绕过、注入、敏感信息泄露、错误配置、不可恢复失败、生产不可用、构建失败或测试误判的问题 |
|
||
| D1 | 架构与边界 | 模块职责是否清晰；前后端、共享类型、脚本、测试和文档边界是否被破坏；是否出现循环依赖、跨层调用、隐式全局状态、启动链路不一致或设计与文档冲突 |
|
||
| D2 | 实现质量 | 命名、类型、错误处理、并发/异步、资源释放、数据校验、状态流转、边界条件、异常路径、可读性、复杂度、可维护性是否达标 |
|
||
| D3 | 代码复用 | 是否重复实现已有 helper、组件、schema、类型、测试工具或三方库能力；是否已引入成熟工具库却自行实现等价能力；公共抽象是否过早、过泛、泄漏业务语义或反而增加耦合 |
|
||
| D4 | 测试覆盖与验证 | 关键路径、边界条件、失败路径、回归场景、配置/schema、前端交互、后端 API、脚本和构建是否有有效测试或可执行验证；测试是否真实断言行为而不是只覆盖实现细节 |
|
||
| D5 | 三方库与依赖 | 依赖是否必要、用途清晰、导入方式正确、运行时兼容、体积和安全风险可接受；是否存在已引入但未优先使用的成熟库、重复依赖、未使用依赖、错误包管理器痕迹或可用内建能力替代的新增依赖 |
|
||
| D6 | 性能与资源 | 是否存在明显 N+1、重复计算、阻塞主线程、无界缓存、内存泄漏、未关闭资源、过大 bundle、无效重渲染、低效 IO 或可避免的启动成本 |
|
||
| D7 | 前端质量 | 组件边界、数据流、表单/交互状态、可访问性、响应式、样式体系、设计系统和 UI 框架官方实践使用、错误/加载/空状态和用户可见文案是否符合项目规范 |
|
||
| D8 | 后端质量 | API 契约、输入输出校验、错误响应、日志、配置加载、数据库访问、迁移、事务、并发控制、外部服务调用和测试隔离是否符合项目规范 |
|
||
| D9 | 工程与文档闭环 | lint/format/typecheck/build/test/schema 等质量门禁是否可运行；脚本与文档是否一致；用户可见行为、配置、开发流程或架构变化是否已同步文档 |
|
||
|
||
风险分级：
|
||
|
||
| 等级 | 判定规则 | 处理要求 |
|
||
| ---- | --------------------------------------------------------------------------------- | ---------------------------------- |
|
||
| 阻断 | 会导致错误结果、数据损坏、安全漏洞、构建/启动失败、核心测试失败或已确认需求不可用 | 必须优先修复或获得用户明确接受风险 |
|
||
| 高 | 影响核心维护性、架构边界、测试可信度、依赖安全、关键异常路径或主要用户场景 | 应纳入近期修复计划 |
|
||
| 中 | 局部重复、复杂度偏高、命名/类型/边界不清、测试覆盖不足但未直接阻断 | 可批量修复或进入后续优化计划 |
|
||
| 低 | 风格、表达、轻微文档不同步、局部可读性问题 | 可顺手修复或记录为建议 |
|
||
|
||
分析时区分以下情况：
|
||
|
||
- 明确缺陷：当前实现与需求、文档、测试或运行结果冲突
|
||
- 质量风险：当前未必出错，但复杂度、边界、测试或依赖使用会提高维护成本
|
||
- 合理取舍：实现与理想状态不同，但符合仓库约束、上下文决策或当前阶段目标
|
||
- 信息不足：缺少运行结果、业务规则、覆盖数据或用户决策，无法给出确定结论
|
||
- 观察建议：缺少明确规则或可复现影响，只能说明潜在收益、成本和适用前提，不得列为缺陷
|
||
|
||
证据与误报控制：
|
||
|
||
- 每个问题必须包含具体位置、触发条件、实际影响、证据来源、为什么现有实现不满足项目规则或需求，以及建议验证方式
|
||
- 无法定位到具体代码、配置、文档、测试或命令证据的问题，只能列为“观察建议”或“信息不足”
|
||
- 不得把个人偏好、未被项目规范要求的最佳实践、未证实的性能猜测直接列为缺陷
|
||
- 每个问题标记置信度：高表示有代码、测试或命令证据；中表示有代码证据但缺少运行验证；低表示依赖业务假设或上下文不足；低置信度问题不得列为阻断
|
||
- 对 diff、PR 或 change 审查，区分本次变更直接引入、本次变更扩大影响、既有问题但与本次风险相关、完全无关既有问题；无关既有问题只在附录中列出
|
||
|
||
重点识别：
|
||
|
||
- 架构边界被破坏、模块职责错位、入口链路和文档描述不一致
|
||
- 同一行为在多个位置重复实现，或公共抽象没有明确复用收益
|
||
- 依赖中已引入成熟工具库，例如 `es-toolkit` 等，但实现时没有优先复用其稳定能力，而是自行实现等价工具函数、集合处理、对象处理、比较、节流防抖、深拷贝或类型判断等逻辑
|
||
- 代码过度复杂、隐式副作用多、错误处理缺失、边界条件未处理
|
||
- 类型定义与运行时校验脱节，配置 schema、共享类型、API 契约和测试不一致
|
||
- 测试只验证 happy path、测试断言过弱、mock 掩盖真实问题、缺少回归验证
|
||
- 三方库用途不明确、引入成本大于收益、替代已有能力、存在包管理器或运行时兼容风险
|
||
- 前端使用统一 UI 框架或设计系统时，没有优先使用官方组件、props、组合模式、表单校验、主题 token、样式扩展点和官方推荐实践
|
||
- 前端通过覆盖内部 class、硬编码样式、`!important`、DOM 结构假设、额外 wrapper hack 或自造组件方式实现 UI 框架已提供的能力，导致行为、可访问性、响应式、主题一致性或维护性下降
|
||
- 前端绕过设计系统、样式规则、可访问性或响应式要求
|
||
- 后端缺少输入校验、错误响应、日志上下文、事务边界、资源释放或测试隔离
|
||
- 质量门禁命令缺失、失败、未纳入文档，或文档中的命令与实际脚本不一致
|
||
- 用户可见行为、配置、部署、架构或开发流程变化未同步文档
|
||
|
||
主 agent 汇总 subagent 结果时遵循：
|
||
|
||
- 主 agent 对最终结论负责，不直接转述 subagent 结论；必须去重、校准风险等级、合并同根因问题，并剔除缺少证据或超出范围的判断
|
||
- 对不同 subagent 的冲突结论，优先采用有明确文件路径、行号、测试结果、配置或文档依据的一方；仍无法判断时标记为“信息不足”或列入“待确认清单”
|
||
- 对阻断和高风险问题，主 agent 必须亲自复核关键证据，必要时重新读取最小相关文件或命令结果
|
||
- 对重复问题，按根因合并为一项，在影响范围中列出涉及文件，不按文件机械重复输出
|
||
- 对跨层问题，主 agent 统一判断责任边界，避免前端、后端、测试或文档 subagent 各自给出互相矛盾的修复方向
|
||
- 对 subagent 提出的修改建议，主 agent 只纳入改进计划，不直接执行；执行仍必须经过用户确认
|
||
- 最终“审查范围与证据”中列出 subagent 分工、覆盖范围、未覆盖范围和主 agent 复核过的关键证据
|
||
|
||
输出审查结果：
|
||
|
||
1. **审查范围与证据**：已读取的规则、代码区域、测试、配置、依赖、命令结果、未覆盖范围和未执行验证
|
||
2. **关键结论**：按“阻断/高/中/低”汇总问题数量；若无明确问题，说明“在本次审查范围和证据内未发现问题”
|
||
3. **问题清单**：每个问题只在一个主分类完整展开，包含位置、等级、置信度、证据、影响、建议和建议验证方式；其他分类只引用问题 ID 或汇总计数，避免重复描述和等级漂移
|
||
4. **待确认事项**：需要用户判断目标、取舍、范围或授权的问题
|
||
5. **可选改进**：无明确缺陷但有潜在收益的观察建议，说明适用前提和成本
|
||
6. **后续计划**：仅当用户要求修复计划时输出；否则不主动展开执行批次
|
||
|
||
无问题的分类可合并为“未发现明确问题的维度”，不要为了满足模板输出大量空清单或重复清单。
|
||
|
||
若在已覆盖范围内未发现问题，输出“在本次审查范围和证据内未发现问题”，并明确列出未覆盖范围、未执行验证和残留风险；不得声称全仓库审查通过。
|
||
|
||
## 3. 计划（用户确认）
|
||
|
||
若用户只要求审查，到步骤 5 收尾，不主动请求执行修复。只有用户明确要求继续处理、制定修复计划或执行修复时，才进入本节。
|
||
|
||
先针对“待确认清单”逐项向用户确认；若环境提供提问工具，优先使用提问工具，否则以普通对话确认。
|
||
|
||
再整理改进计划，按批次列出：
|
||
|
||
- 批次目标：阻断修复、高风险修复、测试补强、依赖清理、架构边界整理、文档同步、低风险清理
|
||
- 拟修改文件或对象
|
||
- 动作类型：修复、补测试、重构、拆分、合并、删除、迁移、依赖调整、文档同步、脚本修正
|
||
- 修改原因和证据
|
||
- 预期影响
|
||
- 风险与回退方式
|
||
- 验证命令或人工检查方式
|
||
|
||
计划规则：
|
||
|
||
- 优先处理阻断和高风险问题
|
||
- 将纯格式化、命名清理和大范围重构与功能性修复分开
|
||
- 将依赖变更、架构迁移、数据库/配置 schema 变更、删除和重写拆成单独批次
|
||
- 对信息不足的问题，先补验证或补调研，不直接修复
|
||
- 对存在多种方案的问题，列出方案差异和适用前提，由用户确认
|
||
|
||
展示完整改进计划并等待用户确认；若环境提供提问工具，优先使用提问工具，否则以普通对话确认。确认计划不等于授权执行所有批次；每批执行仍需单独确认，高风险动作仍需按约束单独确认。
|
||
|
||
## 4. 执行
|
||
|
||
逐批执行已确认的修复。
|
||
|
||
执行规则：
|
||
|
||
- 每批只处理该批明确授权的问题，不顺手扩大范围
|
||
- 优先做最小正确修改，不引入不必要的新抽象、新依赖或兼容层
|
||
- 修复代码时同步补充或调整对应测试
|
||
- 修复测试时确保测试断言真实行为，不通过降低断言、跳过测试或扩大 mock 来制造通过
|
||
- 修复依赖问题时同步检查锁文件、导入位置、构建影响和文档影响
|
||
- 修复文档或脚本时同步检查相关索引、命令和质量门禁描述
|
||
- 修复后验证同样遵守只读优先；有副作用、耗时高、依赖外部服务或会修改工作区的命令需先确认，无法执行则记录原因和风险
|
||
|
||
若涉及删除或重写：
|
||
|
||
- 存在 git 仓库时，先记录当前 `git status` / `git diff`，识别并保护既有未提交改动，不要在源码、测试、配置或文档目录创建 `.bak` 文件
|
||
- 回退方案必须说明如何仅回退本批修改；不得执行 `reset`、`checkout`、`clean` 等 destructive git 操作，除非用户单独确认
|
||
- 不存在版本控制，或用户明确要求备份时，先确认代码目录外的备份路径；若环境提供提问工具，优先使用提问工具，否则以普通对话确认
|
||
- 修改后确认回退依据；若实际创建了备份，再列出备份文件清单和恢复方式
|
||
|
||
执行后重新读取所有被修改的代码、测试、配置、依赖和文档，并复核：
|
||
|
||
- 原问题是否已解决，是否产生新的架构边界、复用、测试或依赖问题
|
||
- 新增或修改的测试是否覆盖原风险点和关键回归路径
|
||
- 质量门禁命令是否按影响范围执行并记录结果
|
||
- 文档影响分析是否完成，必要文档是否同步
|
||
- 未处理问题是否有明确保留原因、风险等级和后续建议
|
||
|
||
## 5. 收尾
|
||
|
||
列出最终结果。
|
||
|
||
若只执行审查，收尾列出：
|
||
|
||
- 审查范围与证据
|
||
- 发现问题和风险等级
|
||
- 未覆盖范围、未执行验证和原因
|
||
- 残留风险和建议下一步
|
||
|
||
若用户授权并执行了修复，收尾列出：
|
||
|
||
- 修改文件清单
|
||
- 回退依据；若实际创建了备份，再列出备份文件清单
|
||
- 已修复问题清单
|
||
- 未处理问题、保留原因和风险等级
|
||
- 执行的验证命令、结果和未执行原因
|
||
- 文档同步摘要；若无需更新文档，说明原因
|
||
- 残留风险和建议后续批次
|
||
|
||
若本次因范围不明、验证无法执行、上下文不足或用户未授权而降级执行，单独说明降级范围和不可下结论的内容。最终只能说“在本次范围内已处理/已验证”，不得泛称“审查通过”“全部修复完成”或“全量质量通过”。
|