22 KiB

Raw Blame History

brooks-lint

植根于十二本经典工程著作的 AI 代码审查。
一致、可溯源、可落地。

English · 简体中文

"一个孩子要十月怀胎，无论派多少人去都一样。" —— Frederick Brooks，《人月神话》（1975）

五十年过去，Brooks 依然正确——McConnell、Fowler、Martin、Hunt & Thomas、Evans、Ousterhout、Winters、Meszaros、Osherove、Feathers 以及 Google 测试团队同样如此。

大多数代码质量工具只数行数和圈复杂度。brooks-lint 更进一步——它对照六个衰退风险维度（综合自十二本经典工程著作）诊断你的代码，每一次都产出带书目出处、严重度标签和具体对策的结构化诊断。

完整的"书目—技能"映射（含例外与误报防护），见 skills/_shared/source-coverage.md。

十二本书

书名	作者	贡献于
The Mythical Man-Month（人月神话）	Frederick Brooks	R2、R4、R5
Code Complete（代码大全）	Steve McConnell	R1、R4
Refactoring（重构）	Martin Fowler	R1、R2、R3、R4、R6
Clean Architecture（架构整洁之道）	Robert C. Martin	R2、R5
The Pragmatic Programmer（程序员修炼之道）	Hunt & Thomas	R2、R3、R4、R5、T2、T3
Domain-Driven Design（领域驱动设计）	Eric Evans	R1、R3、R6
A Philosophy of Software Design（软件设计的哲学）	John Ousterhout	R1、R4
Software Engineering at Google（Google 软件工程）	Winters, Manshreck & Wright	R2、R5
The Art of Unit Testing（单元测试的艺术）	Roy Osherove	T1、T2、T4、T5
How Google Tests Software（Google 测试之道）	Whittaker, Arbon & Carollo	T5、T6
Working Effectively with Legacy Code（修改代码的艺术）	Michael Feathers	T4、T5、T6
xUnit Test Patterns（xUnit 测试模式）	Gerard Meszaros	T1、T2、T3、T4

六类衰退风险

brooks-lint 从六类生产代码衰退风险和六类测试代码衰退风险两个角度评估你的代码，这些维度综合自十二本经典工程著作：

衰退风险	诊断问题	出处
🧠 认知过载	理解这段代码要花多少脑力？	Code Complete、Refactoring、DDD、Philosophy of SD
🔗 变更扩散	改一处会牵连多少不相干的东西？	Refactoring、Clean Architecture、Pragmatic、SE@Google
📋 知识重复	同一个决策是否在多处被表达？	Pragmatic、Refactoring、DDD
🌀 偶发复杂度	代码是否比问题本身更复杂？	Refactoring、Code Complete、Brooks、Philosophy of SD
🏗️ 依赖失序	依赖是否朝一致的方向流动？	Clean Architecture、Brooks、Pragmatic、SE@Google
🗺️ 领域模型失真	代码是否忠实地表达了业务领域？	DDD、Refactoring

Philosophy of SD = A Philosophy of Software Design（Ousterhout） · SE@Google = Software Engineering at Google（Winters 等）

实际效果

给定这段代码：

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

这个方法把四个不相干的业务职责塞进同一个函数，含有一个会静默吞掉"邮箱变更通知"的逻辑 bug，并且对 SQL 注入门户大开。

🔴 变更扩散 —— 单个方法因四个不相干的业务原因而改动

症状： update_profile 在同一个方法体里完成资料字段更新、邮箱变更通知、积分重算和缓存失效。 根源： Fowler — Refactoring — 发散式变更（Divergent Change）；Hunt & Thomas — The Pragmatic Programmer — 正交性（Orthogonality） 后果： 任何对积分公式的改动都可能破坏邮件通知，反之亦然。每次修改都同时背负着四个不相干领域的回归风险。 对策： 抽出 NotificationService、LoyaltyService 和 UserCacheInvalidator。UserService.update_profile 应只做编排、逐一调用它们——本身不持有任何实现逻辑。

🔴 领域模型失真 —— 隐性逻辑 bug：邮箱通知永不触发

症状： user['email'] = email 在 if user['email'] != email 之前就覆盖了旧值——条件恒为 False，通知是死代码。 根源： McConnell — Code Complete — 第 17 章：非常规控制结构 后果： 用户改邮箱时永远收不到通知。这是静默的数据完整性失效——系统看似正常运转，实则违反了业务规则。 对策： 在任何修改之前先捕获 old_email = user['email']，拿它（而非 user['email']）做比较。

（另有 6 条诊断，含 SQL 注入、依赖失序、魔法数字）

带依赖图的架构审查

在模式 2（架构审查）中，brooks-lint 会在报告顶部生成一张 Mermaid 依赖图。模块按严重度着色：红=Critical，黄=Warning，绿=干净。

graph TD
    subgraph src/api
        AuthController
        UserController
    end
    subgraph src/domain
        UserService
        OrderService
    end
    subgraph src/infra
        Database
        EmailClient
    end

    AuthController --> UserService
    UserController --> UserService
    UserController --> OrderService
    OrderService --> UserService
    OrderService --> EmailClient
    UserService --> Database
    EmailClient -.->|circular| OrderService

    classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff
    classDef warning fill:#ffd43b,stroke:#e67700
    classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff

    class OrderService,EmailClient critical
    class AuthController warning
    class UserService,UserController,Database clean

该图在 GitHub、Notion 等 Markdown 环境中原生渲染——无需额外工具。

基准测试

在 3 个真实场景（PR 审查、架构审查、技术债评估）上测试：

评估项	brooks-lint	仅用 Claude
结构化诊断（症状 → 根源 → 后果 → 对策）	✅ 100%	❌ 0%
每条诊断带书目出处	✅ 100%	❌ 0%
严重度标签（🔴/🟡/🟢）	✅ 100%	❌ 0%
健康分（0–100）	✅ 100%	❌ 0%
识别"变更扩散"	✅ 100%	✅ 100%
整体通过率	94%	16%

差距不在于 Claude 能不能发现问题——而在于它能否每一次都稳定地发现，并附上可溯源的证据和可落地的对策。

横向对比

	brooks-lint	ESLint / Pylint	GitHub Copilot Review	原生 Claude
检测语法与风格问题	—	✅	✅	~
结构化诊断链	✅	❌	❌	❌
将诊断溯源到经典著作	✅	❌	❌	❌
一致的严重度标签	✅	✅	~	❌
架构层面的洞察	✅	❌	~	~
领域模型分析	✅	❌	❌	~
零配置、无需安装插件	✅	❌	✅	✅
适用于任何语言	✅	❌	✅	✅

~ = 偶尔 / 不稳定

brooks-lint 不是要取代你的 linter。 它捕捉的是 linter 抓不到的东西：架构漂移、知识孤岛、领域模型失真——这些问题往往在无人察觉的几个月里持续拖慢团队。

安装

Claude Code（推荐）

通过插件市场

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

短命令（/brooks-review）会在首次会话启动时自动安装。手动安装：

cp commands/*.md ~/.claude/commands/

手动安装

mkdir -p ~/.claude/skills/brooks-lint
cp -r skills/* ~/.claude/skills/brooks-lint/

Gemini CLI

通过扩展

/extensions install https://github.com/hyhmrright/brooks-lint

手动安装

mkdir -p ~/.gemini/skills/brooks-lint
cp -r skills/* ~/.gemini/skills/brooks-lint/

Codex CLI

通过技能安装器（在 Codex 会话中）

Install the brooks-lint skill from hyhmrright/brooks-lint

命令行

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo hyhmrright/brooks-lint --path skills --name brooks-lint

手动安装

git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint
mkdir -p ~/.codex/skills/brooks-lint
cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/brooks-lint/

斜杠命令

Claude Code

命令	短命令	作用
`/brooks-lint:brooks-review`	`/brooks-review`	PR 级代码审查
`/brooks-lint:brooks-audit`	`/brooks-audit`	完整架构审查
`/brooks-lint:brooks-debt`	`/brooks-debt`	技术债评估
`/brooks-lint:brooks-test`	`/brooks-test`	测试套件健康审查
`/brooks-lint:brooks-health`	`/brooks-health`	健康仪表盘——全部四个维度
`/brooks-lint:brooks-sweep`	`/brooks-sweep`	全面扫描——分析所有维度并自动修复

短命令由 session-start 钩子在首次会话启动时自动安装。

Gemini CLI

命令	作用
`/brooks-review`	PR 级代码审查
`/brooks-audit`	完整架构审查
`/brooks-debt`	技术债评估
`/brooks-test`	测试套件健康审查
`/brooks-health`	健康仪表盘——全部四个维度
`/brooks-sweep`	全面扫描——分析所有维度并自动修复

Codex CLI

命令	作用
`$brooks-review`	PR 级代码审查
`$brooks-audit`	完整架构审查
`$brooks-debt`	技术债评估
`$brooks-test`	测试套件健康审查
`$brooks-health`	健康仪表盘——全部四个维度
`$brooks-sweep`	全面扫描——分析所有维度并自动修复

当你讨论代码质量、架构、可维护性或测试健康时，这些技能也会自动触发。

使用

PR 审查

/brooks-review                      # Claude Code（短命令）/ Gemini CLI
/brooks-lint:brooks-review          # Claude Code（完整形式）
$brooks-review                      # Codex CLI

粘贴一段 diff，或让 AI 指向改动的文件。它会以症状 → 根源 → 后果 → 对策的格式，逐一诊断六类衰退风险并给出具体诊断。

架构审查

/brooks-audit                       # Claude Code（短命令）/ Gemini CLI
/brooks-lint:brooks-audit           # Claude Code（完整形式）
$brooks-audit                       # Codex CLI

描述你的项目结构或分享关键文件。它会梳理模块依赖、识别循环依赖，并检查是否符合康威定律。

技术债评估

/brooks-debt                        # Claude Code（短命令）/ Gemini CLI
/brooks-lint:brooks-debt            # Claude Code（完整形式）
$brooks-debt                        # Codex CLI

按六类衰退风险对技术债分类，以痛感 × 扩散面为每条诊断打优先级，产出带 Critical / Scheduled / Monitored 分级的偿还路线图。

测试质量审查

/brooks-test                        # Claude Code（短命令）/ Gemini CLI
/brooks-lint:brooks-test            # Claude Code（完整形式）
$brooks-test                        # Codex CLI

对照六类测试空间衰退风险审查你的测试套件——测试晦涩、测试脆弱、测试重复、Mock 滥用、覆盖率幻觉、架构错配——出处为 xUnit Test Patterns、The Art of Unit Testing、How Google Tests Software 和 Working Effectively with Legacy Code。PR 审查还会自动包含一个轻量的第 7 步快速测试检查（对纯文档或非生产代码 diff 会跳过）。

健康仪表盘

/brooks-health                      # Claude Code（短命令）/ Gemini CLI
/brooks-lint:brooks-health          # Claude Code（完整形式）
$brooks-health                      # Codex CLI

对全部四个质量维度做精简扫描，产出加权综合健康分（0–100）。适合发版前、新团队上手时，或任何你想要一份"我们现在怎么样？"全局报告的场景。需要某个维度的深度诊断时，请改用对应的专项技能。

全面扫描

/brooks-sweep                       # Claude Code（短命令）/ Gemini CLI
/brooks-lint:brooks-sweep           # Claude Code（完整形式）
$brooks-sweep                       # Codex CLI

一次性扫描全部生产（R1–R6）与测试（T1–T6）衰退风险以及架构，然后施加修复：安全改动立即自动应用，跨文件或触及接口的改动需确认，复杂的架构决策则标记为人工处理项。输出修复日志、健康分变化和遗留项清单。

配置

在项目根目录放一个 .brooks-lint.yaml 来定制审查行为：

version: 1

disable:
  - T5   # 跳过覆盖率指标检查——我们不强制覆盖率

severity:
  R1: suggestion   # 在该领域下调"认知过载"诊断的严重度

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

可复制 .brooks-lint.example.yaml 作为起点。所有设置均为可选——完全省略该文件即使用默认行为。

设置	说明
`disable`	要跳过的风险码（`R1`–`R6`、`T1`–`T6`）
`severity`	覆盖严重度等级（`critical` / `warning` / `suggestion`）
`ignore`	要排除的文件 glob 模式
`focus`	只评估这些风险码（不能与 `disable` 同时使用）

为什么是这些书，为什么是现在？

在 AI 辅助编程的时代，我们写代码比以往任何时候都更快、更多。但六十年软件工程沉淀下来的洞见并没有改变：

"软件的复杂性是本质属性，而非偶然属性。" —— Frederick Brooks

AI 能帮你更快地写代码，却无法告诉你正在建造的是大教堂还是焦油坑。brooks-lint 弥合了这道鸿沟——它把十二本经典工程著作中来之不易的智慧，带进你现代的开发工作流。

这些作者识别出的衰退风险，如今比以往更切题：

接入 AI 助手 并不能修复认知过载或领域模型失真
生成更多代码 会加剧变更扩散和知识重复
跑得更快 让偶发复杂度和依赖失序更加危险

项目结构

brooks-lint/
├── .claude-plugin/              # Claude Code 插件元数据
├── .codex-plugin/               # Codex CLI 插件元数据
├── skills/
│   ├── _shared/                 # 共享框架文件
│   │   ├── common.md            # 铁律、项目配置、报告模板、健康分
│   │   ├── source-coverage.md   # 12 本书覆盖矩阵、权衡、误报防护
│   │   ├── decay-risks.md       # 六类衰退风险及症状与书目出处
│   │   ├── test-decay-risks.md  # 六类测试空间衰退风险及书目出处
│   │   ├── remedy-guide.md      # --fix 模式：可落地的对策增强规则
│   │   └── custom-risks-guide.md  # 项目自定义风险码模板
│   ├── brooks-review/           # 模式 1：PR 审查
│   │   ├── SKILL.md
│   │   └── pr-review-guide.md
│   ├── brooks-audit/            # 模式 2：架构审查
│   │   ├── SKILL.md
│   │   └── architecture-guide.md
│   ├── brooks-debt/             # 模式 3：技术债评估
│   │   ├── SKILL.md
│   │   └── debt-guide.md
│   ├── brooks-test/             # 模式 4：测试质量审查
│   │   ├── SKILL.md
│   │   └── test-guide.md
│   ├── brooks-health/           # 模式 5：健康仪表盘
│   │   ├── SKILL.md
│   │   └── health-guide.md
│   └── brooks-sweep/            # 模式 6：全面扫描与自动修复
│       ├── SKILL.md
│       └── sweep-guide.md
├── hooks/                       # SessionStart 钩子
├── commands/                    # 短命令包装（由钩子自动安装）
├── evals/                       # 基准测试用例
│   └── evals.json
└── assets/
    └── logo.svg

CI/CD 集成

用 GitHub Action 在每个 PR 上自动运行 brooks-lint：

# .github/workflows/brooks-lint.yml
name: Brooks-Lint PR Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

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

完整模板见 docs/github-action-example.yml。

该 Action 会把审查结果作为 PR 评论发布，并可在健康分跌破阈值时让检查失败。若仓库中提交了 .brooks-lint-history.json，评论还会包含趋势变化（如 "85 → 82（−3），近 3 次运行"）。

成本： 每次 PR 运行约 $0.05–0.15，取决于 diff 大小和模型。建议仅在 pull_request 事件上运行。

路线图

当前状态（v1.0）： 12 本书地基，6 类生产衰退风险（R1–R6）+ 6 类测试衰退风险（T1–T6），5 个技能——PR 审查、架构审查、技术债、测试质量、健康仪表盘。下方较早的条目记录的是历史里程碑，而非当前功能集。

v0.2：插件基础设施（.claude-plugin/、钩子、斜杠命令）
v0.3：八个 Brooks 维度、文档完整度评分
v0.4：六本书框架、衰退风险维度、诊断链、基准套件
v0.5：测试质量审查（模式 4）——四本测试书、六类测试衰退风险
v0.6：架构审查中的 Mermaid 依赖图
v0.7：.brooks-lint.yaml 项目配置、模式 2 主动上下文、扩展到 10 本书
v0.8：带命名空间命令的独立技能架构
v0.9：步骤校验、自动 diff 范围、/brooks-health 仪表盘、趋势追踪、分诊模式、--fix 对策、上手报告、GitHub Action
v1.0：评测自动化（run-evals-live.mjs）、自定义风险扩展（Cx 码）

想出一份力？现在最有价值的贡献是新的评测用例和更好的衰退风险症状模式。见 CONTRIBUTING.md。

贡献

如何新增诊断、改进指南或扩展基准套件，见 CONTRIBUTING.md。

在你自己的 PR 上跑一遍 /brooks-review——我们用正在打造的工具来审查贡献。

许可证

MIT License——详见 LICENSE。

致谢

本项目站在十二位巨人的肩膀上：

生产代码框架

Frederick P. Brooks Jr. — The Mythical Man-Month（1975，纪念版 1995）
Steve McConnell — Code Complete（1993，第 2 版 2004）
Martin Fowler — Refactoring（1999，第 2 版 2018）
Robert C. Martin — Clean Architecture（2017）
Andrew Hunt & David Thomas — The Pragmatic Programmer（1999，20 周年版 2019）
Eric Evans — Domain-Driven Design（2003）
John Ousterhout — A Philosophy of Software Design（2018）
Titus Winters、Tom Manshreck、Hyrum Wright — Software Engineering at Google（2020）

测试质量框架

Gerard Meszaros — xUnit Test Patterns（2007）
Roy Osherove — The Art of Unit Testing（2009，第 3 版 2023）
Google Engineering — How Google Tests Software（2012）
Michael Feathers — Working Effectively with Legacy Code（2004）

本工具中编码的衰退风险，是我们对他们思想的综合，并应用于现代代码质量评估。

Star 历史

⭐ 如果这个工具让你以不同的眼光看待自己的代码库，请给它点个 star！

22 KiB Raw Blame History Unescape Escape

brooks-lint

十二本书

六类衰退风险

实际效果

🔴 变更扩散 —— 单个方法因四个不相干的业务原因而改动

🔴 领域模型失真 —— 隐性逻辑 bug：邮箱通知永不触发

带依赖图的架构审查

更多示例

基准测试

横向对比

安装

Claude Code（推荐）

通过插件市场

手动安装

Gemini CLI

通过扩展

手动安装

Codex CLI

通过技能安装器（在 Codex 会话中）

命令行

手动安装

斜杠命令

Claude Code

Gemini CLI

Codex CLI

使用

PR 审查

架构审查

技术债评估

测试质量审查

健康仪表盘

全面扫描

配置

为什么是这些书，为什么是现在？

项目结构

CI/CD 集成

路线图

贡献

许可证

致谢

Star 历史

22 KiB

Raw Blame History