dflow-sdd-ddd 0.1.0 → 0.1.1

package/README.md

@@ -1,209 +1,185 @@
-# AI-Guided SDD/DDD Development Skills
+# Dflow
 
-AI 引導的規格驅動開發（SDD）與領域驅動設計（DDD）工作流程規範，設計用於 Claude Code 協作開發。
+Dflow is a spec-first workflow kit for AI-assisted software development. It gives your AI coding agent a concrete process for turning change requests into structured specs, domain language, implementation plans, drift checks, and reviewable code instead of jumping straight from prompt to code.
 
-## 這是什麼
+AI makes delivery faster, but it also makes ambiguous domain knowledge more dangerous. Dflow uses DDD ideas such as ubiquitous language, bounded contexts, domain rules, and model ownership as the semantic backbone of SDD, so the AI has constraints before it generates code. The goal is not ceremony for its own sake; the goal is repeatable software change with clearer meaning, fewer scattered rules, and less prompt-dependent behavior.
 
-這套 Skill 讓 AI 在開發過程中擔任**流程守衛（Workflow Guardian）**的角色。開發者不需要熟悉 SDD 或 DDD 的所有細節——AI 會在對的時機問對的問題，引導開發者自然地產出規格文件、領域模型、和技術債記錄。
+## Key Features
 
-適用場景：
-- 團隊導入 SDD/DDD 但成員經驗不一
-- 希望在開發過程中保持架構紀律
-- ASP.NET WebForms 專案準備遷移到 ASP.NET Core
-- 學習 DDD 並透過模擬專案練習
-
-## 目錄結構
+| Feature | What it gives engineering teams |
+|---|---|
+| **Spec-first development** | Every meaningful change starts from an explicit spec, acceptance behavior, and implementation plan before code changes begin. |
+| **Greenfield and Brownfield tracks** | Start clean in a new project, or introduce Dflow into an existing codebase through progressive domain extraction and safer incremental change. |
+| **Hybrid workflow control** | Command-first entry points for intentional work, auto-trigger checks as a safety net, and transparent phase gates so developers stay in control. |
+| **DDD semantic backbone** | Captures domain language, context boundaries, business rules, and model decisions so AI output is constrained by project meaning. |
+| **Three-layer documentation model** | Keeps short-lived phase deltas, feature snapshots, and system-level state separate, so specs stay useful instead of becoming one large document dump. |
+| **Drift verification** | Checks whether specs, domain documents, implementation, tests, and technical debt records still describe the same system. |
 
-```
-├── bin/                           # dflow CLI entrypoint
-├── lib/                           # init runtime implementation
-├── templates/                     # npm package template source
-├── test/                          # smoke tests
-├── tutorial/                      # 人讀教學劇本與範例 outputs
-├── planning/                      # handoff / contract / planning notes
-├── proposals/                     # Proposal 管理目錄
-├── reviews/                       # cross-round review reports and prompts
-├── sdd-ddd-webforms-skill/        # WebForms 版 Skill（英文，供 AI 使用）
-└── sdd-ddd-core-skill/            # ASP.NET Core 版 Skill（英文，供 AI 使用）
-```
+## Get Started
 
----
+Run Dflow from the root of the project you want to adopt it in:
 
-## 兩套 Skill 的差異
+```bash
+npx dflow-sdd-ddd init
+```
 
-| | WebForms Skill | Core Skill |
-|---|---|---|
-| **適用階段** | 目前：在運行中的 WebForms 專案開發 | 未來：ASP.NET Core 新專案 / 模擬練習 |
-| **架構** | Domain 層 + Code-Behind（兩層） | Clean Architecture 四層 |
-| **DDD 深度** | 準備性——術語表、Context 識別、基本抽離 | 完整戰術模式——Aggregate、Domain Events、CQRS |
-| **核心引導** | 「Code-Behind 盡量薄」 | 「每一層各司其職，業務邏輯只在 Domain」 |
-| **遷移意識** | 每次開發都產出可遷移的資產 | 從頭設計乾淨架構 |
-| **附加內容** | — | DDD 建模指南、Aggregate 設計工作表、模擬練習計畫 |
+The init flow asks whether the project is greenfield or brownfield, then previews the files it will create. Existing files are not overwritten.
 
----
+For a fixed global CLI:
 
-## WebForms Skill 檔案說明
+```bash
+npm install -g dflow-sdd-ddd
+dflow init
+```
 
-### SKILL.md — 主文件
-AI 的決策樹和核心規範。定義了五個核心原則、流程嚴謹度對照表、專案目錄結構、各階段引導問題、Domain 層規範。
+If the project is already initialized and you later add another AI coding
+tool, run:
 
-### references/ — 流程參考
-| 檔案 | 內容 |
-|---|---|
-| `init-project-flow.md` | `npx dflow-sdd-ddd init` 的 internal flow / manual fallback，定義 project bootstrap 問答和 scaffolding 行為 |
-| `new-feature-flow.md` | 新功能 8 步驟流程：需求理解 → Context 識別 → 概念發掘 → 撰寫規格 → 實作規劃 → 分支 → 實作 → 完成 |
-| `modify-existing-flow.md` | 修改既有功能流程，重點在趁機從 Code-Behind 抽離業務邏輯到 Domain 層 |
-| `new-phase-flow.md` | 在既有 feature 下新增 phase 的規格與實作流程 |
-| `finish-feature-flow.md` | 完成功能時的 drift 檢查、文件收斂與 tech-debt 收尾 |
-| `drift-verification.md` | 規格、模型、實作與文件間的 drift verification 檢查 |
-| `git-integration.md` | Git principles 與 SDD 階段對齊，每個 gate 有具體檢查項目 |
-| `pr-review-checklist.md` | PR 審查時的合規檢查和遷移準備度 A~F 評分 |
-
-### scaffolding/ — init 建立的基線文件
-| 檔案 | 用途 |
-|---|---|
-| `_overview.md` | Dflow-owned spec tree 的總覽 |
-| `_conventions.md` | 專案 convention，包含 `Prose Language` |
-| `Git-principles-*.md` | Git Flow / Trunk-Based Development 原則模板 |
+```bash
+dflow configure-agents
+```
 
-### templates/ — 模板
-| 檔案 | 用途 |
-|---|---|
-| `_index.md` | feature / phase 索引與 integration summary |
-| `phase-spec.md` | phase 級規格模板 |
-| `behavior.md` | Given/When/Then 行為規格模板 |
-| `lightweight-spec.md` | Bug 修復用的輕量規格模板 |
-| `context-definition.md` | 新 Bounded Context 定義模板 |
-| `CLAUDE.md` | init 用的 AI 協作規範模板來源；採用時由 `npx dflow-sdd-ddd init` 處理 |
-| `context-map.md`、`glossary.md`、`models.md`、`rules.md`、`tech-debt.md` | domain / migration 文件模板 |
+This command only configures AI instruction files. It does not rerun project
+initialization or touch existing specs.
 
----
+After init, start work through the Dflow workflow in your AI coding agent:
 
-## Core Skill 檔案說明
+```text
+/dflow:new-feature
+/dflow:modify-existing
+/dflow:bug-fix
+/dflow:new-phase
+/dflow:finish-feature
+/dflow:verify
+/dflow:pr-review
+```
 
-### SKILL.md — 主文件
-在 WebForms 版基礎上新增：Clean Architecture 四層架構圖、各層不可妥協的規範、DDD 戰術模式的引導問題。
+If your tool does not support custom slash commands, use the same command names as plain instructions in chat. Dflow is Markdown-based workflow material plus a scaffolding CLI, so it can be used with AI coding agents that can read project instructions and repository context.
 
-### references/ — 流程參考
-| 檔案 | 內容 |
-|---|---|
-| `init-project-flow.md` | `npx dflow-sdd-ddd init` 的 internal flow / manual fallback，定義 project bootstrap 問答和 scaffolding 行為 |
-| `new-feature-flow.md` | 新功能流程，新增逐層實作順序（Domain → Application → Infrastructure → Presentation） |
-| `modify-existing-flow.md` | 修改流程，新增 Aggregate 設計重新評估 |
-| `new-phase-flow.md` | 在既有 feature 下新增 phase 的規格與實作流程 |
-| `finish-feature-flow.md` | 完成功能時的 drift 檢查、文件收斂與 tech-debt 收尾 |
-| `drift-verification.md` | 規格、模型、實作與文件間的 drift verification 檢查 |
-| `ddd-modeling-guide.md` | **核心新增**：DDD 建模完整指南，涵蓋 Aggregate 設計規則、Value Object、Domain Events、Specification、Domain Service、Bounded Context 關係、常見錯誤 |
-| `git-integration.md` | Git principles 與 SDD 階段對齊，閘門檢查新增 Aggregate 設計和 Domain Events |
-| `pr-review-checklist.md` | PR 審查，四層各自的檢查項目 |
-
-### scaffolding/ — init 建立的基線文件
-| 檔案 | 用途 |
-|---|---|
-| `_overview.md` | Dflow-owned spec tree 的總覽 |
-| `_conventions.md` | 專案 convention，包含 `Prose Language` |
-| `architecture-decisions-README.md` | architecture decisions 目錄說明 |
-| `Git-principles-*.md` | Git Flow / Trunk-Based Development 原則模板 |
+## Project Tracks
 
-### templates/ — 模板
-| 檔案 | 用途 |
-|---|---|
-| `_index.md` | feature / phase 索引與 integration summary |
-| `phase-spec.md` | phase 級規格模板，支援 Domain Events 和逐層實作計畫 |
-| `behavior.md` | Given/When/Then 行為規格模板 |
-| `lightweight-spec.md` | 輕量規格模板 |
-| `context-definition.md` | Bounded Context 定義模板 |
-| `aggregate-design.md` | **核心新增**：Aggregate 設計工作表（不變條件、狀態變更方法、Events、引用關係） |
-| `CLAUDE.md` | init 用的 AI 協作規範模板來源；採用時由 `npx dflow-sdd-ddd init` 處理 |
-| `events.md`、`context-map.md`、`glossary.md`、`models.md`、`rules.md`、`tech-debt.md` | domain / architecture 文件模板 |
-
-### PRACTICE_PLAN_tw.md — 模擬練習計畫
-7 個 Phase 的 DDD 學習路線，使用費用報銷系統作為模擬專案，預估 15-22 小時：
-
-| Phase | 內容 | 學到的 DDD 概念 |
+| Track | Use it when | Main outcome |
 |---|---|---|
-| 1 | 建立基礎、識別 Bounded Context | Context Map、Ubiquitous Language |
-| 2 | 第一個 Aggregate + Value Objects | Aggregate Root、不變條件、Private Setter |
-| 3 | Domain Events | 事件驅動、最終一致性 |
-| 4 | 第二個 Aggregate + 跨 Aggregate 溝通 | Reference by ID、狀態機 |
-| 5 | CQRS + Application 層 | Command/Query 分離 |
-| 6 | Infrastructure 整合 | EF Core 設定、Repository、Event Dispatching |
-| 7 | 回顧 + Skill 檢視 | 流程改善 |
+| **Greenfield** | You are starting a new system or a new bounded area with room to shape architecture and domain model early. | Clean spec baseline, domain model ownership, feature-by-feature implementation through SDD. |
+| **Brownfield** | You are adding or changing behavior in an existing codebase where business rules may already be scattered. | Progressive domain extraction, safer change planning, and migration-ready domain knowledge. |
 
----
+These tracks describe adoption style, not framework branding. Dflow should be read as a workflow system for software teams that want AI assistance without giving up domain clarity.
 
-## How to adopt Dflow in your project
+## Workflow Model
 
-Dflow is the AI-guided SDD/DDD workflow contained in this repo (see `sdd-ddd-webforms-skill/` and `sdd-ddd-core-skill/`). In V1, project bootstrap is npm CLI first: the default entry is `npx dflow-sdd-ddd init`, which seeds `dflow/specs/` and keeps Dflow-owned documents under the `dflow/` namespace.
+Dflow uses a hybrid design:
 
-The npm package is published as `dflow-sdd-ddd` because the unscoped `dflow` package name is already occupied on npm. The installed CLI still exposes the `dflow` binary for global installs.
+| Layer | Purpose |
+|---|---|
+| **Command-first entry** | Developers intentionally start work with commands such as `/dflow:new-feature` or `/dflow:modify-existing`. |
+| **Auto-trigger safety net** | When the conversation clearly implies a feature, phase, bug fix, verification, or review, the AI should suggest the matching Dflow flow. |
+| **Transparency gates** | The AI announces flow entry, phase transitions, and important internal steps so the developer can approve direction before work expands. |
 
-Adopting Dflow in a project takes 4 steps:
+Dflow also scales ceremony by change risk:
 
-1. In your project root, run `npx dflow-sdd-ddd init`.
-2. Answer the intake questions. Dflow will ask for the edition, project context, optional starter files, and the required project prose language for generated spec content.
-3. Review the file-list preview and confirm the writes. Existing files are never overwritten.
-4. Start your first feature with `/dflow:new-feature`, or for an existing codebase, `/dflow:modify-existing` to work from an incoming change request.
+| Tier | Typical use | Expected weight |
+|---|---|---|
+| **T1 Lightweight** | Small bug fixes or narrow edits. | Minimal spec, focused verification. |
+| **T2 Standard** | Normal feature work. | Feature spec, behavior examples, implementation plan, finish checks. |
+| **T3 Full** | Cross-cutting changes, new bounded contexts, risky architecture work. | Full domain modeling, phase planning, broader drift verification, stronger review gates. |
 
-The generated baseline lives under `dflow/specs/`, for example `dflow/specs/shared/_conventions.md`, `dflow/specs/domain/glossary.md`, and `dflow/specs/features/active/`. The project AI guide is the one special root-level exception: `CLAUDE.md` stays at the project root so AI tools can discover it normally. If a root `CLAUDE.md` already exists, Dflow writes a mergeable snippet instead of overwriting it.
+The transparency gates and T1/T2/T3 tiers are related but separate: transparency controls how the AI communicates the workflow; tiers control how much specification and verification the change needs.
 
-Dflow keeps template structure stable in English: headings, table headers, labels, anchors, IDs, placeholders, file paths, and code-facing terms remain canonical English. Free prose inside those sections follows the project's `Prose Language` setting in `dflow/specs/shared/_conventions.md`.
+## Documentation Model
 
-Advanced usage: `npm install -g dflow-sdd-ddd` may be useful for users who want a fixed global CLI, then run `dflow init`. This is not the V1 default. `npm create dflow-sdd-ddd` is not implemented in V1 and remains a V2 evaluation item.
+Dflow separates documents by lifecycle:
 
-For what gets created at init time, how scaffolding templates are chosen, and how to re-run safely, see `sdd-ddd-webforms-skill/references/init-project-flow.md` (or the Core equivalent).
+| Layer | Shape | Purpose |
+|---|---|---|
+| **Phase Delta** | Short-lived phase spec. | Captures what this phase changes, why, and how it will be verified. |
+| **Feature Snapshot** | Feature-level summary and behavior. | Preserves the accepted behavior and implementation decisions after phases complete. |
+| **System State** | Shared domain and architecture documents. | Maintains durable knowledge such as glossary, context map, rules, models, conventions, and technical debt. |
+
+This keeps AI collaboration grounded. The phase layer gives the agent immediate execution context, the feature layer records what was delivered, and the system layer becomes the long-term source of truth for future prompts and reviews.
+
+## Files Created by Init
+
+A typical initialized project receives a `dflow/` workspace:
+
+```text
+dflow/
+  specs/
+    shared/
+      _overview.md
+      _conventions.md
+      Git-principles-*.md
+    domain/
+      glossary.md
+      context-map.md
+    architecture/
+      tech-debt.md
+    features/
+      active/
+      completed/
+```
 
-### V2 Starter Kit and Dflow — division of labour
+Dflow also creates or provides a mergeable project instruction file for your AI coding agent. The exact file depends on the target tool and existing project setup; Dflow avoids overwriting existing project instructions.
 
-Dflow is distributed alongside a sister project, **V2 Starter Kit** (`SDD-Starter-Kit`), which plays a complementary role:
+When you select AI agent setup during init, Dflow writes
+`dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical project guide, then
+creates small tool-specific shims that point back to it:
 
-| | V2 Starter Kit | Dflow (this repo) |
-|---|---|---|
-| **Format** | Complete distributable starter kit (flat files + tutorial docs) | AI-guided skill (read and executed by Claude Code at runtime) |
-| **Onboarding documents** | Ships full onboarding pack (e.g. `SDD-AI協作開發模式介紹.md`, `使用說明.md`) | Ships minimal scaffolding templates only (`scaffolding/`) |
-| **Primary audience** | Humans reading + copying files manually | AI running slash commands in a live project |
-| **Typical use** | Teams evaluating SDD/DDD or wanting a human-readable reference | Teams who want the workflow enforced at development time |
+| Tool target | Generated file |
+|---|---|
+| Codex / Copilot coding agent | `AGENTS.md` |
+| Claude Code | `CLAUDE.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
 
-The two are designed to coexist: you can start with V2's onboarding docs for reading/training, then adopt Dflow in the project itself for enforcement. Dflow's `scaffolding/` is intentionally a **minimal** template set; if you want the full V2 onboarding documents, copy them from V2 separately (V2's Tutorial rebuild is tracked as Closeout C2 of this repo's work plan).
+If one of those files already exists, Dflow leaves it unchanged and writes a
+merge snippet under `dflow/specs/shared/` instead. The project guide stays the
+single source of truth, so teams can use multiple AI tools without maintaining
+multiple copies of the workflow rules.
 
----
+You can run `dflow configure-agents` later to add more tool shims as the team
+adopts additional AI coding agents.
 
-## 如何使用
+## Main Flows
 
-### 在專案中採用 Dflow
+| Flow | When to use it | Typical outputs |
+|---|---|---|
+| `/dflow:new-feature` | A new user-visible capability or business behavior. | Feature spec, behavior examples, phase plan, domain updates. |
+| `/dflow:modify-existing` | A change to behavior already present in the system. | Impact analysis, updated specs, adjusted domain rules, migration notes when needed. |
+| `/dflow:bug-fix` | A defect where expected behavior can be stated narrowly. | Lightweight spec, reproduction, fix plan, regression check. |
+| `/dflow:new-phase` | A feature needs another implementation slice. | Phase delta, acceptance checks, focused implementation plan. |
+| `/dflow:finish-feature` | The implementation is done and needs closure. | Drift verification, feature snapshot, technical debt update, review checklist. |
+| `/dflow:verify` | You need confidence that docs and code still match. | Drift report across spec, domain docs, implementation, tests, and debt records. |
+| `/dflow:pr-review` | A change is ready for review. | SDD/DDD compliance review with risks, gaps, and follow-up items. |
 
-1. 在專案根目錄執行 `npx dflow-sdd-ddd init`
-2. 依提示選擇 edition、starter files、project prose language
-3. 預覽並確認寫入清單；Dflow 不會覆寫既有檔案
-4. 啟動 AI coding agent，從 `/dflow:new-feature` 或 `/dflow:modify-existing` 開始
+## Why DDD Matters More with AI
 
-### 在 Claude Code 中進行 DDD 模擬練習
+AI agents are strong at filling gaps. That is useful when the missing detail is mechanical, but risky when the missing detail is business meaning. If a prompt does not define the language, boundaries, and allowed behavior, the model may invent plausible rules that are hard to notice in review.
 
-1. 在練習專案根目錄執行 `npx dflow-sdd-ddd init`，選擇 Core edition
-2. 啟動 Claude Code，輸入：
-```
-我要開始一個 DDD 模擬練習專案：員工費用報銷系統（ExpenseTracker）。
-請依照 Skill 中定義的流程引導我，從 Phase 1 開始。
-```
+Dflow treats DDD as the semantic structure behind the spec. Ubiquitous language keeps names consistent. Bounded contexts keep meanings from leaking across areas. Domain rules define what is correct, allowed, or forbidden before implementation starts.
 
----
+In a code-first workflow, design often appears after the fact in classes, handlers, and tests. In an AI-assisted workflow, the spec must become the precondition for generation. The practical flow becomes:
 
-## 設計理念
+```text
+Domain meaning -> Structured spec -> AI implementation -> Code as output
+```
 
-### Spec Before Code（先規格、後程式碼）
-每一次程式碼變更都應該有對應的規格文件。規格不是額外的負擔，而是思考的工具——在寫程式之前先想清楚要做什麼。
+For a longer explanation, see [Why DDD Matters More with AI](docs/why-ddd-for-ai.md).
 
-### AI 作為流程守衛
-AI 不只是回答問題的工具，它主動引導開發流程：在你開分支前確認規格存在、在你寫 Code-Behind 時提醒業務邏輯應該在 Domain 層、在 PR 時檢查架構合規性。
+## Repository Layout
 
-### 漸進式 DDD
-不需要一次到位。WebForms 階段先累積術語表和領域知識，ASP.NET Core 階段再完整落地 DDD 戰術模式。現在寫的每一份規格和每一段 Domain 層程式碼，都是未來遷移的資產。
+| Path | Purpose |
+|---|---|
+| `bin/` | CLI entrypoint. |
+| `lib/` | Init runtime implementation. |
+| `templates/` | Files copied by the init command. |
+| `test/` | Smoke tests for generated output. |
+| `tutorial/` | Guided learning scenarios and expected outputs. |
+| `sdd-ddd-*-skill/` | Source workflow material consumed by AI coding agents. |
 
-### 三份資產
-每次開發循環都產出：**規格文件**（未來的需求文件）、**Domain 層程式碼**（可直接遷移）、**技術債記錄**（遷移指南）。
+## Status
 
----
+Dflow is currently published as `dflow-sdd-ddd` on npm. Version `0.1.0` focuses on project initialization, workflow documentation, and AI-agent-readable SDD/DDD guidance. Additional packaging for specific AI tools can be layered on top without changing the core workflow model.
 
-## 授權
+## License
 
 MIT License. See [LICENSE](LICENSE).

package/bin/dflow.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { runInit } = require('../lib/init');
+const { runConfigureAgents, runInit } = require('../lib/init');
 const pkg = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -9,11 +9,10 @@ function printHelp() {
   process.stdout.write(`Dflow CLI ${pkg.version}
 
 Usage:
-  dflow init       Initialize Dflow specs in the current project
-  dflow --help     Show this help
-  dflow --version  Show the CLI version
-
-Only the init subcommand is implemented in this version.
+  dflow init              Initialize Dflow specs in the current project
+  dflow configure-agents  Add or update AI agent instruction shims
+  dflow --help            Show this help
+  dflow --version         Show the CLI version
 `);
 }
 
@@ -22,8 +21,19 @@ function printInitHelp() {
   dflow init
 
 Initializes Dflow project specs under dflow/specs/.
-The command prompts for project type, edition, tech stack, prose language,
-and optional starter files before showing a full file preview.
+The command prompts for project type, tech stack, prose language,
+optional starter files, and AI coding agents before showing a full file preview.
+`);
+}
+
+function printConfigureAgentsHelp() {
+  process.stdout.write(`Usage:
+  dflow configure-agents
+
+Adds AI agent instruction files to an existing Dflow project.
+The command can create AGENTS.md, CLAUDE.md, GEMINI.md, and
+.github/copilot-instructions.md shims that point to the canonical
+dflow/specs/shared/AI-AGENT-GUIDE.md file.
 `);
 }
 
@@ -57,6 +67,25 @@ async function main() {
     });
   }
 
+  if (args[0] === 'configure-agents') {
+    if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
+      printConfigureAgentsHelp();
+      return 0;
+    }
+
+    if (args.length > 1) {
+      process.stderr.write(`Unsupported configure-agents option: ${args.slice(1).join(' ')}\n`);
+      return 1;
+    }
+
+    return await runConfigureAgents({
+      cwd: process.cwd(),
+      stdin: process.stdin,
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  }
+
   process.stderr.write(`Unsupported subcommand: ${args[0]}\n\n`);
   printHelp();
   return 1;

package/docs/why-ddd-for-ai.md

@@ -0,0 +1,35 @@
+# Why DDD Matters More with AI
+
+AI-assisted development changes the failure mode of software design. The team can produce more code faster, but unclear domain meaning is also amplified faster.
+
+When a project lacks shared language and explicit boundaries, small inconsistencies spread:
+
+- the same concept appears as `Order`, `Booking`, and `Transaction`
+- APIs encode different meanings for similar actions
+- business rules live in handlers, UI code, scripts, and tests
+- nobody can confidently say which behavior is authoritative
+
+An AI coding agent does not know the business domain by default. When the prompt is incomplete, it fills the missing parts with plausible logic. That logic may compile, pass superficial tests, and still be wrong. The most dangerous AI mistakes are often not syntax errors; they are reasonable-looking domain mistakes.
+
+DDD gives the spec a semantic backbone:
+
+| DDD idea | AI-era value |
+|---|---|
+| **Ubiquitous Language** | Keeps names and meanings stable across prompts, specs, code, and reviews. |
+| **Bounded Context** | Defines where a term or rule is valid, and prevents accidental meaning leaks. |
+| **Domain Model** | Gives behavior a clear owner instead of scattering rules across technical layers. |
+| **Domain Rules** | States what is correct, allowed, forbidden, and exceptional before code generation. |
+
+The important shift is where design lives. In older workflows, much of the real design could remain implicit in code. With AI, that is too late. The model needs constraints before it generates code.
+
+```text
+Without DDD:
+Prompt -> AI fills gaps -> Code -> Hidden domain drift
+
+With DDD:
+Domain meaning -> Structured spec -> AI implementation -> Reviewable code
+```
+
+Code still matters, but it is no longer the first place where meaning should be discovered. For AI collaboration, specs become the pre-generation contract, and DDD supplies the language, boundaries, and rules that make the contract precise.
+
+Dflow is built around that idea: spec first, domain meaning explicit, AI constrained before implementation, and drift checked before the work is considered done.