csh/playbook

Fork 0

Files

T

ci[bot] 0a12711d78 📦 deps(thirdparty): update snapshots

2026-08-12 08:38:22 +08:00

25 KiB

Raw Blame History

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。

快速上手

# 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、/brooks-audit、 /brooks-debt、/brooks-test、/brooks-health、/brooks-sweep（各自的作用）。

每條診斷都以 症狀 → 根源 → 後果 → 對策 回傳，附書目出處和 0–100 健康分。完整安裝方式（另外 8 個平台）和 CI/CD 設定見下文。

十二本書

書名	作者	貢獻於
The Mythical Man-Month（人月神話，1975）	Frederick P. Brooks Jr.	R2、R4、R5
Code Complete（程式碼大全，1993，第 2 版 2004）	Steve McConnell	R1、R4
Refactoring（重構，1999，第 2 版 2018）	Martin Fowler	R1、R2、R3、R4、R6
Clean Architecture（無瑕的程式碼：整潔的軟體設計與架構篇，2017）	Robert C. Martin	R2、R5
The Pragmatic Programmer（務實的程式設計師，1999，20 週年版 2019）	Andrew Hunt & David Thomas	R2、R3、R4、R5、T2、T3
Domain-Driven Design（領域驅動設計，2003）	Eric Evans	R1、R3、R6
A Philosophy of Software Design（軟體設計的哲學，2018）	John Ousterhout	R1、R4
Software Engineering at Google（Google 軟體工程，2020）	Winters, Manshreck & Wright	R2、R5
The Art of Unit Testing（單元測試的藝術，2009，第 3 版 2023）	Roy Osherove	T1、T2、T4、T5
How Google Tests Software（Google 測試之道，2012）	Whittaker, Arbon & Carollo	T5、T6
Working Effectively with Legacy Code（修改軟體的藝術，2004）	Michael Feathers	T4、T5、T6
xUnit Test Patterns（xUnit 測試模式，2007）	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 等）

實際效果

給定這段程式碼：

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，綠=乾淨。

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 環境中原生算繪——無需額外工具。

基準測試

在 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（推薦）

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

短命令（/brooks-review）會在首次工作階段啟動時自動安裝——也可以自己跑 bash hooks/session-start。不想走市集：mkdir -p ~/.claude/skills/brooks-lint && cp -r skills/* ~/.claude/skills/brooks-lint/。

Gemini CLI · Codex CLI

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

Install the brooks-lint skill from hyhmrright/brooks-lint       # 在 Codex 工作階段中直接說

或使用下面的安裝器：./scripts/install.sh gemini / ./scripts/install.sh codex。

其他所有平台——OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid

brooks-lint 以標準 Agent Skills 形式散布。任何載入 Agent Skills 的 agent 都能無需任何轉換執行全部六種模式——一條命令即可安裝：

# 選擇你的平台；加 --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 自動觸發。

平台	安裝到	同時讀取	指南
OpenCode	`~/.config/opencode/skills`	`~/.claude/skills`、`AGENTS.md`	設定
Cursor（2.4+）	`~/.cursor/skills`	`.agents/skills`、`AGENTS.md`	設定
Windsurf（Cascade）	`~/.codeium/windsurf/skills`	`AGENTS.md`	設定
Antigravity（Google）	`.agent/skills`（`--project`）	`AGENTS.md`、`GEMINI.md`	設定
pi（earendil-works）	`~/.pi/agent/skills`	—	設定
GitHub Copilot	`.github/skills`（`--project`）	`.claude/skills`、`AGENTS.md`	設定
Kiro（AWS）	`~/.kiro/skills`	`AGENTS.md`	設定
Factory Droid	`~/.factory/skills`	`AGENTS.md`	設定

Kiro 與 Factory Droid 還會自動註冊 /brooks-review。不熟悉 skills、或用的是上面沒列出的 agent？見 docs/getting-started.md。

🧪 驗證狀態。 Claude Code、Gemini CLI、Codex CLI 已由維護者驗證。上面八個平台依據各工具官方技能規範撰寫，並已在檔案佈局層面驗證（安裝器經過測試），但維護者尚未在每個平台端到端實跑。在某平台試過了——無論成功還是失敗？請提一個 issue，附上平台、版本和你看到的結果。用的是其他相容 Agent Skills 的 agent？它幾乎肯定以同樣方式運作——告訴我們，我們會補上。

斜線命令

命令	作用
`/brooks-review`	貼上一段 diff，或讓 AI 指向改動的檔案。以症狀 → 根源 → 後果 → 對策的格式逐一診斷六類衰退風險。
`/brooks-audit`	梳理模組相依（附 Mermaid 相依圖）、辨識循環相依，並檢查是否符合康威定律。
`/brooks-debt`	按六類衰退風險對技術債分類，以痛感 × 擴散面打優先級，產出帶 Critical / Scheduled / Monitored 分級的償還路線圖。
`/brooks-test`	對照六類測試空間衰退風險審查測試套件——測試晦澀、測試脆弱、測試重複、Mock 濫用、覆蓋率幻覺、架構錯配。
`/brooks-health`	對全部四個品質維度做精簡掃描，產出一個加權綜合健康分。適合發版前或新團隊上手時使用。
`/brooks-sweep`	一次性掃描 R1–R6、T1–T6 與架構，然後施加修復：安全改動自動套用，跨檔案改動需確認，架構決策標記為人工處理項。輸出修復日誌與健康分變化。

各平台語法。 Claude Code 也接受帶命名空間的完整形式 /brooks-lint:brooks-review——短命令由 session-start 鉤子在首次工作階段啟動時自動安裝。Codex CLI 用 $brooks-review。Gemini CLI 直接用上表。 OpenCode、Cursor、Antigravity、pi 依據每個技能的 description 自動呼叫 Agent Skills，直接提問即可（「審查這個 PR」、「我們最糟的技術債在哪」）；需要顯式呼叫時用各平台自己的語法（pi 把每個技能註冊為 /skill:brooks-review）。在所有平台上，當你討論程式碼品質、架構或測試健康時，這些技能也會自動觸發。

PR 審查會自動包含一個輕量的第 7 步快速測試檢查（對純文件 diff 會跳過）。需要完整的測試稽核請用 /brooks-test；需要某個維度的深度診斷時，請用該維度的專項技能，而不是 /brooks-health。

設定

在專案根目錄放一個 .brooks-lint.yaml 來客製化審查行為：

version: 1

strictness: balanced   # strict | balanced（預設）| legacy-friendly——對遺留程式碼更寬鬆的評分

disable:
  - T5   # 略過覆蓋率指標檢查——我們不強制覆蓋率

severity:
  R1: suggestion   # 在該領域下調「認知過載」診斷的嚴重度

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

# custom_risks:   # 定義專案專屬 Cx 風險碼——見 skills/_shared/custom-risks-guide.md
# suppress:       # 按風險碼 + 路徑下調特定診斷（如已接受的遺留債務）

可複製 .brooks-lint.example.yaml 作為起點。所有設定均為選用——完全省略該檔案即使用預設行為。

設定	說明
`strictness`	評分預設：`strict`、`balanced`（預設）或 `legacy-friendly`（更輕的扣分，並優先列出高槓桿修復項）
`disable`	要略過的風險碼（`R1`–`R6`、`T1`–`T6`）
`severity`	覆寫嚴重度等級（`critical` / `warning` / `suggestion`）
`ignore`	要排除的檔案 glob 模式
`focus`	只評估這些風險碼（不能與 `disable` 同時使用）
`custom_risks`	定義專案專屬風險碼（`C1`、`C2`……）——見 `custom-risks-guide.md`
`suppress`	按風險碼 + 路徑下調特定診斷的嚴重度（可帶 `expires:` 到期日期）

為什麼是這些書，為什麼是現在？

「軟體的複雜性是本質屬性，而非偶然屬性。」 —— Frederick Brooks

AI 能幫你更快地寫程式，卻無法告訴你正在建造的是大教堂還是焦油坑——而生成越廉價，這些作者辨識出的衰退風險就越尖銳。接入 AI 助手並不能修復認知超載或領域模型失真；生成更多程式碼會加劇變更擴散和知識重複；跑得更快讓偶發複雜度和相依失序更加危險。

專案結構

每個技能都是一個 SKILL.md（觸發條件 + 流程骨架）加上它自己的指南：

brooks-lint/
├── .claude-plugin/ · .codex-plugin/  # 各平台外掛中繼資料
├── skills/
│   ├── _shared/          # common.md（鐵律、設定、報告範本、健康分）
│   │                     # source-coverage.md · decay-risks.md（R1–R6）
│   │                     # test-decay-risks.md（T1–T6）· remedy-guide.md · custom-risks-guide.md
│   ├── brooks-review/    # 模式 1：PR 審查      → pr-review-guide.md
│   ├── brooks-audit/     # 模式 2：架構稽核     → architecture-guide.md、onboarding-guide.md
│   ├── brooks-debt/      # 模式 3：技術債       → debt-guide.md
│   ├── brooks-test/      # 模式 4：測試品質     → test-guide.md
│   ├── brooks-health/    # 模式 5：健康儀表板   → health-guide.md
│   └── brooks-sweep/     # 模式 6：全面掃描     → sweep-guide.md
├── hooks/                # SessionStart 鉤子
├── commands/             # 短命令包裝（由鉤子自動安裝）
├── evals/                # 57 情境評測套件 + 凍結的 parser 保真度語料
└── assets/               # logo、banner、demo

CI/CD 整合

用 GitHub Action 在每個 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/brooks-lint@v1.4.3
        with:
          mode: review
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          fail-below: 70

完整範本見 docs/github-action-example.yml。

該 Action 會把審查結果作為 PR 留言發布，並可在健康分跌破閾值時讓檢查失敗。若儲存庫中提交了 .brooks-lint-history.json，留言還會包含趨勢變化（如 "85 → 82（−3），近 3 次執行"）。

品質閘門與 Code Scanning。 除 fail-below 外，該 Action 還提供：

        with:
          mode: review
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          fail-on: critical            # 出現任何 Critical 即失敗（none | warning | critical）
          fail-on-regression: true     # 健康分較上次執行下降則失敗
          sarif-file: brooks-lint.sarif  # 同時把診斷上傳到 GitHub Code Scanning

fail-on-regression 讀取 .brooks-lint-history.json，因此提交該檔案即可強制「無新增回歸」。設定 sarif-file 會讓診斷直接顯示在 PR 的 Files changed 分頁，並需要 job 具備 security-events: write 權限。

成本： 每次 PR 執行約 $0.05–0.15，取決於 diff 大小和模型。建議僅在 pull_request 事件上執行。

路線圖

當前狀態（v1.4）： 12 本書地基，6 類生產衰退風險（R1–R6）+ 6 類測試衰退風險（T1–T6），6 個技能， CI 品質閘門、面向 GitHub Code Scanning 的 SARIF 輸出、嚴格度預設，以及一個可復現的 parser 保真度基準。

里程碑 v0.2 → v1.4

v0.2–v0.4：外掛基礎設施、六本書框架、衰退風險維度、基準套件
v0.5–v0.7：測試品質審查、Mermaid 相依圖、.brooks-lint.yaml、擴展到 10 本書
v0.8–v0.9：獨立技能架構；步驟驗證、自動 diff 範圍、/brooks-health、趨勢追蹤、分診模式、--fix 對策、GitHub Action
v1.0–v1.2：評測自動化、自訂 Cx 風險碼、全面掃描技能、npm run bump 版本傳播
v1.3：Codex 市集中繼資料、多平台一鍵安裝腳本、多語 README + 著陸頁
v1.4：SARIF 輸出、CI severity + 迴歸閘門、嚴格度預設、57 情境 eval 套件、npm run benchmark

貢獻

見 CONTRIBUTING.md。現在最有價值的貢獻是新的評測用例和更好的衰退風險症狀模式。在你自己的 PR 上跑一遍 /brooks-review——我們用正在打造的工具來審查貢獻。

授權條款

MIT License——詳見 LICENSE。

致謝

本專案站在十二位巨人的肩膀上——完整書單與版本見上面的十二本書。本工具中編碼的衰退風險，是我們對他們思想的綜合，並應用於現代程式碼品質評估。

Star 歷史

⭐ 如果這個工具讓你以不同的眼光看待自己的程式碼庫，請給它點個 star！

25 KiB Raw Blame History Unescape Escape