代码库评审

多阶段深度代码库评审，生成带严重程度评级的发现和修复顺序建议。与 review-pull-request（限于差异范围）或单领域审查（security-audit-codebase、review-software-architecture）不同，此技能在一次审查中跨所有质量维度覆盖整个项目或子项目。

适用场景

• 整个项目或子项目审查（非 PR 范围）
• 新代码库上手——建立现有内容的心智模型并识别需要关注的地方
• 持续开发后的定期健康检查
• 跨架构、安全性、代码质量和 UX 的发布前质量关卡
• 输出应直接用于创建 Issue 或迭代规划时

输入

• 必填：target_path — 要审查的代码库或子项目的根目录
• 可选：
  • scope — 要运行的阶段：full（默认）、security、architecture、quality、ux
  • output_format — findings（仅表格）、report（叙述性）、both（默认）
  • severity_threshold — 要包含的最低严重程度：LOW（默认）、MEDIUM、HIGH、CRITICAL

步骤

第 1 步：普查

对代码库进行清点，确定范围并识别审查目标。

1. 按语言/类型统计文件：find target_path -type f | sort by extension
2. 按语言测量总行数
3. 识别测试目录并估计测试覆盖率（有测试的文件 vs 无测试的文件）
4. 检查依赖状态：锁定文件是否存在、依赖是否过时、是否有已知漏洞
5. 记录构建系统、CI/CD 配置和文档状态
6. 将普查记录为报告的开头章节

预期结果： 真实的清单——文件数量、语言、测试存在情况、依赖健康状况。此阶段不作判断。

失败处理： 若目标路径为空或不可访问，停止并报告。若特定子目录不可访问，记录并继续处理可用内容。

第 2 步：架构审查

评估结构健康状况：耦合度、重复、数据流和关注点分离。

1. 映射模块/目录结构并识别主要架构模式
2. 检查代码重复——跨文件的重复逻辑、复制粘贴模式
3. 评估耦合度——单个功能修改需要更改多少文件
4. 评估数据流——层次之间是否有清晰边界（UI、逻辑、数据）？
5. 识别死代码、未使用的导出和孤立文件
6. 检查一致的模式——代码库是否遵循自己的约定？
7. 对每个发现评级：CRITICAL、HIGH、MEDIUM 或 LOW

预期结果： 架构发现列表，附严重程度评级和文件引用。常见发现：模式分发重复、缺少抽象层、循环依赖。

失败处理： 若代码库太小，没有意义的架构审查（< 5 个文件），记录此情况并跳至第 3 步。架构审查需要足够的代码才能有结构。

第 3 步：安全审计

识别安全漏洞和防御性编码缺口。

1. 扫描注入向量：HTML 注入（innerHTML）、SQL 注入、命令注入
2. 检查认证和授权模式（如适用）
3. 审查错误处理——错误是否被静默吞掉？错误信息是否泄露内部信息？
4. 对照已知 CVE 审计依赖版本
5. 检查硬编码的密钥、API 密钥或凭据
6. 检查 Docker/容器安全性：root 用户、暴露端口、构建密钥
7. 检查 localStorage/sessionStorage 中的敏感数据存储
8. 对每个发现评级：CRITICAL、HIGH、MEDIUM 或 LOW

预期结果： 安全发现列表，附严重程度、受影响文件和修复指导。CRITICAL 发现包含注入漏洞和暴露的密钥。

失败处理： 若不存在安全相关代码（纯文档项目），记录此情况并跳至第 4 步。

第 4 步：代码质量

评估可维护性、可读性和防御性编码。

1. 识别魔法数字和应该命名为常量的硬编码值
2. 检查整个代码库中一致的命名约定
3. 在系统边界查找缺失的输入验证
4. 评估错误处理模式——是否一致？是否提供有用的信息？
5. 检查注释掉的代码、TODO/FIXME 标记和不完整的实现
6. 审查测试质量——测试是在测试行为还是实现细节？
7. 对每个发现评级：CRITICAL、HIGH、MEDIUM 或 LOW

预期结果： 以可维护性为重点的质量发现列表。常见发现：魔法数字、不一致的模式、缺少守卫。

失败处理： 若代码库是生成的或经过压缩的，记录此情况并调整预期。生成的代码与手写代码有不同的质量标准。

第 5 步：UX 和无障碍性（若前端存在）

评估用户体验和无障碍合规性。

1. 检查交互元素上的 ARIA 角色、标签和地标
2. 验证键盘导航——所有交互元素是否都可以通过 Tab 访问？
3. 测试焦点管理——面板打开/关闭时焦点是否有逻辑地移动？
4. 检查响应式设计——在常用断点测试（320px、768px、1024px）
5. 验证颜色对比度比率是否符合 WCAG 2.1 AA 标准
6. 检查屏幕阅读器兼容性——动态内容变化是否被宣告？
7. 对每个发现评级：CRITICAL、HIGH、MEDIUM 或 LOW

预期结果： UX/无障碍发现列表，适用时附 WCAG 引用。若不存在前端，此步骤生成"不适用——未检测到前端代码"。

失败处理： 若前端代码存在但无法渲染（缺少构建步骤），静态审计源代码并记录运行时测试未进行。

第 6 步：发现综合

将所有发现汇编为优先级摘要。

1. 将所有阶段的发现合并到单个表格
2. 按严重程度排序（CRITICAL 优先，然后 HIGH、MEDIUM、LOW）
3. 在每个严重程度级别内，按主题分组（安全性、架构、质量、UX）
4. 对每个发现，包含：严重程度、阶段、文件、一行描述、建议修复
5. 生成考虑修复间依赖关系的推荐修复顺序
6. 摘要：按严重程度的发现总数、前 3 个优先级、估计工作量级别

预期结果： 发现表，列：#、Severity、Phase、File(s)、Finding、Fix。考虑依赖关系的修复顺序建议（如"在添加测试之前重构架构"）。

失败处理： 若未产生任何发现，这本身就是一个发现——要么代码库异常干净，要么审查过于浅层。以更深入的方式重新检查至少一个阶段。

验证清单

• 所有请求的阶段已完成（或明确跳过并附理由）
• 每个发现都有严重程度评级（CRITICAL/HIGH/MEDIUM/LOW）
• 每个发现至少引用一个文件或目录
• 发现表按严重程度排序
• 修复顺序建议考虑了发现间的依赖关系
• 摘要包含按严重程度的总计数
• 若 output_format 包含 report，叙述性章节伴随表格

使用休息进行扩展

在审查阶段之间，将 /rest 用作检查点——尤其是在第 2-5 阶段之间，这些阶段需要不同的分析视角。检查点休息（短暂的、过渡性的）防止一个阶段的惯性影响下一个阶段。有关检查点休息 vs 完整休息的指导，参见 rest 技能的"使用休息进行扩展"章节。

常见问题

• 煮沸海洋：逐行审查大型代码库会产生噪音。关注高影响区域：入口点、安全边界和架构接缝
• 严重程度通货膨胀：并非每个发现都是 CRITICAL。将 CRITICAL 保留给可利用的漏洞和数据丢失风险。大多数架构问题是 MEDIUM
• 只见树木不见森林：个别代码质量问题比系统性模式重要性低。若魔法数字出现在 20 个文件中，那是一个架构发现，不是 20 个质量发现
• 跳过普查：普查（第 1 步）看起来像行政工作，但它能防止审查不存在的代码或遗漏整个目录
• 阶段渗漏：在架构审查期间发现安全问题，或在安全审计期间发现质量问题。将其记录到正确的阶段而非混合关注点——这会产生更清晰的发现表

相关技能

• security-audit-codebase — 当代码库评审安全阶段发现复杂漏洞时进行深度安全审计
• review-software-architecture — 对特定子系统进行详细架构审查
• review-ux-ui — 超出第 5 阶段覆盖范围的综合 UX/无障碍审计
• review-pull-request — 针对个别变更的差异范围审查
• clean-codebase — 实施此评审识别的代码质量修复
• create-github-issues — 将发现表转换为已跟踪的 GitHub Issue