These best practices are extracted from real-world modernization projects across industries. They complement the ModernizeSpec specification (which describes what to document) with guidance on how to work during modernization.
Modernization is not a greenfield build. The existing system is running in production, users depend on it, and mistakes carry real consequences. These practices exist because teams learned the hard way what happens without them: broken migrations, silent regressions, scope creep, and wasted months.
Each practice stands on its own. Adopt what fits your team and project. Start with Quality Gates and Testing Strategy if you are just beginning a modernization effort — they provide the safety net everything else depends on.
Quality Gates
Standards that prevent bad code from reaching production. PR contracts, layered review, stacked PRs, and issue taxonomy.
Every change to a modernizing codebase needs structured review — the stakes are higher when legacy and modern code coexist.
Testing Strategy
How to test legacy and modern code in parallel. Test grades by criticality, parity testing, conservative assertions, and anti-patterns to avoid.
The test suite is the proof that modernization preserved behavior. Without it, “done” is just an opinion.
Incremental Development
Ship continuously, verify constantly. Small commits, trunk-based development, and the discipline of always-deployable main branches.
Large migrations fail when teams batch too many changes. Small, verified steps compound into successful delivery.
Agent Context
Structure information so AI coding agents can help effectively. AGENTS.md conventions, .agents/ directories, progressive disclosure, and token-efficient context.
AI agents are as good as the context they receive. Structured project context turns generic LLM capabilities into project-specific assistance.
Specification-Driven Planning
Plan before you build, especially for complex migrations. Spec structure, decision logs, scope boundaries, and the case for machine-readable specifications.
Migration decisions are hard to reverse. Specifications capture intent, align teams, and document decisions that would otherwise be lost.
ModernizeSpec defines the data model for modernization context — bounded contexts in domains.json, hotspots in complexity.json, sequencing in extraction-plan.json. These best practices define the development process that operates alongside that data.
ModernizeSpec files Best Practices(what to document) (how to work) \ / \ / v v Modernization Project (daily engineering)A team can adopt ModernizeSpec without these practices, and vice versa. Together, they form a complete operating model: structured context for agents and humans, combined with disciplined engineering practices that keep modernization safe.
These practices apply to any team doing enterprise modernization, regardless of technology stack. The examples use generic patterns — adapt the specific tooling to your stack (ESLint for JavaScript/TypeScript, Clippy for Rust, Checkstyle for Java, etc.).
| Role | Start Here |
|---|---|
| Tech Lead | Quality Gates, then Specification-Driven Planning |
| Developer | Testing Strategy, then Incremental Development |
| AI/Agent Engineer | Agent Context, then Specification-Driven Planning |
| Engineering Manager | Quality Gates overview, then Testing Strategy metrics |