上一篇先看過 Spec Kit 的基本運作方式：第一次導入專案時先建立 constitution，後續每個需求或變更，再從 specify、plan、tasks 一路走到 implement。不過，那是我現在回頭整理後，才比較完整看懂的流程。第一次實驗時，我只有大概知道 commands 的執行順序，也簡單看過各個階段會產生什麼文件，並沒有深入理解每份文件為什麼要分開，又該寫到什麼程度。
即使只有這些初步理解，當時看到 spec、plan 與 tasks 都產生出來，我還是理所當然地以為：既然已經有 spec，整套架構一起做應該也沒問題吧？
當時我正在開發一套內部系統，裡面已經有一套使用中的權限設計。我第一次拿 SDD 來做的事情，不是一個獨立的小功能，而是重新設計整套權限架構。
說是重新設計權限，其實不是多加幾個角色而已；從誰能管理誰、每個模組可以做什麼，到特定資料能不能看，都在這次調整的範圍裡。這些判斷又同時影響後端、操作畫面與既有功能，幾乎等於把整套系統的權限基礎重新整理一遍。
當時的專案背景： 在我接觸 SDD 以前，這套系統的前端與後端原本放在不同 repo。開始大量使用 AI Agent 開發後，我就先把兩邊整合成 monorepo，希望 AI 修改功能時可以同時看到前後端的架構與實作。這項調整在第一次實驗前就已經完成，和後來的權限重構沒有直接關係；不過，它也確實讓我導入 SDD 時，比較少遇到前後端分開造成的問題，至少 AI 可以在同一個 codebase 裡一起查看前後端的實作。
也因為改成 monorepo 後，AI 在前後端之間的協作確實順了不少，再加上專案架構與使用的技術也寫在 CLAUDE.md，到了這次實驗時，我很自然地認為：AI 既然看得到整個專案，也讀得到這些規範，應該就知道這次要沿用哪些做法吧？
會有這種想法，也和我當時寫 CLAUDE.md 的方式有關。那時我還在摸索這份文件該怎麼寫，只要覺得 AI 可能會用到，就一直往裡面加。從專案使用的技術與架構，到命名方式、分層規則、錯誤處理、權限檢查、測試與資料庫規範，幾乎全部都放在同一份文件裡。把原本內容簡化一下細節後，大概會像這樣：
# 專案開發規範
## 架構
- API 依照 Controller、Service 與 Data Access 分層
- Controller 處理 request 與 response，商業邏輯放在 Service
## 程式碼
- 公開型別與屬性使用 PascalCase
- 區域變數與參數使用 camelCase
- 註解說明「為什麼」，不要重複程式碼已經表達的事情
## 安全與資料
- 所有輸入都需要驗證
- 權限檢查不能只依賴前端
- 動態查詢必須使用參數化方式
## 測試
- 商業邏輯需要單元測試
- 外部依賴使用 mock
這還只是精簡後的示意。實際那份 CLAUDE.md 寫得更長（看 git 歷史紀錄後才發現有 1000 多行XD），裡面也混在一起放了不少具體實作方式。也因為裡面看起來什麼都有，我更容易認為：架構、技術與規範都已經交代過了，plan 應該不用再寫一次吧？
所以，我先把整個需求丟給 AI 產生 spec。到了 plan 階段，我沒有再把這次調整應該採用的架構、技術作法與重要決策說完整，就接著讓 Spec Kit 產生 plan 與 tasks。
當時 spec、plan 與 tasks 產生出來時，我也有逐項閱讀與比對，並不是看都沒看就直接交給 Agent 實作。只是當這些文件一份一份產生出來，我很容易就覺得需求已經被整理好了。tasks 也確實被分成不同 phase，看起來每一段都有規劃，所以我就直接讓 AI 開始 implement。
進入 implement 後，我印象中 AI 在每個 phase 做完時有停下來，讓我查看結果。只是它一停，我幾乎沒有仔細核對，就直接回覆「請繼續」。現在回頭看，我當時根本是在人工版的「Ralph Loop」XD。就這樣一個 phase 接著一個 phase，直到整份 tasks 全部做完。
然後，對，整個專案就炸了！
等我真的開始檢查時，才發現問題已經不只是某一個功能做錯。我還記得，有些 UI 沒有放在原本應該出現的位置，AI 甚至另外做出一套新的畫面，建立新的 CSS class，沒有沿用專案現有的 UI 套件與 Tailwind CSS。回頭對照 plan，裡面也出現了 codebase 原本不存在的名詞與架構；到了 implement 階段，AI 就把這些內容當成已經確定的設計，繼續往下補出實作。
更麻煩的是，專案裡還出現大量無法編譯的錯誤，原本可以使用的功能也跟著壞掉。這些問題不是集中在某一個 task，修完就能繼續，而是早已散在整個專案裡，讓我一時不知道該從哪裡查起。
到了這個地步，已經不是補幾個 Bug 就能安心繼續，所以我最後乾脆直接用 Git 還原，整個重新開始。
當時的 templates 有安排檢查點嗎？ 後來回頭查看當時的 templates，我才發現 Spec Kit 產生 tasks 時，本來就會依照 user story（使用者故事）安排不同 phase。implement 也要求完成每個 phase 後先驗證，再繼續下一個。只是每次 AI 停下來，我都直接使出「請繼續」大法，沒有真的確認結果就讓它繼續往下做。
Git 還原之後，我第一個想到的就是：下一次真的要停下來檢查了XD。同時我也開始懷疑，是不是第一次提供的需求不夠詳細，plan 時給 AI 的架構與技術作法也寫得不夠完整。
第二次實驗，我仍然保留同樣的目標與範圍，準備從需求、plan 與 implement 的方式開始調整。我當時以為，這樣應該已經把第一次看得到的問題一個個補起來了，但這樣真的足夠嗎？
這次不只是把需求描述得更詳細，到了 plan 階段，我也把適合當時專案的架構與技術作法補得更完整，再讓 Spec Kit 產生 research、plan 與 tasks。
spec、research、plan 與 tasks 產生出來後，我也重新檢查內容是否符合專案既有的架構與規範，尤其是 plan 裡寫下的架構與技術作法。確認過這些內容後，我才交給 AI 實作。
進入 implement 後，我也沒有再讓 AI 一路做到最後，而是直接指定它先完成某個 phase，或是自己選定這一輪要執行的 tasks；等指定範圍做完後，我再看結果，決定下一輪要做哪個 phase 或哪些 tasks。
這些調整確實有效。描述清楚的部分，比第一次更接近我要的結果；因為改成分段執行，無法編譯的問題也比較不會一路累積到最後。至少這次沒有等到整份 tasks 全部做完，才發現整個專案一起壞掉。
可是，才執行幾輪，我就發現 AI 又開始慢慢走向和我預期不同的方向。
蛤？這次我不是已經寫得更詳細，也真的有分段檢查了嗎？
第一次實驗，我等到整份 tasks 做完才看到整個專案一起壞掉；第二次，我已經把執行範圍縮到指定的 phase 或 tasks，也確實更早發現方向不對。分段檢查確實讓我提早看到偏離，卻沒有阻止偏離發生。
需求寫得更多、plan 補得更完整、implement 也改成分段執行，結果為什麼還是沒有回到我要的方向？下一篇，我會把兩次實驗放在一起，從 spec、research、plan、tasks 一路重新往前找！
iThome鐵人賽
看影片追技術