Dflow

繁體中文 | English

AI 協作沒 DDD = 加速混亂；有 DDD = 把 AI 事先約束在領域模型內。 Rich Domain Model（業務規則寫在領域物件本身、而非散在 service 或 prompt 裡）把不變條件、業務規則、Aggregate 邊界編碼進物件 — AI 寫的程式碼必須穿過這個契約。Dflow 把 DDD 當成 SDD 的語意骨幹。

Dflow 是一套 spec-first 的工作流程工具集，專為 AI 輔助軟體開發設計。它為你的 AI 程式設計助理提供具體流程，把變更需求轉成結構化規格、領域語言、實作計畫、漂移檢查、與可審查的程式碼，而不是從 prompt 直接跳到程式碼。

目標不是流程本身，而是讓軟體變更可重複、語意更清楚、規則更不散落、行為更不依賴 prompt。

主要特點

| 特點 | 對工程團隊的幫助 | |---|---| | Spec-first 開發 | 把對齊推到實作之前，避免 AI 從模糊 prompt 直接生程式碼後才發現方向錯、回頭重做。 | | Greenfield 與 Brownfield 雙軌 | 不只服務新專案；既有 codebase 不必先做大規模重構，可邊改邊把散落各處的領域規則抽出來。 | | 混合式工作流程控制 | 不是 autopilot 也不是純手動 — 明確命令進入、AI 在你忘記啟動時建議切入、重要決策點停下確認。三層共存讓 AI 不會一路跑偏，也不會把每一步都變成繁瑣流程。 | | DDD 語意骨幹 | AI 最容易憑直覺發明業務規則（折扣何時有效、帳號權限邊界），這種錯誤 review 時人眼很難察覺。先把領域語言、邊界、業務規則寫下來，AI 補細節時受專案約束、而不是憑感覺。 | | 三層文件模型 | 對應 feature branch 的實際節奏：phase（單次提案-實作循環）/ feature（整條 branch 的累積狀態與接續指引）/ system（跨 feature 的長期知識）。許多 spec 工具只有 phase + system 兩層，多次迭代的 feature branch 跨多個 phase 時就會失真。下方有完整說明。 | | 依改動深淺的 Tier 制（T1/T2/T3） | AI 依改動深淺自動決定規格與驗證量級：改顏色 / typo 只需 _index.md 一行；bug fix 用 lightweight spec + 聚焦驗證；新 feature 或動到 bounded context 才走完整 phase-spec + 分層實作計畫 / 驗證。小修改不會被流程拖累。 | | 漂移驗證 | /dflow:verify 把規格、領域文件、實作、測試、技術債紀錄做交叉比對，找出 PR review 人眼看不出來的「文件還在描述舊行為」漂移。 | | 多 AI 工具共用一份規則 | Canonical 專案指南 + 各工具薄 shim（CLAUDE.md / AGENTS.md / Copilot instructions），團隊在 Claude / Codex / Copilot 之間切換時不必維護多份 workflow 規則。 |

開始使用

前置需求：已安裝 Node.js / npm，且全域 npm bin 目錄已加入 PATH。

於要採用 Dflow 的專案根目錄執行：

npm install -g dflow-sdd-ddd
dflow init

init 流程會詢問是 greenfield 或 brownfield，接著預覽即將建立的檔案。既有檔案不會被覆寫。Init 只建立 workflow 文件與 AI 指示檔，不會檢查、重構、或遷移你的應用程式碼。

若專案已初始化、之後又要加入另一個 AI 程式設計工具，執行：

dflow configure-agents

若想同時建立工具原生的命令 / prompt wrapper，使用 opt-in 模式：

dflow configure-agents --command-adapters

此指令只設定 AI 指示檔與選配 command adapters，不會重跑專案初始化，也不會動到既有 specs。

替代路徑：不安裝直接試用

若無法或不想全域安裝（沒有管理員權限、暫時性環境、或只想試一次），Dflow 每個 CLI 指令都可透過 npx 執行：

npx dflow-sdd-ddd init
npx dflow-sdd-ddd doctor
npx dflow-sdd-ddd configure-agents

走這條路徑時，同一個 session 內所有指令都要用完整的 npx dflow-sdd-ddd <subcommand> 形式；裸 dflow 別名只有全域安裝後才能用。

檢查 legacy artifacts（選用）

要檢查專案內是否仍有 legacy 或 pre-V1 artifacts（如根目錄的 specs/ 或舊版的 _共用/），執行：

dflow doctor

doctor 是唯讀健康檢查；不會修改任何檔案，只報告找到的問題並指向 migration guide。剛 init 的新專案不會有 legacy artifacts、可跳過此步驟。

開始使用 Dflow workflow

完成 init 之後，透過 AI 程式設計助理走 Dflow workflow：

/dflow:new-feature
/dflow:modify-existing
/dflow:bug-fix
/dflow:new-phase
/dflow:finish-feature
/dflow:verify
/dflow:pr-review

/dflow:* 是 Dflow 的 canonical 共同詞彙；各 AI 工具的 / parser 行為不同。實際輸入方式如下：

| 工具 | 建議叫法 | |---|---| | Claude Code（安裝 --command-adapters 後） | /dflow:<id>，例如 /dflow:new-feature | | GitHub Copilot | chat 文字可用 /dflow:<id>；VS Code prompt 選單使用 /dflow-<id> | | Codex CLI | 不帶斜線的純文字 dflow:<id>，例如 dflow:new-feature |

若你的工具不支援自訂 slash command，把 workflow 名稱當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料加一個 scaffolding CLI，能與任何可讀專案指示與 repo 上下文的 AI 程式設計助理一起運作。

第一次採用建議用 branch 或一次性試用專案，讓團隊先檢視產生的 dflow/specs/ 工作區，再把流程引入正式程式碼。

完整評估流程（init 產生哪些檔案、AI 工具支援、模式選擇、30 分鐘試用 playbook）見 評估 Dflow。Greenfield 與 Brownfield 端到端劇情走完與規格範例見 tutorial/ 索引。

專案模式

| 模式 | 何時用 | 主要產出 | |---|---|---| | Greenfield | 新系統或新 bounded area，有空間早期塑形架構與領域模型 | 乾淨的規格 baseline、領域模型歸屬、feature-by-feature SDD 實作 | | Brownfield | 在既有 codebase 增加或修改行為，業務規則可能已散落各處 | 漸進的領域抽出、更安全的變更規劃、可遷移的領域知識 |

兩種模式區分的是專案起始狀態（新建 vs 既有 codebase），不是 framework 品牌；Dflow 對語言與 stack 不做假設，workflow、tier 制與文件模型可套用任何技術組合。本質是給「希望 AI 協助、又不願放棄領域清晰度」的軟體團隊使用的 workflow 系統。

各 stack（.NET / Java-Spring / Node-TS / Python / Go / PHP-Laravel）的填好範例見 docs/examples-by-stack.md。

模式選擇與遷移

模式在 dflow init 時選定、之後不能 in-place 切換（沒有 /dflow:switch-to-greenfield 之類的指令）。Brownfield 設計上是 Greenfield 的前置準備：抽出到專案 domain 層（例如 src/Domain/）的領域程式碼，與 dflow/specs/domain/ 內的領域文件（術語、規則、模型、事件），都是 migration-ready 資產 — 未來要 rewrite 時（建新專案 + 新 dflow init 選 Greenfield），可以直接搬過去。dflow/specs/migration/tech-debt.md 是 brownfield 專用的遷移債紀錄。

也支援「逐 BC（Bounded Context）遷移」— 某個 BC 的業務邏輯已純化到 domain 層、表現層只剩 UI 綁定後，這個 BC 就已是 Clean Architecture 狀態，不必整個 system 一次性切。Brownfield 的 /dflow:modify-existing 內「評估表現層業務邏輯」步驟對該 BC 自然會變 no-op。

Workflow 模型

Dflow 採用混合設計，user 跟 AI 互動有三個層面：

| 層 | 用途 | |---|---| | 命令進入 | 開發者主動以 /dflow:new-feature、/dflow:modify-existing 等命令開始工作。 | | 自動偵測安全網 | 當對話明顯指向某個 feature、phase、bug fix、verification、review 時，AI 應主動建議對應的 Dflow flow。 | | 透明的決策檢查點 | AI 在工作的關鍵節點（flow 進入、Step Gate、重要內部步驟）會停下來告知並等開發者確認方向，避免一路自動跑下去。 |

Workflow 內部結構

每次 user 下一個 /dflow:xxx 指令，就是啟動一個 Workflow run。Workflow 內部由編號的 Step 組成（例如 /dflow:new-feature 共 8 個 Step），Step 之間有兩種邊界：

• Step Gate — AI 必須停下宣告即將進入下一個 Step、等 user 確認方向。確認方式：/dflow:next 指令、或自然語言「OK / 繼續」、或直接提供下一個 Step 需要的資料（implicit confirmation）
• Step-internal transition — AI 只宣告「Step N 完成，進入 Step N+1」、不等待

Step Gate 不是每個 Step 之間都有。以 /dflow:new-feature 為例，8 個 Step 中只有 4 個 Step Gate，其他 Step 之間直接推進。

依改動深淺調整規格、實作計畫與驗證（Tier 制）

Dflow 依改動深淺自動決定規格、實作計畫與驗證的量級（T1 / T2 / T3 三層）：

| Tier | 典型用途 | 預期份量 | |---|---|---| | T1 Heavy | 新 feature、新 phase、新 Aggregate / Bounded Context、架構變更、新業務規則 | 完整 phase-spec、領域建模、行為例子、實作計畫、驗證與收尾檢查 | | T2 Light | Bug fix（邏輯錯誤）、UI 驗證調整、有 BR（business rule）delta 的小幅修改 | Lightweight spec、聚焦驗證、確認修復落在正確架構層 | | T3 Trivial | 按鈕顏色、文案 typo、純 formatting — 不動業務規則、不動 Domain 概念、不動資料結構 | _index.md 一行紀錄，不另開 spec 檔 |

tier 不是每次都 user 決定 — /dflow:new-feature 與 /dflow:new-phase 預設一律 T1，/dflow:modify-existing 與 /dflow:bug-fix 才由 AI 依改動內容判 T1/T2/T3。

不是每個變更都走 Dflow：純 typo、純 formatting commit（例如 prettier / dotnet format 自動跑）連 T3 inline 紀錄都不需要，直接 git commit 即可。Dflow 是給有業務語意或結構變動的修改用的。

透明的決策檢查點與 Tier 制有關但獨立：檢查點控制 AI 如何溝通 workflow；Tier 控制變更需要多少規格、實作計畫與驗證。

文件模型

實際開發中，一個 feature branch 通常會經歷多次「提案 → 實作 → 完成」循環才整個 finish — 多個 milestone、多次迭代、多筆 commit。Dflow 三層文件模型對應這個節奏：

| 層 | 檔案 | 用途 | 對應的 git 概念 | |---|---|---|---| | Phase Delta | phase-spec-{date}-{slug}.md（或 lightweight spec） | 紀錄此次循環改了什麼、為什麼、怎麼實作與驗證 | feature branch 內的一次 milestone 區間 | | Feature Snapshot | _index.md（每個 feature 目錄內） | feature 級 dashboard：phase 列表、cumulative BR Snapshot、Resume Pointer | feature branch 自己的「目前進度」 | | System State | rules.md / behavior.md / glossary.md / context-map.md | 跨 feature 的長期知識：術語、業務規則、模型、慣例、技術債 | main / trunk 累積下來的「系統現在實際是什麼」 |

_index.md 是關鍵的中間層。很多 spec 工具只有 phase + system 兩層，但 feature branch 跨多次 phase 是常態，少了中間層就會遇到三個痛點：

• 翻所有 phase-spec 才能知道「這個 feature 目前累積到哪」
• 新對話接手時要重建 context，不知道上次做到哪
• 歸檔顆粒度太細或太粗 — 要嘛一份份歸檔失去 feature 全貌，要嘛全部塞進 system 層失去 phase 軌跡

Dflow 用 _index.md 解決這三點：Current BR Snapshot 每完成一個 phase 就 regenerate、Resume Pointer 寫接續指引、整個 feature 目錄是自然的歸檔單位。/dflow:finish-feature 收尾時，把 _index.md 的 BR Snapshot reconcile 到 rules.md / behavior.md（feature 層晉升到 system 層），然後 git mv 整個 feature 目錄到 completed/。

Init 產生的檔案

典型初始化專案會建立 dflow/ workspace：

dflow/
└── specs/
    ├── shared/
    │   ├── _overview.md
    │   ├── _conventions.md
    │   └── Git-principles-*.md
    ├── domain/
    │   ├── glossary.md
    │   └── context-map.md
    ├── architecture/
    │   └── tech-debt.md
    └── features/
        ├── active/
        └── completed/

Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指示檔；確切檔名取決於目標工具與既有專案設定。Dflow 不覆寫既有專案指示。

選擇 AI agent 設定時，Dflow 把 dflow/specs/shared/AI-AGENT-GUIDE.md 作為 canonical 專案指南，並為每個 AI 工具建立小型的指向檔（俗稱 shim，內容很短，只是把該工具引導去讀 canonical 指南）：

| 目標工具 | 產生檔案 | |---|---| | Codex / Copilot coding agent | AGENTS.md | | Claude Code | CLAUDE.md | | GitHub Copilot | .github/copilot-instructions.md |

若這些檔案已存在，Dflow 不會覆蓋，改寫 merge snippet 到 dflow/specs/shared/。專案指南保持單一 source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。

之後團隊採用新 AI 程式設計助理時，可隨時跑 dflow configure-agents 新增 shim；若需要 Claude / Copilot 的工具原生命令入口，改用 dflow configure-agents --command-adapters。

產生物的版控政策（建議預設）

dflow configure-agents --command-adapters 產生的命令 / prompt wrapper 是從 canonical guide 投影出來的衍生物（generated artifact）。Dflow 的建議預設是把它們當成可重生成的產物：版控 source、不版控衍生物。

| 檔案 | 角色 | 建議預設 | |---|---|---| | dflow/（canonical guide、規格、merge snippet） | source | 版控 | | 薄 shim（CLAUDE.md / AGENTS.md / .github/copilot-instructions.md） | source | 版控 | | .claude/commands/dflow/、.github/prompts/dflow-*.prompt.md | 衍生物 | 建議不版控（gitignore），clone 後重跑 configure-agents --command-adapters 重生成 |

這是建議，不是唯一正解。若團隊希望 clone 後立即有原生 / 選單、或 CI / 開發環境不裝 npm，版控 adapter 也是合理選擇——代價是升級若改了命名，要重投影並 commit 刪除舊檔。關鍵原則：同一專案對所有工具採一致策略，別像常見的踩雷一樣一邊 ignore、一邊版控。

升級 dflow 後重跑 dflow configure-agents --command-adapters，adapter 會用新版的 command registry 重投影；但不會覆寫已存在的 dflow/specs/shared/AI-AGENT-GUIDE.md（canonical guide 已存在則保留）。「重投影 adapter」與「升級 canonical guide」是兩件事；升級時請用相同的 dflow CLI 版本重投影，避免 registry 與 guide 版本錯位。各工具的 .gitignore 片段、glob 副作用、git rm --cached 切換步驟與升級細節見 per-tool 指南。

特定工具的 init 寫入內容與 Dflow workflow 命令呈現方式，見 docs/ 內的 per-tool 指南：

• 在 Claude Code 中使用 Dflow
• 在 Codex CLI 中使用 Dflow
• 在 GitHub Copilot 中使用 Dflow

Init 不會把 tutorial/ 目錄複製進你的專案。tutorial/ 目錄存放在本 source repository，作為理解 Dflow 如何在 Greenfield / Brownfield 劇情中運作的評估材料。

主要 Flow

Dflow 指令依角色分四類。「我要做的事」對應到指令的速查表附在最後。

入口指令（從這裡開始一個 workflow）

啟動一次 workflow run；可在沒有任何既有 feature 的狀態下使用。三者彼此獨立、不互為前置。

| Flow | 何時用 | 典型產出 | |---|---|---| | /dflow:new-feature | 完全新功能、新增一條系統要實現的業務規則 | feature 目錄 + _index.md + 第 1 份 phase-spec（一律 T1） | | /dflow:modify-existing | 改既有行為 — 不確定改動屬於哪類時用，AI 內部會分流 | T1 → 升 new-phase / new-feature；T2 → lightweight-spec；T3 → _index.md inline 一行 | | /dflow:bug-fix | 可清楚陳述預期行為的 defect | AI 判 tier（多為 T2 lightweight-spec）。Orphan bug 會自建最小 feature 目錄 |

Feature 內指令（限 active feature）

只在已啟動的 active feature 內可用。指向 completed/ 的 feature 會被拒絕。

| Flow | 何時用 | 典型產出 | |---|---|---| | /dflow:new-phase | active feature 需要再一個實作切片 | 新一份 phase-spec-{date}-{slug}.md + Implementation Tasks + 程式實作 / 驗證 + phase 標記完成（一律 T1） | | /dflow:finish-feature | feature 全部 phase 完成、要收尾 | git mv 整個 feature dir 到 completed/、sync BR Snapshot 到 BC 層、Integration Summary（不 auto-merge） |

流程控制（管理進行中的 workflow run）

| Flow | 何時用 | |---|---| | /dflow:status | 看現在在哪個 workflow / Step / 進度 | | /dflow:next | 確認過 Step Gate（等同自然語言「OK」/「繼續」） | | /dflow:cancel | 放棄目前 workflow run、回到自由對話。已建立的 artifacts 保留 |

獨立工具（任何時候可呼叫，不綁定 feature 或 workflow）

| Flow | 何時用 | 典型產出 | |---|---|---| | /dflow:verify | 需要確認文件、程式、測試、債務紀錄是否一致 | 跨規格、領域文件、實作、測試、債務的 drift report | | /dflow:pr-review | 變更已準備接受審查 | SDD/DDD 合規 review 清單，含風險、缺口、後續項目 | | /dflow:report-dflow-feedback | 你或 AI 在使用中發現 Dflow 本身的問題 | sanitized 的本地 feedback 草稿；不自動送出 |

該選哪個指令（rule of thumb）

| 我要做的事 | 直接下指令 | |---|---| | 完全新功能（與現有 feature 無關） | /dflow:new-feature | | 為 active feature 加規劃中的下一個 phase | /dflow:new-phase | | 修一個明確的 bug | /dflow:bug-fix | | 不確定怎麼分類、反正是改既有的 | /dflow:modify-existing | | feature 全部 phase 都完成、要收尾 | /dflow:finish-feature | | 跑變更 review | /dflow:pr-review | | 檢查文件與程式碼 drift | /dflow:verify |

completed feature 是凍結歷史

當 /dflow:finish-feature 把 feature 目錄 git mv 到 completed/ 後，該 feature 不接受任何直接寫入，無論是新 phase-spec、lightweight-spec、還是 _index.md inline 一行。如果之後要再改它，必須建一個 follow-up feature：新 feature 目錄、新 SPEC-ID、_index.md 用 follow-up-of: {原 SPEC-ID} metadata 連回原 feature。

理由：「completed = 凍結歷史」是 Dflow 的核心保證；若接受 post-completion 修改，feature lifecycle 就失去明確終點、_index.md BR Snapshot 也無法可信。/dflow:modify-existing 偵測到目標是 completed feature 時會主動詢問 user 三個選項：A 走 follow-up、B 改用 /dflow:new-feature 當獨立新需求、C（被拒絕，重新引導至 A）。

為什麼 DDD 在 AI 時代更重要

AI 助理擅長把缺少的細節補起來。如果缺少的是「靠規則或慣例就能推出來」的東西（例如命名、樣板語法），這是優點；但如果缺少的是業務語意（什麼樣的折扣才算有效、帳號不能做什麼），模型可能會發明一個看起來合理、實際錯誤的規則，而且這種錯誤在 review 時很難一眼察覺。

Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名一致、bounded context 防止語意跨領域漏氣、領域規則在實作開始之前先定義什麼是正確、允許、禁止。

在 code-first workflow 裡，設計常常在類別、handler、測試完成後才浮現。在 AI-assisted workflow 裡，規格必須成為產生程式碼的前置條件。實務流程變成：

領域意義 → 結構化規格 → AI 實作 → 程式碼即產出

更詳細的說明見 為什麼 AI 時代 DDD 更重要。

Repo 結構

| 路徑 | 用途 | |---|---| | bin/ | CLI 進入點 | | lib/ | Init runtime 實作 | | templates/ | init 指令複製的檔案 | | test/ | 產出物的 smoke test | | tutorial/ | 引導式學習劇情與預期產出 | | sdd-ddd-*-skill/ | AI 程式設計助理消化的 workflow 來源材料 |

貢獻與發布

issue 與 pull request 指引見 CONTRIBUTING.md。Pull request 會在 review 前跑 GitHub 上自動 verification workflow。Maintainer-facing 的 release 規則見 Release and Versioning Policy；手動 npm flow 見 npm Publish Checklist。

狀態

Dflow 目前以 dflow-sdd-ddd 名稱發佈於 npm。最新發佈版本為 0.2.0，涵蓋：

• 專案初始化（dflow init）
• Workflow 文件（/dflow:* 流程）
• 多 AI agent 設定（CLAUDE.md / AGENTS.md / Copilot instructions shim）
• AI agent 可讀的 SDD/DDD 指引
• 公開 migration tooling：手動 migration guide 與 dflow doctor 唯讀健康檢查
• 公開 onboarding：evaluator 指南、Claude Code / Codex CLI 的 per-tool walkthrough
• 僅驗證的 CI workflow（不執行 publish）

GitHub 上的 source 可能包含 0.2.0 之後尚未發佈的 repo 變更。完整 release history 見 CHANGELOG.md。

授權

MIT License，見 LICENSE。