夜雨聆风一个 CL 命令，28/100 健康分，十二本经典工程著作的诊断依据
很多工程师都有过这样的经历：一段代码看起来“能用”，但团队维护它越来越吃力。改一处，炸一片；加新功能，改老逻辑；半年后没人敢动，一年后重写。
传统的 Linter（ESLint、Pylint）只检查语法和风格错误，它们抓不住架构漂移、领域模型失真、知识孤岛等问题——而这些问题往往在无人察觉的几个月里持续拖慢团队。
brooks-lint 正是为此而生。
它不是一个简单的代码检查工具，而是一个植根于十二本经典软件工程著作的 AI 代码审查系统。你只需一条命令，就能得到一份带有健康分（0–100）、书目出处、症状 → 根源 → 后果 → 对策结构化诊断的报告。
一、它解决的问题：六类衰退风险
brooks-lint 从六个维度诊断你的代码，每一个维度都来自经典著作的沉淀：
这些维度不是凭空发明的，而是从十二本经典著作中提炼出来的——从 Brooks 的《人月神话》（1975）到 Winters 等人的《Google 软件工程》（2020）。
二、实际效果：一段代码，28/100 分
来看一个例子。这是 AI 代码生成时代常见的一段 Python：
classUserService:
defupdate_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
self.smtp.send(...)
points = user['login_count'] * 10 + 500
self.db.execute(f"UPDATE loyalty SET points={points} WHERE user_id={user_id}")
/brooks-review 命令的输出：
健康分：28/100
这个方法把四个不相干的业务职责塞进同一个函数，含有一个会静默吞掉“邮箱变更通知”的逻辑 bug，并且对 SQL 注入门户大开。
🔴 变更扩散
症状：update_profile 在同一个方法体里完成资料字段更新、邮箱变更通知、积分重算和缓存失效。
根源： Fowler — 《重构》— 发散式变更；Hunt & Thomas — 《程序员修炼之道》— 正交性
后果： 任何对积分公式的改动都可能破坏邮件通知，反之亦然。每次修改都同时背负着四个不相干领域的回归风险。
对策： 抽出 NotificationService、LoyaltyService 和 UserCacheInvalidator。UserService.update_profile 应只做编排。
🔴 领域模型失真
症状：user['email'] = email 在 if user['email'] != email 之前就覆盖了旧值——条件恒为 False，通知是死代码。
根源： McConnell — 《代码大全》— 第 17 章：非常规控制结构
后果： 用户改邮箱时永远收不到通知。这是静默的数据完整性失效。
对策： 在任何修改之前先捕获 old_email = user['email']，拿它（而非 user['email']）做比较。
（另有 6 条诊断，含 SQL 注入、依赖失序、魔法数字）
三、架构审查：带依赖图的可视化诊断
在架构审查模式（/brooks-audit）下，brooks-lint 会生成一张 Mermaid 依赖图，模块按严重度着色：红=Critical，黄=Warning，绿=Clean。
这张图在 GitHub、Notion 等 Markdown 环境中原生渲染，无需额外工具。一眼就能看出循环依赖和依赖倒置的位置。
四、基准测试：94% vs 16%
在 3 个真实场景（PR 审查、架构审查、技术债评估）上测试：
| 整体通过率 | 94% | 16% |
差距不在于 AI 能不能发现问题——而在于它能否每一次都稳定地发现，并附上可溯源的证据和可落地的对策。
这就是 brooks-lint 的核心价值：把零散、偶发的 AI 代码审查，变成稳定、可复现、有依据的工程实践。
五、横向对比：和传统工具有什么区别？
brooks-lint 不是要取代你的 Linter。 它捕捉的是 Linter 抓不到的东西——架构漂移、知识孤岛、领域模型失真。
六、安装与使用：一条命令搞定
Claude Code（推荐）
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
安装后，短命令自动生效：
/brooks-review | |
/brooks-audit | |
/brooks-debt | |
/brooks-test | |
/brooks-health | |
/brooks-sweep |
其他平台
brooks-lint 以标准 Agent Skills 形式分发，支持：
Gemini CLI · Codex CLI · OpenCode · Cursor · Windsurf · Antigravity · pi · GitHub Copilot · Kiro · Factory Droid
一条命令安装：
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <平台>
项目级配置
在项目根目录放一个 .brooks-lint.yaml：
version:1
disable:
-T5# 跳过覆盖率指标检查
severity:
R1:suggestion# 下调“认知过载”的严重度
ignore:
-"**/*.generated.*"
-"**/vendor/**"
七、为什么是这些书，为什么是现在？
在 AI 辅助编程的时代，我们写代码比以往任何时候都更快、更多。但六十年软件工程沉淀下来的洞见并没有改变：
“软件的复杂性是本质属性，而非偶然属性。”—— Frederick Brooks
AI 能帮你更快地写代码，却无法告诉你正在建造的是大教堂还是焦油坑。brooks-lint 弥合了这道鸿沟——它把十二本经典工程著作中来之不易的智慧，带进你现代的开发工作流。
这些作者识别出的衰退风险，如今比以往更切题：
接入 AI 助手并不能修复认知过载或领域模型失真； 生成更多代码会加剧变更扩散和知识重复； 跑得更快让偶发复杂度和依赖失序更加危险。
八、结语
brooks-lint 不是要告诉你怎么写代码——它让你用六十年软件工程的集体智慧来审视自己的代码。
“一个孩子要十月怀胎，无论派多少人去都一样。”—— Frederick Brooks，《人月神话》（1975）
五十年过去，Brooks 依然正确。McConnell、Fowler、Martin、Hunt & Thomas、Evans、Ousterhout、Winters、Meszaros、Osherove、Feathers 以及 Google 测试团队同样如此。
如果你想让团队在 AI 时代写出更可维护的代码，不妨试试 brooks-lint。
⭐ 如果这个工具让你以不同的眼光看待自己的代码库，欢迎前往 GitHub 点个 Star！
GitHub：hyhmrright/brooks-lint | 官网：https://hyhmrright.github.io/brooks-lint/
本文内容基于 brooks-lint v1.3.0