csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5a5d0a9460ef56facf758b5bb02c50b5a393d829
playbook/brooks-lint/README.zh-CN.md
T
ci[bot] 0a12711d78 📦 deps(thirdparty): update snapshots
2026-08-12 08:38:22 +08:00

25 KiB
Raw Blame History

brooks-lint

brooks-lint

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

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Español

快速上手 • 六类衰退风险 • 实际效果 • 基准测试 • 安装

Version MIT License Claude Code Plugin Codex CLI Skill GitHub Stars

Trendshift 当日 JavaScript 仓库榜第 2 名

你的代码 → 十二本经典 → 十二类衰退风险 → 带出处的结论

brooks-lint 审查代码：一条 /brooks-review 命令产出 28/100 健康分以及引用书目的 症状 → 根源 → 后果 → 对策 诊断

→ 访问官网

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

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

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

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

快速上手

# Claude Code
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

# 其他任意 Agent Skills 平台 —— Cursor · Codex · Gemini · Copilot · Windsurf · OpenCode · Kiro · …
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <平台>

装好后直接开口（"审查这个 PR""审计架构"），或运行六个命令之一——/brooks-review、/brooks-audit、 /brooks-debt、/brooks-test、/brooks-health、/brooks-sweep（各自的作用）。

每条诊断都以 症状 → 根源 → 后果 → 对策 返回，附书目出处和 0–100 健康分。完整安装方式（另外 8 个 平台）和 CI/CD 配置见下文。

十二本书

书名 作者 贡献于
The Mythical Man-Month（人月神话，1975） Frederick P. Brooks Jr. R2、R4、R5
Code Complete（代码大全，1993，第 2 版 2004） Steve McConnell R1、R4
Refactoring（重构，1999，第 2 版 2018） Martin Fowler R1、R2、R3、R4、R6
Clean Architecture（架构整洁之道，2017） Robert C. Martin R2、R5
The Pragmatic Programmer（程序员修炼之道，1999，20 周年版 2019） Andrew Hunt & David Thomas R2、R3、R4、R5、T2、T3
Domain-Driven Design（领域驱动设计，2003） Eric Evans R1、R3、R6
A Philosophy of Software Design（软件设计的哲学，2018） John Ousterhout R1、R4
Software Engineering at Google（Google 软件工程，2020） Winters, Manshreck & Wright R2、R5
The Art of Unit Testing（单元测试的艺术，2009，第 3 版 2023） Roy Osherove T1、T2、T4、T5
How Google Tests Software（Google 测试之道，2012） Whittaker, Arbon & Carollo T5、T6
Working Effectively with Legacy Code（修改代码的艺术，2004） Michael Feathers T4、T5、T6
xUnit Test Patterns（xUnit 测试模式，2007） 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 环境中原生渲染——无需额外工具。

更多示例

完整画廊 收录了 brooks-lint 在 Python、TypeScript、Go、Java 上的真实输出——涵盖 PR 审查、带 Mermaid 依赖图的架构审查、技术债评估和测试质量审查。

初次接触这些衰退风险？衰退风险实战指南 逐一讲解全部六类——每类的诊断问题、代表症状、出处书目与对策。

基准测试

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

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

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

可复现基准

上表是示意性的。下面这些数字确定、可在本地复算：

parser 保真度 —— SARIF 输出与 CI 闸门都依赖于正确解析模型的 Markdown 报告。在一个冻结的 30 份真实模型报告语料上（覆盖全部六种 mode，evals/benchmark-corpus.json），每份都配有独立评分的发现清单（由另一遍模型评分、并经人工抽查），实际发布的 parser 跑分如下——执行 npm run benchmark：

指标（n = 30，冻结语料） 结果
严重度计数精确吻合（parser vs 人工标注真值） 30 / 30
风险码 precision / recall 100% / 100%（56 个 finding-level 码，0 假阳 / 0 假阴）
产出合法 SARIF 2.1.0 30 / 30

由于 parser 是确定性的、语料是冻结的，npm run benchmark 对任何人都给出相同结果，npm test 也将其作为回归守卫。该语料有意包含 9 份假阳性 / tradeoff 报告（例如一个看起来像循环依赖、实则是端口与适配器的设计），它们必须保持干净。

打分确定性 —— 给定一组固定发现（2 Critical / 3 Warning / 1 Suggestion），三个 strictness 预设产出的分数与其 common.md 表的预测分毫不差：strict 34、balanced 54、legacy-friendly 74——且只有 legacy-friendly 会优先列出前三高杠杆修复。

模型质量 —— 模型能否在真实代码上找到正确的风险，由 57 场景 eval 套件（evals/evals.json）衡量：npm run evals（结构校验）与 npm run evals:live（实测，需 ANTHROPIC_API_KEY）。

范围与诚实说明：parser 数字是确定性的、可精确复算；strictness 与 eval 套件的数字是对模型的单次实测，会有轻微跑动差异。parser 基准衡量的是报告解析保真度（工具是否读出了报告里写的每条发现），而非某条发现"是否正确"。严重度计数吻合是完全独立的信号；风险码一致性还反映了 parser 与 grader 共用同一套权威 name→code 映射。

横向对比

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）会在首次会话启动时自动安装——也可以自己跑 bash hooks/session-start。 不想走市场：mkdir -p ~/.claude/skills/brooks-lint && cp -r skills/* ~/.claude/skills/brooks-lint/。

Gemini CLI · Codex CLI

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

Install the brooks-lint skill from hyhmrright/brooks-lint       # 在 Codex 会话中直接说

或使用下面的安装器：./scripts/install.sh gemini / ./scripts/install.sh codex。

其它所有平台——OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid

brooks-lint 以标准 Agent Skills 形式分发。任何加载 Agent Skills 的 agent 都能无需任何转换运行全部六种模式——一条命令即可安装：

# 选择你的平台；加 --project 装进当前仓库而非全局配置
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <平台>
#   <平台> = opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · gemini · codex · agents

安装器会把技能扁平拷进该平台对应的文件夹，让共享框架（../_shared/）始终正确解析——你不可能装错布局。 装好后直接提问（"审查这个 PR"、"审查架构"），对应技能就会依据 description 自动触发。

平台 安装到 同时读取 指南
OpenCode ~/.config/opencode/skills ~/.claude/skills、AGENTS.md 配置
Cursor（2.4+） ~/.cursor/skills .agents/skills、AGENTS.md 配置
Windsurf（Cascade） ~/.codeium/windsurf/skills AGENTS.md 配置
Antigravity（Google） .agent/skills（--project） AGENTS.md、GEMINI.md 配置
pi（earendil-works） ~/.pi/agent/skills — 配置
GitHub Copilot .github/skills（--project） .claude/skills、AGENTS.md 配置
Kiro（AWS） ~/.kiro/skills AGENTS.md 配置
Factory Droid ~/.factory/skills AGENTS.md 配置

Kiro 与 Factory Droid 还会自动注册 /brooks-review。不熟悉 skills、或用的是上面没列出的 agent？ 见 docs/getting-started.md。

🧪 验证状态。 Claude Code、Gemini CLI、Codex CLI 已由维护者验证。上面八个平台依据各工具官方技能规范编写， 并已在文件布局层面验证（安装器经过测试），但维护者尚未在每个平台端到端实跑。在某平台试过了——无论成功还是失败？ 请提一个 issue，附上平台、版本和你看到的结果。 用的是其它兼容 Agent Skills 的 agent？它几乎肯定以同样方式工作——告诉我们，我们会补上。

斜杠命令

命令 作用
/brooks-review 粘贴一段 diff，或让 AI 指向改动的文件。以 症状 → 根源 → 后果 → 对策 的格式逐一诊断六类衰退风险。
/brooks-audit 梳理模块依赖（附 Mermaid 依赖图）、识别循环依赖，并检查是否符合康威定律。
/brooks-debt 按六类衰退风险对技术债分类，以 痛感 × 扩散面 打优先级，产出带 Critical / Scheduled / Monitored 分级的偿还路线图。
/brooks-test 对照六类测试空间衰退风险审查测试套件——测试晦涩、测试脆弱、测试重复、Mock 滥用、覆盖率幻觉、架构错配。
/brooks-health 对全部四个质量维度做精简扫描，产出一个加权综合健康分。适合发版前或新团队上手时使用。
/brooks-sweep 一次性扫描 R1–R6、T1–T6 与架构，然后施加修复：安全改动自动应用，跨文件改动需确认，架构决策标记为人工处理项。输出修复日志与健康分变化。

各平台语法。 Claude Code 也接受带命名空间的完整形式 /brooks-lint:brooks-review——短命令由 session-start 钩子在首次会话启动时自动安装。Codex CLI 用 $brooks-review。Gemini CLI 直接用上表。 OpenCode、Cursor、Antigravity、pi 依据每个技能的 description 自动调用 Agent Skills，直接提问即可 （"审查这个 PR"、"我们最糟的技术债在哪"）；需要显式调用时用各平台自己的语法（pi 把每个技能注册为 /skill:brooks-review）。在所有平台上，当你讨论代码质量、架构或测试健康时，这些技能也会自动触发。

PR 审查会自动包含一个轻量的第 7 步快速测试检查（对纯文档 diff 会跳过）。需要完整的测试审查请用 /brooks-test；需要某个维度的深度诊断时，请用该维度的专项技能，而不是 /brooks-health。

配置

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

version: 1

strictness: balanced   # strict | balanced（默认）| legacy-friendly——对遗留代码更宽松的打分

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

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

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

# custom_risks:   # 定义项目专属 Cx 风险码——见 skills/_shared/custom-risks-guide.md
# suppress:       # 按风险码 + 路径下调特定诊断（如已接受的遗留债务）

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

设置 说明
strictness 打分预设：strict、balanced（默认）或 legacy-friendly（更轻的扣分，并优先列出高杠杆修复项）
disable 要跳过的风险码（R1–R6、T1–T6）
severity 覆盖严重度等级（critical / warning / suggestion）
ignore 要排除的文件 glob 模式
focus 只评估这些风险码（不能与 disable 同时使用）
custom_risks 定义项目专属风险码（C1、C2……）——见 custom-risks-guide.md
suppress 按风险码 + 路径下调特定诊断的严重度（可带 expires: 过期日期）

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

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

AI 能帮你更快地写代码，却无法告诉你正在建造的是大教堂还是焦油坑——而生成越廉价，这些作者识别出的 衰退风险就越尖锐。接入 AI 助手并不能修复认知过载或领域模型失真；生成更多代码会加剧变更扩散和知识重复； 跑得更快让偶发复杂度和依赖失序更加危险。

项目结构

每个技能都是一个 SKILL.md（触发条件 + 流程骨架）加上它自己的指南：

brooks-lint/
├── .claude-plugin/ · .codex-plugin/  # 各平台插件元数据
├── skills/
│   ├── _shared/          # common.md（铁律、配置、报告模板、健康分）
│   │                     # source-coverage.md · decay-risks.md（R1–R6）
│   │                     # test-decay-risks.md（T1–T6）· remedy-guide.md · custom-risks-guide.md
│   ├── brooks-review/    # 模式 1：PR 审查      → pr-review-guide.md
│   ├── brooks-audit/     # 模式 2：架构审查     → architecture-guide.md、onboarding-guide.md
│   ├── brooks-debt/      # 模式 3：技术债       → debt-guide.md
│   ├── brooks-test/      # 模式 4：测试质量     → test-guide.md
│   ├── brooks-health/    # 模式 5：健康仪表盘   → health-guide.md
│   └── brooks-sweep/     # 模式 6：全面扫描     → sweep-guide.md
├── hooks/                # SessionStart 钩子
├── commands/             # 短命令包装（由钩子自动安装）
├── evals/                # 57 场景评测套件 + 冻结的 parser 保真度语料
└── assets/               # logo、banner、demo

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@v1.4.3
        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 次运行"）。

质量闸门与 Code Scanning。 除 fail-below 外，该 Action 还提供：

        with:
          mode: review
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          fail-on: critical            # 出现任何 Critical 即失败（none | warning | critical）
          fail-on-regression: true     # 健康分较上次运行下降则失败
          sarif-file: brooks-lint.sarif  # 同时把诊断上传到 GitHub Code Scanning

fail-on-regression 读取 .brooks-lint-history.json，因此提交该文件即可强制"无新增回归"。设置 sarif-file 会让诊断直接显示在 PR 的 Files changed 标签页，并需要 job 具备 security-events: write 权限。

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

路线图

当前状态（v1.4）： 12 本书地基，6 类生产衰退风险（R1–R6）+ 6 类测试衰退风险（T1–T6），6 个技能， CI 质量闸门、面向 GitHub Code Scanning 的 SARIF 输出、严格度预设，以及一个可复现的 parser 保真度基准。

里程碑 v0.2 → v1.4
  • v0.2–v0.4：插件基础设施、六本书框架、衰退风险维度、基准套件
  • v0.5–v0.7：测试质量审查、Mermaid 依赖图、.brooks-lint.yaml、扩展到 10 本书
  • v0.8–v0.9：独立技能架构；步骤校验、自动 diff 范围、/brooks-health、趋势追踪、分诊模式、--fix 对策、GitHub Action
  • v1.0–v1.2：评测自动化、自定义 Cx 风险码、全量扫描技能、npm run bump 版本传播
  • v1.3：Codex 市场元数据、多平台一键安装脚本、多语言 README + 落地页
  • v1.4：SARIF 输出、CI severity + 回归闸门、严格度预设、57 场景 eval 套件、npm run benchmark

贡献

见 CONTRIBUTING.md。现在最有价值的贡献是新的评测用例和更好的衰退风险症状模式。 在你自己的 PR 上跑一遍 /brooks-review——我们用正在打造的工具来审查贡献。

许可证

MIT License——详见 LICENSE。

致谢

本项目站在十二位巨人的肩膀上——完整书单与版本见上面的十二本书。本工具中编码的衰退风险， 是我们对他们思想的综合，并应用于现代代码质量评估。

Star 历史

Star History Chart

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

Reference in New Issue View Git Blame Copy Permalink