AI Agent 時代的程式碼整潔之道：拆解與實測 Uncle Bob 的 Clean Code Sub-mode

Cover

SOURCE | 資訊源評估

準確性: 極高 - 資深工程師龍海基於 Robert C. Martin (Uncle Bob) 最新開源專案 ub-mode 及四個配套工具原始碼，在開源專案（oh-my-x）中完整實測與修復。
易理解性: 高 - 對比傳統物件導向與現代 AI 提示詞工程，系統拆解了 Agent 防禦約束、三大命令列門禁、AST 結構指紋相似度與變異測試原理。
閱讀策略建議: 後端架構師必讀。重點借鑑其將主觀工程經驗轉化為 Agent 量化門禁（CRAP < 10、AST 相似度 < 0.8、Mutator 退出碼 0）。

NAPKIN | 餐巾紙

餐巾紙公式

$$\text{CRAP} = \text{CC}^2 \times (1 - \text{coverage})^3 + \text{CC} \quad (\text{Constraint: } \text{CRAP} < 10)$$

公式白話解析：CRAP 評分以圈複雜度（CC）為底線，覆蓋率為阻尼器。當圈複雜度 $\text{CC} \ge 10$ 時，即便覆蓋率 100%，得分仍為 10，單靠補測試絕無法達標，強制 Agent 必須拆分函數。

一句話

Vibe Coding 降低了生成程式碼門檻，卻未降低維護複雜度；將工程紀律轉化為 Agent 量化門禁，才是大模型時代交付可靠系統的支點。

行動觸發：在 Agent 工作流引入 ub-mode，並將 crapper（CRAP < 10）與 mutator 配置在每次特徵提交前強制執行。

餐巾紙草圖

┌──
│ Uncle Bob 的 ub-mode 三層治理架構
│ ├── 第一階段：先讓功能可用 (First Make it Work)
│ │   ├── 最小改動約束 (Laziness) ──▶ 單一決策點、最小編輯量
│ │   ├── 前置型別設計 (Data Shape) ──▶ 型別鎖死非法狀態、入口解析一次
│ │   └── 邊界防禦與 TDD ──▶ 核心邏輯純函數、紅綠循環、單一寫入者 (One Writer)
│ ├── 第二階段：再把程式碼寫好 (Then Make it Right)
│ │   ├── crapper ──▶ 圈複雜度 + 覆蓋率計算，強制 CRAP < 10 (限制分支膨脹)
│ │   ├── dryer ──▶ AST 結構指紋 Jaccard 相似度，消除相似度 >= 0.8 重複
│ │   └── mutator ──▶ 注入變異體壓力測試，阻斷存活變異體 (Kill survivors)
│ └── 第三階段：工程實踐 (Follow Practice)
│     └── 操作日誌、守衛上下文視窗、Worktree 清理、小步規範提交
└──

ROUND 1: SKELETON | 骨架掃描

“這本書在說什麼”

核心問題: 為什麼依賴自然語言生成程式碼（Vibe Coding）在專案擴大後，會引發邏輯碎片化、狀態失控與技術債雪崩？
核心答案: Uncle Bob 將軟體品質紀律轉化為給 AI Agent 的 152 行 ub-mode 規範，結合前置型別約束與三項量化工具，重構開發閉環。
論證結構: Vibe Coding 困境 $\rightarrow$ 第一階段前置型別防禦 $\rightarrow$ 第二階段三大工具度量 $\rightarrow$ 第三階段工程實踐 $\rightarrow$ 真實專案實測驗證。

章節骨架

背景：Uncle Bob 與從 Clean Code 到 AI Agent 的典範轉移
第一階段：先讓功能可用（最小改動、型別防禦與 TDD）
第二階段：再把程式碼寫好（crapper、dryer、mutator 與 uml-viewer）
第三階段與實戰：工程規範守則與 oh-my-x 開源專案重構閉環

ROUND 2: DISSECTION | 血肉解剖

“憑什麼這麼說”

論證鏈

┌──
│ [無約束 Vibe Coding] ──▶ [分支無限疊加、虛高行覆蓋率] ──▶ [維護成本飆升、迴歸缺陷爆發]
│         ▼
│ [引入 ub-mode 前置約束] ──▶ [型別鎖死非法狀態 + TDD 最小實現] ──▶ [邊界清晰]
│         ▼
│ [執行量化門禁檢測] ──▶ [crapper 抓高複雜度、dryer 抓結構重複、mutator 殺假測試]
│         ▼
│ [Agent 驅動約束重構] ──▶ [拆分單體純函數 + 補齊邊界斷言] ──▶ [CRAP < 10 且變異體全滅]
│         ▼
│ [工作區紀律管理] ──▶ [守衛上下文視窗 + 規範 Git 提交] ──▶ [生產級可靠交付]
└──

關鍵證據與量化數據

CRAP 臨界值幾何限制：公式 $\text{CRAP} = \text{CC}^2(1 - \text{cov})^3 + \text{CC}$ 中，當 $\text{CC}=10$ 且覆蓋率 100% 時得分仍為 10。「CRAP < 10」是硬性要求單一函數分支必須小於 10 的純數學約束。
變異測試戳破覆蓋率假象：在免運費門檻（amount >= 100）案例中，若僅測 50 與 150，行覆蓋率 100%，但 mutator 將 >= 變異為 > 後變異體存活，唯有補齊 100 邊界斷言才能阻斷。
真實專案實測成效：在瀏覽器套件 oh-my-x 中，依工具報告將圈複雜度超標單體函數抽離為純函數，補齊邊界斷言，使變異測試通過率達 100%，行程退出碼為 0。

隱形假設與邊界條件

隱形假設: 開發專案具備可自動運行的單元測試套件（如 Vitest、Pytest 等），且 Agent 能無障礙呼叫本地 CLI。
邊界條件: 變異測試中編譯失敗亦計為阻斷（Killed），且存在少數語意不變的等價變異（Equivalent Mutants），需工程師具備基礎辨析能力。

ROUND 3: SOUL | 靈魂提取

“還能怎麼用”

作者盲點: 原生規則要求「流程結束直接推送到 main 分支」，在企業研發中存在風險，必須適配 PR 與分支保護機制。
知識連接: 與領域驅動設計 (DDD) 的 豐富領域模型、極限編程 (XP) 的 結對程式設計與重構 深度契合。
行動觸發: 本週將 ub-mode 加入專案設定，並在 CI 整合 crapper --threshold 9.99 門禁。

留白提問 (Guided Reflection)

提問：為什麼不能只靠 Prompt 叮囑 Agent，而必須強制依賴命令列工具？
- 架構師視角：大模型對抽象品質提示存在漂移；唯有語法樹相似度、圈複雜度與變異測試退出碼等客觀指標，才能形成不可逾越的防線。
提問：存量龐大且缺乏測試的專案如何引入這套體系？
- 架構師視角：嚴禁全量暴力重構。應將門禁限制在 Git Diff 範圍內，新程式碼強制執行 CRAP < 10，舊模組透過童子軍法則逐步吸收技術債。

跨域映射

在 現代建築工藝，這叫 無損探傷與載重壓力檢驗
在 製藥品管，這叫 破壞性穩定試驗與純度光譜分析

DEEP READ | 精讀指引

第一階段：前置設計原則
- 「Put domain in structure making illegal states impossible… Parse outside data once.」
- 推薦理由：從源頭阻斷狀態爆炸，型別系統是約束大模型隨意發揮的最強韁繩。
第二階段：Mutator 變異測試
- 「If the test still passes when every function returned nothing, throw it out… Kill survivors.」
- 推薦理由：揭開虛高測試覆蓋率謊言，直擊自動化測試的核心本質。

STRUCTURE MAP | 全書結構圖

┌──
│ ub-mode 治理體系全景
│ ├── 階段一：前置防禦 ──▶ Laziness (單一決策) + Data Shape (型別鎖死非法狀態) + TDD
│ ├── 階段二：工具門禁
│ │   ├── crapper ──▶ 計算 CRAP 指標，強制單函數 CRAP < 10 (限制分支膨脹)
│ │   ├── dryer ──▶ 計算 AST Jaccard 相似度，消除 >= 0.8 結構重複
│ │   ├── mutator ──▶ 注入變異運算子，要求阻斷存活變異體 (Kill survivors)
│ │   └── uml-viewer ──▶ 視覺化模組健康度熱力圖與紅線架構反向依賴
│ ├── 階段三：工程紀律 ──▶ 日誌留痕、保護上下文視窗、Worktree 清理、小步提交
│ └── 落地實戰 ──▶ oh-my-x 四步閉環 (安裝 ──▶ 門禁 ──▶ 體檢 ──▶ 約束重構)
└──

AI Agent 時代的程式碼整潔之道：拆解與實測 Uncle Bob 的 Clean Code Sub-mode (Architectural Deep Dive)

前言/背景

二十多年前，Robert C. Martin (Uncle Bob) 起草《敏捷宣言》並出版《代碼整潔之道》。2026 年 10 月，針對 Vibe Coding 帶來的混亂，Uncle Bob 發布了開源專案 ub-mode。

Uncle Bob Release

這是一套面向 AI Agent 的約束規範，核心堅定：先讓功能可用（First Make it Work），再把程式碼寫好（Then Make it Right）。

Paradigm Shift

章節詳細總結

1. 第一階段：先讓功能可用（前置防禦與 TDD 紀律）

Agent 生成程式碼極易隨意追加分支導致狀態發散。ub-mode 建立防禦規範：

最小改動約束（Laziness Protocol）：業務判斷在程式碼庫中只能存在於單一位置；僅提交解決問題的最小變更。
前置資料設計（Foundational Thinking）：先定義資料形狀（Data Shape）阻斷非法狀態；外部輸入在系統邊界解析一次；嚴禁屏蔽編譯器警報。
邊界防禦與純函數：內部核心邏輯全由無副作用純函數實現；具操作冪等性；共用可變狀態遵循單一寫入者（One Writer）機制。
TDD 先行：修改邏輯前先寫出明確失敗測試，再以最小程式碼轉綠，嚴禁編寫無效測試充數。