hyhmrright/brooks-lint

Portable AI code quality reviews for Codex, Cursor, Copilot and other coding agents: six Agent Skills for architecture, technical debt, tests and remediation.

概述

brooks-lint 是一个工具，让你可以在各种代理平台（Claude、Gemini、Codex、Cursor 等）上运行 AI 驱动的代码审查“技能”。它不检查语法或风格；相反，它根据作者从十二本经典软件工程书籍（例如 人月神话、整洁架构、重构）中提炼出的六个衰退风险维度来评估生产代码和测试套件。对于每个风险，它都会生成一个结构化的发现：

症状 → 来源 → 后果 → 补救措施

每个发现都引用原始书籍，标有严重性（🔴 严重，🟡 警告，🟢 建议），并计入总体健康评分（0-100）。该工具还可以生成架构图（Mermaid）、债务排名表，以及自动应用安全修复的“清扫”模式。

该包以 Agent-Skills 形式分发，可以通过一个微型安装脚本安装在许多 AI 助手平台上。安装后，你可以调用六个斜杠命令之一（/brooks-review、/brooks-audit 等），或让助手“审查这个 PR”。

主要功能

功能	作用	重要性
六个衰退风险维度	认知过载、变更传播、知识重复、意外复杂性、依赖混乱、领域模型扭曲（加上六个测试套件风险）	提供基于书籍的、有原则的代码健康视图，超越行数指标
结构化发现	每个问题都报告为症状 → 来源 → 后果 → 补救措施，并引用经典书籍	使反馈对开发人员和审查者具有可追溯性和可操作性
健康评分（0-100）	使用可配置的严格度预设（严格、平衡、遗留友好）聚合严重性计数	为 PR、发布或整个仓库提供快速、可比较的健康指标
架构审计	生成 Mermaid 依赖图，突出循环和康威定律不匹配	帮助发现 linter 遗漏的高层设计漂移
技术债务路线图	按痛苦 × 扩散对发现进行排名，并将其分组为严重 / 计划 / 监控层级	为团队提供具体的增量改进计划
测试套件审计	检查测试模糊性、脆弱性、重复、模拟滥用、覆盖幻觉、架构不匹配	将相同的风险模型扩展到测试代码库
自动修复 / 清扫模式	自动应用安全的单文件修复；较大的更改记录以供手动审查	减少低风险问题的手动工作量
多平台 Agent-Skills	可通过单个脚本安装在 Claude、Gemini、Codex、Cursor、OpenCode、Windsurf、IBM Bob 等上	让团队无论偏好哪个 AI 助手，都能使用相同的审查逻辑
零配置默认	开箱即用；可选的 `.brooks-lint.yaml` 用于自定义严格度、禁用风险、忽略模式	降低采用门槛

工作原理（高层流程）

安装 – 使用目标平台名称运行提供的 install.sh 脚本（例如 bash scripts/install.sh codex）。该脚本将技能文件复制到平台的技能目录中。
调用 – 在聊天/IDE 中，发出斜杠命令（/brooks-review）或直接让助手审查 PR。
模型调用 – 技能将相关代码（差异、整个文件或依赖图）发送到底层 LLM（Claude、Gemini 等），并附带一个提示，其中编码了六个风险问题和引用风格。
解析 – LLM 返回 Markdown 报告。brooks-lint 的解析器提取每个发现，将其映射到规范的风险代码，并计算严重性计数。
评分与输出 – 工具将计数聚合为健康评分，可选地渲染 Mermaid 图，并将结构化报告返回给用户。
可选清扫 – 在 /brooks-sweep 模式下，工具尝试应用可安全自动化的“补救措施”步骤，然后报告“修复日志”和更新后的评分。

典型用例

场景	命令	你得到什么
拉取请求审查	`/brooks-review`	针对更改文件的衰退风险发现列表，每个都附带书籍引用和修复建议，以及 PR 的健康评分。
架构健全性检查	`/brooks-audit`	Mermaid 依赖图、循环依赖警告，以及与模块耦合和依赖方向相关的风险发现。
技术债务分类	`/brooks-debt`	排名的债务项、痛苦 × 扩散分数，以及路线图（严重 / 计划 / 监控）。
测试套件健康	`/brooks-test`	针对测试代码的发现（模糊性、脆弱性、模拟滥用等），以及重构测试的建议。
快速健康快照	`/brooks-health`	所有维度的综合健康评分 – 在发布前或入职时很有用。
自动清理	`/brooks-sweep`	自动应用安全修复，生成修复日志，并显示健康评分的差异。

安装快速入门

# 以 Codex CLI 平台为例
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh \
  | bash -s -- codex

该脚本将技能文件复制到适当的 ~/.codex/skills（或等效）文件夹，并注册六个斜杠命令。对于 Claude Code、Gemini CLI 或任何其他列出的代理，将 codex 替换为平台名称。

如果你更喜欢手动安装 Claude Code：

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

安装后，只需让助手“审查这个 PR”或运行其中一个斜杠命令。

配置（可选）

在仓库根目录创建 .brooks-lint.yaml 以调整行为：

version: 1
strictness: balanced   # strict | balanced (默认) | legacy-friendly
disable:
  - T5                 # 跳过覆盖率指标检查
severity:
  R1: suggestion       # 降级认知过载发现
ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

strictness 更改健康评分的计算方式。
disable 可以关闭特定的风险类别。
severity 允许你为特定项目重新标记风险。
ignore 使用 glob 模式排除生成或供应商文件。

限制与未解决问题

限制	详情
依赖 LLM 质量	发现的准确性取决于底层模型（Claude、Gemini 等）。仓库提供了确定性解析基准，但发现的语义正确性仍然依赖于模型。
平台验证	维护者指出不再进行 Claude Code 测试；只有 Codex 相关功能得到积极验证。鼓励社区对其他平台进行测试。
语言无关但非语言感知	brooks-lint 适用于任何语言，因为它将代码视为文本，但它无法利用特定语言的 AST 信息，因此与语言感知的静态分析器相比，可能会遗漏某些模式。
基准数字是说明性的	README 声明基准表是“说明性的”，实时评估数字可能会有所不同。
不能替代传统 linter	它旨在补充而非替代 ESLint、Pylint 或静态分析套件等工具。

谁可能受益？

工程经理 希望跨多个仓库获得高层健康指标。
Dev-ops / CI 管道 希望在合并前设置 AI 驱动的质量门禁。
个人开发者 希望获得可操作、有书籍依据的审查评论，而无需阅读原始文本。
使用多个 AI 助手的团队 – 相同的技能适用于 Claude、Gemini、Codex、Cursor 等，提供一致的反馈。

底线

brooks-lint 将经典软件工程智慧与现代基于 LLM 的代码审查相结合。它提供跨六个明确定义的衰退风险的结构化、引用丰富的发现，生成综合健康评分，甚至可以自动应用安全修复。虽然它不能替代传统 linter，但它增加了许多 AI 辅助审查者遗漏的架构和设计层面的宝贵见解。

以上所有信息均直接取自仓库的 README；未添加任何外部假设。