首页 / 开源热榜 / brooks-lint / 使用教程

brooks-lint 中文教程：先用历史 PR 校准，再谈健康分门禁

官方资料核对：2026-09-23 · 文档核对，未安装、未调用模型

brooks-lint 把 12 本软件工程著作整理成 12 类代码衰退风险，并用六个 Agent Skills 执行 PR 审查、架构审计、技术债、测试质量、健康看板和全量扫描。它的输出来自语言模型，书目来源和固定格式能帮助讨论，但不能把建议自动变成事实。

版本口径：官方 workflow 记录 1.4.3 release 提交，README 的 GitHub Action 示例也使用 v1.4.3；功能说明称当前体系为 v1.4。官方可读取页面没有独立的逐条 release notes，本页不补写不存在的变更。

1. 安装前先读三个位置

先检查 skills/ 中的提示词、skills/_shared/ 的风险与来源映射，以及 scripts/install.sh 和 Claude Code hook。官方 SECURITY 说明 installer 会复制文件到用户或项目的 skills 目录，SessionStart hook 会写短命令包装。

Claude Code 可以用 marketplace 安装。Codex 首次试用更适合克隆后复制到项目范围，便于代码审查和回滚：

git clone --branch v1.4.3 https://github.com/hyhmrright/brooks-lint.git
# 阅读 skills、hooks 与 scripts 后，再按官方 Codex 路径安装

如果 tag 不存在或内容与 main 不一致，应停止并回到官方仓库核对；不要为了凑版本自行猜测提交。

2. 第一次只运行 PR Review

从一个已经由团队完成评审的小型历史 PR 开始。让 brooks-review 只读分析 diff，并保存全部 findings。逐条检查四件事：引用的文件和行是否存在，症状是否能由执行路径证明，书目概念是否适用于此处，对策是否能通过现有测试。

把 findings 分成有用、重复、错误和无法判断四类。这个统计比一次漂亮的 0–100 健康分更能说明工具是否适合仓库。

3. 用配置处理误报

version: 1
strictness: balanced
disable:
  - T5
ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

.brooks-lint.yaml 还支持严重度覆盖、focus、自定义风险和按路径 suppress。先记录为什么关闭某条风险，再设置过期日期，避免配置变成永久忽略清单。

4. Full Sweep 必须在独立分支运行

brooks-sweep 会扫描生产、测试和架构风险，并尝试应用修复。即使项目把部分修改归类为安全，也应在独立分支查看 diff、跑完整测试、检查公共接口与迁移，再逐项合并。健康分提高不代表行为保持不变。

5. 接入 CI 前确认代码去向与费用

官方 GitHub Action 使用调用方的 ANTHROPIC_API_KEY，把待审查 diff 发送到 Anthropic API。README 估算每个 PR 约 0.05–0.15 美元，但本轮没有实测。私有仓库要先审查数据政策、secret 权限、fork PR 行为和日志，再考虑 fail-below、Critical 门禁或 SARIF。

上线顺序：先只发布评论，不阻断合并；观察一段时间的误报与漏报，再决定是否启用分数或回退门禁。编译、测试、linter、SAST 和人工 review 始终保留。

6. 相比 GitHub Copilot code review 怎么选

GitHub Copilot code review 原生进入 PR reviewer、IDE、自动复审和组织策略，使用 Copilot AI credits 与 GitHub Actions 分钟。brooks-lint 的优势是风险分类、提示词和来源映射都在仓库中，可改写并安装到多个 Agent 平台。GitHub 官方也明确说 Copilot 会出错并要求人工验证；两者都不应成为唯一批准人。

7. 验证状态与验证边界

验证状态：本轮只阅读官方 README、中文 README、CLAUDE.md、SECURITY、安装说明、工作流和许可证，未安装 plugin/skills，未调用模型或 GitHub Action。

未验证：触发准确率、书目引用、健康分稳定性、57 场景 eval、parser benchmark、自动修复、SARIF、跨平台安装和费用估算。

这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。

先判断这个项目是否适合你

近期变化与关注原因

AI 代码审查常见问题是每次输出口径不同、建议难以追溯。brooks-lint 用风险编号、严重度、书目来源和固定诊断链约束模型，并提供多平台安装和 CI 门禁。关注度判断只基于项目仍在更新及其可复用的审查框架。

原教程未展开的系统信息

核心功能

  • 十二类衰退风险

    生产代码覆盖认知负荷、变更传播、知识重复、偶然复杂度、依赖失序和领域模型失真；测试侧覆盖可读性、脆弱性、重复、Mock 滥用、覆盖率错觉和架构不匹配。

  • 六种审查模式

    提供 PR Review、Architecture Audit、Tech Debt、Test Quality、Health Dashboard 和 Full Sweep。Full Sweep 可以自动应用低风险修复，但多文件、接口和架构调整应保留人工确认。

  • 多平台 Agent Skills

    同一组 Markdown skills 可安装到 Claude Code、Codex、Gemini、Cursor、Copilot、Windsurf 等平台。安装脚本主要复制 skill 文件；Claude Code 还带 SessionStart hook 生成短命令。

技术栈和运行条件

语言

Markdown/YAML skills、JavaScript/Node 验证与 benchmark、Shell 安装和 hook

框架

Agent Skills、Claude Code plugin、Gemini extension 与 GitHub Action

关键依赖

  • 所选 Agent 平台及其模型
  • CI 模式需要 Anthropic API key
  • 仓库维护与评测使用 Node/npm

运行环境

可安装到用户级或项目级 skills 目录；CI 可发布 PR 评论和 SARIF；MIT 许可

常见问题

brooks-lint v1.4.3 是传统 linter 吗？

不是。它是一组交给语言模型执行的审查 skills，关注架构、复杂度、领域模型和测试质量。ESLint、Pylint、编译器、测试和 SAST 仍需保留。

brooks-lint 的书目引用能证明 finding 正确吗？

不能。书目来源提供思考框架，但模型可能误解代码或套用概念。要核对具体文件、执行路径、测试和原书语境，再决定是否接受建议。

可以让 brooks-sweep 自动修复整个仓库吗？

可以运行，但不应无审查合并。官方区分安全修复、多文件或接口改动和人工架构决策；应在独立分支查看 diff、运行测试并逐项确认。

brooks-lint CI 会把代码发到哪里？

官方 SECURITY 说明 GitHub Action 用调用方的 ANTHROPIC_API_KEY，把待审查 diff 发送给 Anthropic API。使用私有仓库前要检查数据政策、保留范围和 secret 权限。

brooks-lint 和 GitHub Copilot code review 怎么选？

要公开可改的风险框架和跨平台 skills，可先试 brooks-lint；要 GitHub 原生 reviewer、IDE 与组织策略，Copilot review 集成更完整。两者都不能替代人工审查。

官方来源：brooks-lint · Security · 中文 README · GitHub Copilot code review