---
title: "AI 時代還需要軟體工程嗎？Clean Code 決定了 AI 戰力的天花板"
description: "AI 時代來臨，我們還需要看程式碼嗎？本文深入探討 AI 軟體工程中的人機協作與程式碼品質優化，說明為何測試系統與架構整理是降低維護成本與認知風險的關鍵。"
canonical_url: "https://blog.markkulab.net/post/clean-code-determines-ai-ceiling"
author: "Mark Ku"
author_url: "https://blog.markkulab.net/author/mark-ku"
site: "Mark Ku's Blog"
date_published: "2026-08-01 19:24:14 +0800"
category: "AI"
language: "zh-TW"
license: "CC BY 4.0"
license_url: "https://creativecommons.org/licenses/by/4.0/"
attribution: "轉載或引用請註明作者並附上原文連結"
---

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

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

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

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

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

關於這個現象，我們在 [Vibe Coding 一些小技巧：AI 是放大器，別讓它放大你的技術債](https://blog.markkulab.net/post/beyond-vibe-coding-ai-amplifier) 中也有過深入的實戰反思。

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

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

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

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

```mermaid
---
title: 一個功能從想法到上線的相對工時（柱狀＝傳統手寫，折線＝AI 輔助）
---
xychart-beta
    x-axis ["需求釐清", "設計", "實作", "驗證 Review", "修正返工"]
    y-axis "相對工時" 0 --> 45
    bar [20, 15, 40, 20, 5]
    line [20, 15, 10, 30, 10]
```

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

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

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

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

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

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


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

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

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

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

#### AI 友善架構對比圖

```text
【高度碎片化的微服務架構】
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  服務 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 的戰力天花板 [10]。為了讓 AI 能夠一兩次就改對程式碼，我們建議在專案中落實以下規範 [10]：

*   **嚴格限制複雜度**：單一函式的圈複雜度（Cyclomatic Complexity）上限設為 12，單一檔案程式碼長度上限為 400 行 [10]。檔案太長會分散 AI 的注意力。
*   **禁用模糊命名**：嚴格禁止使用 `utils`、`helpers`、`common` 等泛用且模糊的命名 [10]。這類命名會讓 AI 無法快速判斷職責，導致程式碼亂塞。
*   **強型別約束**：在 TypeScript 專案中禁用 `any` 型別 [10]，完整的型別定義是 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`、禁止模糊命名，這些不能只寫在文件裡，要讓工具自動執法：

```javascript
// 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 協作下被明顯放大了。

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

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

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


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

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

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

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

#### 標準的 `CLAUDE.md` 範本

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

```markdown
# 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 想繞也繞不過 |

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

1.  **Rules（軟約束）**：放在 `.claude/rules/` 的規則每次對話都會進入 AI 的 Context。例如我的專案放了 `spec-before-code.md`（改程式碼前必須先建立 Spec 文件並取得確認）與 `cache-versioning.md`（AI 生成的靜態資源 URL 必須帶版本號做 cache-busting）。AI 會主動遵守，但本質上仍是「提醒」。
2.  **Commands / Skills（流程標準化）**：把「寫文章」「建規格文件」「部署」這類多步驟工作流寫成 `/write-blog`、`/create-spec`、`/deploy` 等指令與技能，任何人（包括 AI 自己）執行的步驟都一模一樣，消滅「每個人做法不同」的混亂。Skills 的好處是按需載入，AI 只在任務相關時才讀取，不會浪費 Context。
3.  **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` 裡的內容，可以直接複製：

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

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

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

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

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

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

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

這也呼應了我們在 [AI 很勤勞，但它不懂你在做什麼：從 Multi-Agent 到 Vibe Coding 的實戰反思](https://blog.markkulab.net/post/multi-agent-vibe-coding-practical-reflection) 中所提到的，缺乏測試柵欄的 AI 開發，就像是在沒有安全繩的情況下高空彈跳。

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

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

根據答案，把 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」：

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

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


## 注意事項與風險

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

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


## 結論：效率 = 人類架構思維 + AI 執行力

回到最開始的問題：AI 時代我們還需要軟體工程嗎？

答案是：**比以往任何時候都更需要。**

數位資產越內聚，AI 發揮的威力就越大 [10]；相反地，混亂的架構只會讓 AI 成為技術債的加速器。軟體工程並沒有消失，而是轉化為「如何為 AI 準備乾淨的 Context 與架構」[10]。

而這一切的驗收標準，可以濃縮成一句話：**這段程式碼，人類與 AI 是不是都能輕鬆理解？** 能機械判定的部分交給 Linter 與 Hook 強制執行，需要引導的部分寫進 `CLAUDE.md`，剩下真正需要品味的部分，留給人類在 Review 時把關。

當我們能夠用清晰的架構引導 AI，用 `CLAUDE.md` 規範 AI，再用自動化測試約束 AI 時，我們才能真正釋放 AI 的潛力，實現高效且安全的開發模式。關於這點，推薦大家閱讀 [AI 時代，重新思考軟體工程的價值](https://blog.markkulab.net/post/ai-product-mindset-internal-external-growth)，裡面有更多關於開發思維轉型的討論。

**下一步行動**：今天就為你的專案加上 `CLAUDE.md`，把「雙讀者原則」與 Clean Code 規範分別寫進 `.claude/rules/` 與 Linter 設定，再定義一個 Review Agent 當初審，並試著重構那些讓 AI 頻繁出錯的混亂模組吧！


## 參考資料

*   [Clean Code for AI Agents: Make Your Codebase Agent-Ready](https://aidailycheck.com/learn/clean-code-for-ai-agents) [10]
*   [Structuring Your Codebase for AI Tools: 2025 Developer Guide (Propel Code)](https://www.propelcode.ai/blog/structuring-codebases-for-ai-tools-2025-guide) [10]
*   [Anthropic 2026 Agentic Coding Trends Report (Hivetrail 分析)](https://hivetrail.com/blog/anthropic-2026-agentic-coding-report/) [10]
*   [What Is the Claude.md File and Why Does It Matter? (MindStudio)](https://www.mindstudio.ai/blog/what-is-claude-md-file-ai-agents) [10]
*   [Codified Context: Infrastructure for AI Agents (arXiv)](https://arxiv.org/html/2602.20478v1) [10]
*   [Does Code Quality Still Matter in the Age of AI? (Mark Heath)](https://markheath.net/post/2026/3/30/does-code-quality-still-matter) [10]
*   [Keeping AI Agents In Line With Clean Architecture (NimblePros)](https://blog.nimblepros.com/blogs/ai-agents-clean-architecture/) [10]
*   [How to Standardize AI Code Generation (IBM Think)](https://www.ibm.com/think/insights/standardize-ai-code-generation-across-your-development-team) [10]
*   [Code Quality Foundations for AI-assisted Codebases (Nick Tune)](https://medium.com/nick-tune-tech-strategy-blog/code-quality-foundations-for-ai-assisted-codebases-4880f5948394) [10]
*   [AI Coding Assistants in 2026: 4x Faster, 10x Riskier (Kusari)](https://www.kusari.dev/blog/ai-coding-assistants-in-2026-4x-faster-10x-riskier-the-hidden-security-cost) [10]
*   [The 80% Problem: AI Ships Fast But Creates Hidden Debt (Augment Code)](https://www.augmentcode.com/guides/the-80-percent-problem-ai-agents-technical-debt) [10]
*   [The AI Technical Debt Crisis (RocketDevs)](https://rocketdevs.com/blog/AI-Technical-Debt-Crisis) [10]
*   [Software Architecture Considerations with AI-Assisted Coding (Heemeng Foo)](https://heemeng.medium.com/software-architecture-considerations-with-ai-assisted-coding-b4f5139e100a) [10]
*   [Do AI Agents Reason Better in Modular Monoliths? (Vishal Mysore)](https://medium.com/@visrow/do-ai-coding-agents-reason-better-in-modular-monoliths-than-microservices-b2549e1c1ab3) [10]
*   [Context Engineering for Developers (Faros)](https://www.faros.ai/blog/context-engineering-for-developers) [10]
*   [Google Style Guides](https://google.github.io/styleguide/)
*   [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)
*   [Claude Code 官方文件：Memory（CLAUDE.md 與 Rules）](https://code.claude.com/docs/en/memory)
*   [Claude Code 官方文件：Hooks](https://code.claude.com/docs/en/hooks)
*   [Claude Code 官方文件：Subagents（自訂審查 Agent）](https://code.claude.com/docs/en/sub-agents)

---

## 關於本文與作者

本文出自 [Mark Ku's Blog](https://blog.markkulab.net/post/clean-code-determines-ai-ceiling)

授權條款： [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — 轉載或引用請註明作者並附上原文連結

### 關於作者

**[Mark Ku](https://blog.markkulab.net/author/mark-ku)** — Software Solution Provider

- 10+ 年資深軟體工程師，現為 AI 應用 Builder
- 專注大型平台架構設計，從北美電商到AI SaaS訂閱收費系統
- 結合 AI Agent 與自動化，打造高效可演進的產品技術基礎

### 作者開發的免費工具

以下工具皆可免費使用：

- [免費 PDF 簽名工具](https://blog.markkulab.net/tools/pdf-sign): 線上 PDF 簽名工具，瀏覽器內完成手繪、打字、上傳簽名，可拖曳放置、縮放、下載。所有處理都在你的裝置完成，檔案不會上傳。
- [VS Code Refactory](https://blog.markkulab.net/tools/refactory): Refactory 是一款 VS Code 重構擴充套件：34 個重構動作、37 條 code smell 檢查、Code Health 儀表板、18 種語言、534 支測試。懂你的專案慣例：介面放哪、DI 註冊寫在哪、'use client' 該不該加；還會用 git 修改頻率 × 複雜度排出「該先修哪個檔案」，並一鍵把壞味道交給你自己電腦上的 Claude Code 修。免費使用，原始碼不離開你的機器。
- [DB-Kit 資料庫管理工具](https://blog.markkulab.net/tools/db-kit): DB-Kit 是一個用 Tauri + Rust + React 打造的輕量跨平台資料庫管理工具，用單一一致的介面同時管理 MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite、MongoDB、Redis、Kafka、Elasticsearch 與 RabbitMQ 十一種資料來源：連線密碼以 OS keychain 加密、SSH Tunnel、完整 CRUD、視覺化查詢建構器、多結果集同時顯示、跨連線資料傳輸與比對同步、Excel / CSV 匯入匯出、執行計畫視覺化、ER 圖、排程備份、SQL 壓力測試（p50～p99 延遲百分位）、15 條規則的 SQL 審查、Kafka 訊息瀏覽與監控告警；繁中 / 英文雙語介面，內建 AI 助手（自然語言生成 SQL、AI 審查與調校建議）與命令列工具 dbk。免費開源（MIT），提供 Windows / macOS / Linux 安裝檔。
- [VS Code Super Mermaid](https://blog.markkulab.net/tools/super-mermaid): Super Mermaid 是一款 VS Code 擴充套件：開箱即用的漂亮 Mermaid 圖表，自動上色、即時預覽、滑鼠平移縮放、PNG / SVG 高解析匯出，內建 21 種範本與多種主題。免費開源（MIT）。
- [React Super Mermaid](https://blog.markkulab.net/tools/react-super-mermaid): react-super-mermaid 是一個開源 React 元件庫：一行 <MermaidViewer> 即可渲染漂亮的 Mermaid 圖表，內建 colorful / sketch 主題、平移縮放、圖內搜尋、SVG / PNG 高解析匯出。輕量、SSR 安全、完整 TypeScript 型別。免費開源（MIT）。
- [Jira / Confluence Super Mermaid](https://blog.markkulab.net/tools/jira-super-mermaid): Atlassian Forge app：在 Jira issue 與 Confluence 內文直接寫 Mermaid 語法，畫流程圖、時序圖、狀態機與甘特圖。11 種圖表、SVG / PNG 匯出、明暗主題、完整中日韓文字支援。取得 Runs on Atlassian 資格：圖表存在你自己的站台，app 不呼叫任何第三方服務。免費，即將上架 Atlassian Marketplace。
- [Mermaid 線上預覽](https://blog.markkulab.net/tools/mermaid-preview): 在瀏覽器裡寫 Mermaid、即時看圖，整張圖表壓進網址就能分享。免註冊、不上傳伺服器，相容 mermaid.live 的分享連結。
- [React Intl Phone Number](https://blog.markkulab.net/tools/react-intl-phone-number): react-intl-phone-number 是一個開源 React 元件：framework-agnostic、不依賴 antd，提供 E.164 進出、可搜尋國旗 / 國碼下拉、可配置驗證等級（strict / mobile-strict / loose）、可主題化 CSS 與 i18n，電話邏輯由 google-libphonenumber 驅動。輕量、完整 TypeScript 型別。免費開源（MIT）。
- [Uptime Kuma Cluster](https://blog.markkulab.net/tools/uptime-kuma-cluster): 把單機版 Uptime Kuma 改造成高可用叢集：OpenResty + Lua 智慧負載平衡、MariaDB 共享狀態、健康檢查與自動 Failover，附叢集管理 REST API，一行 Docker Compose 啟動。免費開源（MIT）。
- [特教專案](https://blog.markkulab.net/education): 為特殊教育學生製作的學習教材

### 每日 Podcast

- [科技新鮮事](https://blog.markkulab.net/category/tech-news): 每日精選 AI 與科技趨勢，透過語音摘要快速掌握最新技術動態，涵蓋 AI 應用、軟體架構、DevOps 與工程實戰。 — RSS: https://blog.markkulab.net/feed.xml
- [AI股市蝦聊](https://blog.markkulab.net/category/ai-stock-chat): 每個交易日用 AI 分析台股盤勢，以雙人對話聊當天的盤中觀察與隔日預測。 — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml

### 電子報

[訂閱電子報](https://blog.markkulab.net/subscribe) — 第一時間收到新文章通知，無垃圾信、隨時可取消訂閱。