AI 時代還需要軟體工程嗎？Clean Code 決定了 AI 戰力的天花板

前言：AI 寫程式變快了，為什麼維護成本卻飆升 4 倍？

在生成式 AI 與 AI Agent 快速發展的今天，許多開發者都體驗到了前所未有的開發速度。只要輸入幾句 Prompt，AI 就能在幾秒鐘內生成數百行程式碼，開發速度看似提升了 4 倍 ¹⁰。然而，隨著專案規模擴大，我們也開始觀察到一個令人擔憂的現象：系統的「理解債」（Comprehension Debt）正在悄悄累積 ¹⁰。

許多團隊發現，雖然第一天寫程式變快了，但到了第二年，系統的維護成本竟然高達原本的 4 倍 ¹⁰。這讓我們不得不停下來思考：在 AI 時代，我們還需要軟體工程嗎？我們身為工程師，還需要親自閱讀與審查程式碼嗎？

以我們的經驗來看，AI 目前還沒有發展到「一句話就能把所有複雜工作完美做完」的階段，人機協作將會維持很長一段時間。如果我們把不好的程式碼直接交給 AI，AI 只會根據既有的混亂，生產出更多難以維護的垃圾程式碼。誠如業界所言，「一致性」讓 AI 助手成為力量倍增器，而「不一致」則會讓 AI 成為混亂放大器 ¹⁰。

關於這個現象，我們在 Vibe Coding 一些小技巧：AI 是放大器，別讓它放大你的技術債中也有過深入的實戰反思。

為什麼「快 4 倍」在交付週期上感覺不到？

AI 讓實作變快是真的，但一個功能從想法到上線，實作從來就不是唯一的成本。真正吃時間的是前面的需求釐清，以及後面的驗證與 Review，這兩段 AI 幾乎沒有幫我們省下來，其中驗證甚至還變貴了。

前面沒變快，是因為 AI 只能執行你講清楚的東西。需求一含糊，AI 只會用更快的速度產出偏離目標的程式碼，你反而要花更多時間把它拉回來。後面變貴，則是因為那些程式碼不是你寫的，每一行都要重新讀懂才敢合併，而且 AI 一次產出的量遠大於人類手寫，Review 的負擔是等比例放大的。

以我們自己專案的體感抓一個相對比例，大概是這樣：

Loading diagram…

柱狀是傳統手寫，折線是 AI 輔助之後。實作那一段砍掉了四分之三，總工時卻只少了一成多，因為省下來的時間有一大半被驗證與返工吃回去。這也解釋了為什麼很多團隊「感覺 AI 很快」，交付週期卻沒有明顯縮短。

看懂這張圖，才知道力氣該花在哪裡：能被壓縮的不是打字速度，而是把需求與約束寫成 AI 讀得懂的文件，以及把驗證自動化，讓 Review 的人只需要看真正需要人類判斷的部分。這兩件事正是後面「Context 憲法」與「測試防護柵欄」兩個章節要處理的主題。

核心痛點：AI 時代的「理解債」與安全風險

許多人誤以為有了 Copilot 或 Claude Code 之後，程式碼品質就不再重要了，甚至認為「反正看不懂就叫 AI 重寫就好」。然而，根據資安與軟體研究機構的調查，這種盲目的信任正在帶來巨大的風險：

4 倍快、10 倍險：研究指出，AI 生成的程式碼中，有高達 62% 含有設計缺陷或已知漏洞，使用 AI 助手的專案其 Secret（金鑰）洩漏率也高出 40% ¹⁰。更誇張的是，AI 推薦的套件中有 20% 根本不存在，這很容易引發惡意套件劫持（Slopsquatting）的資安危機 ¹⁰。
Token 浪費與成本飆升：當程式碼架構太過混亂、缺乏優化時，AI 為了理解上下文（Context）必須讀取大量無用的程式碼，這會導致 Token 消耗量暴增，開發成本也隨之飆升 ¹⁰。
溝通鏈拉長，效率低下：當程式碼結構不夠內聚、邏輯外放時，AI 無法取得完整的 Context，你就必須花費更多時間去跟 AI 解釋「為什麼要這樣寫」，導致人機溝通效率大打折扣 ¹⁰。
漏洞規模化複製：人類開發者可能只會手寫出一個安全漏洞，但 AI 助手卻能以驚人的速度，將這個不安全的設計模式複製到幾十個檔案中 ¹⁰。

在軟體開發的生命週期中，運維成本 > 維護成本 > 開發成本。架構不整理，這些成本只會一路往上疊，差別只在於 AI 讓它疊得比以前更快。目前不論要修改任何功能，工程師都必須對系統有足夠的了解，才能正確引導 AI 動手，這也是為什麼我們在深入探討 Vibe Coding 限制中提到，缺乏架構思維的開發終將面臨瓶頸。

技術方案：以「數位資產內聚」為核心的 AI 友善架構

面對這些挑戰，我們發現「架構」並沒有因為 AI 的出現而過時，相反地，架構變成了 AI 的 Context 壓縮機制 ¹⁰。好的架構能幫 AI 過濾雜訊，大幅降低其推理的開銷 ¹⁰。

1. 模組化單體（Modular Monolith）勝過微服務

在 AI 協作的場景下，微服務架構容易帶來「Context 碎片化」（Context Fragmentation）的問題 ¹⁰。因為微服務迫使 AI Agent 去理解多個 Repository、服務邊界、異步訊息、API 契約以及最終一致性，這對 AI 來說推理成本極高 ¹⁰。

相對地，模組化單體具有極大的優勢。它將高內聚的業務邏輯集中在單一專案中，邊界清晰，能讓 AI 更快理解專案全貌，減少 Context 碎片化，也更容易進行交易推理 ¹⁰。

AI 友善架構對比圖

【高度碎片化的微服務架構】
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  服務 A (Repo)│   │  服務 B (Repo)│   │  服務 C (Repo)│
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                  │
       └───────────► 異步訊息 / API ◄────────┘
  ⚠️ AI 必須理解多個 Repository、服務邊界、API 契約與最終一致性
  ❌ 缺點：Context 嚴重碎片化、Token 消耗極大、推理錯誤率高

【高內聚的模組化單體架構 (Modular Monolith)】
┌────────────────────────────────────────────────────┐
│ 單一 Repository (共享 Context 邊界)                 │
│  ┌──────────────┐   ┌──────────────┐   ┌─────────┐ │
│  │  模組 A (Domain)│ ◄─│  模組 B (Domain)│ ◄─│CLAUDE.md│ │
│  └──────────────┘   └──────────────┘   └─────────┘ │
└────────────────────────────────────────────────────┘
  ✅ 優點：AI 載入單一專案即可取得完整脈絡、邊界清晰、交易推理簡單

2. Clean Code 規範即是 AI 的「效能設定」

在 AI 時代，程式碼品質不再只是工程師的美學偏好，而是直接決定了 AI 的戰力天花板 ¹⁰。為了讓 AI 能夠一兩次就改對程式碼，我們建議在專案中落實以下規範 ¹⁰：

嚴格限制複雜度：單一函式的圈複雜度（Cyclomatic Complexity）上限設為 12，單一檔案程式碼長度上限為 400 行 ¹⁰。檔案太長會分散 AI 的注意力。
禁用模糊命名：嚴格禁止使用 utils、helpers、common 等泛用且模糊的命名 ¹⁰。這類命名會讓 AI 無法快速判斷職責，導致程式碼亂塞。
強型別約束：在 TypeScript 專案中禁用 any 型別 ¹⁰，完整的型別定義是 AI 最好的導航指南。

3. Coding Standard 業界都怎麼做？把規範從「文件」變成「工具鏈」

業界推行 Coding Standard 數十年，最後沉澱下來的共識其實只有一句話：寫在 Wiki 裡的規範等於不存在。靠人自由心證的規範，在時程壓力下一定會被犧牲；真正活得下來的規範，全部都被編進了工具鏈裡自動執法，這個做法通常被稱為「Standards as Code」。主流團隊的做法可以整理成六個層次：

層次	業界主流工具	攔下什麼問題
風格指南	Google Style Guides、Airbnb JavaScript、PEP 8、.NET Conventions	命名與慣用寫法的共同語言
Formatter	Prettier、Black、gofmt	縮排、引號、換行等所有格式爭論
Linter	ESLint、Ruff、Roslyn Analyzers	複雜度超標、模糊命名、危險語法
型別檢查	TypeScript `strict`、mypy	型別錯誤、隱性 `any`
架構守護	dependency-cruiser、ArchUnit、NetArchTest	跨模組非法依賴、循環依賴
守門機制	husky + lint-staged、CI Quality Gate（SonarQube）	不合格的程式碼進不了 commit / merge

幾個實務上的重點：

直接採用公開規範，不要自己發明：Google、Airbnb、PEP 8 這些主流 Style Guide 已經被成千上萬個團隊驗證過，直接採用可以省下無止盡的風格之爭。對 AI 協作還有一個隱藏紅利：這些規範大量存在於模型的訓練語料中，遵循主流規範等於「說 AI 最熟悉的語言」，AI 生成的程式碼會更貼近你的預期。
用 Formatter 終結格式討論：Prettier 這類 opinionated formatter 的價值就在於「沒得商量」，格式問題從此永遠不會再出現在 Code Review 裡。
上一節的規範必須寫成 Linter 規則：圈複雜度 12、單檔 400 行、禁用 any、禁止模糊命名，這些不能只寫在文件裡，要讓工具自動執法：

// eslint.config.js：把 Clean Code 規範變成可執行的規則
export default [
  {
    rules: {
      complexity: ['error', { max: 12 }], // 圈複雜度上限 12
      'max-lines': ['error', { max: 400 }], // 單一檔案上限 400 行
      '@typescript-eslint/no-explicit-any': 'error', // 禁用 any
      'id-denylist': ['error', 'utils', 'helpers', 'common'], // 禁止模糊命名
    },
  },
]

架構邊界也能寫成測試：「Domain 層不准依賴 Infrastructure 層」這種架構原則，用 dependency-cruiser（JS/TS）、ArchUnit（Java）、NetArchTest（.NET）都可以寫成自動化測試，違反就直接讓 CI 紅燈。
設下兩道守門：本機用 husky + lint-staged 在 commit 前攔第一次，CI 再用 Quality Gate（如 SonarQube 對新增程式碼設定重複率、覆蓋率與漏洞門檻）攔第二次，不合格的 PR 進不了主幹。

對 AI 協作來說，這套工具鏈還有一個放大效果：Linter 的錯誤訊息是 AI 看得懂的即時回饋。AI Agent 改完程式碼跑一次 lint，違規會以明確的錯誤訊息回傳，AI 可以立刻自我修正，這是寫在 Wiki 裡的規範永遠做不到的修正閉環。

4. 回到本質：Clean Code 的新定義是「人類與 AI 都能輕鬆理解」

前面談的複雜度上限、命名規範與工具鏈，其實都指向同一件事。如果要用一句話重新定義 AI 時代的 Clean Code，我會這樣寫：能同時被人類與 AI 輕鬆理解的程式碼，才叫乾淨。

過去我們談可讀性，讀者只有兩種：三個月後的自己，以及接手的同事。現在多了第三種讀者，而且它的閱讀方式跟人類完全不同：

人類是「跳讀」：看到 PaymentCalculator 就知道細節可以先跳過，看不懂的地方能問同事、翻 Wiki、追 Git 歷史，靠經驗與專案脈絡自動補完缺漏的資訊。
AI 是「有限視窗內的檢索」：它只看得到被塞進 Context 的那幾個檔案，沒被檢索到的程式碼對它而言等於不存在，沒人可問，只能猜。

有趣的是，兩者的理解障礙高度重疊，差別只在嚴重程度：

面向	人類會卡在哪	AI 會卡在哪	共同解法
命名	看不懂縮寫，要猜語意	無法從名稱判斷職責，語意檢索也撈不到	用業務語言命名，避免縮寫
檔案長度	捲動疲勞，抓不到重點	吃掉 Context 額度，注意力被稀釋	單檔 400 行上限
隱性知識	靠口耳相傳或直接問人	沒人可問，只能照字面猜	把 why 寫進註解與 `CLAUDE.md`
風格不一致	要適應多套寫法，心累	學到互相矛盾的樣板，複製到錯的那套	Formatter 與 Linter 強制單一風格
副作用與隱性依賴	靠 debug 一步步追	看不到執行期行為，幾乎無法推理	純函式、依賴顯性注入

這帶來一個好消息：為 AI 優化可讀性，幾乎等於為人類優化可讀性，我們不需要為了討好 AI 而犧牲人類的閱讀體驗。

但有一個地方兩者會分歧，值得特別留意：過度抽象。層層繼承、滿天飛的泛型、事件驅動的隱性跳轉，對資深工程師來說可能很優雅，因為他腦中有整張地圖；但對 AI 來說是災難，它得跳過五、六個檔案才能拼出一次完整的執行路徑，而這些檔案往往不會全部被載入 Context。抽象的代價，在 AI 協作下被明顯放大了。

因此在實務上，我會用一個很簡單的「雙讀者測試」來判斷一段程式碼夠不夠乾淨：

三個月後的我，只讀這一個檔案，能不能看懂它在做什麼、為什麼這樣做？
一個只讀得到「這個檔案 + CLAUDE.md」的 AI，能不能正確改對這段程式碼？

兩題都答得出「可以」，才算通過。至於這個標準能不能直接寫進 Claude 的設定檔讓 AI 自動遵守，我們在下一段的〈步驟三〉展開。

實作步驟：建構專案的「Context 基礎設施」與人機協作流程

要讓 AI 真正成為生產力工具，我們必須主動建構專案的「Context 基礎設施」¹⁰。以下是我們推薦的實作步驟：

步驟一：建立「Context 憲法」文件

在專案根目錄下建立一個 CLAUDE.md 或專屬的 Context 文件。這個文件是寫給 AI Agent 看的「專案說明書」，用來明確定義架構原則、技術堆疊與開發規範。

根據 Anthropic 的分析報告，維護良好 Context 文件的團隊，AI 錯誤率降低了 40%，任務完成速度提升了 55% ¹⁰。

標準的 `CLAUDE.md` 範本

以下是一份適用於 TypeScript 專案的 CLAUDE.md 範本，你可以直接放入專案根目錄中：

# CLAUDE.md - 專案開發憲法

## 專案簡介
本專案為一個基於 Node.js / TypeScript 的電子商務後端系統，採用模組化單體（Modular Monolith）架構。

## 技術堆疊
- 執行環境：Node.js v20+
- 語言：TypeScript v5+
- 框架：NestJS
- 資料庫：PostgreSQL (Prisma ORM)

## 常用指令
- 安裝依賴：`npm install`
- 啟動開發伺服器：`npm run start:dev`
- 執行單元測試：`npm run test`
- 執行整合測試：`npm run test:integration`
- 程式碼格式化：`npm run format`

## 程式碼風格與架構約束
- **架構模式**：嚴格遵循 Domain-Driven Design (DDD) 與高內聚原則。
- **命名規範**：
  - 禁止使用 `utils`、`helpers`、`common` 等模糊命名，請依業務邏輯命名（例如：`PaymentCalculator`、`EmailNotifier`）。
- **類型系統**：
  - 嚴格禁用 `any` 類型，所有變數與函式必須有明確的型別定義。
- **複雜度限制**：
  - 單一函式複雜度（Cyclomatic Complexity）上限為 12。
  - 單一檔案程式碼長度上限為 400 行。超過時必須進行模組化拆分。
- **錯誤處理**：
  - 統一使用自定義的 `AppError` 類別，禁止直接拋出未捕獲的 Generic Error。

步驟二：用 `.claude/` 資料夾把規範升級成 AI 的行為約束

CLAUDE.md 只是入口。Claude Code 的 .claude/ 資料夾提供了一整組機制，讓團隊規範從「參考文件」升級成「行為約束」，而且這些檔案都可以進版控，讓全團隊的人與 AI 共享同一套標準：

機制	位置	載入時機	適合放什麼
常駐規則（Rules）	`.claude/rules/*.md`	每次對話自動載入	非遵守不可的團隊鐵律
自訂指令（Commands）	`.claude/commands/*.md`	使用者輸入 `/指令` 時	標準化的重複工作流
技能模組（Skills）	`.claude/skills/*`	AI 判斷任務相關時自動載入	特定領域的操作手冊
Hooks	`.claude/hooks/` + `settings.json`	工具呼叫前後（Shell 層）	硬性攔截，AI 想繞也繞不過

這四層的約束強度是遞增的，以我自己部落格專案的實際配置為例：

Rules（軟約束）：放在 .claude/rules/ 的規則每次對話都會進入 AI 的 Context。例如我的專案放了 spec-before-code.md（改程式碼前必須先建立 Spec 文件並取得確認）與 cache-versioning.md（AI 生成的靜態資源 URL 必須帶版本號做 cache-busting）。AI 會主動遵守，但本質上仍是「提醒」。
Commands / Skills（流程標準化）：把「寫文章」「建規格文件」「部署」這類多步驟工作流寫成 /write-blog、/create-spec、/deploy 等指令與技能，任何人（包括 AI 自己）執行的步驟都一模一樣，消滅「每個人做法不同」的混亂。Skills 的好處是按需載入，AI 只在任務相關時才讀取，不會浪費 Context。
Hooks（硬約束）：這是最關鍵的一層。Hook 是在 Shell 層執行的腳本，可以在 AI 呼叫 Edit/Write 等工具之前攔截檢查。例如我的專案設了一個 PreToolUse hook：當 docs/specs/pending/ 沒有任何 Spec 文件時，直接阻擋 AI 修改程式碼檔案，並回傳「請先建立 Spec」的訊息。這跟 Linter 擋人類的 commit 是同一個哲學：規範不靠自覺，靠攔截。

換句話說，.claude/ 資料夾就是「Standards as Code」在 AI 協作時代的延伸：Linter 約束人類寫的程式碼，.claude/ 約束 AI 的行為，兩者加起來才是完整的防護網。

步驟三：哪些規範寫進設定檔有效，哪些沒效

「人類與 AI 都要看得懂」這個標準，能不能直接寫進 CLAUDE.md，讓 AI 自動照做？

答案是一半可以。判斷方法很簡單：問自己「這條規範，機器能不能自己判斷對錯？」

機器判斷得出來的（單檔 400 行、圈複雜度 12、禁用 any、模糊命名）：交給 Linter 和 Hook，違反就紅燈，AI 繞不過去。
說得清楚但要靠判斷的（註解要寫「為什麼」、不要過度抽象、寫直白一點）：寫進 CLAUDE.md，AI 大多會照做，但不保證。
只能靠人看的（這個抽象有沒有對應到真實業務、這個名字有沒有真的講出意圖）：設定檔幫不上忙，留給 Code Review。

這裡最常被誤會的一件事是：CLAUDE.md 是提醒，不是規定。它只是每次對話被塞進 AI 記憶裡的一段文字，對話拉得越長越容易被忽略。所以「希望 AI 這樣做」的寫 CLAUDE.md，「一定要這樣做」的就往下沉到 Linter 和 Hook。

下面這段是我實際放在 CLAUDE.md 裡的內容，可以直接複製：

## 可讀性原則：人類與 AI 都要看得懂

寫程式碼時，同時滿足這兩點：

1. 只讀這一個檔案，就要能看懂它在做什麼
   - 判斷條件寫在看得到的地方，不要藏在遠端設定或繼承鏈裡
   - 不要拆出「要跳 5 個檔案才拼得出流程」的抽象層

2. 名字和註解負責說「為什麼」，程式碼本身才說「做什麼」
   - ❌ // 迴圈處理資料
   - ✅ // 逾期滿 30 天才計違約金（法務 2026-03 要求）
   - 用業務語言命名（calculateOverdueFee），
     不要用 processData、handleItem 這種看不出在做什麼的名字

有疑慮時，選「多打幾個字但一看就懂」，不要選「短而聰明」。

一句話總結：設定檔負責讓 AI 有正確的預設值，工具鏈負責守住底線，剩下需要品味的部分還是得靠人。

步驟四：落實自動化測試作為「防護柵欄」

AI 產出的程式碼必須有客觀的驗證機制。單元測試與整合測試就是最好的「防護柵欄」。在沒有建立完整的自動化測試系統前，我們強烈建議由人類工程師進行手動測試與最終把關，絕對不能完全放手讓 AI 自行部署。

這也呼應了我們在 AI 很勤勞，但它不懂你在做什麼：從 Multi-Agent 到 Vibe Coding 的實戰反思中所提到的，缺乏測試柵欄的 AI 開發，就像是在沒有安全繩的情況下高空彈跳。

步驟五：建立以「風險」為準的程式碼審查準則

即使 AI 幫我們寫了大部分的程式碼，人類的閱讀與審查依然不可或缺。但審查不該是「全部都看」或「全部不看」的二選一，審查深度應該與出錯的代價成正比。實務上可以先問自己三個問題：

這段程式碼出錯，代價是什麼？（金錢損失、資料外洩，還是只是版面跑掉？）
出錯後能不能快速回滾？（一鍵還原，還是資料已被汙染、覆水難收？）
這段程式碼未來會不會持續擴充維護？（活得越久的程式碼，品質的複利越大）

根據答案，把 AI 生成的程式碼分成三個風險等級來處理：

風險等級	典型範圍	審查方式
高風險	資安、金流、權限控管、個資處理、資料遷移與刪除、對外 API 契約	逐行審查，必要時搭配第二位審查者，絕不直接合併
中風險	核心業務邏輯、系統架構與模組邊界、會長期擴充維護的程式碼	重點審查設計與邊界是否正確，實作細節交給測試把關
低風險	一次性腳本、內部工具、UI 樣式調整、原型驗證（POC）	靠自動化測試與 Linter 把關即可，人工抽查

延伸：定義一個 Review Agent，真的有用嗎？

Claude Code 可以在 .claude/agents/ 定義專屬的 subagent，例如一個只負責審查的 code-reviewer。常見的疑問是：讓 AI 審查 AI 寫的程式碼，這不是球員兼裁判嗎？

我的實際經驗是：有用，但它補的是第一道關卡，不是最後一道。

它真正的價值來自「獨立的 Context」。同一個對話裡直接問「你剛剛寫得對嗎」，AI 幾乎一定會替自己辯護，因為它的 Context 裡塞滿了自己的推理過程；而 subagent 跑在全新的 Context 中，只拿到 diff 與規範，沒有那段自我合理化的記憶，抓錯率明顯高得多。加上它不會累、不會因為時程壓力放水，很適合擋掉那些人類 Review 最容易眼花漏掉的低階問題。

但它有三個硬邊界，不能假裝看不到：

同源盲點：寫的跟審的是同一種模型，會共享同一套思考習慣，那些「它本來就想不到」的問題，換個 agent 一樣想不到。
看不到執行期：它只讀得到靜態的 diff，跑起來會不會炸、效能會不會掉，只有測試與實際執行能回答。
會產出「看起來很有道理但其實是錯的」意見：這是最耗人的一種噪音，照單全收反而讓團隊開始無視 Review 結果。

要讓它真的有用，關鍵在於別只丟一句「幫我 review」：

給明確的 checklist，而不是抽象目標：把上表的風險分級、CLAUDE.md 的規範、雙讀者原則直接寫進 agent 的指令裡，讓它照表操課。
要求可驗證的輸出格式：每條意見都必須附上 檔案:行號、嚴重程度，以及「什麼輸入會造成什麼錯誤結果」。說不出具體失敗情境的意見，一律丟掉。
用 Hook 或指令固定觸發：跟前面的邏輯一樣，靠 AI 自覺記得審查是不可靠的，把它綁在流程上才會每次都跑。
高風險程式碼照樣人工逐行：Review Agent 負責先掃掉那些機械性、重複性的問題，讓人類把有限的注意力留給出錯代價最高的地方。

換句話說，它的定位是「一個永遠不會偷懶的初審者」，而不是「可以取代人類的終審者」。

注意事項與風險

在導入 AI 協作的過程中，我們需要特別留意以下幾點：

認知風險：如果工程師「不知道為什麼而做」，只是盲目複製貼上 AI 生成的程式碼，將會逐漸失去對系統的主導權。一旦系統發生非預期錯誤，人類將完全失去除錯能力。
不變是最大的風險：雖然 AI 帶來了技術債的風險，但拒絕引進 AI 工具，或因為害怕出錯而拒絕重構舊系統，在技術迭代如此迅速的時代，往往會面臨更大的競爭淘汰風險。
過度委派的陷阱：目前 AI 僅能完全委派 0% 到 20% 的簡單任務，其餘 80% 的工作仍然需要人類工程師進行脈絡管理與系統設計 ¹⁰。千萬不要把 AI 當作可以完全甩手不管的萬靈丹。