模組六｜工程文化與收斂（Day 27–30）

Day 3 講過一個場景：兩套系統裡有三行程式碼，一邊是活的、一邊被註解掉了。

沒有註解說明原因。git 找得到是誰哪天關的，但找不到為什麼。

於是那三行永遠卡在那裡：要動它的人得先考古半天，然後多半選擇不碰。

今天這篇要回答的就是：怎麼讓「為什麼」不要消失。

我會講兩件看起來無關的事：規格文件和寫給 AI 的專案守則。它們解的其實是同一個問題。

第一件事：把需求變成三份文件

專案後期導入了規格驅動的變更管理。做法是：每個需求有自己的目錄，裡面固定放三份東西。

現況是 7 份穩定規格、4 個進行中的變更、9 個已封存。

每個變更目錄長這樣：

某個需求/
├── proposal.md   為什麼要做、要做什麼
├── specs/        改完之後，行為規格是什麼
└── tasks.md      拆成哪些可勾選的步驟

為什麼是「後期」才導入

這件事的時機很有意思。

遷移初期不需要規格，因為需求來源是舊系統本身：「照著舊的做」就是規格。你要問「這個欄位該不該必填」，答案是「去看舊系統怎麼做」。

但當新系統開始接全新的需求時，這個答案就消失了。

規格驅動的價值，是在你沒有參考對象的時候才顯現的。 太早導入只會變成多寫一份跟舊系統重複的文件。

最重要的欄位，是最常被省略的那個

三份文件裡，我認為最有價值的一段是提案裡的「哪些方案被否決了」。

因為：

• git 已經記錄了「做了什麼」：每一行改動都在那裡
• 程式碼本身說明了「怎麼做」：讀就知道
• 但「為什麼不用另一種做法」，不會留在任何地方

而三年後那個要動這段程式碼的人，需要的正是最後這一項。

回到 Day 3 那三行：如果當初留下的是「這段先關掉，因為某某情況會出錯，等後端調整完再打開」，那後來的人就不用考古了。

文件的價值不在記錄「做了什麼」，在記錄「為什麼不那樣做」。

已完成的規格要封存，不要刪

那 9 個已封存的規格，我一開始覺得是垃圾：需求都做完了，留著幹嘛？

後來想通：它們是未來考古的唯一線索。

當某個奇怪的邏輯讓人困惑時，你可以去封存區搜。而如果當初把它刪了，那段邏輯就會變成另一個「那三行」。

第二件事：讓 AI 讀得懂你的專案

這件事表面上跟前面無關，但我認為它們是同一件事的兩面。

我們做了兩樣東西。

一份專案守則

一份約 170 行的文件，內容分三塊：

工作準則：先讀再改、外科手術式的改動（不要順手重構無關的東西）、遵從既有慣例而非個人偏好、失敗要明確報錯不要吞掉。

專案慣例：路徑別名怎麼設、API 檔案要先用列舉宣告路徑、元件是全域自動引入不要手動 import。

地雷清單，Day 25 講的那些：拼錯的欄位名、會觸發全域登出的錯誤碼、不能手改的自動產生檔案。

一套上下文打包腳本

它把某個業務域的相關檔案打包成單一檔案，餵給 AI 當背景資料，用完即丟。

為什麼要打包，而不是讓 AI 自己找？

因為大型專案的檔案搜尋很貴，而且找到的多半不是你要的那幾個。你問「訂單查詢頁怎麼組搜尋條件」，它可能翻出十個名字裡有 order 的檔案，其中八個無關。

打包的本質是：你已經知道答案在哪裡，所以直接把範圍給它。

而這件事有個副作用很有意思：為了能打包，你必須先有清楚的目錄結構。如果檔案散得到處都是，你連「這個功能相關的檔案有哪些」都圈不出來。

協作流程

團隊的文件寫了五步：說清範圍 → 掛上下文 → 先讀再改 → 改完驗收 → 大改之後重新打包。

第三步「先讀再改」是最容易被跳過、也最容易出事的一步。

兩件事的共通點

規格文件和 AI 守則，做的是同一件事：

把只存在腦袋裡的東西寫出來。

而我後來發現一個反直覺的收穫：

寫給 AI 的守則，人讀了也受益。

因為要寫給 AI，你被迫把那些「大家都知道的默契」變成文字。而那些默契，新人其實也不知道。

舉個例子：「API 檔案要先用列舉宣告路徑」這條慣例，在寫下來之前，是靠 review 時被提醒才學會的。寫下來之後，新人第一天就知道了。

所以我認為導入 AI 協作最大的收穫，不是 AI 幫你寫了多少程式碼，是它逼你把專案的隱性知識顯性化。

有沒有覺得這個結論很耳熟？Day 7 講 Composition API、Day 8 講事件改狀態、Day 17 講旗標取代推測，全部都是「把隱性的東西變顯性」。

這篇只是把同一件事做在文件層。

誠實的部分：AI 協作會產生垃圾

講完好處，講我們搞砸的地方。

那個上下文打包腳本會產生打包檔。而在某個時間點，有人把這些產生出來的檔案 commit 進版控了。

後來被發現，一次刪掉，八萬多行。

八萬行的自動產生檔案，躺在版本紀錄裡。它們不會造成 bug，但會：

• 讓每次 git diff 都變得很難看
• 讓 clone 變慢
• 讓搜尋結果充滿噪音

修正之後的做法是：打包檔一律不進版控，需要時現產。

而這件事的教訓比表面上大：

AI 協作會產生一批「中間產物」：上下文檔案、驗證腳本、臨時的測試頁、截圖。

它們的共同特徵是：產生的時候很有用，五分鐘後就是垃圾。而沒有人會回頭刪。

我們專案裡現在還有一些這類殘留：某次功能驗證留下的腳本和截圖、一個為了預覽某個元件而建的臨時網頁。它們都沒有被清掉。

所以正確的做法應該是在建立這類東西的時候就決定它的歸宿：進版控？進忽略清單？還是產在暫存目錄？

不決定，預設就是留著。

代價

一、規格文件會過期，而過期的文件比沒有文件更糟。 我們沒有機制確保規格跟程式碼同步：如果某個需求後來改了實作但沒更新規格，那份文件就開始說謊。

二、寫文件的成本是真的。 一個需求要多寫三份文件，在交期壓力下第一個被砍的就是它。我們的實際狀況是：大需求有寫、小需求多半沒有。而那些小需求累積起來，就是下一批「不知道為什麼」的程式碼。

三、AI 在「決定要不要改」上完全不能信。 它在重複性改寫和掃同類問題上很強，但它會很有自信地告訴你某個東西可以刪，而它沒有辦法知道那個東西在某個一年跑一次的排程裡被用到（Day 14 講過的那個情境）。

四、上下文打包讓人偷懶。 因為餵資料很方便，所以容易跳過「自己先讀一遍」。而跳過理解直接改，正是那份守則第一條想防的事。

帶走什麼

1. 文件的價值不在記錄「做了什麼」，在記錄「為什麼不那樣做」。 前者 git 已經有了。
2. 規格驅動要在「沒有參考對象」的時候導入。 遷移初期舊系統就是規格，太早寫只是重複。
3. 已完成的規格要封存不要刪。 它是未來考古的唯一線索。
4. 寫給 AI 的守則，人讀了也受益，因為它逼你把默契變成文字。這是導入 AI 協作最被低估的收穫。
5. 中間產物要在建立時就決定歸宿。 不決定，預設就是留在 repo 裡，然後累積成八萬行。

明天 Day 28 講一件我覺得很少被當成工程問題看待的事：刪除。

我們寫了一組腳本來找出「沒有人在用的 API」：而最難的部分不是找，是定義什麼叫「安全」。