AI Dev Workflow — Agent Skill

AI 根據 SPEC.md, DOMAIN-MODEL.md, AGENTS.md，可以了解系統的全貌，並根據對應的測試框架進行行為驗證

DDD（怎麼拆）→ Agent 規範（怎麼規範 AI）

注意：若需要 DDD 戰略設計（Domain Model），請先呼叫 skill: ddd。 若專案使用 BDD (.feature 文件)，請先呼叫 skill: bdd 處理 BDD 流程。

按需參考

根據當前任務讀取對應的 reference：

• 需要 DDD 戰略設計 → 呼叫 skill: ddd（產出 DOMAIN-MODEL.md）
• 需要 BDD (.feature, Gherkin, Step Definitions) → 呼叫 skill: bdd
• 需要撰寫專案規範檔 → 讀 references/agent-rules.md

Part A：如何產出需求與規範文件

完整的開發流程從文件開始。由使用者撰寫，或與 Agent 討論後產出。

產出流程

1. [DDD] 呼叫 skill: ddd 產出 DOMAIN-MODEL.md（領域建模）
      ↓
2. [BDD] 呼叫 skill: bdd 撰寫 .feature 檔案（詳細行為規格）
      ↓
3. [規範] 將其餘 Agent 需要知道的需求與規範寫進 AGENTS.md（補充架構、UI 偏好與限制等）
      ↓
4. 全部交給 AI Agent

各組成的定位

文件的增量更新

新增功能 → 新增 .feature
修改功能 → 修改 .feature
刪除功能 → 刪除 .feature + 告知 Agent 清理程式碼
架構異動 → 修改 AGENTS.md

Part B：Agent 的端到端開發流程

當規格文件已就緒，Agent 按以下流程自主開發。

Phase 1：理解

1. 讀取 DOMAIN-MODEL.md
   → 領域模型（Bounded Context, Ubiquitous Language, Context Map）

2. 讀取 SPEC.md
   → 產品全貌、技術架構、功能需求

3. 讀取專案規範檔 AGENTS.md
   → 程式碼風格、架構規則、測試要求、禁止事項

在讀完所有規格文件之前，不要寫任何程式碼。 若文件有缺漏，要求使用者補充文件，或詢問是否需要幫忙補充。

Phase 2：規劃

4. 理解 AGENTS.md 中的規範，依照規範中的要求規劃實作方式
5. 理解 Feature 間的依賴關係決定實作順序

Phase 3：實作迴圈

以下驗證指令以 Node.js / JavaScript 專案為例，請依照 SPEC.md 和專案規範檔中指定的測試工具替換對應指令。

6. 選擇下一個待實作的功能
7. 實作讓功能通過的程式碼
8. 自我審查（符合 AGENT.md 規範、邊界情況、null 檢查、效能、a11y）
9. 執行驗證：
    a. npx tsc --noEmit    → 修復型別錯誤
    b. npx jest             → 修復單元測試
10. 失敗 → 分析錯誤 → 修復 → 回到 9
11. 通過 → 回到 6

若有 BDD 測試 (.feature)，呼叫 skill: bdd 執行驗證。

Phase 4：最終驗證

12. 完整測試 suite（單元測試 + BDD 測試若有）
13. 確認零失敗
14. 回報結果

場景指南

A：全新專案

引導使用者完成 SPEC.md, AGENTS.md，若需要 BDD 則呼叫 skill: bdd

B：已有文件，從 0 開始建立新專案

Phase 1 → Phase 2 初始化專案（按 AGENTS.md 技術棧）→ Phase 3 → Phase 4 ...

C：新增功能

讀新需求 → 實作 → 測試通過

D：修改既有功能

全部測試全綠 → 讀修改後的需求 → 預期失敗 → 改實作 → 全綠

E：修復 Bug

新測試 fail（重現 Bug）→ 修復 → 新測試 pass + 全綠

F：重構

全綠（基線）→ 重構（不改外部行為）→ 仍然全綠

開發原則

• DDD：明確劃分邊界 (Bounded Context)、統一命名 (Ubiquitous Language)、嚴格定義模組溝通 (Context Map)（詳見 skill: ddd，實作時需持續檢查是否符合）
• BDD：若專案使用 BDD，呼叫 skill: bdd 處理 .feature 和 Step Definitions
• 規範：遵循 AGENTS.md 技術與偏好、不擅自加功能

卡住時的處理

完整專案結構

my-project/
├── DOMAIN-MODEL.md            ← 領域模型（由 skill: ddd 產出）
├── SPEC.md                    ← 產品規格（Part A 產出）
├── AGENTS.md                  ← 專案與 Agent 規範（Part A 產出）
├── features/                  ← BDD 測試（由 skill: bdd 處理）
│   └── ...
├── src/                       ← 原始碼（Agent 實作，按 Context 分）
│   ├── [context-1]/
│   ├── [context-2]/
│   ├── shared/
│   └── __tests__/             ← 單元測試（Agent 撰寫）
└── package.json

若要了解 DDD 戰略設計，請參考 skill: ddd 若要了解 BDD 檔案結構，請參考 skill: bdd