Menu
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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Intent-First design craft specialist covering design direction, domain vocabulary, design memory, and post-build critique. Use when establishing design intent or auditing code against design principles.
Design tool integration specialist covering Figma MCP, Pencil renderer, and Pencil-to-code export. Use when fetching design context from Figma, rendering Pencil designs, or exporting to React/Tailwind code.
Documentation generation patterns for technical specs, API docs, user guides, and knowledge bases using real tools like Sphinx, MkDocs, TypeDoc, and Nextra. Use when creating docs from code, building doc sites, or automating documentation workflows.
Backend development specialist covering API design, database integration, microservices architecture, and modern backend patterns. Use when designing APIs, implementing server logic, authentication, or authorization.
Brand-aligned visual design system specialist for web projects. Enforces hero-first layout chaining, WCAG 2.1 AA accessibility, Lighthouse >= 80, and design token extraction from brand identity files. Covers color palettes, typography, spacing, and component specifications.
Brand-aligned copywriting specialist for marketing and product text. Enforces brand voice, anti-AI-slop rules, concrete numbers, and JSON section structure for downstream agent consumption. Covers hero, features, social_proof, cta, and footer sections with A/B variant output.
| 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, mcp__context7__resolve-library-id, mcp__context7__get-library-docs |
| 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","context":"fork","agent":"manager-ddd","related-skills":"moai-tool-ast-grep, moai-workflow-testing, moai-foundation-quality"} |
[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:
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:
When to Use DDD:
When NOT to Use DDD:
Greenfield Project Adaptation:
For new projects without existing code, DDD adapts its cycle:
This makes DDD a superset of TDD - it includes TDD's test-first approach while also supporting refactoring scenarios.
TDD Approach (for new features):
DDD Approach (for refactoring):
The golden rule of DDD is that observable behavior must remain identical before and after refactoring. This means:
The analyze phase focuses on understanding the current codebase structure and identifying refactoring opportunities.
Identify logical boundaries in the codebase by examining:
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.
Evaluate code quality metrics:
Low cohesion and high coupling indicate refactoring candidates.
Use AST-grep to identify problematic patterns:
Create analysis reports documenting:
The preserve phase establishes safety nets before making any changes.
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:
Characterization test naming convention: testcharacterize[component]_[scenario]
For complex outputs, use snapshot testing to capture current behavior:
Snapshot files serve as behavior contracts during refactoring.
Before proceeding to improvement phase, verify:
Run mutation testing if available to verify test effectiveness.
The improve phase makes structural changes while continuously validating behavior preservation.
Never make large changes at once. Follow this pattern:
Extract Method: When a code block can be named and isolated. Use AST-grep to identify candidates by searching for repeated code blocks or long methods.
Extract Class: When a class has multiple responsibilities. Move related methods and fields to a new class while maintaining the original API through delegation.
Move Method: When a method uses data from another class more than its own. Relocate while preserving all call sites.
Inline Refactoring: When indirection adds complexity without benefit. Replace delegation with direct implementation.
Rename Refactoring: When names do not reflect current understanding. Update all references atomically using AST-grep rewrite.
Use AST-grep for safe, semantic-aware transformations:
For method extraction, create a rule that identifies the code pattern and rewrites to the extracted form.
For API migration, create a rule that matches old API calls and rewrites to new API format.
For deprecation handling, create rules that identify deprecated patterns and suggest modern alternatives.
After each transformation:
When executing DDD through moai:2-run in DDD mode:
Step 1 - Initial Assessment:
Step 2 - Analyze Phase Execution:
Step 3 - Preserve Phase Execution:
Step 4 - Improve Phase Execution:
Step 5 - Validation and Completion:
For complex refactoring requiring multiple iterations:
Behavior Preservation (Required):
Structure Improvement (Goals):
Apply TRUST 5 framework with DDD focus:
DDD relies heavily on AST-grep for:
Load moai-tool-ast-grep for detailed pattern syntax and rule creation.
DDD complements testing workflow:
DDD outputs feed into quality assessment:
Tests Fail After Transformation:
Characterization Tests Are Flaky:
Performance Degradation:
When DDD session encounters issues:
Version: 1.0.0 Status: Active Last Updated: 2026-01-16
| Rationalization | Reality |
|---|---|
| "This legacy code is obviously broken, I will just rewrite it" | The broken-looking code may encode production behavior callers depend on. ANALYZE first, rewrite with tests. |
| "Characterization tests are just busywork" | They are the safety net that lets you refactor without fear. Without them, refactor equals rewrite. |
| "I understand this module well enough to skip ANALYZE" | Understanding is not verification. ANALYZE forces you to name assumptions and confront callers. |
| "This function has no tests because it has no behavior worth testing" | If it has callers, it has contract. The contract is the thing to characterize. |
| "I will preserve behavior by being careful" | Carefulness is not a mechanism. Tests are the only mechanism that catches regressions. |
| "This refactor is too small to need DDD" | Small refactors cause silent regressions exactly because people skip the safety net. |
Chesterton's Fence: Do not remove or replace code whose purpose you cannot explain. ANALYZE phase exists specifically to uncover the reasoning behind code that looks wrong.