ai-dev-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Dev Workflow — Agent Skill

AI 根據 SPEC.md, AGENTS.md, features 中的 Gherkin .feature 文件，可以了解系統的全貌，並擁有行為驗證的能力

DDD（怎麼拆）→ BDD（做什麼 / 怎麼驗）→ Agent 規範（怎麼規範 AI）

AI can understand the full picture of the system and gain behavior verification capabilities based on the Gherkin .feature files in SPEC.md, AGENTS.md, and features

DDD (how to split) → BDD (what to do / how to verify) → Agent Specifications (how to standardize AI)

按需參考

Reference on Demand

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

需要組織程式碼結構或定義命名 → 讀 references/ddd.md
需要撰寫或實作 .feature → 讀 references/bdd.md
需要撰寫專案規範檔 → 讀 references/agent-rules.md

Read the corresponding reference according to the current task:

Need to organize code structure or define naming conventions → Read references/ddd.md
Need to write or implement .feature → Read references/bdd.md
Need to write project specification files → Read references/agent-rules.md

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

Part A: How to Produce Requirements and Specification Documents

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

The complete development process starts with documents. Written by the user, or produced after discussion with the Agent.

產出流程

Production Process

1. [DDD] 用業務思維切模組、定義命名，撰寫 SPEC.md
      ↓
2. [BDD] 按 DDD Bounded Context 和 Agent 合作撰寫 .feature 檔案（詳細行為規格）
      ↓
3. [規範] 將其餘 Agent 需要知道的需求與規範寫進 AGENTS.md（補充架構、UI 偏好與限制等）
      ↓
4. 全部交給 AI Agent

1. [DDD] Split modules with business thinking, define naming conventions, and write SPEC.md
      ↓
2. [BDD] Collaborate with the Agent to write .feature files (detailed behavior specifications) based on DDD Bounded Context
      ↓
3. [Specifications] Write other requirements and specifications that the Agent needs to know into AGENTS.md (supplementary architecture, UI preferences and restrictions, etc.)
      ↓
4. Hand over all documents to the AI Agent

各組成的定位

Positioning of Each Component

方法論	產出文件	解決什麼問題	詳細說明
DDD	SPEC.md 的「戰略設計」區塊	邊界、術語與溝通	references/ddd.md
BDD	features/*.feature	怎麼驗證做對了	references/bdd.md
補充說明	AGENTS.md 等專案規範檔	規範 AI 行為和實作細節	[references/agent-rules.md]

Methodology	Output Document	What Problem It Solves	Detailed Description
DDD	"Strategic Design" section of SPEC.md	Boundaries, terminology and communication	references/ddd.md
BDD	features/*.feature	How to verify correct implementation	references/bdd.md
Supplementary Notes	AGENTS.md and other project specification files	Standardize Agent behavior and implementation details	[references/agent-rules.md]

文件的增量更新

Incremental Update of Documents

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

Add new features → Add .feature
Modify features → Modify .feature
Delete features → Delete .feature + inform the Agent to clean up code
Architecture changes → Modify AGENTS.md

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

Part B: Agent's End-to-End Development Process

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

When the specification documents are ready, the Agent develops independently following the process below.

Phase 1：理解

Phase 1: Understanding

1. 讀取 SPEC.md
   → 產品全貌、技術架構、功能需求
   → 戰略設計（Bounded Context, Ubiquitous Language, Context Map）

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

3. 讀取 features/*.feature
   → 所有行為規格（可自動驗證的驗收標準）

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

1. Read SPEC.md
   → Product overview, technical architecture, functional requirements
   → Strategic Design (Bounded Context, Ubiquitous Language, Context Map)

2. Read project specification file AGENTS.md
   → Code style, architecture rules, testing requirements, prohibited items

3. Read features/*.feature
   → All behavior specifications (automatically verifiable acceptance criteria)

Do not write any code until all specification documents are read. If documents are missing, request the user to supplement them, or ask if help is needed to supplement.

Phase 2：規劃

Phase 2: Planning

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

4. Understand the specifications in AGENTS.md and plan the implementation method according to the requirements in the specifications
5. Understand the dependency relationship between Features to determine the implementation order

Phase 3：實作迴圈

Phase 3: Implementation Loop

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

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

The following verification commands are examples for Node.js / JavaScript projects. Please replace them with the corresponding commands specified in the SPEC.md and project specification files.

6. Select the next Feature
7. Implement Step Definitions (Cucumber)
8. Implement code to make the Scenario pass
9. Self-review (compliance with AGENTS.md specifications, edge cases, null checks, performance, a11y)
10. Execute verification:
    a. npx tsc --noEmit    → Fix type errors
    b. npx jest             → Fix unit tests
    c. npx cucumber-js      → Fix BDD tests
11. Failed → Analyze errors → Fix → Return to 10
12. Passed → Return to 6

Phase 4：最終驗證

Phase 4: Final Verification

13. 完整測試 suite（所有 Feature + 所有 Jest）
14. 確認零失敗
15. 回報結果

13. Complete test suite (all Features + all Jest tests)
14. Confirm zero failures
15. Report results

場景指南

Scenario Guidelines

A：全新專案

A: New Project

引導使用者完成 SPEC.md, AGENTS.md, features/*.features 文件

Guide the user to complete SPEC.md, AGENTS.md, features/*.features files

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

B: Existing Documents, Build New Project from Scratch

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

Phase 1 → Phase 2 Initialize project (follow tech stack in AGENTS.md) → Phase 3 → Phase 4 ...

B：新增功能

B: Add New Features

讀新 .feature → 實作 → 新舊 .feature 全部通過

Read new .feature → Implement → All old and new .features pass

C：修改既有功能

C: Modify Existing Features

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

All tests pass → Read modified .feature → Expected failure → Modify implementation → All tests pass

D：修復 Bug

D: Fix Bugs

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

New Scenario fails (reproduce Bug) → Fix → New Scenario passes + all tests pass

E：重構

E: Refactoring

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

All tests pass (baseline) → Refactor (no change to external behavior) → All tests still pass

F：刪除功能

F: Delete Features

使用者告知移除 → 刪 Step Definitions、程式碼、元件 → 剩餘測試全綠

User informs to remove → Delete Step Definitions, code, components → Remaining tests all pass

開發原則

Development Principles

DDD：明確劃分邊界 (Bounded Context)、統一命名 (Ubiquitous Language)、嚴格定義模組溝通 (Context Map)（詳見 references/ddd.md）
BDD：.feature 是驗收標準、新舊都要通過、BDD + TDD 分層（詳見 references/bdd.md）
規範：遵循 AGENTS.md 技術與偏好、不擅自加功能

DDD: Clearly define boundaries (Bounded Context), unify naming (Ubiquitous Language), strictly define module communication (Context Map) (see references/ddd.md for details)
BDD: .feature is the acceptance criteria, both old and new must pass, layered BDD + TDD (see references/bdd.md for details)
Specifications: Follow AGENTS.md technology and preferences, do not add features without permission

卡住時的處理

Handling When Stuck

症狀	處理方式
.feature 描述不清	回報使用者，請求釐清
修一個破另一個	向使用者提出重構建議
任務太大或太複雜	拆成更小的子任務

Symptom	Solution
Unclear .feature description	Report to user and request clarification
Fixing one breaks another	Propose refactoring suggestion to user
Task is too large or complex	Split into smaller subtasks

完整專案結構

Complete Project Structure

my-project/
├── SPEC.md                     ← 產品規格（Part A 產出）
├── AGENTS.md                   ← 專案與 Agent 規範（Part A 產出）
├── features/
│   ├── [context]/
│   │   ├── [feature].feature   ← BDD .feature（Part A 產出）
│   │   └── [feature].steps.ts  ← Step Definitions（Agent 實作）
├── src/                        ← 原始碼（Agent 實作，按 Context 分）
│   ├── [context-1]/
│   ├── [context-2]/
│   ├── shared/
│   └── __tests__/              ← 單元測試（Agent 撰寫）
└── package.json

my-project/
├── SPEC.md                     ← Product Specification (Output of Part A)
├── AGENTS.md                   ← Project and Agent Specifications (Output of Part A)
├── features/
│   ├── [context]/
│   │   ├── [feature].feature   ← BDD .feature (Output of Part A)
│   │   └── [feature].steps.ts  ← Step Definitions (Implemented by Agent)
├── src/                        ← Source Code (Implemented by Agent, grouped by Context)
│   ├── [context-1]/
│   ├── [context-2]/
│   ├── shared/
│   └── __tests__/              ← Unit Tests (Written by Agent)
└── package.json