本文同步刊載於個人連載網站

上一篇寫到，系統拆成不同 repo 之後，還需要有地方保留整套產品共同的規格和架構脈絡。

但做到這裡，我又注意到另一件事。

只知道：

「現在決定怎麼做。」

有時候還不夠。

我還需要知道：

「當初為什麼會這樣決定？」

很多工程選擇沒有永遠正確的答案

這個想法來自 mentor 的提醒。

他曾經跟我說過一句話：

「其實所有技術選擇都是對的，只是看當下情況評估要選哪個而已。」

我理解這句話的方式是：

很多工程選擇都不是單純的對或錯。

同一個方案，在不同需求、限制和成本下，可能會有不同結果。

所以如果只留下最後答案：

我們用了這個方案。

過一段時間之後，很容易只看到結論，卻看不到它原本建立在哪些條件上。

而那些條件可能已經改變了。

我想留下的不只是決策結果

所以這個專案從一開始，就會把重要決策背後的理由一起記下來。

不只是：

最後選了什麼。

也包括：

• 當時在解什麼問題
• 考慮過哪些方案
• 為什麼最後選這個方向
• 當時有哪些限制
• 這個決定適用到什麼範圍

這些內容會整理進決策總目錄和對應文件。

對我來說，規格和決策紀錄處理的是不同事情。

規格比較像在回答：

現在系統應該怎麼運作？

決策紀錄則多回答一層：

為什麼當時會選成現在這樣？

這些紀錄主要不是寫給我的記憶

到目前為止，大部分重大決策我自己還記得。

所以留下這些文件，主要不是因為怕自己忘記。

更重要的是：

讓 AI 重新進入專案時，也能讀到過去做過的判斷。

Codex 處理新的修改時，不只需要知道目前的程式和規格。

它還需要知道：

這個分工原本為什麼存在？

這個方案是為了避開什麼問題？

某個限制是暫時的，還是產品原本就需要守住？

新的做法有沒有和過去的決策衝突？

如果它只看到現在的程式，很容易把現況當成理所當然。

但很多結構都有一段形成過程。

所以我還做了一個自訂 skill，讓 Codex 在處理新的工作時，先檢查既有決策，並持續維護這些紀錄。

決策存在，不代表已經做完

真正開始用這套文件之後，我又看到另一個很實際的問題。

一開始，決策總帳主要記：

做了什麼決定。

但過了一段時間，我想確認：

這些決定到底做到哪裡了？

才發現「已經決定」和「已經實作」很容易混在一起。

有些事情方向早就確定。

文件也已經寫好了。

但程式還沒有全部完成。

如果只看：

有沒有這份決策文件？

很容易把：

已經決定

誤認成：

已經完成。

所以後來我又把幾種狀態拆開。

例如：

• 決策狀態
• 實作狀態
• 證據狀態

讓 Codex 可以直接比對：

這個決策現在還有效嗎？

對應實作做到哪裡？

還有哪些部分沒完成？

目前有沒有測試、驗收或其他證據可以確認它真的落地？

決策本身也會改變

留下「為什麼」還有另一個作用。

有些決策會一直有效。

有些只需要調整一部分。

有些則會因為新的需求和條件，正式被另一個決策取代。

如果只留下最新答案，很容易看不出：

原本哪個前提已經失效。

哪個部分仍然適用。

又是哪個條件改變，才讓新方案變得更合理。

留下決策脈絡之後，重新評估就不會只變成：

「以前這樣做是錯的，所以現在改掉。」

更接近：

「以前的判斷建立在什麼條件上？現在又是哪個條件已經變了？」

這也和前面寫過的 n8n 很像。

當時用 n8n 本來就有它成立的條件。

後來不是突然證明那個選擇錯，而是問題本身已經變了。

我開始留下的不只是系統現在長什麼樣子

以前我比較容易只關心：

現在功能是什麼。

現在架構怎麼分。

現在程式怎麼運作。

到了這個專案，我開始多留下一層：

它為什麼會長成現在這樣。

這些紀錄讓後面的修改不只是看目前狀態。

也可以回頭理解：

這個選擇原本是為了解決什麼。

現在那些條件還在不在。

如果要改，真正改變的是哪個前提。

對 AI 協作來說，這也很重要。

因為我想交給 Agent 的，不只是：

目前系統長什麼樣子。

也包括：

我們為什麼會把它做成這樣。

而再往前追一步，這些工程決策通常又建立在另一個更基本的問題上：

這個功能如果真的成立，系統到底必須保證什麼？