Back to Details

moai-workflow-ddd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Domain-Driven Development (DDD) Workflow

Domain-Driven Development (DDD) 工作流

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.
Domain-Driven Development为重构现有代码库提供了系统化方法，其中行为保留是重中之重。与用于创建新功能的TDD不同，DDD在不改变行为的前提下改进代码结构。
核心循环 - ANALYZE-PRESERVE-IMPROVE：
  • ANALYZE：领域边界识别、耦合度指标、AST结构分析
  • PRESERVE：特征测试、行为快照、测试安全网验证
  • IMPROVE：持续行为验证下的增量结构变更
适用DDD的场景：
  • 重构带有现有测试的遗留代码
  • 在不改变功能的前提下改进代码结构
  • 降低生产系统中的技术债务
  • API迁移与弃用处理
  • 代码现代化项目
  • 代码已存在时（此时不适用其他全新开发流程）
  • 全新项目（需适配循环流程，见下文）
不适用DDD的场景：
  • 需要改变行为时（需先修改SPEC）
全新项目适配方案：
针对无现有代码的新项目，DDD可调整其循环流程：
  • ANALYZE：需求分析（替代代码分析）
  • PRESERVE：通过规范测试定义预期行为（测试先行）
  • IMPROVE：实现代码以满足定义的测试要求
这使得DDD成为TDD的超集——它包含了TDD的测试先行方法，同时也支持重构场景。

Core Philosophy

核心理念

DDD vs TDD Comparison

DDD与TDD对比

DDD 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
DDD方法（针对新功能）：
  • 循环：RED-GREEN-REFACTOR
  • 目标：通过测试创建新功能
  • 起点：无现有代码
  • 测试类型：定义预期行为的规范测试
  • 结果：带有测试覆盖率的可运行新代码
DDD方法（针对重构）：
  • 循环：ANALYZE-PRESERVE-IMPROVE
  • 目标：在不改变行为的前提下改进结构
  • 起点：带有既定行为的现有代码
  • 测试类型：捕获当前行为的特征测试
  • 结果：结构更优但行为完全一致的代码

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
DDD的黄金准则是：重构前后的可观察行为必须完全一致。这意味着：
  • 所有现有测试必须无修改通过
  • API契约保持完全一致
  • 副作用保持完全一致
  • 性能特征保持在可接受范围内

Implementation Guide

实施指南

Phase 1: ANALYZE

阶段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.
通过检查以下内容识别代码库中的逻辑边界：
  • 模块依赖与导入模式
  • 组件间的数据流
  • 共享状态与耦合点
  • 公共API表面
使用AST-grep分析结构模式。对于Python，可搜索导入模式以理解模块依赖；对于类层次结构，可分析继承关系与方法分布。

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.
评估代码质量指标：
  • 传入耦合度（Ca）：依赖此模块的类数量
  • 传出耦合度（Ce）：此模块依赖的类数量
  • 不稳定性（I）：Ce / (Ca + Ce) —— 值越高表示稳定性越差
  • 抽象性（A）：抽象类数量 / 总类数量
  • 主序列距离：|A + I - 1|
低内聚度与高耦合度的模块是重构候选对象。

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
使用AST-grep识别有问题的模式：
  • 包含过多方法或职责的上帝类
  • 方法过度使用其他类数据的特性羡慕问题
  • 表示缺少抽象的长参数列表
  • 跨模块的重复代码模式
创建分析报告，记录：
  • 当前架构概述
  • 带有严重程度评级的已识别问题区域
  • 带有风险评估的拟议重构目标
  • 展示耦合关系的依赖图

Phase 2: PRESERVE

阶段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: testcharacterize[component]_[scenario]
特征测试捕获现有行为，不做正确性假设。目标是记录代码实际的行为，而非它应该有的行为。
创建特征测试的步骤：
  • 步骤1：通过执行识别关键代码路径
  • 步骤2：创建测试以覆盖这些路径
  • 步骤3：让测试初始失败以发现实际输出
  • 步骤4：更新测试以预期实际输出
  • 步骤5：记录发现的任何意外行为
特征测试命名规范：testcharacterize[组件]_[场景]

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.
对于复杂输出，使用快照测试捕获当前行为：
  • API响应快照
  • 序列化输出快照
  • 状态转换快照
  • 错误消息快照
快照文件在重构期间充当行为契约。

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.
进入改进阶段前，需验证：
  • 所有现有测试均通过（100% 绿色）
  • 新特征测试覆盖了重构目标
  • 受影响区域的代码覆盖率达到阈值
  • 安全网中不存在不稳定测试
若有可用工具，运行突变测试以验证测试的有效性。

Phase 3: IMPROVE

阶段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 structural change
  • Run full test suite
  • If tests fail, revert immediately
  • If tests pass, commit the change
  • Repeat until refactoring goal achieved
切勿一次性进行大规模变更。遵循以下模式：
  • 进行最小的结构变更
  • 运行完整测试套件
  • 若测试失败，立即回滚
  • 若测试通过，提交变更
  • 重复直至达成重构目标

Safe Refactoring Patterns

安全重构模式

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.
提取方法：当代码块可被命名并隔离时使用。使用AST-grep识别重复代码块或长方法作为候选对象。
提取类：当一个类承担多个职责时使用。将相关方法和字段移至新类，同时通过委托保持原API。
移动方法：当方法更多使用其他类的数据而非自身类数据时使用。迁移方法的同时保留所有调用点。
内联重构：当间接性增加复杂度却无收益时使用。用直接实现替代委托。
重命名重构：当名称无法反映当前认知时使用。使用AST-grep重写工具批量更新所有引用。

AST-Grep Assisted Transformations

AST-Grep辅助转换

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.
使用AST-grep进行安全的、语义感知的转换：
  • 对于方法提取，创建规则识别代码模式并重写为提取后的形式。
  • 对于API迁移，创建规则匹配旧API调用并重写为新API格式。
  • 对于弃用处理，创建规则识别已弃用模式并建议现代替代方案。

Continuous Validation Loop

持续验证循环

After each transformation:
  • Run unit tests (fast feedback)
  • Run integration tests (behavior validation)
  • Run characterization tests (snapshot comparison)
  • Verify no new warnings or errors introduced
  • Check performance benchmarks if applicable
每次转换后：
  • 运行单元测试（快速反馈）
  • 运行集成测试（行为验证）
  • 运行特征测试（快照对比）
  • 验证未引入新的警告或错误
  • 若适用，检查性能基准

DDD Workflow Execution

DDD工作流执行

Standard DDD Session

标准DDD会话

When executing DDD through moai:2-run in DDD mode:
Step 1 - Initial Assessment:
  • Read SPEC document for refactoring scope
  • Identify affected files and components
  • Assess current test coverage
Step 2 - Analyze Phase Execution:
  • Run AST-grep analysis on target code
  • Generate coupling and cohesion metrics
  • Create domain boundary map
  • Document refactoring opportunities
Step 3 - Preserve Phase Execution:
  • Verify all existing tests pass
  • Create characterization tests for uncovered paths
  • Generate behavior snapshots
  • Confirm safety net adequacy
Step 4 - Improve Phase Execution:
  • Execute transformations incrementally
  • Run tests after each change
  • Commit successful changes immediately
  • Document any discovered issues
Step 5 - Validation and Completion:
  • Run full test suite
  • Compare before/after metrics
  • Verify all behavior snapshots match
  • Generate refactoring report
通过moai:2-run以DDD模式执行DDD时：
步骤1 - 初始评估：
  • 阅读SPEC文档了解重构范围
  • 识别受影响的文件与组件
  • 评估当前测试覆盖率
步骤2 - 分析阶段执行：
  • 对目标代码运行AST-grep分析
  • 生成耦合度与内聚度指标
  • 创建领域边界图
  • 记录重构机会
步骤3 - 保留阶段执行：
  • 验证所有现有测试通过
  • 为未覆盖路径创建特征测试
  • 生成行为快照
  • 确认安全网足够可靠
步骤4 - 改进阶段执行：
  • 增量执行转换
  • 每次变更后运行测试
  • 立即提交成功的变更
  • 记录发现的任何问题
步骤5 - 验证与完成：
  • 运行完整测试套件
  • 对比变更前后的指标
  • 验证所有行为快照匹配
  • 生成重构报告

DDD Loop Pattern

DDD循环模式

For complex refactoring requiring multiple iterations:
  • Set maximum loop iterations based on scope
  • Each loop focuses on one refactoring target
  • Exit conditions: all targets adddessed or iteration limit reached
  • Progress tracking through TODO list updates
针对需要多次迭代的复杂重构：
  • 根据范围设置最大循环迭代次数
  • 每个循环专注于一个重构目标
  • 退出条件：所有目标完成或达到迭代上限
  • 通过更新TODO列表跟踪进度

Quality Metrics

质量指标

DDD Success Criteria

DDD成功标准

Behavior Preservation (Required):
  • All pre-existing tests pass
  • All characterization tests pass
  • No API contract changes
  • Performance within bounds
Structure Improvement (Goals):
  • Reduced coupling metrics
  • Improved cohesion scores
  • Reduced code complexity
  • Better separation of concerns
行为保留（必填）：
  • 所有预先存在的测试通过
  • 所有特征测试通过
  • 无API契约变更
  • 性能在可接受范围内
结构改进（目标）：
  • 耦合度指标降低
  • 内聚度得分提升
  • 代码复杂度降低
  • 关注点分离更清晰

DDD-Specific TRUST Validation

DDD专属TRUST验证

Apply TRUST 5 framework with DDD focus:
  • Testability: Characterization test coverage adequate
  • Readability: Naming and structure improvements verified
  • Understandability: Domain boundaries clearer
  • Security: No new vulnerabilities introduced
  • Transparency: All changes documented and traceable
针对DDD应用TRUST 5框架：
  • 可测试性：特征测试覆盖率足够
  • 可读性：命名与结构改进已验证
  • 可理解性：领域边界更清晰
  • 安全性：未引入新漏洞
  • 透明度：所有变更均已记录且可追溯

Integration Points

集成点

With AST-Grep Skill

与AST-Grep Skill集成

DDD relies heavily on AST-grep for:
  • Structural code analysis
  • Pattern identification
  • Safe code transformations
  • Multi-file refactoring
Load moai-tool-ast-grep for detailed pattern syntax and rule creation.
DDD严重依赖AST-grep实现：
  • 结构化代码分析
  • 模式识别
  • 安全代码转换
  • 多文件重构
加载moai-tool-ast-grep以获取详细的模式语法与规则创建方法。

With Testing Workflow

与测试工作流集成

DDD complements testing workflow:
  • Uses characterization tests from testing patterns
  • Integrates with mutation testing for safety net validation
  • Leverages snapshot testing infrastructure
DDD与测试工作流互补：
  • 使用测试模式中的特征测试
  • 集成突变测试以验证安全网
  • 利用快照测试基础设施

With Quality Framework

与质量框架集成

DDD outputs feed into quality assessment:
  • Before/after metrics comparison
  • TRUST 5 validation for changes
  • Technical debt tracking
DDD输出可用于质量评估：
  • 变更前后指标对比
  • 针对变更的TRUST 5验证
  • 技术债务跟踪

Troubleshooting

故障排除

Common Issues

常见问题

Tests Fail After Transformation:
  • Revert immediately to last known good state
  • Analyze which tests failed and why
  • Check if transformation changed behavior unintentionally
  • Consider smaller transformation steps
Characterization Tests Are Flaky:
  • Identify sources of non-determinism
  • Mock external dependencies
  • Fix time-dependent or order-dependent behavior
  • Consider snapshot tolerance settings
Performance Degradation:
  • Profile before and after
  • Identify hot paths affected by changes
  • Consider caching or optimization
  • Document acceptable trade-offs
转换后测试失败：
  • 立即回滚至最后已知的稳定状态
  • 分析测试失败的原因
  • 检查转换是否意外改变了行为
  • 考虑采用更小的转换步骤
特征测试不稳定：
  • 识别非确定性来源
  • 模拟外部依赖
  • 修复时间依赖或顺序依赖的行为
  • 考虑调整快照容差设置
性能下降：
  • 对比变更前后的性能分析结果
  • 识别受变更影响的热点路径
  • 考虑缓存或优化方案
  • 记录可接受的权衡

Recovery Procedures

恢复流程

When DDD session encounters issues:
  • Save current state with git stash
  • Reset to last successful commit
  • Review transformation that caused failure
  • Plan alternative approach
  • Resume from preserved state
Version: 1.0.0 Status: Active Last Updated: 2026-01-16
当DDD会话遇到问题时：
  • 使用git stash保存当前状态
  • 重置至最后一次成功提交
  • 回顾导致失败的转换
  • 规划替代方案
  • 从保留的状态恢复
版本：1.0.0 状态：活跃 最后更新：2026-01-16