SuperAPI AI 工具集

codebase-review

编程与开发

查看项目

更新于 10-22 16:15

技能介绍

用途

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 类)

  1. 架构与系统设计:架构基础、API 设计与契约、服务通信、数据架构。评估所选模式是否适合规模与团队大小。
  2. 密钥、凭证与敏感数据:主动密钥扫描、密钥类型清单、AI 工具配置文件、注释感知凭证扫描、密钥管理、预防性控制。此节对所有层级都关键。
  3. 代码重复与可复用性:重复分析、共享代码与库、抽象质量。
  4. 代码质量、效率与优化:基础代码质量、算法效率、数据库效率、内存与资源效率、并发与线程安全。
  5. 整洁代码与软件工程原则:命名与可读性、函数设计、SOLID 原则、错误处理、防御性编程。
  6. 代码可读性与 AI/人类可维护性:人类可读性、文档、AI 与自动化友好性。
  7. 测试:测试存在性、覆盖率、测试类型(单元、集成、API、E2E、性能、安全)、测试质量(验证测试确实测试行为,而非仅导入)。
  8. 安全:认证、授权、输入验证、数据保护、依赖安全。
  9. 多租户(第 3 层+):租户隔离、配置、生命周期。
  10. 身份与 SSO(第 3 层+):SSO 支持、会话管理。
  11. 可扩展性与性能(第 2 层+):水平扩展、自动扩展、响应时间、缓存、CDN。
  12. 可靠性(第 2 层+):容错、数据持久性、备份、灾难恢复。
  13. 可观测性(第 2 层+):日志、监控、告警、分布式追踪。
  14. 部署与运维:构建与部署文档及自动化、部署策略、配置管理。
  15. 许可与法律:依赖许可证、知识产权、署名。
  16. 开发者体验:入门文档、开发工作流、CI 速度。

附录

  • 开源软件附录——许可证、社区文档、安全政策、版本管理、分发、贡献流程、项目健康、测试、文档
  • 专有软件附录——商业秘密保护、供应商管理、客户数据保护
  • 行业特定附录——金融服务、医疗、电子商务、政府/公共部门

使用方式

步骤

  1. 评估项目层级:完成项目复杂度评估以确定适用层级。
  2. 审查适用章节:根据层级指示聚焦对应检查项。
  3. 跳过不适用项:按层级选择检查范围。

预检清单

开始任何审查前完成以下检查。跳过预检曾导致真实项目中的实际浪费。

分支选择:

  • 确认哪个分支代表当前工作状态——不要假设 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,本介绍未包含该文件内容。
  • 具体收费、价格、平台支持等信息暂未提供。
  • 各层级检查项数量为资料中给出的近似值。