/moai-workflow-ddd

name: moai-workflow-ddd
description: >
  Domain-Driven Development workflow specialist using ANALYZE-PRESERVE-IMPROVE
  cycle for behavior-preserving code transformation. Use when refactoring
  legacy code or reducing technical debt safely.
license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Write, Edit, Bash(git:*), Bash(pytest:*), Bash(ruff:*), Bash(npm:*), Bash(npx:*), Bash(node:*), Bash(uv:*), Bash(make:*), Bash(cargo:*), Bash(go:*), Bash(mix:*), Bash(bundle:*), Grep, Glob
user-invocable: false
metadata:
  version: "1.0.0"
  category: "workflow"
  status: "active"
  updated: "2026-01-16"
  modularized: "true"
  tags: "workflow, refactoring, ddd, domain-driven, behavior-preservation, ast-grep, characterization-tests"
  author: "MoAI-ADK Team"
  related-skills: "moai-workflow-testing, moai-foundation-quality"

Domain-Driven Development (DDD) Workflow

Development Mode Configuration (CRITICAL)

[NOTE] This workflow is selected based on `.moai/config/sections/quality.yaml`:

constitution:
  development_mode: ddd    # or tdd

**When to use this workflow**:

• `development_mode: ddd` → Use DDD (this workflow)
• `development_mode: tdd` → Use TDD instead (moai-workflow-tdd)

**Key distinction**:

• **DDD**: Characterization-test-first for existing codebases with minimal test coverage
• **TDD** (default): Test-first development for all work, including brownfield projects with pre-RED analysis

Quick Reference

Domain-Driven Development provides a systematic approach for refactoring existing codebases where behavior preservation is paramount. Unlike TDD which creates new functionality, DDD improves structure without changing behavior.

Core Cycle - ANALYZE-PRESERVE-IMPROVE:

• ANALYZE: Domain boundary identification, coupling metrics, AST structural analysis
• PRESERVE: Characterization tests, behavior snapshots, test safety net verification
• IMPROVE: Incremental structural changes with continuous behavior validation

When to Use DDD:

• Refactoring legacy code with existing tests
• Improving code structure without functional changes
• Technical debt reduction in production systems
• API migration and deprecation handling
• Code modernization projects
• Greenfield projects (with adapted cycle - see below)

When NOT to Use DDD:

• When behavior changes are required (modify SPEC first)
• When the code already exists and the goal is behavior change rather than behavior-preserving refactoring (DDD preserves behavior; for new behavior, modify the SPEC first, or use TDD)

Greenfield Project Adaptation:

For new projects without existing code, DDD adapts its cycle:

• ANALYZE: Requirements analysis instead of code analysis
• PRESERVE: Define intended behavior through specification tests (test-first)
• IMPROVE: Implement code to satisfy the defined tests

This makes DDD a superset of TDD - it includes TDD's test-first approach while also supporting refactoring scenarios.

---

Core Philosophy

DDD vs TDD Comparison

TDD Approach (for new features):

• Cycle: RED-GREEN-REFACTOR
• Goal: Create new functionality through tests
• Starting Point: No code exists
• Test Type: Specification tests that define expected behavior
• Outcome: New working code with test coverage

DDD Approach (for refactoring):

• Cycle: ANALYZE-PRESERVE-IMPROVE
• Goal: Improve structure without behavior change
• Starting Point: Existing code with defined behavior
• Test Type: Characterization tests that capture current behavior
• Outcome: Better structured code with identical behavior

Behavior Preservation Principle

The golden rule of DDD is that observable behavior must remain identical before and after refactoring. This means:

• All existing tests must pass unchanged
• API contracts remain identical
• Side effects remain identical
• Performance characteristics remain within acceptable bounds

---

Implementation Guide

Phase 1: ANALYZE

The analyze phase focuses on understanding the current codebase structure and identifying refactoring opportunities.

Domain Boundary Identification

Identify logical boundaries in the codebase by examining:

• Module dependencies and import patterns
• Data flow between components
• Shared state and coupling points
• Public API surfaces

Use AST-grep to analyze structural patterns. For Python, search for import patterns to understand module dependencies. For class hierarchies, analyze inheritance relationships and method distributions.

Coupling and Cohesion Metrics

Evaluate code quality metrics:

• Afferent Coupling (Ca): Number of classes depending on this module
• Efferent Coupling (Ce): Number of classes this module depends on
• Instability (I): Ce / (Ca + Ce) - higher means less stable
• Abstractness (A): Abstract classes / Total classes
• Distance from Main Sequence: |A + I - 1|

Low cohesion and high coupling indicate refactoring candidates.

Structural Analysis Patterns

Use AST-grep to identify problematic patterns:

• God classes with too many methods or responsibilities
• Feature envy where methods use other class data excessively
• Long parameter lists indicating missing abstractions
• Duplicate code patterns across modules

Create analysis reports documenting:

• Current architecture overview
• Identified problem areas with severity ratings
• Proposed refactoring targets with risk assessment
• Dependency graphs showing coupling relationships

Phase 2: PRESERVE

The preserve phase establishes safety nets before making any changes.

Characterization Tests

Characterization tests capture existing behavior without assumptions about correctness. The goal is to document what the code actually does, not what it should do.

Steps for creating characterization tests:

• Step 1: Identify critical code paths through execution
• Step 2: Create tests that exercise these paths
• Step 3: Let tests fail initially to discover actual output
• Step 4: Update tests to expect actual output
• Step 5: Docume