安安～我是ChiYu～

前兩個 iThome 鐵人賽系列，我從七月就開始準備，八月底也都如期完成，雖然中間斷更了...

可是在寫那兩個系列時，我一直惦記著這個題目，甚至覺得它可能會寫得更好。

到了八月底，我還是決定再開第三個系列。

有點趕，也代表接下來要準備的東西更多。讀書筆記要整理，兩則貼文的脈絡要重新確認，技術主張要找來源，後續還要準備 API 範例、AI 實驗與可以公開的工程證據。

我還是覺得值得。

這個系列沒有從某個突然冒出的熱門名詞開始。它來自三件剛好撞在一起的事：我讀完 Robert C. Martin，也就是 Uncle Bob 所寫的《無瑕的程式碼 第二版：敏捷軟體開發技巧守則》後留下的心得、他談 Coding Agent 的兩則 X 貼文，以及近期大量 AI Coding 累積的感受。

一本談 Clean Code 的書、兩則談 Agent 工作方式的貼文，再加上實際把 AI 帶進開發流程後遇到的問題。這三條線放在一起，讓我很想重新追問一件事：

當 AI 開始大量產生程式碼，Clean Code 還在解決什麼問題？

這個問題，就是我決定再開第三個參賽系列的原因。

這個系列來自第二版、兩則 X 貼文與近期 AI Coding

第一條線，是《無瑕的程式碼》第二版。

這本就是我這次閱讀的博碩文化繁體中文版，也是後續文章核對章名與術語時使用的版本。

有一說一，這本書拿在手上真的很有份量。繁體中文版至少有 753 頁，前面還有用羅馬數字編頁的序言與推薦內容，整本厚度大約五、六公分。讀完不是普通的累。我也不覺得只讀一遍就能完全吸收，很多章節還得配合實作，再回來多讀幾次。

跟上一版相比，第二版直接加入〈AI、LLM 以及天知道還有什麼〉。而且，在〈清理你的程式碼〉的後記裡，Uncle Bob 已經請 Grok3 協助改進程式碼；Grok3 產出的版本符合要求，也通過了作者準備的測試。

這個例子很直接：AI 讀取現有 Code、提出修改，Uncle Bob 再用事前要求與測試驗收結果。看到這裡，我更想知道：當 AI 已經進入真實開發流程，過去談可讀性、設計與軟體工藝的 Clean Code，會怎麼延伸到現在的 AI Coding？

封面先在這裡和大家見面。全書共有 37 章，我不打算把它寫成逐章摘要。我會把讀書心得帶回 AI Coding 的實際問題，再用同一支 API，以及固定起點、模型與驗收條件的實驗，檢查自己的理解。

Clean Code 很容易被縮成幾條我們早就聽過的規則，例如名稱要清楚、函式要短、類別只負責一件事。可是第二版的範圍遠比一份風格檢查表大。從程式碼、設計、架構一路談到軟體工藝，官方目錄共有 37 章。它問的已經不只有「這段 Code 好不好讀」，還包括軟體如何持續維護、如何留下可重複的證明，以及一個團隊怎麼長期保持生產力。

這一系列會從我的讀書心得出發，再把書裡的觀念放回 AI Coding 現場。我想看看哪些原則依然成立、哪些地方需要新的做法，以及哪些漂亮口號一進入真實 Repository 就不夠用了。

Uncle Bob 的兩則 X 貼文：少讀 Agent Code，改看測試與品質關卡

2026 年 4 月 14 日，Uncle Bob 在第一則 X 貼文分享，他不逐行 Review Agent 產生的程式碼。他會查看測試覆蓋率、依賴結構、循環複雜度、模組大小與 Mutation Testing，透過這些訊號判斷品質。

這裡的測試覆蓋率（Test Coverage），指測試執行時觸及多少程式結構。它能指出哪些路徑或程式碼沒有被測試碰到，卻不能單獨證明測試驗證了正確行為；測試把每一行都跑過，仍可能漏掉關鍵斷言。

Mutation Testing（變異測試）則會刻意改動 Production Code，再看測試能不能抓到這些變化。Coverage 告訴我們哪些地方執行過，Mutation Testing 檢查的是測試對錯誤變化夠不夠敏感。

到了 7 月 23 日，他在第二則 X 貼文與討論串補充得更完整：Unit Test、Gherkin Acceptance Test、QA Procedure、品質指標、Mutation Testing 與測試覆蓋率，共同構成約束 Agent 的工程關卡。

其中，Gherkin Acceptance Test 會用 Given／When／Then 描述可以驗收的行為；QA Procedure 則是交付前實際要走過的品質檢查流程。

我在意的正是這個轉變：人少讀一部分 Implementation 之後，Review 就得更依賴規格、測試、結構與品質證據。

當 Agent 能讀取 Repository、一次修改多個檔案、執行測試，再依工具結果繼續修正，人工逐行閱讀可能成為流程中最慢的一段。Uncle Bob 因此把注意力放在規格、測試、結構與品質證據。工作方式變了，需求、驗收條件、測試品質，以及修改能不能進入正式環境，仍然要由人判斷。

兩則貼文沒有交代足夠的專案規模、風險等級與團隊情境，無法證明這套做法適合所有軟體。所以我先把它當成值得實際檢驗的工作方式，不外推成所有 Agent 專案都該照做的通則。

撰寫途中多了一支訪談：Uncle Bob 再談 AI 與 Clean Code

這個系列原本從第二版、兩則 X 貼文與我的 AI Coding 經驗出發。撰寫期間，開發者與教育者 Matt Pocock 又發布了一支與 Uncle Bob 的長篇訪談：Uncle Bob on Software Fundamentals in the Age of AI。

訪談裡，Uncle Bob 再次談到 AI 產生 Code 的速度、沒有及時清理會留下的垃圾、測試與品質關卡，以及哪些 Clean Code 價值應該保留、哪些人類工作習慣可以依 Agent 能力重新調整。

我覺得這支影片非常值得讓大家知道。它出現時，系列架構其實已經大致完成了，我還是回頭重新看前面的文章，把與函式長度、TDD 節奏、品質關卡、軟體基本功，以及 Values 與 Discipline 有關的內容補進去。

所以你後面讀到的內容，沒有完全停在最初的大綱。這個系列也跟著新的訪談、實驗結果與反例持續調整。

這也帶出了我最在意的問題：如果人類以後真的少讀一些 AI 產生的程式碼，Clean Code 是否就失去價值了？

人類少讀幾行，AI 還是要讀 Repository

Clean Code 最常被提到的價值，是讓人更容易閱讀與維護程式碼。

AI Coding 時代，人類閱讀每一行 Implementation 的時間可能下降，維護工作仍然會持續發生。需求會改、Bug 會出現、依賴會升級、資料契約會演進，幾個月後也一定有人或 Agent 要再次理解當初的設計。

而且，AI 本身也需要讀程式碼。

OpenAI 對 Coding Agent 的說明提到，Agent 會在 Repository 中讀取與修改檔案，也會執行測試、Linter 與 Type Checker。Harness Engineering 的實作分享進一步把 Context 視為稀缺資源：Repository 必須讓 Agent 找得到系統與業務領域的真實資訊。

工具能幫 Agent 讀取與驗證，最後仍需要人判斷結果。GitHub 在負責任地使用 Copilot Chat的文件中，也提醒使用者 Review 並測試產出的程式碼。

這裡的 Repository Context，指 Agent 為了理解專案而實際取得的程式碼、測試、文件、規則與領域資訊。Repository 裡有檔案，不代表 Agent 已經找到正確規則；能看見哪些內容，以及能否把它們連回當前任務，才決定這次 Context 是否足夠。

以前，我們主要考慮下一位工程師能不能看懂；現在還多了一位讀者：Agent。它得找到正確檔案、追到真正的規則、辨識依賴方向，並在有限的 Context 裡建立足夠準確的理解。

如果名稱模糊、函式同時處理多種責任、邊界藏在實作細節裡，Agent 就得搜尋更多位置、讀取更多檔案，再自行猜測缺少的關係。清楚的名稱、集中的責任、明確的依賴與可執行的測試，至少有機會降低這些額外的理解成本。

Clean Code 風格能不能節省 Token，我目前沒有答案。結構清楚可能減少反覆搜尋、補充說明與載入無關脈絡的成本；較長的命名、更多抽象層與拆得更細的檔案，也可能增加 Agent 必須讀取的內容。後面的實驗會看整個任務的總成本：它讀了多少 Context、走了多少錯路、來回修正幾次，最後又需要多少人工說明。

AI Coding，讓我反覆撞上同一批問題

另一個起點，是我近期大量 AI Coding 的實作感受。AI 確實讓產出速度變快；速度一快，散落在需求、程式碼、測試、架構與 Review 裡的問題也跟著放大。

AI 沒拿到真實需求與 Repository 規則時，會用常見做法補完空白。任務範圍沒切清楚，一個局部修改就可能一路擴張；名稱、狀態與副作用不夠明確，它只能從實作細節猜意圖。更麻煩的是，Agent 說「完成」時，我們未必拿得到能重跑的測試與工具輸出。就算所有關卡都綠了，API 契約、資料或通知行為仍可能在沒有授權的情況下改變。

這些是我目前的實作觀察，適用範圍還不能外推到所有團隊。後面進入案例時，我會逐篇交代使用工具、Repository 規模、任務條件與實驗證據。

一句「請遵守 Clean Code」處理不了這些問題。

我需要一組能放進任務、開發與 Review 的共同語言，用來提醒 User 怎麼駕馭 Agent：情境有沒有查清楚？修改有沒有越界？證據在哪裡？外部行為有沒有改？

於是，我把自己從 Clean Code 與 AI Coding 實作中反覆遇到的問題，歸納成 CLEAN 五原則。

CLEAN：我從 Clean Code 延伸出的五項 AI 協作責任

CLEAN 是我為 User 使用 AI Agent 進行 AI Coding 整理出的原則。它沿用 Clean Code 對可讀性、可維護性與工程紀律的要求，再補上 AI 協作中的情境、修改範圍、意圖與邊界、審查證據，以及可預期行為。

五個字母各自負責一項任務：

• C：掌握真實情境。
• L：限制變更範圍。
• E：說清楚意圖與邊界。
• A：留下可審查實據。
• N：守住可預期行為。

完整名稱與 Review 問題如下：

CLEAN 沒有固定的執行順序。

有時候要先補 Context，才能判斷改動範圍；有時候要先用測試固定行為，才知道哪些地方不能碰；碰到架構問題時，也可能先釐清邊界，再把工作切成幾個局部變更。順序會隨任務調整，五項責任都需要有人守住。

後面 32 篇談到的命名、函式、測試、SOLID、架構、軟體工藝與 Policy-to-Skill，很多都可以看成 CLEAN 五原則在不同情境下的排列組合。CLEAN 不會取代書裡的原則；它是我把那些觀念帶進 AI 協作流程時，反覆使用的檢查視角。

後面 32 篇：從 Code、Design、Architecture 走到 Craftsmanship 與 Skill

系列名稱保留「30 天」作為參賽主線識別，實際內容共有 33 篇。文章會沿著第二版的四個部分前進，最後再把 Policy 整理成 Skill，回到工程師的責任與持續學習。

這個系列會把重心放在觀念與工程判斷。後續實驗沿用同一支 C#／ASP.NET Core Work Item API，讓前後結果可以比較。API 專案負責留下 Prompt、Diff、測試、工具輸出與人工決策，文章則專注在我如何判斷與取捨。

時間很緊，我還是想把它寫完

時間確實很趕。可這個題目正好連著我最近最常想的問題：AI 已經進入開發流程，Clean Code 也沒有停在舊時代。產生程式碼變便宜之後，理解、驗證、維護與承擔責任的成本更需要說清楚。

接下來，我會從 Uncle Bob 的 Clean Code 出發，把書裡的觀念放進 AI 開發現場，再用 CLEAN 五原則一篇篇檢查。

明天，我會先把一句很常見的要求交給 AI：

幫我把這段程式碼整理得更 Clean。

這句話聽起來很合理。等它真的進入 Repository，我們才會看見：AI 要清理的究竟是哪裡、哪些行為不能改，以及一句模糊的「更 Clean」，到底留下了多少空白讓它自己猜。

參考資料

• Robert C. Martin，2026-04-14 X 貼文。
• Robert C. Martin，2026-07-23 X 貼文與討論串。
• Robert C. Martin／Matt Pocock，Uncle Bob on Software Fundamentals in the Age of AI，YouTube，2026-08-19。
• OpenAI, Introducing Codex（頁面已標示為較早期的產品介紹，本文只引用 Coding Agent 會讀取 Repository、修改檔案與執行驗證工具等基本工作方式）。
• OpenAI, Harness engineering: leveraging Codex in an agent-first world。
• GitHub Docs, Responsible use of GitHub Copilot Chat in your IDE。