主站 Developer ToolsSpec-Driven Development (SDD)

Spec-Driven Development (SDD)

Name: Spec-Driven Development (SDD)
Author: Tai-ch0802

Spec-Driven Development (SDD): a structured workflow (Requirement -> Analysis -> Implementation) that enforces explicit documentation before coding.

9 Stars0 Installs更新于 195 days agoMIT

本文件是 SDD 流程的單一事實來源 (single source of truth)。 RULE_007_SDD_WORKFLOW.md 與 .agent/workflows/sdd-process.md 為摘要與入口，流程細節以本文件為準；三者若有出入，以本文件為準並回頭修正另兩份。

核心原則

Spec 與風險成比例 (Proportional Specs)：文件的厚度應對應變更的風險與影響面，而不是一律套用最重的流程。低風險變更被流程拖慢，和高風險變更裸奔，是同一種失敗。
Spec 是給未來的 context：spec 的主要讀者是「之後接手的人與 AI agent」。寫「為什麼這樣設計、排除了哪些方案」，比堆 boilerplate 章節有價值。
Living Documentation（以 PR merge 為界）：實作中發現設計需變更時，先更新 spec 再繼續寫 code（T1 隨手改；T2 需重新取得核准）。merge 後 spec 即成為歷史決策記錄（ADR 語意），不回頭維護；後續變更開新 spec 並引用舊的。
驗收可檢驗：不論哪一級，「怎樣算做完」都必須在動工前說得出口（T0 在 commit message、T1/T2 在 spec 的驗收條件）。

分級判定（動工前第一步）

| 層級 | 適用 | 產出 | Review 時機 | |---|---|---|---| | T0 直接做 | typo、文案/翻譯、註解、純樣式微調、依賴版本更新、根因明顯的單點小修 | 無 spec；commit body 把背景講清楚 | PR review | | T1 輕量 SPEC（預設） | 一般 bug fix、小～中型功能、局部重構 — 影響面一份文件講得完，且未觸及 T2 升級條件 | 單檔 SPEC.md（骨架見下） | 隨 PR 一起審；不設事前 gate，spec 與實作可同步進行 | | T2 完整 SDD | 觸及任一升級條件（見下） | PRD_spec.md + SA_spec.md | 兩道事前 gate：PRD 核准 → SA 核准 → 才動工 |

T2 升級條件（任一成立即升級）

變更 chrome.storage（local/sync）的 schema，或需要資料 migration
變更 manifest.json 的 permissions / host_permissions
新增或重切跨 context 通訊協定（background ↔ sidepanel ↔ content script ↔ offscreen）
涉及資料遺失風險的邏輯（同步引擎、快照/還原、刪除流程）
新增大型使用者可見功能面（新 UI 區塊、新互動模式）
大規模架構重構（動到 ≥3 個 modules 的職責劃分，或新增模組層）

判定規則

由 agent 在動工前主動提出分級與理由（一兩句即可），使用者可隨時覆寫升降級。
拿不準 T1/T2 時，問使用者一句，不要自行猜重的或猜輕的。
修 bug 常要先調查才知道影響面：允許「先調查、後判級」，調查本身不需 spec；值得留存的技術驗證結論可落地為同目錄 SPIKE.md（判例：BASE-018 GramJS 可行性驗證）。

T1：單檔 SPEC.md 骨架

放在 /docs/specs/{type}/{ID-PREFIX}_{desc}/SPEC.md，1–2 頁為度：

# {標題}

## 背景與問題
（要解什麼？bug 的話寫根因分析，不是只寫症狀）

## 方案
（怎麼解＋為什麼選這個做法；有排除的替代方案就一句帶過）

## 影響面
（動到哪些 modules / storage keys / manifest；連動風險）

## Test Impact
（unit / E2E 哪些要新增或改；驗證指令）

## 驗收條件
（可檢驗的完成定義，條列）

spec 可以在實作過程中補完（例如調查完根因才寫得出「背景與問題」），但 PR 送審時 SPEC.md 必須完整，與程式碼一起被 review。

T2：完整流程（PRD → SA → 實作）

Phase 1: PRD — 定義 What & Why

檔案：/docs/specs/{type}/{ID-PREFIX}_{desc}/PRD_spec.md
指引：prd skill（.agent/skills/prd/SKILL.md）
必要內容：User Stories、Functional Requirements（EARS）、Acceptance Criteria（Given-When-Then）⭐、Out of Scope
Gate：User Review → Approved 後才進 Phase 2

Phase 2: SA — 定義 How

檔案：同目錄 SA_spec.md
指引：sa skill（.agent/skills/sa/SKILL.md）
必要內容：Requirement Traceability Matrix ⭐、Module Impact Map、Storage Schema Diff、Test Impact Analysis ⭐
Gate：User Review → Approved 後才動工

Phase 3: 實作與驗收

實作中發現設計需變更：暫停 → 更新 spec（bump 版本）→ 重新核准 → 繼續
對照 PRD 的 Acceptance Criteria 驗收並回報

命名規範（各層級通用）

目錄：/docs/specs/{type}/{ID_PREFIX}_{desc}/

type：feature / fix（必要時 refactor / chore）
ID_PREFIX：
- ISSUE-{n}：對應 GitHub Issue（標準）
- PR-{n}：外部貢獻、無 Issue
- BASE-{n}：歷史回溯／基礎架構（無對應 Issue）
desc：簡短英文 kebab-case

/docs/specs/
  ├── feature/
  │    ├── ISSUE-101_tab-groups/        # T2：PRD_spec.md + SA_spec.md
  │    └── BASE-014_quick-toggle/       # T1：SPEC.md
  └── fix/
       └── ISSUE-88_drag-ghost/         # T1：SPEC.md

既有目錄裡的 PRD_spec.md + SA_spec.md 為歷史文件，不需回頭改制。

Agent 操作指引

分級：對照上表提出層級與一句理由；T1/T2 邊界拿不準就問。
T0 → 直接做，commit body 交代背景。
T1 → mkdir -p 建目錄；調查→實作→補完 SPEC.md（或先寫後做，順序自由）；PR 連同 spec 一起送審。
T2 → 走 Phase 1–3，兩道 gate 缺一不可。
收尾：spec 與最終實作一致（Living Doc）；PR description 引用 spec 路徑。

Related Skills

local-places

Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.

246,840·openclaw

github

Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.

246,840·openclaw

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

246,840·openclaw

voice-call

Start voice calls via the OpenClaw voice-call plugin.

246,840·openclaw

notion

Notion API for creating and managing pages, databases, and blocks.

246,840·openclaw

gemini

Gemini CLI for one-shot Q&A, summaries, and generation.

246,840·openclaw

Category:developer

主站 Developer ToolsSpec-Driven Development (SDD)

Spec-Driven Development (SDD)

Spec-Driven Development (SDD): a structured workflow (Requirement -> Analysis -> Implementation) that enforces explicit documentation before coding.

9 Stars0 Installs更新于 195 days agoMIT

本文件是 SDD 流程的單一事實來源 (single source of truth)。 RULE_007_SDD_WORKFLOW.md 與 .agent/workflows/sdd-process.md 為摘要與入口，流程細節以本文件為準；三者若有出入，以本文件為準並回頭修正另兩份。

核心原則

Spec 與風險成比例 (Proportional Specs)：文件的厚度應對應變更的風險與影響面，而不是一律套用最重的流程。低風險變更被流程拖慢，和高風險變更裸奔，是同一種失敗。
Spec 是給未來的 context：spec 的主要讀者是「之後接手的人與 AI agent」。寫「為什麼這樣設計、排除了哪些方案」，比堆 boilerplate 章節有價值。
Living Documentation（以 PR merge 為界）：實作中發現設計需變更時，先更新 spec 再繼續寫 code（T1 隨手改；T2 需重新取得核准）。merge 後 spec 即成為歷史決策記錄（ADR 語意），不回頭維護；後續變更開新 spec 並引用舊的。
驗收可檢驗：不論哪一級，「怎樣算做完」都必須在動工前說得出口（T0 在 commit message、T1/T2 在 spec 的驗收條件）。

分級判定（動工前第一步）

T2 升級條件（任一成立即升級）

變更 chrome.storage（local/sync）的 schema，或需要資料 migration
變更 manifest.json 的 permissions / host_permissions
新增或重切跨 context 通訊協定（background ↔ sidepanel ↔ content script ↔ offscreen）
涉及資料遺失風險的邏輯（同步引擎、快照/還原、刪除流程）
新增大型使用者可見功能面（新 UI 區塊、新互動模式）
大規模架構重構（動到 ≥3 個 modules 的職責劃分，或新增模組層）

判定規則

由 agent 在動工前主動提出分級與理由（一兩句即可），使用者可隨時覆寫升降級。
拿不準 T1/T2 時，問使用者一句，不要自行猜重的或猜輕的。
修 bug 常要先調查才知道影響面：允許「先調查、後判級」，調查本身不需 spec；值得留存的技術驗證結論可落地為同目錄 SPIKE.md（判例：BASE-018 GramJS 可行性驗證）。

T1：單檔 SPEC.md 骨架

放在 /docs/specs/{type}/{ID-PREFIX}_{desc}/SPEC.md，1–2 頁為度：

# {標題}

## 背景與問題
（要解什麼？bug 的話寫根因分析，不是只寫症狀）

## 方案
（怎麼解＋為什麼選這個做法；有排除的替代方案就一句帶過）

## 影響面
（動到哪些 modules / storage keys / manifest；連動風險）

## Test Impact
（unit / E2E 哪些要新增或改；驗證指令）

## 驗收條件
（可檢驗的完成定義，條列）

spec 可以在實作過程中補完（例如調查完根因才寫得出「背景與問題」），但 PR 送審時 SPEC.md 必須完整，與程式碼一起被 review。

T2：完整流程（PRD → SA → 實作）

Phase 1: PRD — 定義 What & Why

檔案：/docs/specs/{type}/{ID-PREFIX}_{desc}/PRD_spec.md
指引：prd skill（.agent/skills/prd/SKILL.md）
必要內容：User Stories、Functional Requirements（EARS）、Acceptance Criteria（Given-When-Then）⭐、Out of Scope
Gate：User Review → Approved 後才進 Phase 2

Phase 2: SA — 定義 How

檔案：同目錄 SA_spec.md
指引：sa skill（.agent/skills/sa/SKILL.md）
必要內容：Requirement Traceability Matrix ⭐、Module Impact Map、Storage Schema Diff、Test Impact Analysis ⭐
Gate：User Review → Approved 後才動工

Phase 3: 實作與驗收

實作中發現設計需變更：暫停 → 更新 spec（bump 版本）→ 重新核准 → 繼續
對照 PRD 的 Acceptance Criteria 驗收並回報

命名規範（各層級通用）

目錄：/docs/specs/{type}/{ID_PREFIX}_{desc}/

type：feature / fix（必要時 refactor / chore）
ID_PREFIX：
- ISSUE-{n}：對應 GitHub Issue（標準）
- PR-{n}：外部貢獻、無 Issue
- BASE-{n}：歷史回溯／基礎架構（無對應 Issue）
desc：簡短英文 kebab-case

/docs/specs/
  ├── feature/
  │    ├── ISSUE-101_tab-groups/        # T2：PRD_spec.md + SA_spec.md
  │    └── BASE-014_quick-toggle/       # T1：SPEC.md
  └── fix/
       └── ISSUE-88_drag-ghost/         # T1：SPEC.md

既有目錄裡的 PRD_spec.md + SA_spec.md 為歷史文件，不需回頭改制。

Agent 操作指引

分級：對照上表提出層級與一句理由；T1/T2 邊界拿不準就問。
T0 → 直接做，commit body 交代背景。
T1 → mkdir -p 建目錄；調查→實作→補完 SPEC.md（或先寫後做，順序自由）；PR 連同 spec 一起送審。
T2 → 走 Phase 1–3，兩道 gate 缺一不可。
收尾：spec 與最終實作一致（Living Doc）；PR description 引用 spec 路徑。

Category:developer

Spec-Driven Development (SDD)

核心原則

分級判定（動工前第一步）

T2 升級條件（任一成立即升級）

判定規則

T1：單檔 SPEC.md 骨架

T2：完整流程（PRD → SA → 實作）

Phase 1: PRD — 定義 What & Why

Phase 2: SA — 定義 How

Phase 3: 實作與驗收

命名規範（各層級通用）

Agent 操作指引

相關資源

Related Skills

local-places

github

skill-creator

voice-call

notion

gemini

Spec-Driven Development (SDD)

核心原則

分級判定（動工前第一步）

T2 升級條件（任一成立即升級）

判定規則

T1：單檔 SPEC.md 骨架

T2：完整流程（PRD → SA → 實作）

Phase 1: PRD — 定義 What & Why

Phase 2: SA — 定義 How

Phase 3: 實作與驗收

命名規範（各層級通用）

Agent 操作指引

相關資源

Related Skills

local-places

github

skill-creator

voice-call

notion

gemini