前言：「感覺寫得太複雜」不是一個可以放進 checklist 的標準

前幾天講了本質複雜度跟意外複雜度的區別，但這種區分方式有一個實務上的問題：它終究要靠「感覺」跟「經驗」去判斷,不是每個 reviewer 都有一樣的敏感度,也很難寫進一份客觀的 code review checklist 裡要求每個人一致執行。

今天想提供一個更具體、更容易操作的替代方案：與其問「這段程式碼複不複雜」，不如問「改一個小需求，要動幾個檔案」。 這個問題的答案是一個可以數出來的數字,不是主觀感受。

今日目標

• 理解「改動範圍 vs 需求範圍」這個指標為什麼比「複雜度高不高」更容易操作
• 用 ai-news-test 實際跑過的「新增分類欄位」案例看這個指標怎麼運作
• 學會估算一個新需求「合理」的改動範圍大概長什麼樣子
• 認識這個指標的限制：不是每種需求都能簡單量化
• 建立一個 review 時可以直接問的具體問題句型

指標定義：改動範圍應該跟需求範圍成比例

這個指標的核心想法很直接：如果一個需求本身很小（例如新增一個欄位），改動的檔案數量也應該很小；如果改動的檔案數量遠遠超過需求本身的複雜度，那多出來的部分很可能是意外複雜度在作祟，而不是需求真的需要這麼多改動。

這跟前幾天講的「本質複雜度 vs 意外複雜度」是同一個概念，只是換了一個更容易數出具體數字的角度——不用先判斷「這段邏輯複不複雜」，只需要數「改了幾個檔案」。

實測案例：新增一個「分類」欄位

在 ai-news-test 這個示範專案裡，我實際估算了一個具體的小需求：替文章加上「分類」欄位。這是一個很典型的「小需求」——不涉及新的業務規則，只是多一個屬性。

需求本身沒有變複雜——就是多一個欄位。乾淨版本改動範圍跟需求範圍大致成比例（一個欄位，動到儲存與傳遞這個欄位的三個環節）；過度設計版本因為多了一層又一層的轉換鏈（Aggregate 到 TableGateway 到 SQL Builder 到 Mapper，還有 Command 到 Handler 到 Validator 兩組），同一個欄位要在每一層都補上對應的改動，改動範圍因此放大了 3-4 倍。

這個數字比「行數多寡」更能具體回答一個問題：AI 寫出來的東西,有沒有讓後續維護變貴？ 21,727 行本身不是問題（如果這些行數服務著相對應的業務複雜度,行數多也合理），問題是「多一個欄位要動 10 個檔案」這件事,直接反映了維護成本被不成比例地推高。

❌ / ✅ 對照：怎麼用這個指標檢查

❌ 只看行數或檔案數的絕對值，沒有跟需求範圍對照：

「這個 PR 改了 800 行,有點多,要不要拆小一點？」
（沒有問：這 800 行對應的需求本身有多大？）

✅ 把改動範圍放進需求範圍的脈絡裡去問：

「這個需求只是新增一個欄位，正常情況大概會動到
『儲存層 + 傳遞層 + 讀取層』三個環節。
這個 PR 動了 10 個檔案,多出來的 7 個檔案在解決什麼問題？」

後者的問法把「複雜度高不高」轉換成「這個改動範圍有沒有合理的理由」，這是一個 reviewer 可以具體回答、也可以要求對方具體回答的問題，不需要依賴模糊的架構品味。

這個指標的限制

這個方法不是萬能的,有幾個要注意的地方：

• 不是每種需求都能簡單換算成「應該動幾個檔案」——涉及跨模組的重構、或者本質複雜度真的很高的需求（例如真的需要處理多個資料來源的一致性），改動範圍本來就會比較大，這個指標不能用來一刀切地說「動超過 N 個檔案就是過度設計」。
• 這個指標比較適合用在新增一個小屬性/小規則這種相對單純的變更上，用來當作「意外複雜度是不是偏高」的訊號，而不是唯一的判準。
• 真正要落地成可執行的規則，還需要搭配一個「複雜度預算」的概念——這部分會在系列後半段（第三部）具體展開,今天先建立「改動範圍可以被量化、可以被拿來對照需求範圍」這個核心概念。

為什麼這件事重要

「感覺太複雜」是主觀的，不同人、不同心情、不同熟悉程度,判斷結果都會不一樣；「改一個欄位要動幾個檔案」是客觀的,任何人數出來的答案都一樣。 這個差異在 AI 產出速度下特別關鍵——如果 review 的標準只能靠資深工程師的直覺去把關，這個把關能力沒辦法規模化，也沒辦法被寫進自動化流程裡。而一個可以量化的指標,理論上可以變成一條可以被工具驗證的規則，這正是本系列的主題句：AI 沒有發明過度設計，它只是讓過度設計的速度追上了你按下 Enter 的速度；Review 要跟得上，審的就不能再是程式碼本身，而是產生程式碼的規則。 而規則要能執行，前提是它要能被量化。

今日思考題

想一個你最近處理過的小需求（新增一個欄位、加一個簡單的檢查規則），回想一下當時實際動了幾個檔案。如果現在請你的團隊成員憑直覺猜這個數字，猜出來的答案跟實際數字會差多少？

今日重點回顧

• 「改動範圍 vs 需求範圍」是一個比「感覺複不複雜」更容易操作、可以數出具體數字的指標
• ai-news-test 實測案例：新增分類欄位,乾淨版本動 3 個檔案，過度設計版本要動 10-11 個檔案，需求本身完全沒變複雜
• 這個指標適合當作「意外複雜度是否偏高」的訊號，不是唯一判準,不能一刀切套用在所有需求類型上
• 可量化的指標才有機會變成可以被工具或流程自動驗證的規則

明日預告

Day 7 要把前面幾天的觀察收斂成第一部的結論：Code Review 這套「人眼逐行看程式碼」的舊模型,為什麼從結構上就追不上 AI 現在的產出速度。

老派工程師的心得

我自己在推動 code review 文化的過程中，長期以來最頭痛的一件事，就是很難把「這樣寫感覺怪怪的」這種直覺講清楚，讓不同資歷的人有一致的判斷標準。這幾年我開始試著把這種直覺轉換成可以量化的問題——不是每次都成功，但「改動範圍跟需求範圍成不成比例」這個問法,是少數幾個真的讓不同資歷的人都能給出接近答案的問題之一。能被量化的判準，才有機會變成團隊共同的語言，而不是只掛在資深工程師腦子裡的默契。