Agent-almanac review-codebase

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/review-codebase" ~/.claude/skills/pjt222-agent-almanac-review-codebase-b1429e && rm -rf "$T"

manifest: i18n/zh-CN/skills/review-codebase/SKILL.md

source content

代码库评审

多阶段深度代码库评审，生成带严重程度评级的发现和修复顺序建议。与

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 步：普查

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

按语言/类型统计文件：

find target_path -type f | sort by extension

按语言测量总行数
识别测试目录并估计测试覆盖率（有测试的文件 vs 无测试的文件）
检查依赖状态：锁定文件是否存在、依赖是否过时、是否有已知漏洞
记录构建系统、CI/CD 配置和文档状态
将普查记录为报告的开头章节

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

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

第 2 步：架构审查

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

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

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

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

第 3 步：安全审计

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

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

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

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

第 4 步：代码质量

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

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

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

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

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

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

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

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

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

第 6 步：发现综合

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

将所有阶段的发现合并到单个表格
按严重程度排序（CRITICAL 优先，然后 HIGH、MEDIUM、LOW）
在每个严重程度级别内，按主题分组（安全性、架构、质量、UX）
对每个发现，包含：严重程度、阶段、文件、一行描述、建议修复
生成考虑修复间依赖关系的推荐修复顺序
摘要：按严重程度的发现总数、前 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 步）看起来像行政工作，但它能防止审查不存在的代码或遗漏整个目录
阶段渗漏：在架构审查期间发现安全问题，或在安全审计期间发现质量问题。将其记录到正确的阶段而非混合关注点——这会产生更清晰的发现表