brooks-lint：AI Agent 工具实践指南

准备试用brooks-lint之前，先别急着安装；这个项目提供的是AI 代码审查基于 12 本经典工程书籍 - 通过书籍引用、严重性标签和 6 种分析模式（包括全面自动修复）进行衰退风险诊断。在数据与知识处理场景里，常见问题是数据结构、更新策略和可追溯性会决定结果是否可信，这正是评估时需要盯住的地方。我建议用一份规模可控且答案已知的数据集试跑，重点记录模式兼容、增量更新、查询结果和来源追踪，再与现有方案比较。我会把它列入需要保留数据来路与变更记录的使用者的候选清单，而不是仅凭项目介绍直接纳入生产。

brooks-lint

AI 植根于十二个经典工程的代码审查 books.

一致。可追溯。 Actionable.

Quick Start • 该六衰 Risks • What 看起来 Like • Benchmark • Installation

→ 访问website

“无论分配多少女性，生孩子都需要九个月的时间。” ——弗雷德里克·布鲁克斯，《人月神话》（1975）

50 年后，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

# Any other Agent Skills platform — Cursor · Codex · Gemini · Copilot · Windsurf · OpenCode · Kiro · Bob …
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>

然后只需询问（“查看此 PR”、“审核架构”），或运行六个命令之一 - /brooks-review, /brooks-audit, /brooks-debt, /brooks-test, /brooks-health, /brooks-sweep （每个人做什么）。

每项发现都以症状 → 来源 → 结果 → 补救措施 的形式返回，并附有书籍引文和 0–100 健康评分。完整安装选项（另外 10 个平台）和 CI/CD 设置为 ，低于。

十二本书

六大衰退风险

brooks-lint 通过从十二个经典工程书籍中综合而来的 六种生产代码衰退风险 和 六种测试套件衰退风险 来评估您的代码：

SD 的哲学 = 软件设计哲学 (Ousterhout) · SE@Google = 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:   # always False — silent bug
            self.smtp.send(...)
        points = user['login_count'] * 10 + 500
        self.db.execute(f"UPDATE loyalty SET points={points} WHERE user_id={user_id}")

布鲁克斯林特生产：

健康评分：28/100

此方法将四个不相关的业务职责集中到一个函数中，包含一个逻辑错误，该错误会默默地抑制电子邮件更改通知，并且对 SQL 注入敞开大门。

变更传播 — 四个不相关的业务原因导致的单一方法变更

症状： update_profile 在一个方法体中执行配置文件字段更新、电子邮件更改通知、忠诚度积分重新计算和缓存失效。 来源： Fowler — 重构 — Divergent Change； Hunt 和 Thomas — 务实的程序员 — 正交性 后果： 对忠诚度公式的任何更改都有可能破坏电子邮件通知，反之亦然。每次编辑都会同时在四个不相关的领域带来回归风险。 补救措施： 提取 NotificationService、LoyaltyService 和 UserCacheInvalidator。 UserService.update_profile 应该通过调用每个来进行编排——它本身不应该包含任何实现逻辑。

领域模型失真 — 无声逻辑错误：电子邮件通知永远不会触发

症状： user['email'] = email 覆盖 if user['email'] != email 之前的旧值 — 条件始终为 False。该通知是死代码。 来源： McConnell — 代码完整 — 第 1 章17：不寻常的控制结构 后果： 当用户的电子邮件地址发生变化时，他们永远不会收到通知。无声数据完整性故障——系统看似正常运行，但违反了业务规则。 补救措施： 在任何突变之前捕获 old_email = user['email']。与 old_email 进行比较，而不是与 user['email'] 进行比较。

（+ 6 个发现，包括 SQL 注射、依赖性障碍、幻数）

使用依赖图进行架构审计

在模式 2（架构审核）中，brooks-lint 在报告顶部生成 Mermaid 依赖关系图。模块按严重程度进行颜色编码：红色 = 严重发现，黄色 = 警告，绿色 = 干净。

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 环境中本地呈现 - 不需要额外的工具。

查看更多示例

完整画廊 具有跨 Python、TypeScript、Go 和 Java 的真正 brooks-lint 输出，包括 PR 审查、使用 Mermaid 依赖图的架构审计、技术债务评估和测试质量审查。

对腐烂风险不熟悉？ The Decay Risk Field Guide explains all six — diagnostic question, signature symptoms, source books, and remedy for each.

基准测试

在 3 个现实场景中进行了测试（PR 审查、架构审计、技术债务评估）：

这个差距不是克劳德“能够”找到的——而是它“始终如一”发现的，每次都有可追踪的证据和可行的补救措施。

可重复的基准

上表是说明性的。这些数字是确定性的，您可以在本地重现它们：

解析器保真度 — SARIF 导出和 CI 门取决于正确解析模型的 Markdown 报告。 Against a frozen corpus of 30 real, model-generated reports spanning all six modes (evals/benchmark-corpus.json), each paired with an independently graded finding inventory (a separate model pass, spot-checked by hand), the shipped parser scores — run npm run benchmark:

因为解析器是确定性的并且语料库是冻结的，所以 npm run benchmark 给每个人相同的结果，并且 npm test 将其作为回归来保护。该语料库故意包含 9 个必须保持干净的误报/权衡报告（e.g。“看起来”像依赖循环的端口和适配器设计）。

评分确定性 - 对于固定的结果集（2 个严重/3 个警告/1 个建议），严格性预设准确地生成其 common.md 表预测的分数：严格 34、平衡 54、传统友好 74 - 并且只有 legacy-friendly 领先于前三名修复。

模型质量 - 模型是否在真实代码上找到“正确”的风险是通过 57 场景评估套件 (evals/evals.json) 来衡量的：npm run evals（结构）和 npm run evals:live（实时，需要 ANTHROPIC_API_KEY）。

Scope & honesty: the parser numbers are deterministic and exactly reproducible. The strictness and eval-suite figures are single-run live measurements against the model and vary slightly run to run. The parser benchmark measures report-parsing fidelity (does the tooling read every finding the report states?), not whether a given finding is "correct." The severity-count match is the fully independent signal; risk-code agreement also reflects the shared canonical name→code legend.

How It Compares

~ = 偶尔/不一致

brooks-lint 不会取代你的 linter。 它能捕捉到 linter 无法捕捉到的东西：架构漂移、知识孤岛和领域模型扭曲——这些问题在任何人注意到之前就已经让团队的速度慢了几个月。

安装

克劳德代码（推荐）

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

简短命令 (/brooks-review) 在第一次会话启动或运行时自动安装 bash hooks/session-start 自己。 To skip the marketplace: mkdir -p ~/.claude/skills/brooks-lint && cp -r skills/* ~/.claude/skills/brooks-lint/.

双子座 CLI · 法典 CLI

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

Install the brooks-lint skill from hyhmrright/brooks-lint       # ask inside a Codex session

Or use the installer below: ./scripts/install.sh gemini / ./scripts/install.sh codex.

Every other platform — OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid · DeepSeek Harness · IBM Bob

brooks-lint ships as standard Agent Skills. 任何加载Agent的代理 技能无需转换即可运行所有六种模式 — 一个命令即可安装它们：

# pick your platform; --project installs into the current repo instead of your global config
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>
#   <platform> = opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · dsh · gemini · codex · claude · bob · agents

安装程序将技能扁平复制到正确的文件夹中，因此共享框架 (../_shared/) always resolves — you can't get the layout wrong.然后就问（“回顾一下这个PR”， “审核架构”）以及从其 description 中自动触发的匹配技能。

OpenCode v2、Kiro、Factory Droid 和 DeepSeek Harness 也会自动注册 /brooks-review。 New to 技能，或使用未列出的代理？请参阅 docs/getting-started.md。

验证状态。 Claude Code、Gemini CLI 和 Codex CLI 均经过维护者验证。的 上述十个平台均记录在每个工具的官方技能规范中，并在 文件布局级别（安装程序经过测试），但维护人员尚未在每个 平台。尝试过——工作还是坏了？ 打开一个问题 与平台，版本， and what you saw.另一个特工技能特工？几乎可以肯定，它的工作原理是一样的——告诉我们， 我们会添加它。

斜线命令

Syntax by platform. Claude Code also accepts the namespaced form /brooks-lint:brooks-review — 简短的表格会在第一个会话启动时自动安装 会话启动挂钩。 Codex CLI uses $brooks-review. Gemini CLI 和 OpenCode v2 使用该表作为 写的。光标、反重力、pi 和 DeepSeek Harness 从每个技能的 description，所以只要问（“回顾一下这个 PR”，“我们最严重的技术债务在哪里？”）；对于明确的 调用使用平台自己的语法（pi 将每个技能注册为 /skill:brooks-review；dsh 从其 / 菜单或内联键入中获取所写的表格）。在每个平台上 当您讨论代码质量、架构或测试运行状况时，技能也会自动触发。

PR reviews include a lightweight Step 7 Quick Test Check automatically (skipped for docs-only 差异）。对于完整的测试审核，请运行 /brooks-test； for a deep dive on any single dimension, 使用该维度自己的技能而不是/brooks-health。

配置

将 .brooks-lint.yaml 放入项目根目录中以自定义审核行为：

version: 1

strictness: balanced   # strict | balanced (default) | legacy-friendly — softer scoring for legacy code

disable:
  - T5   # skip coverage metrics check — we don't enforce coverage

severity:
  R1: suggestion   # downgrade Cognitive Overload findings for this domain

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

# custom_risks:   # define project-specific Cx codes — see skills/_shared/custom-risks-guide.md
# suppress:       # downgrade specific findings by risk + path (e.g. accepted legacy debt)

Copy .brooks-lint.example.yaml as a starting point. 所有设置都是可选的 - 完全省略该文件以实现默认行为。

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

"The complexity of software is an essential property, not an accidental one." — 弗雷德里克·布鲁克斯

AI 可以帮助你更快地编写代码，但它不能告诉你你正在建造一座大教堂还是一座教堂 tar pit — and the decay risks these authors identified only get sharper as generation gets cheaper. Adding an AI assistant doesn't fix cognitive overload or domain model distortion;产生更多 code increases change propagation and knowledge duplication;移动得更快会带来意外 complexity and dependency disorder more dangerous.

项目结构

Every skill is one SKILL.md (trigger + process skeleton) plus its own guide:

brooks-lint/
├── .claude-plugin/ · .codex-plugin/  # plugin metadata per platform
├── skills/
│   ├── _shared/          # common.md (Iron Law, config, report template, Health Score)
│   │                     # source-coverage.md · decay-risks.md (R1–R6)
│   │                     # test-decay-risks.md (T1–T6) · remedy-guide.md · custom-risks-guide.md
│   ├── brooks-review/    # Mode 1: PR Review          → pr-review-guide.md
│   ├── brooks-audit/     # Mode 2: Architecture Audit → architecture-guide.md, onboarding-guide.md
│   ├── brooks-debt/      # Mode 3: Tech Debt          → debt-guide.md
│   ├── brooks-test/      # Mode 4: Test Quality       → test-guide.md
│   ├── brooks-health/    # Mode 5: Health Dashboard   → health-guide.md
│   └── brooks-sweep/     # Mode 6: Full Sweep         → sweep-guide.md
├── hooks/                # SessionStart hook
├── commands/             # short-form command wrappers (auto-installed by the hook)
├── evals/                # 57-scenario eval suite + frozen parser-fidelity corpus
└── assets/               # logo, banner, demo

CI/CD 集成

使用 GitHub 操作在每个 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/[email protected]
        with:
          mode: review
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          fail-below: 70

See docs/github-action-example.yml for the full template.

The action posts the review as a PR comment and optionally fails the check if the Health Score drops below a threshold.如果 .brooks-lint-history.json 已提交到您的存储库，则注释还包括趋势增量（e.g.，“过去 3 次运行中的 85 → 82 (−3)”）。

Quality gates and Code Scanning. Beyond fail-below, the action exposes:

        with:
          mode: review
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          fail-on: critical            # fail on any Critical finding (none | warning | critical)
          fail-on-regression: true     # fail if the Health Score dropped vs the last run
          sarif-file: brooks-lint.sarif  # also upload findings to GitHub Code Scanning

fail-on-regression reads .brooks-lint-history.json, so commit that file to enforce "no new regressions". Setting sarif-file makes findings appear inline on the PR's Files changed tab and requires security-events: write permission on the job.

自定义 API 端点。 api-base-url 将操作指向任何与 Anthropic 兼容的 /v1/messages 端点（自托管代理、LLM 网关、区域镜像），而不是 api.anthropic.com。将该端点的密钥作为 anthropic-api-key 传递，并将其期望的模型 ID 作为 model 传递：

        with:
          mode: review
          api-base-url: https://your-gateway.example.com
          anthropic-api-key: ${{ secrets.GATEWAY_API_KEY }}
          model: gateway-model-id

brooks-lint 会将您的差异发送到您在此处命名的任何主机，因此仅将其指向您信任的源主机。自己运行 scripts/ci-review.mjs 根本不需要任何标志 - Anthropic SDK 直接读取 ANTHROPIC_BASE_URL。

成本： 每次 PR 运行约为 0.05–0.15 美元，具体取决于 diff 大小和型号。建议仅在 pull_request 事件上运行。

路线图

当前状态（v1.4）： 12本书基础，6个生产衰减风险（R1–R6）+ 6个测试衰减 风险 (T1–T6)、6 项技能、CI 质量门、SARIF 代码扫描输出、严格性 预设和可重现的解析器保真度基准。

Milestones v0.2 → v1.4

• v0.2–v0.4：插件基础设施、六本书框架、衰退风险维度、基准套件
• v0.5–v0.7：测试质量审查，美人鱼依赖图，.brooks-lint.yaml，10本书扩展
• v0.8–v0.9：独立技能架构；步骤验证、自动比较范围、/brooks-health、趋势跟踪、分类模式、--fix 补救措施、GitHub 操作
• v1.0–v1.2：评估自动化、自定义Cx风险代码、全面扫描技能、npm run bump版本传播
• v1.3：Codex 市场元数据、一命令多平台安装程序、本地化 READMEs + 登陆站点
• v1.4：SARIF 输出、CI 严重性 + 回归门、严格性预设、57 场景评估套件、npm run benchmark