Feature Flow

> 🌐 English version · 繁體中文（正本 / canonical）

feature-flow — 規格驅動的完整功能開發流程

融合 OpenSpec 的 change lifecycle 與 agent-skills 的工程紀律。適用於「值得留下決策紀錄」的變更：新功能、跨模組重構、API 設計、資料遷移。

何時用

✅ 適用：新功能跨 3+ 檔案或涉及新模組／修改 public API 或共用元件介面／需要架構決策（state 管理、資料流、快取策略、認證）／資料遷移、schema 變更／重構牽動多個使用點／預估工時 > 半天。

❌ 不適用：小改 → quick-fix；想法尚未成形 → 先 openspec-explore 或 superpowers:brainstorming。

實戰分流表（含「3+ 檔但無架構決策 → quick-fix」與 over-engineering 警訊）：見 references/lessons.md。

六階段流程（嚴格依序，每階段有檢查點）

┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────┐
│ 1. Spec  │→│ 2. Design│→│ 3. Tasks │→│4. Implement │→│ 5. Review│→│ 6. Ship  │
│  (Why)   │ │  (How)   │ │ (Break)  │ │ (TDD loop)  │ │ (5-axis) │ │ (Verify) │
└──────────┘ └──────────┘ └──────────┘ └─────────────┘ └──────────┘ └──────────┘
     ▲______________________________________________________│
                   Review-fix loop：Stage 5 不過回 Stage 4

產出位置：specs/changes/-/ 下的 proposal.md / design.md / tasks.md / review.md / shipping.md（五份模板全文見 references/artifact-templates.md）。若專案已有 OpenSpec openspec/changes/ 或類似目錄，優先沿用。完成 merge 後移至 specs/changes/archive/。

Stage 1 — Spec（Why & What）

• 目標：動手前把 Why 與驗收標準白紙黑字化。產出 proposal.md（Why／What in-out scope／Acceptance Criteria／Risks & Assumptions）。
• 檢查點 ✅：用戶確認 proposal.md 後才進 Stage 2。模糊處用 AskUserQuestion 問清楚。
• 原型先行：需求涉及 UI/UX 或存在兩種以上合理解讀時，proposal 必附可看的東西（ASCII mockup／行為走查／截圖標註），讓用戶對實物而非文字點頭——「不是這個」發生得越早越便宜。

Stage 2 — Design（How）

• 目標：決定技術路徑，留下取捨紀錄。產出 design.md（Architecture／Key Decisions 表／Interfaces／Migration／Test Strategy）。
• 通用要點（視專案調整）：i18n 新字串管理與語系齊備／theme 與深色模式／元件重用與共用目錄／外部依賴的 rate limit、錯誤處理、離線行為／資料層 schema migration 與向下相容／平台差異（iOS/Android/Web/Desktop）。
• 若專案有 CLAUDE.md / AGENTS.md，對照該檔確認守則（命名、禁用 API、發布流程等）。
• 檢查點 ✅：用戶 review 設計取捨，特別是 Key Decisions 表。

Stage 3 — Tasks（拆解與排序）

• 目標：把 Design 拆成可獨立驗證、可獨立 commit 的小任務。產出 tasks.md（依賴順序＋可平行 group）。
• 拆解原則：每 task < 2h／每 task 有明確驗收（test 或可觀測行為）／標註依賴、能平行就標平行／先 scaffolding 基礎層，再功能層，最後打磨。
• 檢查點 ✅：用戶確認粒度與順序。

Stage 4 — Implement（TDD 增量實作）

對每個 task 走完整 TDD 小迴圈：

1. 建立或切換到 feature branch
2. 寫 failing test → 跑、看到紅
3. 寫最小實作 → 跑、看到綠
4. Refactor（如需要）→ test 仍綠
5. 靜態檢查（linter / type check）乾淨
6. 勾掉 tasks.md 的 checkbox
7. Commit（含為什麼的訊息）→ 進下一 task

• 通用守則：新字串進 i18n 資源檔（多語齊全）；UI-only 變更無法自動化測試 → tasks.md 註明「手動驗證」並在 Stage 6 實測；符合專案既有風格與工具。
• 禁止：一口氣改完所有 task 才 commit／跳過 test 說「等等再補」／動 tasks.md 以外的檔案（發現遺漏 → 回 Stage 3 補 task，不偷加）。
• 平行化：同一 Parallelizable Group 可用 superpowers:dispatching-parallel-agents 或 superpowers:subagent-driven-development。

Stage 5 — Review（五維審查 + Fix loop）

• 產出 review.md：Correctness／Readability／Architecture（是否符合 design.md、偏離處是否合理）／Security（OWASP Top 10）／Performance 五維，加 Acceptance Criteria checklist（逐條附證據）。
• Review-fix loop：每條 Action 回 Stage 4 以獨立 commit 處理；處理完再走一次 Stage 5，直到 Actions 清空且所有 AC 打勾；陷 3+ 輪仍有重大問題 → 退回 Stage 2 重新檢視 Design。
• 獨立審查不要跳過（實測高價值低成本）：派 code-reviewer subagent，給完整 context（spec／design／變動檔清單／commits hash），不要只丟 diff。🔴 必修立刻處理；🟡 評估本輪修或 defer。
• 檢查點 ✅：Actions 全關閉、AC 全打勾。

Stage 6 — Ship（驗證與交付）

• 目標：evidence-before-assertion，不說「應該可以」。產出 shipping.md（Pre-flight／Manual verification log／Rollout／Post-ship 歸檔與監控）。
• Stage 6 是真 fix loop，不是 checkbox：UI/UX feature 預期實機測出 2~5 個視覺/互動 bug 回 Stage 4——這是流程的一部分，不是失敗。實機測試比 widget test 重要（theme 套用、元件擠壓、動畫節奏、平台差異、權限對話框，test 都驗不出）。
• 禁止：未經用戶明確授權 push / merge / deploy（授權 scope 限定當次，不外推）／跳過人眼實測就宣告完成／以「CI 綠燈」代替功能正確性。
• 檢查點 ✅：用戶明確授權後才 merge / push。Merge 後歸檔到 archive/。

紅旗與急停

下列情況立即停下並回報用戶：

• Design 假設在 Implement 時被打臉 → 退 Stage 2
• Task 粒度明顯錯誤（一個 task 開 10+ 檔案）→ 退 Stage 3
• Review 發現 AC 無法達成 → 退 Stage 1 調整 scope
• 遇到不在 scope 的既有 bug → 記錄但不修，另開 quick-fix
• 外部依賴 / API 與假設不符 → 退 Stage 2 重新設計

References 索引

| 檔案 | 何時讀 | |------|--------| | references/artifact-templates.md | 產出各階段檔案時——proposal／design／tasks／review／shipping 五份模板全文 | | references/lessons.md | 開工分流拿不準、design 被 fix loop 推翻、寫 spec 文件抓重點、與其他 skill 搭配時——real-run 教訓 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tienenwu
• Source: tienenwu/fables
• License: MIT

Install and usage instructions live in the source repository linked above.