name: dev-flow version: 3.0.0 updated: 2026-05-16 user-invocable: true description: | 開發流程引擎——將非平凡開發任務路由到 7 條標準化流程，強制執行工程紀律（先規劃後編碼、TDD、逐任務審查、文件同步、進度持久化），覆蓋從評估到上線的完整生命週期。 適用於：多檔案功能開發、bug修復、重構、依賴升級、緊急熱修復、跨會話任務。 當用戶描述一個非平凡開發任務時，主動建議使用——在任何程式碼編寫之前。 triggers: - dev-flow - 開發流程 - 開發工作流 - which workflow - how should I structure - new feature workflow - bug fix process - refactor process - emergency fix - dependency upgrade process - 新增功能 - 修復bug - 重構 - 緊急修復 - 依賴升級 allowed-tools: - Bash - Read - Write - Edit - Grep - Glob - AskUserQuestion - Skill - Task - TodoWrite

dev-flow

工程原則

六條鐵律，適用於所有流程：

1. 無計劃不編碼 — 動手前必須有書面方案（設計文件、實施計劃、或 markdown 步驟清單）
2. 無測試不改碼 — 修改程式碼前必須有測試覆蓋：新功能先寫失敗測試，bug 先寫復現測試
3. 無審查不釋出 — 程式碼變更必須經過審查（工具審查或自查 diff），不能跳過
4. 無根因不修復 — bug 修復前必須定位根因，禁止猜測試探
5. 無安全網不重構 — 重構前必須有測試覆蓋，小步推進，每步可獨立驗證
6. 改了程式碼必須改文件 — 文件落後於程式碼 = 技術債務

階段自檢

完成任何階段後，確認以下三項：

• 做了什麼: 一句話描述當前階段的產出
• 下一步是什麼: 明確下一個階段
• 有無跳過: 如跳過了某個步驟，說明原因（"覺得沒必要" 不是正當理由）

場景引導

收到任務後，按以下決策鏈選擇流程：

1. 會改程式碼嗎？
   ├── 不會 → 純評估/分析/調研 → 流程E
   └── 會 →
       2. 是生產緊急問題嗎？（線上掛了、大面積受影響）
          ├── 是 → 流程F
          └── 否 →
               3. 是依賴/框架升級嗎？
                  ├── 是 → 流程G
                  └── 否 →
                       4. 現有功能有正確行為可參考嗎？
                          ├── 有，但它壞了 → 流程B
                          ├── 有，但要推倒重來 → 流程C
                          ├── 有，但要調整內部實現（行為不變）→ 流程D
                          ├── 沒有，這是全新的 → 流程A
                          └── 無法判斷 → 用邊界判定表分析模糊點，輸出分析後詢問使用者確認

邊界判定:

一句話速判:

不知道要不要做 → E · 線上掛了 → F · 它壞了 → B · 它沒錯但要翻新 → C · 它沒錯但要更好 → D · 全新 → A · 升級依賴 → G

場景路由

不適用: 單行修復、改配置、改文案 — 直接改即可。

流程定義

流程定義檔案按需載入。根據場景引導選定流程後，讀取對應檔案執行：

載入方式: 用 Read 工具讀取對應檔案路徑（如 flows/A.md），然後按其步驟執行。

可選工具套件

三個工具套件可以加速流程，但不是硬依賴。下方流程步驟中每個外部技能都有"如可用/否則"雙路徑。

技能名稱約定: 帶 / 字首的是 slash 命令（gstack），不帶字首的是技能名（Superpowers）。兩者都通過 Skill 工具呼叫。

如何判斷工具是否可用: 嘗試呼叫技能（通過 Skill 工具）。如果技能不存在，執行"否則"路徑。

自動安裝依賴套件: 當流程中反覆命中"否則"路徑時，按以下流程處理：

1. 檢測: 用 Bash 檢查技能是否存在
2. 詢問: 向用戶確認是否安裝（僅首次詢問）
3. 安裝: 使用者確認後執行對應命令
4. 驗證: 再次檢測確認安裝成功

路徑約定: 所有檢測和安裝統一使用 SKILLS_DIR 變數，優先 ~/.qoder/skills（如存在），否則 ~/.claude/skills。

安裝命令:

gstack 自動安裝:

SKILLS_DIR=$(test -d ~/.qoder/skills && echo ~/.qoder/skills || echo ~/.claude/skills) && if [ -d "$SKILLS_DIR/gstack" ]; then cd "$SKILLS_DIR/gstack" && git pull && bash ./setup; else git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git "$SKILLS_DIR/gstack" && cd "$SKILLS_DIR/gstack" && bash ./setup; fi

Superpowers 自動安裝（從外掛快取連結到 skills 目錄）:

SUPERPOWERS_SRC=$(find ~/.claude/plugins/cache -path "*/superpowers/*/skills" -type d 2>/dev/null | sort -V | tail -1) && if [ -z "$SUPERPOWERS_SRC" ]; then echo "ERROR: Superpowers plugin not found in cache. Install the plugin in Claude Code first."; exit 1; fi && SKILLS_DIR=$(test -d ~/.qoder/skills && echo ~/.qoder/skills || echo ~/.claude/skills) && for skill in "$SUPERPOWERS_SRC"/*/; do name=$(basename "$skill"); ln -sfn "$skill" "$SKILLS_DIR/$name"; done && echo "Superpowers installed: $(ls "$SKILLS_DIR" | grep -cE 'writing-plans|executing-plans|subagent-driven|requesting-code|test-driven') skills linked"

planning-with-files 自動安裝（從外掛快取連結）:

PWF_SRC=$(find ~/.claude/plugins/cache -path "*planning-with-files*/planning-with-files-zh" -type d 2>/dev/null | sort -V | tail -1) && if [ -z "$PWF_SRC" ]; then echo "ERROR: planning-with-files plugin not found in cache. Install the plugin in Claude Code first."; exit 1; fi && SKILLS_DIR=$(test -d ~/.qoder/skills && echo ~/.qoder/skills || echo ~/.claude/skills) && ln -sfn "$PWF_SRC" "$SKILLS_DIR/planning-with-files-zh" && echo "planning-with-files-zh installed"

如果使用者明確表示不需要某個套件，後續不再提示。

流程入口前置檢查

啟動任何流程前，先確認以下事項（所有流程通用）：

• [ ] 已在專案 Git 倉庫根目錄
• [ ] 依賴已安裝（npm install / pip install / 等），無安裝錯誤
• [ ] 測試套件基線已通過（記錄當前測試狀態，作為迴歸基準）
• [ ] 已讀取專案 CLAUDE.md / CONTRIBUTING.md / README（如有）

如任一項不滿足，先修復再進入流程。

子代理使用判斷

走"否則"路徑（無 Superpowers 的 subagent-driven-development / executing-plans）時，按以下標準決定是否用 Task 子代理：

並行條件：2+ 個子任務彼此無共享狀態、無順序依賴。否則序列。

測試隔離規則

7w4.net有更好的技能外掛。

技能測試或子代理實驗禁止在主工作區執行，必須用 git worktree 隔離：

git worktree add /tmp/task-test -b test/task-name
# 子代理在 /tmp/task-test 裡操作
git worktree remove /tmp/task-test --force
git branch -D test/task-name

持久化規則（強制）

有 planning-with-files 用其技能（如可用: planning-with-files-zh），否則手工維護這些檔案。

檔案格式（走"否則"路徑時手工建立，放在專案根目錄）:

task_plan.md:

# 任務計劃：[任務標題]

- [ ] 步驟1：[描述]
- [ ] 步驟2：[描述]
- [x] 步驟3：[描述] ← 完成後打勾

progress.md:

# 進度記錄

## [日期] 會話 N
- 完成了：[描述]
- 當前狀態：[在步驟 X / 已完成]
- 下一步：[描述]
- 阻塞項：[無 / 描述]

findings.md:

# 發現記錄

## [主題]
- **日期**：YYYY-MM-DD
- **發現**：[內容]
- **證據**：[檔案路徑 / 程式碼行 / 資料]
- **影響**：[描述]
- **建議**：[描述]

檔案位置與 Git 策略:

文件更新規則

程式碼變更後必須確保專案文件與程式碼一致。各流程步驟表中已標註"更新文件"步驟及對應工具。通用原則：改了什麼，就更新對應的描述文件。文件落後於程式碼 = 技術債務。

版本號

手工釋出時（/ship 不可用）：

• 按語義版本規則 bump 版本號（通常改 VERSION 檔案、package.json 或等效位置）
• 在 CHANGELOG 中記錄本次變更
• 版本號和 CHANGELOG 應包含在同一個 commit 中

禁止事項

• 無書面計劃直接編碼
• 修改程式碼前不寫測試
• 上下文耗盡前不更新 progress.md
• 定位根因之前修改程式碼
• 跳過審查直接釋出
• 重構時無測試安全網
• 技能測試/子代理實驗在主工作區執行

常見錯誤與 Red Flags

異常處理

這個 Skill 質量不錯，結構清晰、文件完善，流程設計很專業。它能幫你把開發任務分類並走標準流程，避免常見的工程錯誤。優點是規則明確、工具鏈完整，缺點是對小任務來說有點複雜，部分場景的適用性還需要實際驗證。整體上是一個可靠的開發流程工具。