dflow-sdd-ddd 0.9.0 → 0.11.0

package/docs/using-with-github-copilot.md

@@ -2,7 +2,10 @@
 
 > **繁體中文** | [English](using-with-github-copilot.en.md)
 
-當你的 AI 程式設計助理是 GitHub Copilot（IDE chat + inline completions）時，Dflow 的使用體驗 walk-through。閱讀約需 10 分鐘。
+當你的 AI 程式設計助理是 GitHub Copilot 時，Dflow 的使用體驗 walk-through。GitHub
+Copilot 有兩個介面——**VS Code Copilot Chat**（IDE 內的 chat panel + inline
+completions）與 **GitHub Copilot CLI**（終端機）——兩者觸發 Dflow 與調用命令的方式
+不同，本指南會分開說明。閱讀約需 10 分鐘。
 
 本指南專注於 GitHub Copilot 的具體使用體驗。工具中立的評估流程請見
 [`docs/evaluating-dflow.md`](evaluating-dflow.md)。完整的 Get Started
@@ -12,8 +15,8 @@
 
 你正在使用或評估以 GitHub Copilot 作為 AI 程式設計助理的 Dflow。
 本指南說明 `init` 之後 Copilot 看到了什麼、repository shim 的位置、
-如何從 IDE 呼叫 Dflow workflow，以及幾個值得了解的 Copilot 專屬使用模式
-與 permission 行為。
+如何在 VS Code Copilot Chat 與 Copilot CLI 兩個介面呼叫 Dflow workflow，
+以及幾個值得了解的 Copilot 專屬使用模式與 permission 行為。
 
 ## 前置條件
 
@@ -36,28 +39,36 @@
 
 This project uses Dflow for spec-first AI-assisted development.
 
-Before planning or editing code, read and follow:
+For spec-impacting work — a new feature, a change to product, user-facing, or
+domain behavior, a new requirement, or a bug-fix workflow — read and follow:
 
-- `dflow/specs/shared/AI-AGENT-GUIDE.md`
+- `dflow/specs/shared/AI-AGENT-GUIDE.md` — command registry, routing rules, and project context.
+- `dflow/specs/shared/dflow-workflows/` — vendored workflow bundle with executable step definitions.
+
+For routine work (refactors, renames, chores, formatting, dependency bumps, or
+general code questions), proceed normally; you need not read the guide first.
+
+Keep tool-specific instruction files small. The guide and workflow bundle are
+the authoritative sources for Dflow workflow rules, slash-command behavior,
+spec locations, and SDD/DDD constraints.
 ```
 
 重點說明：
 
 - Copilot shim 位於 `.github/copilot-instructions.md`（見 `lib/init.js` mapping）。
-- Copilot shim 不含 Markdown `@` import。它只透過路徑指向 canonical 指南，讀取
+- Copilot shim 是薄指標，只透過路徑指向 canonical 指南；讀取
   `dflow/specs/shared/AI-AGENT-GUIDE.md` 時需明確開啟該檔案。
 
 ## 在 GitHub Copilot 中使用 Dflow Workflow 指令
 
-預設情況下，Copilot 是 IDE 優先的助理（chat panel + inline completions），不是
-CLI 工具。請把 Dflow workflow 名稱當成普通的對話指示，而非 CLI slash command：
+GitHub Copilot 有兩個介面，Dflow 在兩者的觸發與命令行為不同，先分清楚再用：
 
-- 在 Copilot Chat 中：「Run the Dflow /dflow:new-feature workflow」—— Copilot
-  應讀取 canonical 指南並繼續執行。
-- 在程式碼 comment 或 editor chat 中，以普通文字描述 workflow：
-  `Run the Dflow /dflow:new-feature workflow.`
+- **VS Code Copilot Chat**（IDE 內的 chat panel）：自然語言**會自動觸發** Dflow
+  的 skill；若你 opt in prompt adapters，工具原生命令 `/dflow-<id>`（連字號）也可用。
+- **GitHub Copilot CLI**（終端機）：**沒有**自然語言自動觸發；要先打 `/dflow`
+  **手動喚起** skill 再由它引導；per-id 的 `/dflow-<id>` 命令在 CLI **不可用**。
 
-可用的 workflow 入口：
+兩介面共用同一組 workflow 入口（詞彙相同，差別只在怎麼喚起）：
 
 | 指令 | 適用情境 |
 |---|---|
@@ -70,9 +81,43 @@ CLI 工具。請把 Dflow workflow 名稱當成普通的對話指示，而非 CL
 | `/dflow:pr-review` | 變更已準備好進行 SDD/DDD review。 |
 | `/dflow:report-dflow-feedback` | 你發現了 Dflow 的問題或改進點，想要一份清理過的上游回饋草稿。 |
 
+> **語法提醒**：表中 `/dflow:<id>`（**冒號**）是 Dflow 的 canonical 詞彙，也是
+> Claude / Codex 的**實際命令**語法。Copilot 的 prompt-adapter 命令改用
+> `/dflow-<id>`（**連字號**），且只在 VS Code 活；在 Copilot 裡不要照字面把冒號
+> 形式當命令輸入（Copilot CLI 會把 `/dflow:new-feature` 斷成 `/dflow`）。下面分介面
+> 說明各自怎麼呼叫。
+
+### 介面 A：VS Code Copilot Chat
+
+- **自動觸發**：有。在 chat 直接用自然語言描述要做的事（例：「I want to add CSV
+  export for users」），Dflow 的 skill 會自動 engage、判斷對應 workflow，並以
+  **suggest-and-wait**（建議命令、等你確認）開始，不會擅自跑完整個 workflow。
+- **命令**：`/dflow-<id>`（**連字號**）可用，但需先在專案跑
+  `dflow configure-agents --command-adapters` 投影
+  `.github/prompts/dflow-<id>.prompt.md`（見下節），之後在 prompt 選單選
+  `/dflow-new-feature` 即可。
+- **純文字也行**：你也可以在 chat 用普通文字描述 workflow（例：`Run the Dflow
+  /dflow:new-feature workflow.`）——此時 `/dflow:new-feature` 只是被當成**文字
+  稱呼**，不是被當命令解析。
+
+### 介面 B：GitHub Copilot CLI
+
+- **自動觸發**：**無**。直接送自然語言**不會** engage Dflow 的 skill。
+- **喚起方式**：先打 `/dflow`（無 id 後綴）**手動喚起** skill；skill engage 後會
+  列出可用的 workflow / 問你要做什麼，接著你用**自然語言描述**（例：「I want to
+  add CSV export」）或回覆它列的選項即可繼續。它一樣以 suggest-and-wait 運作。
+- **命令**：per-id 的 `/dflow-<id>` 在 CLI **不可用**——
+  `.github/prompts/dflow-<id>.prompt.md` 是 VS Code Chat 專屬、**CLI 不讀取**，
+  輸入 `/dflow-new-feature` 會得到 Unknown；冒號形式 `/dflow:new-feature` 則被
+  CLI 斷成 `/dflow`。CLI 沒有 per-id 命令入口，統一走「`/dflow` 喚起 → 會話描述」。
+- **skill 建議的命令怎麼辦**：skill engage 後可能會建議你用某個 `/dflow:<id>`
+  （這是給 Claude / Codex 的 canonical 寫法）。在 Copilot **不必照字面輸入那串
+  命令**——CLI 裡 skill 已經 engage，直接在會話用文字描述要的 workflow、或回覆
+  確認即可；VS Code 裡則改用 prompt 選單的 `/dflow-<id>`（連字號）。
+
 ### 選配 Prompt Adapters
 
-如果想在支援 prompt files 的 Copilot / VS Code 環境中使用工具原生入口，可在
+如果想在支援 prompt files 的 VS Code Copilot 環境中使用工具原生**命令**入口，可在
 已初始化的專案中執行：
 
 ```bash
@@ -84,11 +129,28 @@ dflow configure-agents --command-adapters
 
 - `.github/prompts/dflow-<id>.prompt.md`
 
-這些 prompt 在 Copilot / VS Code prompt 選單中使用 `/dflow-<id>` 形式，例如
-`/dflow-new-feature`。Prompt 內容只指向 canonical `/dflow:new-feature`
-workflow 與 `dflow/specs/shared/AI-AGENT-GUIDE.md`，不複製 workflow 步驟。
-Copilot 的 `/` parser 行為與 Claude / Codex 不同：選單入口是 `/dflow-<id>`，
-但在 chat 文字中也可以直接說 canonical `/dflow:<id>`。
+這些 prompt **只在 VS Code Copilot Chat 的 prompt 選單**生效（形式為
+`/dflow-<id>`，例如 `/dflow-new-feature`）；**Copilot CLI 不讀取**
+`.github/prompts/`，所以這條命令路徑在 CLI 不可用（見上方「介面 B」）。Prompt
+內容只指向 canonical `/dflow:new-feature` workflow 與
+`dflow/specs/shared/AI-AGENT-GUIDE.md`，不複製 workflow 步驟。注意命令語法用
+**連字號** `/dflow-<id>`，不是 canonical 的**冒號** `/dflow:<id>`——後者是
+Claude / Codex 的命令寫法，在 Copilot 只能當文字稱呼、不能當命令輸入。
+
+### `--skills` flag 與 Copilot 的 skill 觸發
+
+`dflow configure-agents --skills` 會為 **Claude Code、Codex 與 GitHub Copilot**
+各自投影同一份工具中立的 thin skill 到它們的 project-level skill 路徑；Copilot 的是
+`.github/skills/dflow/SKILL.md`。實測（2026-06-05）確認 Copilot 會從**自己原生的
+`.github/skills/`** 探索並運作（即使移除 `.claude`/`.agents` 的跨讀路徑也成立），
+觸發方式依介面而異——**VS Code Chat 自然語言自動觸發**、**Copilot CLI 需打 `/dflow`
+手動喚起**（細節見上方介面 A / B）。
+
+> 註：Copilot 也會跨讀 `.claude/skills` 與 `.agents/skills`；若你同一專案同時選了
+> Copilot 與 Claude / Codex，同一份 `dflow` skill 可能從多條路徑被看到。Dflow **產生**
+> 的各份內容逐字相同（同 `name`），所以正常情況一致；但若你在某條路徑已有自己的
+> （非 Dflow）`dflow` skill，Dflow 會原地保留、不覆寫——它可能與原生那份內容不同，
+> 建議移除或改名以免同名重複。
 
 ### 產生物的版控政策與升級
 
@@ -142,22 +204,33 @@ Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
 
 ### 既有的 Repository 指示
 
-如果你的專案中已有 `.github/copilot-instructions.md`，`init` 不會覆蓋它。
-它改為在 `dflow/specs/shared/` 下寫入 merge snippet，讓你手動審閱後貼入
-既有檔案。這樣可以避免破壞你已有的自訂 Copilot 指示。
+如果你的專案中已有 `.github/copilot-instructions.md`，`init` 不會覆蓋自訂內容。
+已是 Dflow-generated shim 的檔案會原地刷新；其他已指向
+`dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過。若既有檔案尚未指向 guide，
+Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
+`<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block；重跑會
+原地更新同一段，不會重複。這樣可以避免破壞你已有的自訂 Copilot 指示。若你刪除
+該 block，下一次 `init` / `configure-agents` 會再附加它。
+
+只有遇到衝突或 malformed Dflow markers 時，才到
+`dflow/specs/shared/copilot-instructions-snippet.md` 找 fallback merge snippet，
+再手動處理你現有的 `.github/copilot-instructions.md`。
+
+### `/dflow:<id>`（冒號形式）能不能直接輸入？
 
-到 `dflow/specs/shared/COPILOT-INSTRUCTIONS-MERGE-SNIPPET.md` 找到 merge
-snippet，再把相關段落貼入你現有的 `.github/copilot-instructions.md`。
+canonical 的 `/dflow:<id>`（冒號）是給 Claude / Codex 的命令寫法。在 Copilot
+**兩個介面都不要把它當命令字面輸入**：
 
-### Slash Command Passthrough 說明
+- **VS Code Chat**：當文字稱呼可以（Copilot 會理解你指的 workflow）；要命令入口
+  請用 prompt-adapter 的 `/dflow-<id>`（連字號）。
+- **Copilot CLI**：輸入 `/dflow:new-feature` 會被斷成 `/dflow`（只喚起 skill、不帶
+  id）。直接打 `/dflow` 喚起後，用文字描述要的 workflow 即可。
 
-Copilot 是否會直通（passthrough）原始的 `/dflow:*` slash command，取決於
-IDE 整合方式與 Copilot 版本。若 Copilot 無法識別以 slash 為前綴的 workflow
-名稱，以普通文字重新送出請求：
+任何介面只要 slash 形式沒被識別，就改用普通文字重新送出請求：
 
 ```text
-You: Instead of /dflow:new-feature, try: "Please help me start a new Dflow
-     feature workflow. Read dflow/specs/shared/AI-AGENT-GUIDE.md first."
+You: Please help me start a new Dflow feature workflow. Read
+     dflow/specs/shared/AI-AGENT-GUIDE.md first.
 ```
 
 ## 與其他 AI 工具的差異
@@ -168,20 +241,20 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 | 工具 | 產生的 shim | 載入 canonical 指南的方式 |
 |---|---|---|
 | GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取 repository 指示 |
-| Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Claude Code | `CLAUDE.md` | 啟動時直接讀取檔案內容 |
 | Codex / Copilot coding agent | `AGENTS.md` | 啟動時直接讀取檔案內容 |
 
 - Shim 路徑：Copilot 使用 `.github/copilot-instructions.md`（不是 `AGENTS.md`
   或 `CLAUDE.md`）。
-- Markdown import：Copilot shim 不含 `@dflow/specs/shared/AI-AGENT-GUIDE.md`
-  import。這點與 Claude Code 的 shim 透過 `@` import inline 嵌入不同。
-- 工具模型：Copilot 是 IDE-based（chat panel + inline completions）；
-  Codex / Claude Code 是 CLI-based agent。Copilot 透過編輯器 UI 互動，而非
-  command-line session。
+- 載入方式：Copilot shim 是薄指標、不 inline 指南（與其他工具一致）；
+  canonical 指南按需載入。
+- 工具模型：Copilot 有兩個介面——VS Code Chat（chat panel + inline completions）
+  與 Copilot CLI（終端機）；Codex / Claude Code 是 CLI-based agent。兩個 Copilot
+  介面與 Dflow 的互動方式不同（見上方介面 A / B）。
 - Workflow 呼叫：canonical `/dflow:*` 是共同詞彙，但各工具 `/` parser 行為不同。
-  Copilot 可在 chat 文字中使用 `/dflow:<id>`，若已 opt in
-  `--command-adapters`，VS Code prompt 選單名則是 `/dflow-<id>`，例如
-  `/dflow-new-feature`。
+  Claude / Codex 直接吃 `/dflow:<id>`（冒號）當命令；Copilot **不行**——VS Code
+  的命令入口是 prompt-adapter 的 `/dflow-<id>`（連字號，需 `--command-adapters`），
+  Copilot CLI 則沒有 per-id 命令、改打 `/dflow` 喚起 skill（見上方介面 A / B）。
 - Permission 模型：Copilot 依賴 IDE 的 permission 與 extension sandbox。它可能
   受 editor-level approvals 管理；CLI 工具通常有明確的 sandbox flags 與獨立的
   permission gates。
@@ -196,8 +269,10 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
   需要 spec-driven 輸出時，請明確要求執行 workflow。
 - Copilot Chat context 不一定會在所有 IDE 版本中自動包含 `.github/` 目錄下的
   repository 指示檔；行為因 Copilot / IDE 版本而異（見頁尾說明）。
-- 當 slash-prefixed forms 被 IDE 拒絕時，改用普通文字描述 canonical
-  `/dflow:<id>` workflow 名稱。
+- 先分清楚介面：VS Code Chat 自然語言自動觸發、命令用 `/dflow-<id>`；Copilot CLI
+  無自動觸發、先打 `/dflow` 喚起、沒有 per-id 命令（見上方介面 A / B）。
+- 當 slash 形式沒被識別（VS Code Chat 偶發、或 Copilot CLI 的 `/dflow-<id>`
+  Unknown）時，改用普通文字描述 workflow，或在 CLI 先打 `/dflow` 喚起 skill。
 - Prompt adapter 是從 canonical command registry 產生的薄 wrapper；不要在
   `.github/prompts/` 中手寫或複製 Dflow workflow 步驟。
 
@@ -223,5 +298,7 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 
 ---
 
-IDE 行為說明：Slash command passthrough 與 `.github/` 指示檔的自動包含行為，
-會因 Copilot / IDE 版本而異。依賴確切語意前請向 maintainer 確認。
+行為說明：本指南描述的介面差異（VS Code Chat 自然語言自動觸發、Copilot CLI 以
+`/dflow` 手動喚起、prompt adapters 僅 VS Code）依 2026-06-05 實測；`.github/`
+指示檔的自動包含與各介面的 `/` 命令解析仍可能因 Copilot / IDE 版本而異，依賴確切
+語意前請向 maintainer 確認。

package/docs/why-dflow.en.md

@@ -0,0 +1,72 @@
+# Why Dflow (Even When AI Already Knows DDD)
+
+> [繁體中文](why-dflow.md) | **English**
+
+If your instinct is "today's AI already knows DDD — tell it to *build a feature using DDD* and out come aggregates, value objects, events; isn't a spec-first tool on top of that over-engineering?" — this document is written for you. It is not trying to convince you; it lays Dflow's value, the evidence, and the limits flat so you can judge for yourself.
+
+## What Dflow is
+
+Dflow does not teach AI what DDD is — it is a scaffold: it forces the AI to keep a full record of the trade-offs behind each design decision, and fills in the blind spots the AI tends to miss while filling in details on its own and that review can't easily catch.
+
+Split "AI knows DDD" into two things and you see why it is still needed:
+
+1. **Can the AI state the correct DDD answer?** Yes. The model has read the textbooks — aggregate boundaries, invariants, ubiquitous language, it can recite them all.
+2. **When you review it, does the AI leave a complete enough record to audit — which options it weighed, why it chose this one, what it left undecided — and does it proactively catch the traps it tends to miss on its own?** Not necessarily — it depends on how you ask.
+
+So the real comparison is not "AI tool vs process" but:
+
+- **AI alone** output = AI knowledge × the implicit prompt structure × your ability to review it
+- **AI + Dflow** output = AI knowledge × an **explicit elicitation scaffold** × an **auditable record of the decisions (trade-offs, rejected options, open questions)** × your ability to review it
+
+The difference is not "a smarter AI." It is "**a more reviewable AI**."
+
+## Dflow's DDD guidance is grown, not copied from a textbook
+
+Part of Dflow's value is this: its guidance is fed back from real blind spots, and once added, the model actually reuses it afterward. A concrete, checkable example —
+
+**Blind spot**: modeling on its own, the model guarded "a connector can have at most one in-progress charging session" — a uniqueness rule — with just an in-memory `if Status == InUse throw` check inside the aggregate. By the DDD textbook this is correct, but under concurrency two requests each read `Available`, each pass the check, and each save → the invariant is broken (modeling-correct, production-broken).
+
+**Feedback**: that blind spot was written up as a section of guidance and added to Dflow's `ddd-modeling-guide.md` — "Set-Based / Uniqueness Invariants": for any "only one active X at a time" rule, no matter how you slice the aggregate, an in-memory check is never enough under concurrency; you need a DB unique / partial index or a concurrency token, and you must translate the conflict into an HTTP 409.
+
+**Reuse**: on a different domain (cold-chain sensors, "a sensor is attached to at most one carton at a time," structurally parallel) and with the model unaware it was being tested, it **proactively cited that section** and produced the full three-layer protection (in-memory guard + a concurrency token + a DB partial unique index + a 409).
+
+What this proves is something concrete: **Dflow turns "the blind spots AI misses on its own" into reusable guidance it actually follows.** This is not the grand conclusion "a few runs prove AI+process wins across the board" (the sample is small); it is evidence that Dflow's guidance loop works — **blind spot → add guidance → the model reuses it**. You can reproduce it yourself (see the end).
+
+> An honesty note: the domain and the framing also differ between the two runs, but both cut against the "it wasn't the guidance" counter-argument — neither domain is a high-frequency concurrency-design topic in the model's pre-training; the framing in the second run is purer (unaware of the test), and if that were the cause the result should be worse, not better. Once those two are pushed down as less plausible, the best remaining explanation for the flip is whether that section is present.
+
+## A few more things Dflow forces on the record that AI misses on its own
+
+The same observation round also showed (each point is "what Dflow does → what happens without it"):
+
+- **Forces the rejected-alternative reasoning**: one prompt in the aggregate-design template elicits a full decision block — "this boundary + why + which alternatives were considered + why rejected." On its own the AI usually hands you a single option, and at review you cannot audit "did it consider X?"
+- **Step gates turn decisions into reviewable moments**: the model naturally stops to confirm at naming and model-spike points; on its own the AI writes all the way to code and tests before you get to review, by which time the aggregate boundary is no longer negotiable.
+- **Open Questions get logged for the domain expert**: the model lists uncertain points as OQs awaiting an answer, instead of "guess something plausible" and burying the assumption in code logic.
+- **Ubiquitous language does not drift**: a glossary plus code mapping keeps spec / model / code on one set of terms; on its own the AI can mix `Sensor` / `Device` / `Tracker` within a single paragraph.
+- **Rules are queryable**: each business rule has an ID, a status, an owning aggregate, and a behavior link; on its own the AI scatters rules across prose, so "which tests does BR-003 affect?" is answerable only by grep and inference.
+
+## The honest trade-off
+
+Not hiding the limits is what makes the argument trustworthy:
+
+- **Scope**: the observations so far ran on a single model × a few moderate-complexity domains × lightweight modeling scope (through domain modeling, not the implementation phase). Whether the guidance is equally effective at the implementation phase, and whether a different model behaves the same, is **untested**.
+- **Prior**: the tested model already has a DDD pre-training prior. Dflow demonstrates it can turn "knows DDD but doesn't always think carefully" into "thinks carefully" — **not** "turns an AI with no DDD concept into one that does."
+- **Adoption implies compliance**: Dflow is a spec-first tool; it only works when it is followed. Cases where the AI or a person deliberately bypasses it are outside the claim. That is a property of the tool, not a bug.
+
+For audit-sensitive settings — medical, finance, compliance, safety-sensitive, or anything where a production failure is expensive or carries personal liability — this reviewability difference is a deal-breaker. The cost has two sides. *Producing* the DDD documents is no longer the pre-AI era when DDD by hand carried a heavy labor cost — the AI generates the specs, the decision record, and the domain model for you, so the marginal cost is mainly a few more tokens and running the workflow; and just being constrained by the domain model during generation already makes the output steadier (as in the concurrency blind spot above), a layer you get even if you never read the record closely. Dflow's DDD is also deliberately pragmatic (not the full academic suite), fitting a typical company's mid-sized systems with a low adoption barrier (a team need not be DDD experts first). But cashing in the further "reviewable" value still takes a person actually reviewing that record — that is the key cost in human attention and discipline. So the trade-off stands and is worth discussing: when stakes are high, an audit is needed, or a team maintains it long-term, the investment clearly pays off; when you won't review it, the cost of failure is low, and iteration is fast, AI alone may still be the more practical choice — Dflow does not always win.
+
+## Verify it yourself
+
+Don't trust any of the above — run it once (about 10–30 minutes):
+
+```bash
+npm install -g dflow-sdd-ddd
+mkdir dflow-test && cd dflow-test
+git init && git commit --allow-empty -m "init"
+dflow init           # choose greenfield + your AI tool + your stack
+```
+
+Then in your AI coding agent run `/dflow:new-feature` and assign a feature with a "cross-instance uniqueness" invariant, e.g. "at most one active session per account at a time." Watch whether, at domain modeling, the model reaches the "Set-Based / Uniqueness Invariants" section (in Dflow's `ddd-modeling-guide.md`), cites it, and adds a DB unique / partial index + a concurrency token + a 409. Note: installing the latest version verifies the half "when the guidance is present the model uses it"; the "without the guidance the model misses it" half was established by the run above before the guidance was added, and is not a variable you can toggle on the latest version — which always contains it.
+
+---
+
+Dflow does not claim to make the AI smarter; it makes the AI more reviewable: spec-first, domain meaning made explicit, decisions and rejected alternatives kept on the record, AI constrained before implementation, and drift verified before the work is called done. For why domain meaning itself matters more in the AI era, see [Why DDD Matters More with AI](why-ddd-for-ai.en.md).

package/docs/why-dflow.md

@@ -0,0 +1,72 @@
+# 為什麼用 Dflow（即使 AI 已經會 DDD）
+
+> **繁體中文** | [English](why-dflow.en.md)
+
+如果你的直覺是「現在的 AI 已經會 DDD，叫它『用 DDD 建一個 feature』，aggregate、value object、event 都出得來，再加一層 spec-first 工具是不是過度工程？」——這份文件是寫給你的。它不打算說服你，而是把 Dflow 的價值、證據與限制攤平，讓你自己判斷。
+
+## Dflow 是什麼
+
+Dflow 不是教 AI 什麼是 DDD——它是一層 scaffold（鷹架）：強迫 AI 把每個設計決策的取捨完整留檔，並補上「AI 自己補細節時容易漏、而 review 又難一眼看出」的盲區。
+
+把「AI 會 DDD」拆成兩件事，就懂為什麼還需要它：
+
+1. **AI 能不能說出對的 DDD 答案？** 能。模型讀過教科書，aggregate 邊界、不變式、ubiquitous language 都答得出來。
+2. **AI 在你 review 時會不會留下夠完整的紀錄（它考慮過哪些、為何這樣選、哪裡還沒確定）讓你 audit、會不會主動 catch 它自己容易漏的陷阱？** 不一定，要看你怎麼問。
+
+所以真正該比的不是「AI 工具 vs process」，而是：
+
+- **AI alone** 的產出 = AI 知識 × 隱含的 prompt 結構 × 你 review 它的能力
+- **AI + Dflow** 的產出 = AI 知識 × **明確的 elicitation scaffold** × **可審查的決策紀錄（取捨、否決的方案、open questions）** × 你 review 它的能力
+
+差異不是「更聰明的 AI」，是「**更可審查的 AI**」。
+
+## Dflow 的 DDD 引導是「長出來的」，不是抄教科書
+
+Dflow 的價值有一部分在於：它的引導是從真實盲區回灌的，而且補上之後，模型真的會在後續主動沿用。一個具體、可檢查的例子——
+
+**盲區**：模型自己建模時，把「一個充電槍同時只能有一筆進行中 session」這條唯一性規則，只用 aggregate 內 `if Status == InUse throw` 的 in-memory check 保護。DDD 教科書角度這是對的，但並發下兩個請求各自讀到 `Available`、各自通過檢查、各自 save → 不變式被破壞（modeling-correct、production-broken）。
+
+**回灌**：把這個盲區寫成一段引導，補進 Dflow 的 `ddd-modeling-guide.md`——「Set-Based / Uniqueness Invariants」：這類「同 X 只能有一筆 active」的規則，無論怎麼切 aggregate，in-memory check 在並發下永遠不夠，要加 DB unique / partial index 或 concurrency token，並把衝突 translate 成 HTTP 409。
+
+**沿用**：換一個 domain（冷鏈感測器「一個 sensor 同時最多掛在一個 carton」，結構平行）、且讓模型不知道自己在被測，它就**主動引用那段**、補上完整三層保護（in-memory guard + concurrency token + DB partial unique index + 409）。
+
+這證明的是一件具體的事：**Dflow 把「AI 自己會漏的盲區」固化成可重用、會被遵循的引導。** 這不是「跑幾次就證明 AI+process 全面勝出」那種大結論（樣本很小）；它是 Dflow 引導迴路有效的證據——**盲區 → 補引導 → 模型沿用**。你也能自己複現（見文末）。
+
+> 補充誠實度：兩次 run 之間 domain 與 framing 也不同，但都不利於「不是引導的功勞」這個反方——兩個 domain 在模型的 pre-training 裡都不是高頻並發設計題材；framing 在第二次更純（不知被測），若它是主因，結果該更差而非更好。把這兩條的可能性壓低後，最能解釋這個翻轉的就剩那段引導在不在。
+
+## 其他幾個「Dflow 強制留檔、AI 自己容易漏」
+
+同一輪觀察裡還看到（每點都是「Dflow 做了什麼 → 沒它會怎樣」）：
+
+- **強迫寫否決理由**：aggregate 設計模板一句 prompt，誘出「選這個邊界 + 理由 + 考慮過哪些替代 + 為何否決」的完整決策段；AI 自己通常只給你一個方案，review 時你無法 audit「它想過 X 嗎」。
+- **Step gate 把決策變成 reviewable moment**：模型在命名、模型 spike 等節點自然停下等確認；AI 自己一路寫到 code、tests 都好了你才有機會 review，這時 aggregate 邊界已經沒有商量空間。
+- **Open Question 留檔給 domain expert**：模型把不確定的點列成 OQ 等人答，而不是「不確定就猜一個合理的」把假設藏進 code。
+- **Ubiquitous language 不漂移**：術語表 + code mapping 讓 spec / model / code 用同一組名詞；AI 自己一段話內就能混用 Sensor / Device / Tracker。
+- **規則可被查詢**：每條 business rule 有 ID、status、所屬 aggregate、behavior 連結；AI 自己把規則散在 prose 裡，「BR-003 影響哪些測試」只能用 grep 推敲。
+
+## 誠實的取捨
+
+不掩蓋限制，反而是這套論點的可信來源：
+
+- **scope**：目前觀察只跑在單一模型 × 幾個中等複雜度 domain × lightweight modeling scope（到領域建模、不含 implementation phase）。implementation 階段的引導是否同樣有效、換不同模型會不會一樣，**未驗**。
+- **先驗**：被測模型本來就對 DDD 有 pre-training 先驗。Dflow 證明的是「能讓『會、但不一定每次仔細想』變成『仔細想』」，**不是**「能讓完全不懂 DDD 的 AI 變會」。
+- **採用即承諾遵循**：Dflow 是 spec-first 工具，只在被遵循時有效；AI 或人故意走偏的情境不在宣稱範圍內。這是工具屬性，不是 bug。
+
+對需要 audit 的場景——醫療、金融、合規、安全敏感、或任何「上線出包代價高 / 個人責任重」的領域——這個 reviewability 差異是 deal-breaker。成本要分兩塊看：**產出** DDD 文件已經不是徒手做 DDD 的高人力年代——AI 幫你生規格、決策紀錄與領域模型，邊際成本主要是多花一些 token 與走一遍流程；而且光是「生成時被領域模型約束」就已讓產出更穩（如上面那個並發盲區），這層就算你沒深讀紀錄也拿得到。Dflow 的 DDD 也刻意務實裁剪（不是學院派全套）、適合一般公司的中型系統，採用門檻不高（不需要團隊先是 DDD 專家）。但要再兌現「可審查」這份價值，得有人實際去 review 那份紀錄——那才是人力與紀律的關鍵成本。所以取捨仍在、值得討論：高風險、需 audit、要長期維護時，這筆投資明顯划算；你不會去 review、失敗成本低、迭代又快時，AI alone 仍可能是更實際的選擇，不是 Dflow 一定贏。
+
+## 自己驗證
+
+不用相信任何說法，自己跑一次（約 10–30 分鐘）：
+
+```bash
+npm install -g dflow-sdd-ddd
+mkdir dflow-test && cd dflow-test
+git init && git commit --allow-empty -m "init"
+dflow init           # 選 greenfield + 你的 AI 工具 + 你的 stack
+```
+
+接著在你的 AI coding agent 裡跑 `/dflow:new-feature`，指派一個含「跨實例唯一」型不變式的 feature，例如「同帳號同時最多一個 active session」。看模型走到領域建模時，會不會寫到「Set-Based / Uniqueness Invariants」段（Dflow 的 `ddd-modeling-guide.md`）、cite 它、並補上 DB unique / partial index + concurrency token + 409。注意：裝最新版能驗證的是「引導在場時模型確實會用它」這一半；「引導不在場時模型會漏」那一半是上面那段在加入引導之前建立的，不是你在最新版上能切換的——最新版一律含這段。
+
+---
+
+Dflow 不宣稱讓 AI 更聰明，它讓 AI 更可審查：規格優先、領域語義顯式化、把決策與否決理由留檔、在實作前約束、完成前驗證漂移（drift）。為什麼領域語義本身在 AI 時代更關鍵，見 [為什麼 AI 時代 DDD 更重要](why-ddd-for-ai.md)。