在既有企業專案導入 Spec Kit：你可能需要先思考的幾個問題

前情提要

最近公司積極擁抱 AI，提供大家使用 AI 工具輔助開發，這套做法也施行了一陣子。

在這個基礎上，接下來希望團隊進一步嘗試以 Spec Kit 的方式來開發——把需求寫成結構化的 Spec，讓 AI 讀得懂、照著做；工程師則轉向 review、監督、決策 的角色，把實作交給 AI 去完成。

這樣的大方向聽起來很棒——好像只要大家對齊使用的 AI 工具、對齊開發流程，再決定哪個資料夾要放文件、文件規範怎麼寫，這些事情搞定就好了？

但仔細想想，其實還有更多的問題需要考慮。

接下來這篇文章，會提到幾個我在這個過程中，考慮到的現實面。

從零開始：Spec Kit 在小專案上確實很驚艷

其實 Spec Kit（Spec-Driven Development）剛推出的時候，我就自己試用過，拿來做幾個小 side project。

老實說，功能很令人驚艷。

在從零開始的新專案裡，整個開發流程被切得很清楚：你先用自然語言描述「要做什麼」，AI 幫你把需求結構化，再依序產出計畫、任務，最後動手實作。工程師的角色確實比較像在 review 每個階段的產出，而不是從第一行 code 開始硬寫。

大致流程長這樣：

1. 初始化專案

specify init 建立好 AI Agent 需要的指令檔、目錄結構與 context 規則，之後在 Cursor 裡就能直接使用 /speckit.* 系列指令。

2. 定下憲法：/speckit.constitution

建立專案不可妥協的原則（Code 品質、測試要求、效能規範等）。這份 constitution.md 會在後續每個階段被引用，確保 AI 實作不會各自發揮、越寫越偏。

3. 建立規格：/speckit.specify

描述你要做的功能——專注在 what 和 why，不需要先決定 tech stack。AI 產出結構化的 spec.md，包含 User Story、需求、驗收條件、邊界案例。有模糊之處可用 /speckit.clarify 進一步釐清。

4. 產生實作計畫：/speckit.plan

告訴 AI 打算用的技術棧與架構方向，AI 產出 plan.md，包含技術選型、專案結構、分階段實作策略，這一步也會對照憲法確認計畫沒有違反專案原則。

5. 拆解為可執行的任務：/speckit.tasks

把 plan 拆成逐項執行的 tasks.md，每個任務有明確的順序、依賴關係，可平行處理的也會標出來。

6. 動手實作：/speckit.implement

AI Agent 照著 spec 和 plan 逐項把 code 寫出來，工程師負責 review 產出、決定是否調整 spec 或 plan，再讓 AI 繼續。

整條路徑可以濃縮成：

specify init
    ↓
/speckit.constitution   ← 專案憲法
    ↓
/speckit.specify        ← 功能規格
    ↓
/speckit.plan           ← 實作計畫
    ↓
/speckit.tasks          ← 任務拆解
    ↓
/speckit.implement      ← AI 實作

在 side project 的場景裡，這套流程跑起來非常順——需求清楚、repo 只有一個、沒有歷史包袱，AI 有完整的 context 可以依循。也正因為這個體驗太好，才會讓人直覺地覺得：「公司導入應該也是這樣吧？」

但這正是問題的起點。

拿既有專案來試：情境完全不同

好，既然這東西這麼好，下一步很自然——拿我目前的專案來試試看。

等等，你說目前的專案？

沒錯，就是目前既有的專案，不是從頭開始打造的那種。

這一點，跟網路上大部分的文章、YouTube 教學影片的情境非常不同。那些教學幾乎都是 greenfield：一個空 repo、一個 side project、從 specify init 一路跑到底。看起來很順，也容易讓人以為導入 Spec Kit 就是這麼簡單。

但公司裡的專案不是這樣。codebase 可能已經跑了好幾年，當初的決策文件散落各處，coding style 可能因人而異，測試覆蓋率參差不齊——這樣的狀況並不罕見，毫無章法才是更真實的現場。

這時候，Spec Kit 教學影片裡不會告訴你的問題，開始一個一個浮上來：

舊有的功能，需不需要先補齊 Spec？

系統裡已經有幾百個功能在跑了，AI 要理解現有系統，是不是得先把這些都寫成 spec？更關鍵的是——這些問題是不是得先處理完，才有辦法開始開發新功能？

如果答案是「要」，那可能還沒動到新功能，團隊就得先花大量時間對齊、補齊目前專案的 spec，新功能的開發反而被延後。但如果答案是「不要」、新功能先開發再說——AI 在實作時對既有系統的理解從哪來？新 code 跟舊 code 的規格、風格要怎麼接？會不會越開發，新舊之間的落差越大？

我們該如何定下憲法？

/speckit.constitution 在 greenfield 專案裡是第一步——先定規則，再寫 code。但既有專案的 code 早就存在了，憲法要寫成什麼？照現況寫，等於把混亂制度化；照理想寫，又跟現實脫節。

假設真的定下憲法之後，舊有的專案不符合憲法怎麼辦？

新功能照憲法走，舊 code 到處違規——要全部跟著改嗎？還是憲法只約束從今天開始的新 code？如果選後者，同一個 repo 裡會同時存在兩套標準，AI 要聽哪一套？

附：可行做法

重點不是找到「對的做法」，而是清楚知道自己做的決策，可能帶來什麼優缺點與後果。例如選擇新功能先做，短期能交付，但 AI 對舊系統的理解不足、新舊規格落差變大，這些都是可預期的代價；選擇先補 spec，長期基礎較穩，但新功能時程會被壓後。

知道後果之後，團隊還得安排後續怎麼彌補——選了哪條路，就要有對應的補救計畫。同時也要明確訂定影響範圍與規範範圍：憲法約束哪些 repo、哪些新 code？舊功能哪些要補 spec、哪些暫時不管？這些邊界訂清楚了，取捨才有依據，而不是走一步算一步。

先顧新功能：Jira / Confluence 上的 Spec 要搬嗎？

好，那我們先做個決定——既有功能先不管，等日後有休耕期，再回頭補 spec、對齊 codebase。

目前公司急著要開發新功能，這也符合前面說的 trade-off：先把交付跑起來，舊的問題留到後面處理。

那下一個問題來了：這次新功能的 spec，公司其實早就準備好了，就放在 Jira 和 Confluence 上面——需求描述、流程圖、驗收條件、相關 Epic / Story 連結，應有盡有。

既然決定走 Spec Kit，規格文件勢必得轉成 AI 能吃的結構化格式——總不能丟一個 Confluence 連結給 Agent，請它自己進去看、照著開發吧？這樣做問題很多：Agent 通常無法直接存取需要登入的內部頁面；就算看得到，頁面裡混雜的討論串、過期決策、無關連結，對 AI 來說都是噪音；更別說 Confluence 的格式本來就不是為 Agent 設計的，很難穩定產出可預期的結果。

所以轉換是必要的。但真要轉，問題又來了：

• Confluence 頁面往往圖文並茂——流程圖、UI mockup、表格截圖
• 內文混雜超連結——連到 Jira ticket、其他 Confluence 頁、外部文件
• 底下還掛著討論串——來回確認的細節、後來才追加的決策
• 匯出通常只有 Word 或 PDF，格式一轉就散，圖片、連結、結構很難 intact 地搬過去

也就是說，Jira / Confluence 上的 spec 跟 Spec Kit 要的 spec.md，長得完全不像同一種東西。要怎麼搬、搬多少、誰來整理、整理完誰負責維護——每一關都是問題。

附：可行做法

就算只能匯出 Word 或 PDF，還是能做，只是多一步。重點是按需轉、不要全轉——只處理「現在要開發的 Feature」，Confluence 繼續當正式需求來源就好。原因是：Confluence 上的文件混雜了討論脈絡、決策過程和 Jira 連結，本來就適合當「需求的正式紀錄」；但 AI 需要的是精煉、結構化的執行規格，兩者用途不同。若硬要全部轉，光是整理過期文件就會耗掉大量時間，新功能反而開不了工；只轉當前要做的 Feature，成本可控，也避免維護兩份文件越差越遠。

實際流程： Confluence 匯出 Word（比 PDF 好，標題階層和表格還在）→ 放進專案 docs/confluence/ → 請 Cursor 整理成 requirements.md、design.md、tasks.md，保留 User Story、驗收條件、Business Rules、API 規格，忽略已廢棄方案；會議紀錄則略過來回討論的過程，只取最終結論——開會時決策常變來變去，過程對 AI 是噪音，結論才是要實作的依據。

轉換時兩個坑：

• 圖片轉不成文字： Confluence 裡的流程圖、Wireframe 匯出後 AI 看得到圖，但不保證讀得懂細節——要請它依圖片補一段文字描述，讀不清楚的就標 TODO，後續人工補。
• AI 整理不能全信： 就算文字部分，AI 也可能漏掉條件、誤解語意，或把已廢棄方案當成現行規格。產出的 Markdown 還是要有人 review，確認跟 Confluence 上的最終結論一致，才能拿去開發。

更輕量的路： 如果覺得 Spec Kit 太重，也可以只做 docs/specs/*.md + Cursor Rules（「開發前先讀 specs」）。對既有專案來說，Confluence → 結構化 Markdown → Cursor 常常已有八成效果；Spec Kit 的價值主要在標準化新功能開發流程，不是搬歷史文件。

多 Repo 微服務：Spec 應該寫在哪？

還有一個 specify init 的教學範例通常不會提到的問題——Spec 要寫在哪？

很多 side project 很單純：一個前端、一個後端、一個資料庫，spec 就放在同一個 repo 裡，開發完就結案了。specify init 的範例大多也是這種結構：

my-app
├── frontend
├── backend
└── spec

但以我們公司來說，服務拆成很多微服務，各自一個 repo：

customer-portal
order-service
payment-service
notification-service
auth-service
...

這時候 spec 要寫在哪，就變成一個很實際的問題。假設要開發一個新功能，這個功能會動到四五個 repo——spec 要放在哪一個？如果只放在其中一個 repo，其他 repo 的同仁怎麼知道全貌？如果每個 repo 各寫一份，又很容易出現大量重複內容——同一段流程、同一組驗收條件，在 order-service、payment-service、notification-service 各 copy 一份；各自 repo 再補自己的實作細節，到最後變成好幾份 spec 描述同一件事，未來要更新時不知道改哪一份，改 A 忘了改 B，很快就對不上。

如果把 Spec 硬塞進某一個 repo 裡，其他 repo 的同仁看不到全貌；如果各自維護，又會分裂、重複、難以同步——好像怎麼放都不對。

可行做法：拆成兩層

建立獨立的 product-specs repo 作為 Spec Hub，以 Feature 為單位放跨服務規格（需求、流程、驗收條件、事件流）；各服務 repo 的 .specify/specs/ 只放這個服務的實作細節，不重複 Feature 層的內容。一份 Feature 只有一份 master spec——一個功能動到 5 個 repo，也不會出現 5 份互相衝突的規格。

在某個服務開發時，建議同時給 AI 三份 context：Feature Spec（要做什麼）、Architecture（系統地圖）、目前 Repo Spec（這個服務怎麼接）——少了任何一層，AI 對跨服務脈絡的理解都會有缺口。

更新順序固定：先改 Spec Hub，再更新各 Repo Spec。PR 分開送，Spec Hub 的 PR 指定各相關服務負責人 review，避免改 A 忘了改 B。若只有實作細節調整、不影響跨服務流程，可以只改 Repo Spec；但若需求本身變了，不要只改某一個 repo 就當作改完。

工具之外：工程師角色轉換的現實

前面討論的都是流程和文件架構，但在企業裡推行 Spec Kit 還有一個容易低估的問題——工程師的角色定位會跑掉。

這套流程讓工程師從「自己寫 code」變成「review AI 寫的 code」。聽起來好像更輕鬆，但這個轉換並不小：

• Review AI code 是不同的技能。 你不再從第一行邏輯開始思考，而是要判斷 AI 的產出對不對、合不合 spec、有沒有潛在風險——這需要對系統有更全面的理解，而不只是局部的實作能力。
• 有些人會有抵觸感。 「我的價值在哪？」是一個真實的情緒。習慣從寫 code 中獲得成就感的工程師，突然變成監督 AI 的角色，適應期不一定短。
• 不能因為 AI 寫得整齊就少看幾眼。 AI 很容易在格式漂亮、邏輯正確的前提下，悄悄寫出不符合系統脈絡的東西——review 的眼光要更全面，不只看 code 對不對，還要看它合不合現有系統的設計。

工程師需要建立的能力

在這套流程裡，「能寫 code」變成了基本門檻，不再是核心競爭力。工程師更需要著重的，是對系統架構和商業邏輯的深度理解——知道為什麼要這樣設計、這個決策對其他服務的影響是什麼、這段邏輯背後的業務規則是什麼。

這些才是 AI 讀不懂、也補不了的東西。AI 可以照 spec 實作，但它不知道這個 spec 合不合理、有沒有遺漏業務邊界、跟系統現有架構有沒有衝突——判斷這些，需要的是對系統和業務的整體理解，而不只是程式碼層面的實作能力。

換句話說，Spec Kit 確實讓寫程式這件事變輕鬆了，但同時也讓「光會寫程式」變得不夠用。

Spec 同步問題：Code 改了，Spec 誰來改？

前面談的都是「怎麼把 spec 建起來、放對地方」。但 spec 建起來之後，還有一個更麻煩的問題——怎麼讓它跟 code 保持同步？

現實是，我們不見得每一個改動都會叫 AI 來做。有時候只是改個按鈕顏色、調一行文案、修一個小 bug——自己動手改一下，往往比叫 AI 來改還快。AI 得先理解專案 context、讀 spec、讀 code，光這段前置就夠久了；對這種小改動來說，得不償失。

但手動改 code 的代價是：spec 不會自動跟著更新（這就是所謂的 Spec Drift——code 往前走，spec 停在原地，兩邊越差越遠）。改完就 merge 了，spec 還停在舊版本——下次再叫 AI 依 spec 開發，它讀到的是過時的規格，產出的 code 可能跟現況對不上；更糟的是，AI 會照舊 spec 把已經改好的 code 改回去或改壞。舊 spec 不只是「過時的文件」，它是會在後續開發中持續造成傷害的地雷。

更複雜的是，我們是多人同時維護多個微服務。collision 不只在 code——spec 也會撞：

• A 在改 order-cancellation 的 Feature Spec，B 也在改同一份，merge 時 spec 衝突
• A 改了 Feature Spec 裡的事件流，但 B 的 notification-service PR 還是依舊 spec 在寫，兩邊對不上
• 某個 repo 的 Repo Spec 更新了，Feature Spec 沒人知道要一起改，其他 repo 的同仁還照舊版開發

也就是說，Spec Kit 解決了「spec 怎麼寫、放哪」的問題，但沒有自動解決「spec 跟 code、spec 跟 spec 之間怎麼同步」的問題。這在 greenfield 單 repo 的小專案不太明顯——一個人寫、一個人改，腦子裡還記得 spec 寫了什麼。但在多 repo、多人、部分 AI、部分手改的環境裡，這會變成日常問題。

附：可行做法

老實說，目前沒有成熟方案能讓 spec 與 code 100% 自動同步。與其追求理想狀態，不如用流程把 drift 控制在可接受範圍內。

PR 順便更新 Spec： 把 spec 更新納入 PR checklist——改 code 就改 spec，跟改測試一樣是交付的一部分。手動改顏色、改文案這種小改動，團隊可以先訂界線：純 UI 微調、不影響行為的，spec 可以不動；但只要動到行為、API、事件流、驗收條件，spec 就要跟著改，否則下次 AI 依舊 spec 開發，很容易把 code 改壞。

定期 Drift Review： 每隔一段時間（例如每個 Sprint 結束），針對已上線的 Feature 做比對——spec 已實作、spec 未實作、code 有但 spec 沒寫。第三種最危險，通常是手改或 AI 自行發揮的結果，定期抓出來才能避免 spec 變成「理想文件」。

減少 Spec Collision： Feature Spec 在 Spec Hub 只有一份 master，改之前先在 Jira / Slack 對齊「誰在動這份 spec」；跨服務的需求變更，先改 Feature Spec 再通知各 repo 負責人更新 Repo Spec，不要各自開工各改各的。Spec Hub 的 PR 可以指定 reviewer 來自會被影響的服務，避免 A 改完 B 還不知道。

總結：Spec Drift 不會自己消失，要靠 PR 習慣 + 定期 review + 跨 repo 對齊 三件事一起扛。做不到完美同步沒關係，但要讓團隊知道 drift 的代價，並且訂好「什麼時候一定要回寫 spec」的規則。

結語

我支持擁抱 AI，也肯定公司朝這個方向走。AI 能幫我們更快交付、讓工程師從重複的實作中解放出來，這是真實的效益。

只是，網路上大多數在推廣 Spec Kit 的文章和影片，幾乎都是從零打造的 side project——那個情境確實很順，也很令人心動。但對大多數公司來說，真實的情況是：專案已經跑了幾年、需求管理在 Jira / Confluence、服務拆成多個 repo、團隊有不同的開發習慣。

這個落差，很容易讓人低估導入的複雜度，進而在評估和規劃上出現盲點。

這篇文章想做的，不是勸退，而是提早把問題攤開來——既有的 spec 要怎麼處理、Confluence 的文件怎麼轉、多 repo 下 spec 放哪、code 改了 spec 誰來更新。這些問題早點想到，就能早點規劃、早點預防，而不是導入到一半才發現卡關。

最後，AI 開始能寫程式，不代表工程師失去了位置。從這篇討論的內容就能看出來：憲法怎麼定、spec 怎麼寫才合理、多服務的架構怎麼拆、AI 產出的 code 合不合系統設計——這些判斷，都還是需要工程師來做。AI 接手了實作，但工程師需要看得更全面、想得更深。