当 AI 编码 Agent 写出「快但坏」的代码，Brooks-Lint 用 12 本经典书给代码做诊断

AI 编码工具让开发者写代码的速度提升了数倍甚至数十倍，但你有没有发现一个奇怪的现象：代码仓库的健康状况反而在下降？

Claude Code 和 Codex 可以在一小时内生成整个微服务的代码骨架，但这些代码往往缺少边界检查、混合了多层职责、忽略了领域模型的边界——说得直白点，它们写出了大量「看起来能跑，但经不起迭代」的代码。传统的 linter（ESLint、Pylint）只能检查格式和语法问题，对架构漂移和知识孤岛毫无办法。手动 Code Review 又太慢——尤其是当你需要审查 AI Agent 每小时生成的数百行代码时。

Brooks-Lint 就是为解决这个问题而生的。它不是又一个 linter——它是一个基于 12 本经典软件工程书籍的 AI 代码质量诊断工具，能识别传统工具无法捕捉的 6 种「代码衰败风险」，每次输出都附带书籍引用、严重性标签和具体的修复建议。

问题对比：传统工具能检查什么？

✅ = 完全支持 · ~ = 偶尔/不一致 · ❌ = 不支持 · — = 不在范围内

Brooks-Lint 的目标不是替代你的 linter——它补上了 linter 抓不到的问题：架构漂移、知识孤岛、领域模型失真——那些让团队慢下来几个月才有人注意的问题。

三种安装方式

Claude Code（推荐）

/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

任意 Agent Skills 平台（OpenCode / Cursor / Codex / Gemini / Windsurf 等）

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

GitHub Actions CI/CD

name: Brooks-Lint PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  brooks-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hyhmrright/brooks-lint/.github/actions/brooks-lint@main
        with:
          mode: review
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          fail-below: 70

六种分析模式

Brooks-Lint 提供了 6 个独立技能，覆盖代码质量诊断的不同维度：

1. PR Review（/brooks-review）

粘贴一段 diff 或指定变更文件，它会从 6 个衰败风险维度逐一诊断。每个发现返回「症状 → 来源 → 后果 → 修复方案」的结构化格式，附带书籍引用和健康分数。

给定这样一段代码：

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(...)
        points = user['login_count'] * 10 + 500
        self.db.execute(f"UPDATE loyalty SET points={points} WHERE user_id={user_id}")

Brooks-Lint 会输出 健康分数：28/100，并指出：

• 🔴 变更传播：update_profile 在一个方法中承担了四个不相关的业务职责（字段更新、邮件通知、积分重算、缓存失效）。来源：《Refactoring》— Divergent Change
• 🔴 领域模型失真：user['email'] = email 在比较之前就覆盖了旧值，条件永远为 False，邮件通知是死代码。来源：《Code Complete》第 17 章
• 更多发现包括 SQL 注入、依赖混乱、魔法数字等

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

描述项目结构或分享关键文件，Brooks-Lint 生成 Mermaid 依赖图，按严重性着色模块：红色 = 严重问题，黄色 = 警告，绿色 = 健康。依赖图在 GitHub、Notion 和其他 Markdown 环境中原生渲染。

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

将代码库中的债务按 6 个衰败风险分类，按痛苦度 × 扩散度排优先级，生成 Critical / Scheduled / Monitored 三个优先级的偿还路线图。

4. 测试质量审查（/brooks-test）

基于 xUnit Test Patterns、The Art of Unit Testing、How Google Tests Software、Working Effectively with Legacy Code 四本测试经典，评估 6 个测试维度的健康状况：测试模糊性、测试脆弱性、测试重复、Mock 滥用、覆盖率幻觉、架构不匹配。

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

一次运行简化扫描全部四个质量维度，生成加权综合健康分数（0–100）。适合在发布前、新团队入职时使用。

6. 全面扫描与自动修复（/brooks-sweep）

同时运行所有生产代码（R1–R6）和测试代码（T1–T6）的衰败风险检查，并自动应用修复：安全变更立即执行，多文件或接口变更需确认，复杂架构问题标记为手动。

六种代码衰败风险

Brooks-Lint 的诊断框架基于 12 本经典书籍的提炼，定义了 6 种生产代码衰败风险：

配置与自定义

在项目根目录放置 .brooks-lint.yaml 自定义审查行为：

version: 1

strictness: balanced   # strict | balanced（默认） | legacy-friendly

disable:
  - T5   # 跳过覆盖率检查

severity:
  R1: suggestion   # 对认知过载降级处理

ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

横向对比：与其他方案的区别

最后一行数据来自作者提供的 Benchmark：Brooks-Lint 在 PR Review、架构审计、技术债务评估三个真实场景中的综合通过率为 94%，而单独使用 Claude 只有 16%。差距不在于 Claude 能发现什么——而在于它能 一致地发现什么，并总是附带可追溯的证据和可操作的修复方案。

注意事项

1. 成本：每次 PR 审查大约 $0.05–$0.15（取决于 diff 大小和模型），建议只在 PR 事件上启用
2. 它是 linter 的补充，不是替代：Brooks-Lint 不检查格式和语法——先用 ESLint/Pylint 过一遍，再用它做深度诊断
3. 需要 API Key：默认使用 Anthropic Claude，需要设置 ANTHROPIC_API_KEY
4. 语言无关：任何语言都可以审查，但对 TypeScript/Python/Go/Java 的支持最为成熟

总结

AI 编码工具让我们写代码更快，但「快」不等于「好」。Brooks-Lint 把 12 本经典软件工程书籍中提炼出的 6 种代码衰败风险框架，直接嵌入到你的 AI Agent 工作流中——每次 CI、每次 PR、每次架构讨论，都有一个读过 Brooks、McConnell、Fowler 和 Evans 的诊断师帮你把关。

相关链接

• GitHub 仓库
• 官方文档站
• MIT 许可证