用途
codebase-review 是一套全面、实用的代码库审计方法论,适用于任意规模的项目。它并非要求每个项目执行所有检查,而是通过分级体系确保应用恰当的严格程度。该技能用于代码库审查、代码审计等任务。
主要能力
分级审查体系
每个章节及许多单项都标注了层级指示:
- Essential(第 1 层)——适用于所有项目,包括周末小项目
- Standard(第 2 层)——适用于团队项目和生产应用
- Enterprise(第 3 层)——适用于大规模、多团队或受监管系统
- Mission-Critical(第 4 层)——适用于金融、医疗、基础设施或高风险系统
按层级聚焦的检查项数量:
- 第 1 层:仅 Essential 项(约 50 项检查)
- 第 2 层:包含 Essential 与 Standard 项(约 150 项检查)
- 第 3 层:包含 Essential、Standard 与 Enterprise 项(约 400 项检查)
- 第 4 层:包含全部(约 900+ 项检查)
项目复杂度评估
对每项特征评分(0 = 否,1 = 是):
- 规模与用户:>1 名开发者、>5 名开发者、>20 名开发者、>100 用户、>10K 用户、>1M 用户
- 业务关键性:生产系统、停机造成金钱损失、停机损失 >$10K/小时、数据泄露会上新闻、合同 SLA
- 数据敏感性:用户账户、PII、财务数据、健康数据(HIPAA)、受监管数据(GDPR、SOX)
- 架构复杂度:>1 个服务、>5 个服务、存在数据库、多个数据存储、第三方集成、>5 个集成
- 运维要求:99% 正常运行时间、99.9%、99.99%、专职运维/SRE 团队、7×24 待命
评分范围与层级对应:
- 0-4:第 1 层 Essential——个人/业余项目、原型、内部工具
- 5-10:第 2 层 Standard——小团队项目、生产应用、初创公司
- 11-18:第 3 层 Enterprise——大型团队、受监管行业、企业客户
- 19+:第 4 层 Mission-Critical——金融系统、医疗、关键基础设施
最小可行审查(15 分钟快速检查)
用于快速健康评估,适用于任何项目:
安全要点(5 分钟):
- 代码中无密钥:运行 git log -p | grep -i "password|secret|api_key|token",应无返回
- 依赖不过时:检查关键漏洞(npm audit、pip-audit 等)
- 所有外部通信仅用 HTTPS
- 使用前验证输入
- 若有用户则存在认证
代码健康(5 分钟):
- 能构建:干净构建无错误
- 测试存在且通过
- 无明显重复(无复制粘贴文件或大量重复块)
- 可读:新开发者能理解主流程
运维要点(5 分钟):
- 存在 README 并包含运行说明
- 有文档化或自动化的部署流程
- 应用产生日志
- 错误被记录或发送到可见位置
- 配置外置(无硬编码环境特定值)
快速评分:___ / 15。若低于 12,先解决差距再继续。
审查类别(共 16 类)
- 架构与系统设计:架构基础、API 设计与契约、服务通信、数据架构。评估所选模式是否适合规模与团队大小。
- 密钥、凭证与敏感数据:主动密钥扫描、密钥类型清单、AI 工具配置文件、注释感知凭证扫描、密钥管理、预防性控制。此节对所有层级都关键。
- 代码重复与可复用性:重复分析、共享代码与库、抽象质量。
- 代码质量、效率与优化:基础代码质量、算法效率、数据库效率、内存与资源效率、并发与线程安全。
- 整洁代码与软件工程原则:命名与可读性、函数设计、SOLID 原则、错误处理、防御性编程。
- 代码可读性与 AI/人类可维护性:人类可读性、文档、AI 与自动化友好性。
- 测试:测试存在性、覆盖率、测试类型(单元、集成、API、E2E、性能、安全)、测试质量(验证测试确实测试行为,而非仅导入)。
- 安全:认证、授权、输入验证、数据保护、依赖安全。
- 多租户(第 3 层+):租户隔离、配置、生命周期。
- 身份与 SSO(第 3 层+):SSO 支持、会话管理。
- 可扩展性与性能(第 2 层+):水平扩展、自动扩展、响应时间、缓存、CDN。
- 可靠性(第 2 层+):容错、数据持久性、备份、灾难恢复。
- 可观测性(第 2 层+):日志、监控、告警、分布式追踪。
- 部署与运维:构建与部署文档及自动化、部署策略、配置管理。
- 许可与法律:依赖许可证、知识产权、署名。
- 开发者体验:入门文档、开发工作流、CI 速度。
附录
- 开源软件附录——许可证、社区文档、安全政策、版本管理、分发、贡献流程、项目健康、测试、文档
- 专有软件附录——商业秘密保护、供应商管理、客户数据保护
- 行业特定附录——金融服务、医疗、电子商务、政府/公共部门
使用方式
步骤
- 评估项目层级:完成项目复杂度评估以确定适用层级。
- 审查适用章节:根据层级指示聚焦对应检查项。
- 跳过不适用项:按层级选择检查范围。
预检清单
开始任何审查前完成以下检查。跳过预检曾导致真实项目中的实际浪费。
分支选择:
- 确认哪个分支代表当前工作状态——不要假设 main 是最新的
- 检查目标分支最近提交日期。若 main 数周未更新而存在领先许多提交的活跃分支,很可能在审查过时快照
- 询问团队使用 git-flow、主干开发还是其他模型。在 git-flow 中,develop 常是正确的审查目标
审查范围:
- 确认排除哪些目录(vendor/、node_modules/、generated/ 等)
- 询问是否进行过先前审查。若有,获取先前发现以启用增量审查模式
- 确认预期输出格式(markdown、PDF 等)与受众(工程团队、领导层或两者)
输出格式
关键原则:先优势后发现。所有报告先呈现优势再列发现。展示理解团队做得好的地方,使关键发现作为建设性指导而非攻击。
第 1-2 层:简化报告,包含项目、层级、日期、快速健康检查、优势、关键发现表格(编号、发现、严重性、位置、修复)、推荐行动。
第 3-4 层:完整报告,包含执行摘要与总体评分、各分类评分、主要优势、主要关键发现、详细发现(严重性/位置/证据/建议/工作量)以及分阶段行动计划(立即、短期、中期)。
增量审查模式
当存在先前审查时使用增量模式。独立审查说“这是你的问题”,增量审查说“这是你的轨迹”。后者对工程领导层更有用。对先前审查的每项发现,分类其当前状态:已修复、部分修复、仍存在、恶化、新增。
交付物组织
按日期戳文件夹组织审查交付物:
reviews/ ├── 2025-01-15/ │ ├── review-summary.md │ ├── detailed-findings.md │ └── executive-report.pdf ├── 2025-04-15/ │ ├── delta-review.md ← 与 2025-01-15 对比 │ ├── detailed-findings.md │ └── executive-report.pdf
适用场景
适用于代码库审查、代码审计等任务,覆盖从个人项目到金融、医疗、关键基础设施等高风险系统的各类项目。
限制
- 完整详细检查清单见技能目录中的 references/detailed-checklist.md,本介绍未包含该文件内容。
- 具体收费、价格、平台支持等信息暂未提供。
- 各层级检查项数量为资料中给出的近似值。