Brooks-Lint：用 12 本经典工程书做有权威背书的 AI 代码审查

AI 编码工具每天都在帮我们写更多代码，速度越来越快，但一个隐忧正在浮现：架构正在”悄悄腐化”。Linter 能检查语法和风格合规，却看不出领域模型扭曲（Domain Model Distortion）、知识重复（Knowledge Duplication）、变更传播（Change Propagation）这类架构层面的”软性”问题——这些问题通常不会被 CI 阻断，但累积几个月后，会让整个团队的迭代速度骤降。

这个困境的根源在于：AI 编码工具擅长生成语法正确的代码，但对架构合理缺乏判断力。它不知道你正在构建的是一个干净的分层架构，还是一个大泥球。

Brooks-Lint 正是为了解决这个问题而生的——一个跨平台的 AI 代码审查技能（Skill/Plugin），将 12 本经典软件工程书籍中的架构原则编码为可重复的诊断框架。它面向 Claude Code、Codex CLI、Gemini CLI、Cursor、OpenCode、Windsurf、Copilot 等主流 AI 编码工具，能在 PR 审查、架构审计、技术债评估等场景中生成带经典著作引用的结构化评审报告。

背后的知识体系：12 本书 × 12 种衰败风险

Brooks-Lint 的知识体系来自以下经典著作：

• 《人月神话》（Frederick Brooks）— 软件项目管理本质
• 《代码大全》（Steve McConnell）— 代码质量最佳实践
• 《重构》（Martin Fowler）— 改善既有代码设计
• 《整洁架构》（Robert C. Martin）— 架构边界与依赖方向
• 《程序员修炼之道》（Hunt & Thomas）— 务实的编程哲学
• 《领域驱动设计》（Eric Evans）— 领域模型与统一语言
• 《软件设计的哲学》（John Ousterhout）— 降低认知复杂度
• 《Google 的软件工程》（Winters 等）— 大规模工程实践
• 《xUnit 测试模式》（Gerard Meszaros）— 测试代码设计模式
• 《单元测试的艺术》（Roy Osherove）— 可维护的测试编写
• 《Google 如何测试软件》— 测试基础设施与流程
• 《与遗留代码有效共事》（Michael Feathers）— 遗留系统改造

从中提炼出 6 种生产代码衰败风险和 6 种测试代码衰败风险：

安装：一行命令覆盖几乎所有平台

Brooks-Lint 以 Agent Skills 标准格式分发，官方提供通用安装脚本：

curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- claude

curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- codex

curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- 

安装后，在 AI 编码工具中直接输入斜杠命令即可触发审查。

六种审查模式详解

Brooks-Lint 的六个功能维度覆盖了从日常 PR 到季度架构审计的完整场景：

1. PR 级别代码审查（/brooks-review）

粘贴 diff 或指向变更文件，输出格式为 Symptom → Source → Consequence → Remedy 四段式诊断链。每条发现都会标注来源书籍和页次引用的灵感。

class UserService:
    def update_profile(self, user_id, name, email, avatar_url):
        user = self.db.query(f"SELECT * FROM users WHERE id = {user_id}")
        user['email'] = email
        if user['email'] != email:   # 永远为 False — 静默 bug
            self.smtp.send(...)

Brooks-Lint 对此的输出：

🔴 Change Propagation — 单个方法为四个无关业务原因而修改
Symptom: update_profile 在同一个方法体中处理字段更新、邮件通知、积分重算、缓存失效
Source: Fowler — Refactoring — Divergent Change
Consequence: 积分公式修改可能破坏邮件通知，每次编辑跨四个领域
Remedy: 提取 NotificationService、LoyaltyService，UserService 只做编排

2. 全架构审计（/brooks-audit）

生成 Mermaid 依赖关系图，模块按严重度染色（红色=高危，黄色=警告，绿色=健康）。直接从图里就能发现循环依赖和不合规的跨层调用。

3. 技术债评估（/brooks-debt）

按 Pain × Spread 优先级对每条发现排序，分类为 Critical / Scheduled / Monitored，产生可落地的还款路线图。

4. 测试套件健康度审查（/brooks-test）

检测测试空间的 6 种衰败风险：测试晦涩、测试脆弱、测试重复、Mock 滥用、覆盖率错觉、架构不匹配。

5. 健康仪表盘（/brooks-health）

综合四个维度的扫描结果，输出加权健康评分（0-100）。适合在发布前、新团队入职时使用。

6. 全维度扫描 + 自动修复（/brooks-sweep）

一次扫描所有生产代码和测试代码的衰败风险，安全变更自动应用，复杂架构决策标记为人工项目。输出 Fix Log + 健康分数 Delta。

Benchmark 数据

官方在 3 个真实项目（PR 审查、架构审计、技术债评估）上做了对比测试：

差距不在于 Claude 的能力，而在于一致性和可追溯性——原生 Claude 有时能给出精彩的架构洞察，但无法每次都稳定输出带证据链和可操作建议的诊断。

CI/CD 集成

Brooks-Lint 提供了 GitHub Action，可在每个 PR 上自动运行审查：

on:
  pull_request:
    types: [opened, synchronize]
jobs:
  brooks-lint:
    runs-on: ubuntu-latest
    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

成本约每次 PR $0.05-0.15，视 diff 大小而定。如果 .brooks-lint-history.json 提交到仓库中，评论还会包含历史趋势（如”85 → 82 (−3) over last 3 runs”）。

配置定制

项目根目录放一个 .brooks-lint.yaml 即可自定义审查行为：

version: 1
disable:
  - T5      # 跳过覆盖率指标检查
severity:
  R1: suggestion  # 将认知过载降级为建议
ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

所有设置可选，不配置则使用默认行为。

与同类工具对比

Brooks-Lint 不是要替代你的 Linter——它是捕捉 Linter 看不见的问题：架构漂移、知识孤岛、领域模型失真。MIT 许可证，源码可自托管和自定义。项目当前为 v1.0 版本，已在 GitHub 上提供完整的 12 本书源覆蓋矩阵和基准测试套件。

如果你正在使用 AI 编码工具生成大量代码，但又担心代码质量在”高效”中悄悄下滑，Brooks-Lint 提供了一条用经典工程智慧为 AI 生成代码做把关的实用路径。