moai-workflow-ddd

Behavior-preserving refactoring uses a structured ANALYZE-PRESERVE-IMPROVE cycle with AST-grep analysis and characterization tests to validate behavior after each incremental structural change. This ensures public API contracts remain intact while reducing technical debt across complex modules.

The best way to migrate APIs safely is applying an incremental transformation workflow with safety nets, ensuring existing tests validate behavior preservation throughout the migration. This structured approach targets safe changes across complex modules without breaking observable functionality.

Characterization tests function as safety nets during refactoring by capturing and validating the current observable behavior of legacy code before structural changes begin. They run after each incremental transformation to confirm the public API contracts and existing behavior remain completely intact.

AST-grep is needed when analyzing mature codebases for structured refactoring, as it provides domain boundary analysis to target safe structural changes across complex modules. It identifies specific code patterns to transform incrementally while maintaining behavior preservation safety nets.

This structured refactoring workflow is designed specifically for mature codebases with existing tests requiring safe structural changes. Without existing tests to act as safety nets, validating behavior preservation during incremental transformations would not be reliably possible.

The main limitation is that behavior-preserving refactoring maintains existing public API contracts, meaning it cannot intentionally change observable functionality. It focuses strictly on structural improvements and debt reduction, relying heavily on existing tests to catch any accidental behavioral deviations.