Brooks-Lint 完全指南：用 12 本经典工程书籍的智慧为 AI 代码做架构审查
AI 编程工具每分钟生成上千行代码，但代码越多，架构退化越快。传统 Linter 能抓到命名规范和空指针，却对「一个函数塞了四种业务逻辑」「循环依赖正在悄悄蔓延」「领域模型逐渐失真」这类问题完全无能为力——而正是这些问题，在几个月后会把一个项目拖入不可维护的深渊。
Brooks-Lint 是一个开源的 Agent Skill，它将《人月神话》《代码大全》《重构》《Clean Architecture》等 12 本经典工程书籍的核心洞见，编码为一套可重复的六维衰减风险诊断框架。你只需在编辑器里敲一条斜杠命令，就能获得一份带书籍引用、严重度标签和具体修复建议的架构审查报告。
核心理念：六维衰减风险
Brooks-Lint 将代码质量退化的根源归纳为六个维度，每个维度对应一本或多本经典著作的洞见：
| 衰减风险 | 诊断问题 | 来源书籍 |
|---|---|---|
| 🧠 认知过载 | 要花多少脑力才能理解这段代码？ | Code Complete, Refactoring, DDD |
| 🔗 变更传播 | 改一处代码，多少无关模块会受影响？ | Refactoring, Clean Architecture |
| 📋 知识重复 | 相同决策是否散落在多个地方？ | Pragmatic Programmer, DDD |
| 🌀 意外复杂度 | 代码真的需要这么复杂？ | Brooks, Philosophy of SD |
| 🏗️ 依赖混乱 | 依赖方向是否一致且清晰？ | Clean Architecture, SE@Google |
| 🗺️ 领域模型失真 | 代码忠实反映了业务领域吗？ | DDD, Refactoring |
其中「意外复杂度」直接源于 Brooks 在《人月神话》中的论断：软件的本质复杂度是固有的，但大量代码中有的是我们凭空制造出来的额外复杂度。
六大模式（Slash Commands）
Brooks-Lint 提供六个独立技能，覆盖从 PR 审查到全量扫描的完整工作流：
| 命令 | 模式 | 用途 |
|---|---|---|
/brooks-review | PR 审查 | 对变更代码做六维风险诊断 |
/brooks-audit | 架构审计 | 生成模块依赖图和隐患定位 |
/brooks-debt | 技术债务评估 | 按 Pain × Spread 优先级排序 |
/brooks-test | 测试质量审查 | 评估测试套件的六维退化风险 |
/brooks-health | 健康仪表盘 | 全维度加权综合评分 |
/brooks-sweep | 全量扫描+自动修复 | 一键运行全部检查并应用安全修复 |
报告格式：Symptom → Source → Consequence → Remedy
每条发现都遵循标准诊断链格式，而不是模糊的「代码需要改进」：
🔴 变更传播 — 单个方法因四个不相关的业务原因而变化 Symptom: update_profile 同时处理字段更新、邮件通知和积分重算 Source: Fowler — Refactoring — Divergent Change Consequence: 改积分公式可能破坏邮件通知 Remedy: 提取 NotificationService、LoyaltyService
Health Score 评分：每个审查输出一个 0-100 的健康分数。在 Benchmark 测试中，Brooks-Lint 的结构化报告通过率（94%）远超裸 Claude（16%）——不是 Claude 找不到问题，而是它无法一致地给出带可追溯证据和具体修复方案的结构化发现。
安装与使用
Brooks-Lint 以 Agent Skill 形式分发，支持 11 个主流 AI 编程平台。推荐在 Claude Code 中使用插件市场安装：
/plugin marketplace add hyhmrright/brooks-lint /plugin install brooks-lint@brooks-lint-marketplace curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- opencode
安装完成后，在 PR 审查中直接使用：
/brooks-review
将 PR diff 粘贴或指明变更文件即可。如果需要针对某个模块深入分析架构：
/brooks-audit
Brooks-Lint 会生成一个 Mermaid 依赖图，用红/黄/绿三色标注模块的健康状态——循环依赖显示为红色虚线，直接嵌入报告顶部。
配置与定制
在项目根目录创建 .brooks-lint.yaml 即可定制审查行为：
version: 1 disable: - T5 # 跳过覆盖率检查 severity: R1: suggestion # 将认知过载降级为建议 ignore: - "**/*.generated.*" - "**/vendor/**"
所有配置项可选。完全省略配置文件就使用默认行为——六维风险全量启用。
CI/CD 集成
Brooks-Lint 提供官方 GitHub Action，可自动在每个 PR 上运行审查：
name: Brooks-Lint PR Review
on:
pull_request:
types: [opened, synchronize]
jobs:
brooks-lint:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: hyhmrright/brooks-lint/.github/actions/brooks-lint@main
with:
mode: review
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
fail-below: 70
Action 会自动将审查结果以 PR Comment 形式发布，并支持趋势追踪（brooks-lint-history.json）。每次运行的成本约 $0.05-0.15，建议只在 pull_request 事件上触发。
与同类工具的对比
| Brooks-Lint | ESLint/Pylint | GitHub Copilot Review | |
|---|---|---|---|
| 语法/风格检测 | — | ✅ | ✅ |
| 结构化诊断链 | ✅ | ❌ | ❌ |
| 引用经典书籍 | ✅ | ❌ | ❌ |
| 严重度标签 | ✅ | ✅ | ❌ |
| 架构级洞察 | ✅ | ❌ | ~ |
| 领域模型分析 | ✅ | ❌ | ❌ |
| 支持任意语言 | ✅ | ❌ | ✅ |
Brooks-Lint 不替代你的 Linter——它捕捉的是 Linter 抓不到的东西：架构漂移、知识孤岛和领域模型失真，这些才是让团队在数月后才惊觉项目已不可维护的根源。
总结
在 AI 每分钟生成上千行代码的时代，代码量不再是瓶颈，代码质量才是。Brooks-Lint 将 12 本跨越 50 年的经典工程书籍提炼为可重复的六维诊断框架，让你的 AI 编程工具不仅会写代码，还能客观地评价自己的代码——就像有一位读过所有经典著作的资深架构师坐在旁边，每次提交都帮你做一次免费的架构审查。
项目地址: github.com/hyhmrright/brooks-lint 许可: MIT