# Review Codebase

> 多阶段深度代码库评审，附严重程度评级和结构化输出。在单次协调的审查中涵盖 架构、安全性、代码质量和 UX/无障碍性。生成适合通过 create-github-issues 技能直接转换为 GitHub Issue 的优先级发现表。

- Skill: `pjt222/review-codebase-4` (Agent Skill)
- Install (CLI): `npx get-skill add pjt222/review-codebase-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/review-codebase-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/review-codebase-4

---


# 代码库评审

多阶段深度代码库评审，生成带严重程度评级的发现和修复顺序建议。与 `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

