ai-dev-workflow

Original：🇨🇳 Chinese

Translated

Connect the complete AI development workflow through documents. It covers domain modeling and code organization (DDD), behavior verification and automated testing (BDD), as well as AI development specification setting (Agent specifications). Use when (1) the project has .feature files, (2) the user asks to organize code by business features or define naming conventions, (3) creating or updating AGENTS.md / project rule files, (4) writing or implementing Gherkin scenarios, (5) starting a new project from scratch, or (6) the agent needs the full development lifecycle.

3installs

Sourcecacaorick/skills

Added on2026-02-21

NPX Install

npx skill4agent add cacaorick/skills ai-dev-workflow

SKILL.md Content (Chinese)

View Translation Comparison →

AI Dev Workflow — Agent Skill

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

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: How to Produce Requirements and Specification Documents

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

Production Process

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

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

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's End-to-End Development Process

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

Phase 1: Understanding

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: Planning

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: Implementation Loop

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: Final Verification

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

Scenario Guidelines

A: New Project

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

B: Existing Documents, Build New Project from Scratch

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

B: Add New Features

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

C: Modify Existing Features

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

D: Fix Bugs

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

E: Refactoring

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

F: Delete Features

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

Development Principles

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

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                     ← 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