brooks-lint

dsh plugin --profile web add brooks-lint

<p align="center">

<img src="assets/logo.svg" alt="brooks-lint" width="200">

</p>

<h1 align="center">brooks-lint</h1>

<p align="center">

<strong>植根於十二本經典工程著作的 AI 程式碼審查。<br>

一致、可溯源、可落地。</strong>

</p>

<p align="center">

<a href="README.md">English</a> ·

<a href="README.zh-CN.md">简体中文</a> ·

<strong>繁體中文</strong> ·

<a href="README.ja.md">日本語</a> ·

<a href="README.ko.md">한국어</a> ·

<a href="README.es.md">Español</a>

</p>

<p align="center">

<a href="#快速上手">快速上手</a> •

<a href="#六類衰退風險">六類衰退風險</a> •

<a href="#實際效果">實際效果</a> •

<a href="#基準測試">基準測試</a> •

<a href="#安裝">安裝</a>

</p>

<p align="center">

<img src="https://img.shields.io/badge/version-1.9.1-blue.svg" alt="Version">

<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">

<img src="https://img.shields.io/badge/Claude_Code-Plugin-blueviolet.svg" alt="Claude Code Plugin">

<img src="https://img.shields.io/badge/Codex_CLI-Skill-orange.svg" alt="Codex CLI Skill">

<img src="https://img.shields.io/github/stars/hyhmrright/brooks-lint?style=social" alt="GitHub Stars">

</p>

<p align="center">

<a href="https://trendshift.io/repositories/47738" target="_blank"><img src="https://trendshift.io/api/badge/trendshift/repositories/47738/daily?language=JavaScript" alt="Trendshift 當日 JavaScript 儲存庫排行榜第 2 名" style="width: 250px; height: 55px;" width="250" height="55"/></a>

</p>

<p align="center">

<img src="assets/banner-zh-TW.svg" alt="你的程式碼 → 十二本經典 → 十二類衰退風險 → 帶出處的結論" width="900">

</p>

<p align="center">

<a href="https://hyhmrright.github.io/brooks-lint/"><img src="assets/demo.gif" alt="brooks-lint 審查程式碼：一條 /brooks-review 命令產出 28/100 健康分以及引用書目的 症狀 → 根源 → 後果 → 對策 診斷" width="820"></a>

</p>

<p align="center">

<strong><a href="https://hyhmrright.github.io/brooks-lint/">→ 造訪官網</a></strong>

</p>

---

"一個孩子要十月懷胎，無論派多少人去都一樣。"

—— 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)。

快速上手

# Claude Code
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

# 其他任意 Agent Skills 平台 —— Cursor · Codex · Gemini · Copilot · Windsurf · OpenCode · Kiro · Bob …
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 健康分。完整安裝方式（另外 10 個

平台）和 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
  

…(truncated)