設計文件照「第幾批」分，不到半天，就有一份把第五關講錯了

我自己在做一款雙人橫向清版遊戲，玩起來像小時候的《吞食天地 II》，一路往右走一路打，主角換成了寶可夢，算是一款致敬作。兩個人可以擠在同一副鍵盤上玩，也可以各拿一台平板連同一個 Wi-Fi，目前只有 Mac 和 Windows 版，沒有公開發行。

這個遊戲大部分的程式是 agent 寫的，我決定要做什麼，它們做出來。為了讓每個新開的 agent 都知道遊戲現在長什麼樣，repo 裡有一個資料夾專門放設計文件，每一關有哪些敵人、王是誰、玩家在這關要學會什麼，都寫在裡面。agent 開工前會先讀，文件開頭也寫著一條規矩：文件跟程式碼對不上的時候，以程式碼為準。

這次出事的就是這個資料夾。

6 月 15 日晚上，我開始替遊戲擴充一大批招式和關卡。量很大，拆成幾批做，一批叫一個 slice，設計文件也照這樣分，第一批的機制一份，第二批的內容一份，第四批再一份。寫的當下很自然，做到哪一批就打開哪一份。

16 日早上 7 點 15 分，第二批的文件寫好了，裡面說第五關是超能力系，第六關是火系。37 分鐘後，第四批的文件提議把關卡重排，對齊初代遊戲的道館順序：第五關毒、第六關超能力、第七關火。那時還特別註明，這一批先不動順序。

晚上 7 點 51 分，程式碼真的照新順序換了，遊戲裡的第五關變成毒系，玩起來也對。第二批那份文件卻還寫著第五關是超能力。它沒有打錯字，在它寫下來的那個早上，這句話是真的，只是遊戲往前走了，文件還留在早上。另外有一座城市，幾份文件裡有的叫「山吹」，有的叫「金黃」，講的是同一個地方。

這種錯不會發出聲音。程式壞了會噴錯，測試會變紅，玩家會抱怨，文件只會安靜地躺著，排版整齊，連結點得進去，看起來很可信。下一個打開它的 agent 不會知道它過期了，就照著它去做第五關。

8 點 38 分，我先用最直覺的辦法處理，讓 agent 把所有文件跟程式碼對過一遍。舊的關卡編號改成現在的，城市名統一叫「金黃」，跟後來決定互相矛盾的段落直接刪掉。第四批那份沒動，它的內容剛好是對的，另一個 agent 也還在用它做後面的關卡。

改完之後，我盯著這幾份檔案想，今天是對齊了，下次關卡再調一次順序，同樣的事還要再來一遍。毛病出在分類的方式上。「第幾批」只在開發的那幾天有意義，做完以後沒人在乎某個機制是第二批還是第四批做的，玩家更不在乎，文件掛在一個註定會過期的名字底下，內容遲早跟著過期。

21 分鐘後，我換了做法，設計文件改成一關一份。第五關到第九關各寫一份，原本散在幾批裡的內容，看它實際影響哪一關就搬過去：睡眠和混亂兩種狀態第一次出現在第六關，就寫進第六關；毒寫進第五關；半路殺出來的精英怪寫進第八關。搬完以後，四份按批次分的文件直接刪掉，那一筆刪了 494 行、加了 354 行，文件之間互相連結的地方全部重新接好，一條斷掉的都沒有。

刪的時候我猶豫了一下，畢竟是寫過的東西。可是過期的文件比沒有文件更麻煩，沒有文件，agent 會老實去讀程式碼，有一份過期的文件，它會相信那份文件。

新的第八關文件裡有一句我很喜歡的老實話：程式碼裡這一關還是舊的龍系佔位，地面系的內容還沒做。它沒有假裝自己已經完成。不到一個小時，地面系的第八關就接進了遊戲。

我比較在意的是讀文件的對象換了。以前設計文件主要寫給自己看，記錯了自己會發現。現在每天開工的是好幾個 agent，每一個都從零開始讀，不會記得昨天關卡換過順序，文件分錯了，最先被騙的就是它們。

其他作品在作品集。

先不說了，我得去看看別的資料夾裡，還有沒有用「第幾批」命名的文件。

這段 code 寫於 2026 年 6 月 16 日，文章整理於 2026 年 10 月。