Verified:GitHub

migration-principles

Identify and guide stepwise migration of legacy code to clean architecture preserving contracts and enabling testable equivalence per step.

Updated Apr 9, 2026

Search Tags:#architecture #migration #refactor #legacy #stepwise #ports-adapters #anti-corruption

Ready to run

npx skills add https://github.com/SergeuMatyasov/dotnet-shared-skills --skill migration-principles

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: migration-principles
Source: https://github.com/SergeuMatyasov/dotnet-shared-skills/tree/main/migration-principles
Command: npx skills add https://github.com/SergeuMatyasov/dotnet-shared-skills --skill migration-principles

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Legacy migrations often cause behavior drift and risky long rewrites. This guide provides a safe, controlled approach to moving code to a clean architecture without changing external behavior.

Core Features & Use Cases

Stepwise migration with explicit domain, application, and infrastructure boundaries.
Use of ports, adapters, and anti-corruption layers to preserve contracts.
Clear, testable milestones with risk and equivalence checks before moving to the next step.

Quick Start

Begin by cataloging current behavior, identifying the smallest migratable step, and documenting explicit acceptance criteria.

Frequently Asked Questions about migration-principles

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I migrate legacy code to a clean architecture without changing behavior?▼

Migrate legacy code safely by taking a stepwise approach that separates domain, application, and infrastructure while preserving contracts. You catalog current behavior, identify the smallest migratable step, and verify testable equivalence before proceeding.

What is an anti-corruption layer and when do I need it for a legacy refactor?▼

An anti-corruption layer preserves external contracts during a legacy refactor by isolating new clean architecture boundaries from old code. You need it when migrating modules or services to prevent behavior drift and ensure testable equivalence at each milestone.

How to use ports and adapters to separate domain logic during a stepwise migration?▼

Use ports and adapters to enforce explicit separation of concerns, isolating domain logic and application orchestration from infrastructure. This structured migration approach establishes clear boundaries, allowing you to verify risk and equivalence checks at each step.

What's the best way to prevent behavior drift when rewriting legacy services?▼

The best way to prevent behavior drift during a legacy rewrite is to define explicit acceptance criteria and perform testable equivalence checks after each stepwise migration milestone. This controlled approach avoids risky long rewrites by validating behavior continuously.

Can I use a stepwise migration approach for entire architectures or only individual modules?▼

You can use this stepwise migration approach for both individual modules and entire architectures. It applies to any project where domain logic, application orchestration, and infrastructure must be separated, allowing you to identify the smallest migratable step regardless of scale.

Why does a full legacy rewrite often cause behavior drift and risky delays?▼

A full legacy rewrite causes behavior drift and delays because it lacks controlled, testable milestones. A stepwise migration with explicit boundaries and risk checks after each step ensures equivalence is maintained throughout the transition.