「這段程式碼看起來繞了一大圈，直接改成更直覺的寫法不好嗎？」
如果你請 AI 重構一套系統，這句話大概會在某個時間點出現——而它可能是對的，也可能正好戳破一個當初刻意做出來、卻沒有留下任何紀錄的設計取捨。AI 讀程式碼的能力很強，但程式碼本身只記錄「現在長什麼樣」，不記錄「為什麼長這樣、當初還考慮過哪些做法、為什麼放棄了它們」。這個落差，正是今天要講的主題。
一段程式碼繞路，可能有兩種完全不同的原因：一種是純粹的技術債，當初沒想清楚、後來也沒空整理；另一種是刻意的取捨——團隊評估過更直覺的寫法，但基於某個當下才成立的限制（效能考量、跟另一個系統的相容性、暫時性的資源限制）決定不那麼做，繞路本身就是設計的一部分。
問題是：光看程式碼，這兩種情況長得一模一樣。人類工程師如果剛好在場、剛好記得，還能靠記憶補上「為什麼」；但 AI 沒有這段記憶，它只能根據程式碼現狀做推論，而推論的起點通常是「這看起來像技術債」——因為技術債本來就是更常見的情況，AI 的先驗假設會自然地往這個方向傾斜。
這正是這個系列反覆出現的模式：AI 給出的判斷，只在它實際查證過的範圍內成立——而「為什麼當初這樣設計」這件事，不寫下來,就永遠不在任何 AI 查證得到的範圍內。
ADR（Architecture Decision Record，架構決策紀錄）這個概念，是 Michael Nygard 在 2011 年一篇文章〈Documenting Architecture Decisions〉裡提出並推廣開來的做法——核心精神很簡單：針對每一個重要的架構決策，寫一份簡短的紀錄，內容包含當時的背景（context）、做出的決定（decision）、還有這個決定帶來的後果與取捨（consequences）。它刻意設計成輕量、簡短，目的是讓團隊真的願意持續維護,而不是變成又一份沒人讀的大部頭文件。
ADR 不是設計文件，不需要鉅細靡遺地描述系統怎麼運作；它記錄的是「決策當下的脈絡」——考慮過哪些替代方案、為什麼選了這一個、放棄的方案有什麼代價。這正好補上程式碼本身缺的那一塊。
❌ 沒有 ADR：
AI 讀到一段程式碼：某個查詢刻意不用 ORM 的關聯查詢，
改用兩次獨立查詢再手動組合結果。
AI 的判斷：「這裡應該可以簡化成一次關聯查詢，效能更好、
程式碼更簡潔，我先改掉。」
→ AI 只看到「現在這樣寫比較繞」，看不到這個決定
當初是不是為了避開某個已知的效能陷阱
✅ 有 ADR：
AI 讀到同一段程式碼，同時查到對應的 ADR 記錄著：
「考慮過用關聯查詢，但在資料量大的情境下會產生
笛卡兒積導致的效能問題，改用兩次獨立查詢是刻意取捨，
如果未來 ORM 支援更好的分批關聯查詢，可以重新評估。」
AI 的判斷：「這是一個已知的刻意取捨，如果要改，
要先確認 ORM 有沒有解決當初那個效能陷阱。」
→ AI 的查證範圍多了「這個決策的脈絡」，
判斷因此更貼近真實情況
沒有 ADR 的版本裡，AI 不是判斷錯了，它只是在一個不完整的資訊範圍內給出了一個看起來合理、實際上可能倒退回舊坑的建議。這不是 AI 能力的問題，是它從來沒機會查到那個關鍵的「為什麼」。
ADR 的價值建立在「輕量、只記重要的事」這個前提上，如果什麼決定都要寫一份，維護成本會壓垮團隊，最後變成沒人更新的裝飾品。值得寫 ADR 的通常是：影響範圍夠廣（不是一支函式內部的小選擇）、有明確的替代方案被考慮過又放棄、未來很可能被人（或 AI）質疑「為什麼要這樣做」的決定。日常的、顯而易見的實作選擇不需要每個都寫。
回想你手上系統裡某一段「看起來繞了一圈」的程式碼：你知道它繞路的原因嗎？如果讓 AI 去看，它有辦法查到這個原因，還是只能靠猜？
明天用一個具體案例，示範沒有 ADR 時，AI 真的把一個刻意的設計決策誤判成技術債、動手「修正」之後會發生什麼事。
iThome鐵人賽
看影片追技術