AIDive

影片資料包

在 Git 中治理 AI 的 spec 與 plan：五條規則、drift gate、來源與檢查清單

閱讀約 11 分鐘

TL;DR

  • 請把 AI 寫的 spec 和 plan 一起 commit。每個工具預設就是這麼做，真正懸而未決的是治理。
  • 每個 squad 一個資料夾，搭配一行 CODEOWNERS，spec 一有變動就會請該程式碼的 owner 來 review。
  • 每份共用 spec 都加上 ADR 風格的標頭：status、superseded-by、owner、touched paths、review date。不要把已 accepted 的 spec 改寫成新的決策。
  • 在 CI 跑 drift gate：對每份 accepted 的 spec，只要它提到的路徑已經不存在，就讓 build 失敗。
  • 用 CLAUDE.md 裡一行粗體的命令句改掉輸出路徑，個人 plan 放在 CLAUDE.local.md 和 .git/info/exclude，並且在分支上寫，絕不寫在 main。
  • 只為跨 squad 邊界、或 90 天後還會被重讀的工作寫 spec。以 spec 驅動的流程大約多花兩倍時間、三倍 token。

來源怎麼說

預設值：大家都 commit

Superpowers 的 writing-plans skill 把 plan 存到 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md，底下附一行說明：使用者對 plan 位置的偏好會覆蓋這個預設值 s1。brainstorming skill 把驗證過的設計寫到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md，最後一步是 "Commit the design document to git" s2。Spec Kit 的結構是 specs/[branch-name]/，裡面有 spec.md、plan.md、tasks.md，編號 001、002，另外在 memory/constitution.md 放 constitution s6。Kiro 維護 .kiro/specs/，一個功能一個資料夾，並鼓勵團隊 "collaborate with team members on different features simultaneously" s8。Anthropic 的 playbook 講得很明白："Every stage commits an artifact the next stage can read"、"Commit the approved plan as plan.md"、"When implementation departs from the plan, update plan.md in the same commit" s5。

這些文件都沒說 commit 進去的 spec 歸誰管，也沒說它什麼時候不再成立。三個有記錄的失敗案例，都出在這個空缺。

失敗 1：公開外洩

2026-06-05 開的 issue 1690 回報，預設位置 docs/superpowers/ 可能經由 Sphinx 和 Read the Docs，把內部 plan 洩漏到公開文件裡 s15。中招的專案是 okama，一個有 273 顆星的 Python 函式庫。它的修正 commit 重新加入 5 份 plan 和 3 份 spec，刪掉一行 .gitignore，訊息是 "track superpowers plans/specs in git, excluded from the Sphinx build" s21。docs/conf.py 第 84 行現在是 exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22。目前這個資料夾裡有 8 份 plan 和 6 份 spec s15。團隊保留了這個做法，修的是 build。

失敗 2：plan 進了 main

2026-04-22 開、至今仍未關閉的 issue 1246 問：為什麼 plan 在開發分支建立之前就被 commit 了？一位使用者說 "I'm getting 10 to 15 commits"；另一位說："Yes please, no plans and specs on main branch!" s16。外掛不會強制分支規則，下面的檢查清單會。

失敗 3：模型略過的覆蓋設定

issue 337 在 2026-03-10 關閉，維護者留言說從 v5.0 起，外掛會以專案的 CLAUDE.md 優先於自己的預設值，範例是這一行："Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17。v5.0.6 的 issue 939 顯示了它的極限：CLAUDE.md 裡的 "Output Paths" 表格被忽略，spec 還是持續存到 docs/superpowers/specs/。有效的解法是在表格下方加一行粗體命令句：design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18。調整指令順序的 pull request 1020 沒有合併就關閉了 s19。覆蓋設定是 prompt，不是設定檔：每次外掛發新版都要重新檢查。至於外掛自己的暫存檔，issue 1780 在 v6.0.3 關閉，做法是一個會自我忽略的 .superpowers/sdd/ 資料夾，裡面自帶一個內容為 * 的 .gitignore s20。

個人與共用

Claude Code 有文件說明這個切分："For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3。各目錄的 CLAUDE.md 會按需載入，"Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file"，而 monorepo 可以用 claudeMdExcludes 設定隱藏其他團隊的檔案 s4。Git 有三層 ignore：$XDG_CONFIG_HOME/git/ignore、$GIT_COMMON_DIR/info/exclude 和 .gitignore s24；中間那層可以在不動共用檔案的前提下，藏起個人的 plan 資料夾。歸屬的部分由 CODEOWNERS 負責："Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23。

生命週期，比照 ADR

Michael Nygard 2011 年的文章就是範本：決策 "may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement"，而且 "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9。Thoughtworks 把 spec 的用法分成 spec-first（為單一任務寫一次）、spec-anchored（持續維護以演進功能）和 spec-as-source（只編輯 spec），作者還補了一句："I'd rather review code than all these markdown files" s10。Superpowers 寫的是 spec-first 檔案，而且永遠留著：預設就是 drift。

Drift 與 gate

arXiv 論文把這個問題叫做 "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair"，並提出 "a drift gate that makes spec-code divergence a blocking merge condition" s11。Spec Kit 自己的指南也警告："Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7。TrueFoundry 把治理的理由說得很直接："forty-one specs and nine agent files aren't a tidiness problem"，它們是 "forty-one unversioned behavior inputs and nine competing standing policies"，而 drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable"。同一篇文章建議每份 spec 約 300 行，常駐指令的預算是 150 到 200 條 s13。一位實務者描述了手動版本："I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26。

成本

實驗 結果 來源
用 Spec Kit 做一個顯示目前日期的功能 8 個檔案、1,300 行文字 s14
OpenSpec 對照實驗，相同需求，spec 工具對純 Claude Code OpenSpec 多找出 3 個缺漏；程式碼多 50%、循環複雜度多 50%；時間兩倍、成本三倍 s12
一個持續數月採用 spec 驅動開發的團隊 "two to three times as many tokens and take about twice as long"；沒有證據顯示程式碼變好 s25

對照實驗只是一次實驗，作者自己也這麼說，但三筆資料的方向一致。所以：架構性的路徑才寫 spec，有界的路徑就讓它保持有界，並照實務者反覆提醒的兩句話做："don t spec too big / read the generated specs" s26。

週一就動手

  • 為每個 squad 建立 docs/specs/<squad>/，並為每個資料夾加一行 CODEOWNERS，指向該 squad 的 reviewer。
  • 在專案的 CLAUDE.md 加一行粗體命令句：plan 和 spec 必須存到 docs/specs/<squad>/，不是 docs/superpowers/。跑一次 brainstorm，確認檔案落在哪裡。
  • 把個人 plan 移到列在 .git/info/exclude 的資料夾，個別開發者的偏好放進 CLAUDE.local.md，且該檔也要被 ignore。
  • 每份共用 spec 都加標頭：status（proposed、accepted、superseded）、superseded-by、owner、paths、review-by。
  • 寫好 drift gate：對每份 status: accepted 的 spec，擷取它提到的路徑，只要有一個不存在就讓 pull request 失敗。大約十五行 shell 或 Python。
  • 加一條分支規則：沒有經過 pull request，任何 spec 或 plan 的 commit 都不能進 main。
  • 如果儲存庫用 Sphinx 之類的工具發布文件，今天就把 specs 資料夾加進 exclude_patterns。
  • 訂下大小預算：spec 維持在 300 行左右，只有跨 squad 邊界或會被重讀的工作才寫 spec。

延伸閱讀

  • 選擇標頭方案之前，先讀 spec 的三種用法（spec-first、spec-anchored、spec-as-source）；生命週期只對 spec-anchored 檔案有意義 s10。
  • arXiv 論文不只做路徑檢查，還談到完整的 drift 強制架構；當十五行的 gate 顯得太粗略時很有用 s11。
  • Spec Kit 指南列出三種演進流程（Flow-Forward、Living Spec、Flow-Back），對應到同一個 commit 的規則 s7。
  • playbook 建議用 hook 強制 plan 與 diff 同步；相關的 Reddit 討論串有 43 分和 27 則實地回報留言 s5、s27。
  • TrueFoundry 主張 spec 變更就是政策變更，所以該放在附帶執行 metadata 的 eval gate 後面，這是 CI 路徑檢查之後的下一步 s13。
  • 追蹤兩個仍開著的 issue：1246（plan 進 main）和 939（被忽略的覆蓋設定）；其中一個關閉時，本資料包的某條規則就會變成外掛預設值 s16、s18。
  • Marmelab 的完整文章解釋了那 1,300 行是怎麼冒出來的，以及 Spec Kit 在哪裡確實有用 s14。

來源

FAQ

第一天就需要全部五條規則嗎？

不用。CLAUDE.md 的導向和 Sphinx 排除只要十分鐘。等 spec 第一次跨 squad 時再加 CODEOWNERS 和標頭，等某份 accepted 的 spec 放過一個 sprint 之後再加 drift gate。

drift gate 會漏掉什麼？

行為的改變。它只檢查被提到的路徑是否還存在，所以條件寫反了照樣會通過。請搭配同一 commit 規則和 review 一起用。

為什麼不乾脆把資料夾 gitignore 掉？

因為之後要讀 spec 的 agent 需要它，而且只有中間的產物都納入版本控管，稽核軌跡才成立。okama 團隊試過 gitignore，後來改回 commit，並用 build 排除設定處理。