brooks-lint
植根於十二本經典工程著作的 AI 程式碼審查。
一致、可溯源、可落地。
English ·
简体中文 ·
繁體中文 ·
日本語 ·
한국어 ·
Español
快速上手 •
六類衰退風險 •
實際效果 •
基準測試 •
安裝
→ 造訪官網
---
> *"一個孩子要十月懷胎，無論派多少人去都一樣。"*
> —— Frederick Brooks，《人月神話》（1975）
**五十年過去，Brooks 依然正確——McConnell、Fowler、Martin、Hunt & Thomas、Evans、Ousterhout、Winters、Meszaros、Osherove、Feathers 以及 Google 測試團隊同樣如此。**
大多數程式碼品質工具只數行數和循環複雜度。**brooks-lint** 更進一步——它對照六個衰退風險維度（綜合自十二本經典工程著作）診斷你的程式碼，每一次都產出帶書目出處、嚴重度標籤和具體對策的結構化診斷。
完整的「書目—技能」對應（含例外與誤報防護），見
[`skills/_shared/source-coverage.md`](skills/_shared/source-coverage.md)。
## 快速上手
```bash
# 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` | 審查一個 PR 或 diff |
| `/brooks-audit` | 架構稽核（含 Mermaid 相依圖） |
| `/brooks-debt` | 排好優先順序的技術債路線圖 |
| `/brooks-test` | 測試套件品質審查 |
| `/brooks-health` | 跨所有維度的健康儀表板 |
| `/brooks-sweep` | 全維度掃描並自動修復 |
每條診斷都以 **症狀 → 根源 → 後果 → 對策** 回傳，附書目出處和 0–100 健康分。完整安裝方式（另外 8 個平台）、逐命令用法、CI/CD 設定見[下文](#安裝)。
## 十二本書
| 書名 | 作者 | 貢獻於 |
|------|--------|----------------|
| *The Mythical Man-Month*（人月神話） | Frederick Brooks | R2、R4、R5 |
| *Code Complete*（程式碼大全） | Steve McConnell | R1、R4 |
| *Refactoring*（重構） | Martin Fowler | R1、R2、R3、R4、R6 |
| *Clean Architecture*（無瑕的程式碼：整潔的軟體設計與架構篇） | Robert C. Martin | R2、R5 |
| *The Pragmatic Programmer*（務實的程式設計師） | Hunt & Thomas | R2、R3、R4、R5、T2、T3 |
| *Domain-Driven Design*（領域驅動設計） | Eric Evans | R1、R3、R6 |
| *A Philosophy of Software Design*（軟體設計的哲學） | John Ousterhout | R1、R4 |
| *Software Engineering at Google*（Google 軟體工程） | Winters, Manshreck & Wright | R2、R5 |
| *The Art of Unit Testing*（單元測試的藝術） | Roy Osherove | T1、T2、T4、T5 |
| *How Google Tests Software*（Google 測試之道） | Whittaker, Arbon & Carollo | T5、T6 |
| *Working Effectively with Legacy Code*（修改軟體的藝術） | Michael Feathers | T4、T5、T6 |
| *xUnit Test Patterns*（xUnit 測試模式） | 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 等）
## 實際效果
給定這段程式碼：
```python
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，綠=乾淨。
```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 環境中原生算繪——無需額外工具。
## 更多範例
[完整畫廊](docs/gallery.md) 收錄了 brooks-lint 在 Python、TypeScript、Go、Java 上的真實輸出——涵蓋 PR 審查、帶 Mermaid 相依圖的架構審查、技術債評估和測試品質審查。
初次接觸這些衰退風險？[**衰退風險實戰指南**](https://hyhmrright.github.io/brooks-lint/guide.html) 逐一講解全部六類——每類的診斷問題、代表症狀、出處書目與對策。
---
## 基準測試
在 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 報告（例如一個*看起來像*循環相依、實則是埠與配接器（ports-and-adapters）的設計），它們必須保持乾淨。
**評分確定性** —— 給定一組固定發現（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（推薦）
#### 透過外掛市集
```bash
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
```
短命令（`/brooks-review`）會在首次工作階段啟動時自動安裝。手動安裝：
```bash
bash hooks/session-start
```
#### 手動安裝
```bash
mkdir -p ~/.claude/skills/brooks-lint
cp -r skills/* ~/.claude/skills/brooks-lint/
```
### Gemini CLI
#### 透過擴充功能
```bash
/extensions install https://github.com/hyhmrright/brooks-lint
```
#### 手動安裝
```bash
mkdir -p ~/.gemini/skills
cp -r skills/* ~/.gemini/skills/ # 扁平——Gemini 只探索一層深的技能
```
> 或直接：`./scripts/install.sh gemini`
### Codex CLI
#### 透過技能安裝器（在 Codex 工作階段中）
```
Install the brooks-lint skill from hyhmrright/brooks-lint
```
#### 命令列
```bash
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
--repo hyhmrright/brooks-lint --path skills --name brooks-lint
```
#### 手動安裝
```bash
git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint
mkdir -p ~/.codex/skills
cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/ # 扁平——與技能安裝器佈局一致
```
> 或直接：`./scripts/install.sh codex`
### 更多平台——OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid
brooks-lint 以標準 [Agent Skills](https://agentskills.io) 形式散布。**任何載入 Agent Skills 的 agent
都能無需任何轉換執行全部六種模式**——一條命令即可安裝：
```bash
# 選擇你的平台；加 --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` 自動觸發。
不熟悉 skills、或用的是別的 agent？見 **[docs/getting-started.md](docs/getting-started.md)**。
OpenCode
`./scripts/install.sh opencode` → `~/.config/opencode/skills`（同時讀取 `~/.claude/skills` 與
`AGENTS.md`）。完整指南：[docs/opencode-setup.md](docs/opencode-setup.md)。
Cursor（2.4+）
`./scripts/install.sh cursor` → `~/.cursor/skills`（也讀 `.agents/skills`；讀取 `AGENTS.md`）。
完整指南：[docs/cursor-setup.md](docs/cursor-setup.md)。
Windsurf（Cascade）
`./scripts/install.sh windsurf` → `~/.codeium/windsurf/skills`（讀取 `AGENTS.md`）。
完整指南：[docs/windsurf-setup.md](docs/windsurf-setup.md)。
Antigravity（Google）
`./scripts/install.sh antigravity --project` → `.agent/skills`（讀取 `AGENTS.md` / `GEMINI.md`）。
完整指南：[docs/antigravity-setup.md](docs/antigravity-setup.md)。
pi（earendil-works）
`./scripts/install.sh pi` → `~/.pi/agent/skills`，或讓 pi 的 `skills` 設定指向一個克隆。
完整指南：[docs/pi-setup.md](docs/pi-setup.md)。
GitHub Copilot
`./scripts/install.sh copilot --project` → `.github/skills`（也自動辨識 `.claude/skills`；讀取
`AGENTS.md`）。完整指南：[docs/copilot-setup.md](docs/copilot-setup.md)。
Kiro（AWS）
`./scripts/install.sh kiro` → `~/.kiro/skills`（自動註冊 `/brooks-review`；讀取 `AGENTS.md`）。
完整指南：[docs/kiro-setup.md](docs/kiro-setup.md)。
Factory Droid
`./scripts/install.sh droid` → `~/.factory/skills`（註冊 `/brooks-review`；讀取 `AGENTS.md`）。
完整指南：[docs/factory-droid-setup.md](docs/factory-droid-setup.md)。
⭐ 如果這個工具讓你以不同的眼光看待自己的程式碼庫，請給它點個 star！