brooks-lint —— 植根经典工程著作的 AI 代码审查框架

图1：brooks-lint 项目概览

场景切入：你的代码库正在悄悄腐烂

想象一下：团队迭代半年后，新增一个字段要改七八个文件；代码审查时大家凭经验说「这段看起来不太对」，但说不出具体依据；技术债越积越多，没人知道从哪下手。这不是某个人的问题——这是所有快速迭代团队都会面临的软件熵增。

brooks-lint 正是为解决这个问题而来。它不是一个普通的代码风格检查工具，而是将 AI 的理解能力与十二本经过时间验证的软件工程经典著作结合，对代码进行有据可查的质量诊断。

项目起源与背景

brooks-lint 由开发者 hyhmrright 创建，GitHub 主页为 https://github.com/hyhmrright/brooks-lint，当前版本 1.3.0。核心理念：大多数代码质量工具只数行数和圈复杂度，而软件工程领域已经有五十年的积累——《人月神话》《重构》《代码大全》《架构整洁之道》等经典著作早已总结出代码腐化的系统性规律。将这些规律结构化地灌输给 AI，让每一次审查都产出一致、可溯源、可落地的诊断，是 brooks-lint 的核心价值。

技术架构

brooks-lint 的技术栈极为轻量：开发语言为 JavaScript/TypeScript（Node.js ESM 模块），内置 @anthropic-ai/sdk 依赖用于调用 Claude API。

项目采用标准化 Agent Skill 架构，以 Markdown 文件定义技能（skills/ 目录），包含六种分析模式（review / sweep / health / audit / debt / test），每种模式对应独立子目录，内含 SKILL.md + pr-review-guide.md 等子文档，通过统一的 commands/ 命令入口分发至 Claude Code、Codex CLI、Gemini CLI、OpenCode 等主流 AI Coding Agent。

核心亮点是建立了完整的书目—风险映射表，涵盖 Frederick Brooks 的《人月神话》、Martin Fowler 的《重构》、Steve McConnell 的《代码大全》、Robert C. Martin 的《架构整洁之道》、Hunt & Thomas 的《程序员修炼之道》、Eric Evans 的《领域驱动设计》、John Ousterhout 的《软件设计的哲学》等十二本经典。R1R6 六类代码衰退风险和 T1T6 六类测试衰退风险均可溯源至具体书目章节。

架构审查模式（brooks-audit）可自动生成 Mermaid 格式的模块依赖图，按严重度着色（红=Critical，黄=Warning，绿=干净），在 GitHub、Notion 等 Markdown 环境中原生渲染，无需额外工具。

安装方式极为简洁：通过 ./scripts/install.sh 脚本一键安装，支持 Claude Code / Gemini CLI / Codex CLI / OpenCode / Cursor / Windsurf 等所有支持 Agent Skills 标准的 AI Coding Agent，一条 curl 命令即可完成全局安装。

核心功能详解

brooks-lint 提供六种分析模式：

• brooks-review：PR 代码审查，触发时机灵活，覆盖 R1R6 + T1T6 全部衰退风险维度，产出 Symptom → Source → Consequence → Remedy 结构化诊断链。
• brooks-sweep：一键全量扫描 + 自动修复安全发现 + 确认风险发现的复合模式，适合定期健康检查。
• brooks-health：代码库健康仪表盘，从四个维度评估整体状况，输出 0~100 健康分。
• brooks-audit：架构审查，生成 Mermaid 依赖图，识别循环依赖、正交性违反、Shotgun Surgery 等架构层面问题。
• brooks-debt：技术债量化评估，标注债务来源和优先级。
• brooks-test：测试质量审查，评估测试覆盖率、可维护性、隔离性。

六类代码衰退风险包括：

R1 认知过载：函数过长、嵌套过深、魔法数字、含义模糊的变量名导致理解成本过高，对应《代码大全》《重构》《DDD》《软件设计的哲学》。 R2 变更扩散：一处修改牵连多个无关模块，Shotgun Surgery、Divergent Change，对应《重构》《架构整洁之道》《人月神话》。 R3 知识重复：同一业务决策在多处重复编码，违反《程序员修炼之道》正交性原则。 R4 偶发复杂度：解决方案比问题本身更复杂，对应《重构》《代码大全》重点关注领域。 R5 依赖失序：依赖方向不符合分层架构，DIP 违反，循环依赖，对应《架构整洁之道》《人月神话》。 R6 领域模型失真：代码命名与业务语言不一致，Primitive Obsession，对应《DDD》《重构》。

智能辅助功能方面：通过 .brooks-lint.yaml 可按风险代码选择性禁用、按文件 glob 忽略、按风险代码调整严重度；Suppress 机制允许对特定文件的风险打 suppress 标签并附过期时间；支持自定义衰退风险（C1、C2...）；历史追踪生成 .brooks-lint-history.json 用于趋势分析；零配置启动。

上手门槛

安装要求极低：只需 Node.js >= 18（仅用于内置 validate/test 脚本）和一个 AI Coding Agent 环境（Claude Code / Codex CLI / Gemini CLI 等），通过 ./scripts/install.sh 一键安装，耗时不到 1 分钟。没有 Web UI，完全通过命令行交互。

对于没有 AI Coding Agent 环境的团队，需要先安装 Claude Code 或 Codex CLI 等工具，这是主要的使用门槛。

多平台覆盖是项目一大亮点：以标准 Agent Skills 格式分发，兼容所有支持 Skills 协议的 AI Agent，包括 Claude Code、Codex CLI、Gemini CLI、OpenCode、Cursor、Windsurf、Copilot、Kiro、Factory Droid、Antigravity 等，一个技能库覆盖十余个主流平台。

局限与争议

1. 依赖 AI 模型能力：brooks-lint 本质上是提示工程框架，运行效果高度依赖底层 AI 模型（Claude）的理解和推理能力。不同模型版本、不同复杂度的代码可能导致分析结果不稳定。

2. 不检测语法/风格：项目明确表示不替代 ESLint/Pylint 等传统 linter，专注于架构层面的深层问题。两者互补，不是替代关系。

3. 诊断一致性：内置基准测试（evals/ 目录）显示，在结构化诊断链和严重度标签上，brooks-lint 对比原生 Claude 的通过率从 16% 提升至 94%，但仍有约 6% 的失败率——特别是在边界情况的严重度判断上。

4. 无本地模型支持：目前依赖 Anthropic Claude API，需要互联网连接和 API 配额，不支持离线环境或本地模型部署。

5. 配置复杂度：对于大型多语言项目，六类衰退风险 + 十二本书的配置组合可能较为复杂，需要一定的学习成本。

行业意义

brooks-lint 的出现代表了 AI Code Review 从规则匹配向知识图谱推理的演进。传统 ESLint/Pylint 只能检测可枚举的规则违反，而 brooks-lint 将软件工程的系统性知识——那些需要多年经验才能积累的设计原则——结构化地编码为 AI 可调用的分析框架。这使得初级工程师也能获得高级架构师的视角。

从趋势上看，随着 Claude Code、Codex CLI 等 AI Coding Agent 越来越普及，将专业工程知识封装为可分发的技能包将成为新范式。brooks-lint 1.3.0 已支持十余个 Agent 平台，GitHub Stars 突破 1082，说明社区对有理论依据的 AI 审查有真实需求。

长期来看，这类工具的价值在于：将隐性知识（架构直觉、设计品味）显性化、知识化，让 AI 审查不再是模糊的「感觉不太对」，而是可追溯到经典著作具体章节的结构化诊断。这是 AI 辅助软件工程走向成熟的重要一步。