Software migrations and modernization
Legacy and migrated code share one repository for the length of the project, and the legacy side is better represented. These essays cover why agents copy the architecture you are removing and what makes the distinction enforceable. See the migrations use case.
A migration is the one situation where following the surrounding code is the wrong instinct. For as long as the project runs, the repository demonstrates two architectures, and the one being removed is almost always the better represented of the two. An agent that infers house style by looking at what is already there will infer the architecture you are paying to eliminate, and it will do so while every individual change looks locally reasonable.
These essays cover why that happens, why better retrieval makes it worse rather than better, and what a decision corpus needs in order to describe a system in transition: states for legacy, target, transitional and superseded patterns, and path applicability so a rule can govern migrated modules while staying silent where migration has not reached.
If you want to see the enforcement path before reading the argument, the migration demo traces an agent copying the legacy pattern into a migrated module: denied there, and silently skipped in the legacy tree where the same pattern is still correct.
Why AI Coding Agents Copy Legacy Architecture During Migrations
The agent is not forgetting the plan. It is reading the repository correctly, and the repository is mostly the architecture you are removing.
ADRs for Software Migrations: Legacy, Target and Transitional Decisions
Classic ADR practice assumes one architecture at a time. A migration needs states that expire and decisions scoped to the paths they govern.
Strangler-Fig Migrations: Preventing Architectural Drift at the Boundary
A strangler migration works because only the adapter depends on the legacy system. Here is why agents break that guarantee, and how to stop them.
Why Codebase Memory Goes Stale During a Migration
A memory layer is most confident about the code you are removing and most out of date about the code you are moving toward, and cannot express which is which.
How to Encode Migration Guardrails for AI Coding Agents
Five path-scoped rules cover most migration guardrails an AI coding agent needs: persistence, adapter boundaries, freezes, deprecated APIs, legacy imports.
Architectural Drift During Cloud and Platform Migrations
AWS to Azure, VM to Kubernetes, monolith to services: five common platform migrations, and why each needs the same path-scoped decision as any other.
How AI Coding Agents Use ADRs (Architecture Decision Records)
The general case behind migration ADRs: whether records are ignored, advisory, or enforced, and how to make them executable.
Why Context Alone Doesn’t Prevent Architectural Drift
Better retrieval improves recall. During a migration it also strengthens the signal pointing at the architecture you are leaving.
Architecture Cannot Be a Prompt: What Context Compaction Silently Drops
Compaction keeps the task and drops the rule that governed it, which is why a migration plan in the prompt does not survive the project.