如果您還在觀望軟體系統開發是否要導入SDD， 或者已經導入SDD開發流的朋友， 以下文章真心推薦您先行閱讀， 這是我們實際的開發經驗分享， 也將踩過的坑進行彙總， 讓大家一起避開這些坑：
• 【🔒 江湖一點訣】規格即內功 - 用 Spec Kit 打造穩健的 AI 開發體系(最完整的教程)
• 【🔒 江湖一點訣】招式有形，內力無聲 - 用 OpenSpec 打造 AI 協作的可控套路（實戰教學）
• 【🔒江湖一點訣】憲章的兩面刃：我在 Spec Kit 中學到的「剛柔並濟之道」
• 【🔒江湖一點訣】舊劍新磨：我如何用 Claude Code + Spec Kit 重構十年技術債
• 【🔒江湖一點訣】測試為劍，以憲章為鞘 - 我如何用 Spec Kit 打造可維護的前後端測試憲章
前言
相信在做 Spec-Driven Development（SDD） 的你，也一定曾遇過這種情境， 👀 「咦？我明明花大把時間寫了完整的憲章，規格也描述得鉅細靡遺，為什麼 AI 還是寫錯？」
你開始懷疑：是 AI 不夠聰明？還是 spec 根本沒用？但其實，問題往往不在工具，而是在我們自以為定義清楚的規格，其實還沒那麼清楚。
⛏️ 規格非常完整，卻不一定代表需求被真正「理解」。
🎯 Spec-driven 開發的確能大幅降低幻覺，也能讓成品有 8～9 成貼近需求，但剩下的 1～2 成，往往藏在：
• 我們自己還沒完全釐清的需求
• 沒有事先被文字化的隱性認知
• 只有在「實作後才會浮現」的模糊角落
也就是說，規格不是從一開始就要寫到完美，而是透過實作－回饋－修正，不斷迭代精煉， 但可以怎麼做呢？ 尤其我們已經寫好規格、計畫、任務， 甚至已經實作完成才發現問題， 這…到底該怎麼辦呀？ 沒關係， 我們都會分享我們的經驗給您參考。
🕳️ 踩坑經驗：規格各自完美，卻忽略了彼此的「對話」
我們憲章與規格大致上都寫得很正確了， 每一項任務也大致檢視過， 但怎麼到後面發現實作出來卻有一些小錯誤呢？
📋 情境還原
比如我們寫了一個前台登入系統， 後台管理系統， 前台能夠建立會員帳號並登入， 後台可以管理前台的會員帳號， 同樣是會員帳號登入我們可能切成兩個specs去寫：
兩份 spec 各自都寫得很完整，第一份做完時實際操作測試，一切完美 🎉。
但當第二份 spec 完成後，問題浮現了：
❌ 前台登入：密碼至少需要 6 位數（有驗證）
❌ 後台改密碼：想改幾位就幾位（沒驗證）
結果？後台把密碼改成 123，前台就再也登不進去了， 接著可能就會被報修的BUG追殺… 💀
🔍 問題根源
┌─────────────────┐ ┌─────────────────┐
│ 001-frontend │ │ 002-admin │
│ ───────────── │ │ ───────────── │
│ 密碼 ≥ 6 字元 │ ←❌→ │ 密碼：無限制 │
│ （有寫驗證） │ │ （沒寫驗證） │
└─────────────────┘ └─────────────────┘
↑ ↑
└────── 同一個欄位 ───────┘
但規則不一致！
每份 spec 單獨看都沒問題，但它們之間缺乏「共識」。
🛡️ 解決方案：預防 + 補救雙軌並行
踩坑不可怕，可怕的是同一個坑踩兩次。以下分享我的兩階段防護策略：
🔮 策略一：預防勝於治療 - 規格制定時的「回顧儀式」
在撰寫新 spec 之前，先讓 AI 幫你做一次「跨規格健檢」：
## 📋 跨規格檢查請求
我即將撰寫新的規格文件：`002-admin-cms`（後台管理系統）
請協助我：
1. 回顧現有的相關規格文件（特別是 `001-frontend-auth-system`）
2. 找出可能的「功能重疊區」（例如：都會操作到密碼欄位）
3. 檢查是否存在潛在的「規則衝突」（例如：驗證邏輯不一致）
4. 建議需要在新 spec 中明確定義的「共用規範」
請以表格方式呈現檢查結果。
💡 關鍵心法：把「跨規格一致性檢查」變成每次開新 spec 的標準動作，就像程式碼的 code review，規格也需要 spec review。
🔧 策略二：事後補救 - 修 Bug 也要自動化測試與修文件
發現問題後，除了修正程式碼，更重要的是讓整個知識庫保持同步。
## 🐛 問題修復與文件同步
以上所陳述的問題請協助我進行修正，並確認以下事項：
### 程式碼修正
- [ ] 實際的 bug 修復
### 文件同步檢查
1. 📄 **Specs 文件**：是否需要更新或補充規格描述？
2. 🧪 **測試案例**：是否需要修改現有測試或新增測試案例？
3. 📚 **其他文件**：charter、README 或其他相關文件是否需要一併更新？
請列出所有需要變更的檔案清單，並說明變更內容。
⚠️ 血淚教訓：只修 code 不修 spec，下次 AI 讀到舊規格，同樣的坑還是會再挖一次給你跳。
分享我們透過上述的prompt讓AI進行後的成果：
📊 兩種策略的適用時機
🎬 結語：Prompt 的品質，取決於你思考的深度
踩過這些坑之後，我最大的體悟是： AI 不會主動幫你想到你沒想到的事。AI 不會主動幫你想到你沒想到的事。
當我們下 prompt 時，很容易只專注在「眼前這個任務」，卻忘了問自己：
• 這個功能會不會影響到其他模組？
• 之前有沒有定義過類似的規則？
• 如果我是測試人員，會怎麼試著打破它？
🧠 培養「系統性思維」的提問習慣
與其期待 AI 自己發現問題，不如在每次下 prompt 時多問一層：
💡 最後的最後
spec-kit 是一套很棒的方法論，但它終究是工具，工具的上限，是使用者的思考深度，坑一定會踩，但每踩一次，就是在訓練自己的「系統性思維」。當你開始習慣性地多想一步、多問一層，你會發現
不只是 AI 協作變順了，你解決問題的能力也在升級。
希望這篇踩坑心得對你有幫助，我們下篇文章見 👋
