- Published on
Kiro SDD 入門（一）：Specs 基礎 + Design-first 怎麼選
Table of Contents
Specs 到底在幹嘛
用過 AI IDE 的人應該都有經驗：你丟一段需求給 AI，它就開始亂寫，寫到一半方向歪了你還不一定發現。Kiro 的 Specs 就是要解決這個問題 => 先把意圖收斂清楚，再讓 AI 動手。
簡單講，Specs 就是把一個需求拆成三個階段跑完：
- Requirements（要做什麼）
- Design（怎麼做）
- Tasks（拆成步驟去執行）
每個階段都會產出一份 .md 文件，你可以 review 完再往下走，不用一次賭 AI 全部做對。
Kiro 官網：
https://kiro.dev/
三個階段分別在做什麼
Requirements：把需求寫到「可以驗證」
Kiro 用一種叫 EARS 的寫法來寫需求，格式長這樣：
WHEN [什麼情況發生]
THE SYSTEM SHALL [系統應該做什麼]
舉個例子，假設你在做一個表單：
WHEN a user submits a form with invalid data
THE SYSTEM SHALL display validation errors next to the relevant fields
為什麼要這樣寫？因為這種格式每一條都可以直接對應一個測試案例。你不會再寫出「表單驗證應該要正常運作」這種模糊到無法驗證的需求。
Design：把技術方向定下來
Design 文件回答的是「怎麼做」：
- 架構跟模組怎麼拆
- API 設計、資料流
- 技術選型
- 跟現有 codebase 怎麼整合
Kiro 會自動幫你生成 design.md，裡面包含架構圖跟流程圖，你看完覺得 OK 再往下。
Tasks：拆成可追蹤的步驟
最後 Kiro 會把實作拆成一個一個 task，每個 task 都有明確的完成條件。你可以一個一個跑，也可以一次全跑，跑的過程中會即時更新狀態。
重點是每個 task 都能獨立 review => 不要一次全吞，中間看一下 diff 比較安全。
Requirements-first vs Design-first 怎麼選
Kiro 的 Feature Spec 有兩種起手式，選哪個取決於你現在手上有什麼：
| 你的狀態 | 選哪個 | 典型情境 |
|---|---|---|
| 知道要什麼功能，但技術怎麼做還沒定 | Requirements-first | 全新功能、新專案、產品需求導向 |
| 已經有架構或技術限制 | Design-first | 在既有專案上加功能、架構已經定了 |
兩個 flow 的差別就是順序不同：
- Requirements-first：
Requirements → Design → Tasks - Design-first：
Design → Requirements → Tasks
Design-first 適合什麼情況？比如你要在既有的 FastAPI 專案上加一個 MCP server，技術棧跟架構限制都很明確，這時候先寫 design 再回推 requirements 會比較順。
補充： Design-first 不是比較厲害，就只是另一種起手式。你缺需求釐清就先 Requirements-first；你缺技術收斂就先 Design-first。
修 bug 不要硬套 Feature Spec
如果你的目標是修 bug，不要用 Feature Spec 硬套，Kiro 有專門的 Bugfix Spec。
Bugfix Spec 的核心結構是三段：
- Current Behavior：現在錯在哪（bug 的重現條件）
- Expected Behavior：修完應該怎樣
- Unchanged Behavior：哪些行為不能動
第三段是最重要的 => 你把「不能動的」寫清楚，AI 才不會為了修一個 bug 把其他地方一起改掉。後面第三篇會專門講這個。
我自己跑 Specs 的流程
- 開新專案 Spec 用預設的（requirements=>design=>task）
- 已有專案=>新增功能Feature =>用Design-first(design=>requirements=>task)
- 這基本上都是要review,修正幾次才能寫到符合滿意的標準
- 開發中是可以回來修正 spec (這也是官方說法)
坑點在第 3 步：很多人會想說「反正 AI 生的，直接跑 tasks 就好」，但 requirements 或 design 如果方向錯了，後面全部要重來。
新功能是可以開全新的spec按照領域切分是很好的做法.
什麼時候用 Specs、什麼時候直接 vibe
不是所有事情都要開 Spec：
- 用 Specs：複雜功能、需要結構化規劃、團隊協作需要文件、修 bug 怕 regression
- 直接 vibe：快速 prototype、探索性的 coding、沒有明確目標的時候
參考
https://kiro.dev/docs/specs/https://kiro.dev/docs/specs/feature-specs/https://kiro.dev/blog/specs-bugfix-and-design-first/https://kiro.dev/docs/specs/bugfix-specs/
支持作者 ☕
透過 LINE Pay 支持
透過 Ko-fi 支持