moai-workflow-ddd

# Domain-Driven Development (DDD) Workflow

## Development Mode Configuration (CRITICAL)

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

```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
- When DDD is not applicable because code already exists
- Greenfield projects (with adapted cycle - see below)

When NOT to Use DDD:

- When behavior changes are required (modify SPEC first)

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: Document any surprising behavior discovered

Characterization test naming convention: test*characterize*[component]\_[scenario]

#### Behavior Snapshots

For complex outputs, use snapshot testing to capture current behavior:

- API response snapshots
- Serialization output snapshots
- State transformation snapshots
- Error message snapshots

Snapshot files serve as behavior contracts during refactoring.

#### Test Safety Net Verification

Before proceeding to improvement phase, verify:

- All existing tests pass (100% green)
- New characterization tests cover refactoring targets
- Code coverage meets threshold for affected areas
- No flaky tests exist in the safety net

Run mutation testing if available to verify test effectiveness.

### Phase 3: IMPROVE

The improve phase makes structural changes while continuously validating behavior preservation.

#### Incremental Transformation Strategy

Never make large changes at once. Follow this pattern:

- Make smallest possible structur