Legacy Migration Playbook – Design the Ideal End State


| December 10, 2019 | in

“If you don’t know where you are going you might end up somewhere else.” – Yogi Berra

One of the critical challenges with legacy systems is not having a clear goal in mind. Knowing where you want to end up is essential for a few reasons. First, it provides you and your team with a sense of how to get the system under control. Second, it creates a lens through which to look while making decisions. Third, it provides a sense of how far off you are from arriving at a good solution.

Probably the number one issue when working with legacy systems is the emotion associated with it – and it is negative. Developers often hate working on poorly-structured systems that are held together with baling wire and duct tape. Having a plan for your team makes it seem possible to get the system under control. If you can’t come up with a plan, you have a problem. But if you can, you have hope.

There is a tension between “get it done quickly” and “migrate to something better” when working on a legacy system. And there often isn’t a straightforward answer. But identifying the end state allows us to judge each piece of work through the lens of determining how your team can reach the end goal. Otherwise, it’s difficult to make the appropriate decisions.

Identifying an ideal end state gives your team an idea of the size of the overall effort (e.g., “Can we achieve this one bite at a time?”). This often prompts discussions around finding subsystems that are maybe “good enough” as they exist today. Compartmentalizing aspects of the system by “carving off a few pieces” can save some time and reduce some anxiety.

Legacy systems can be a challenge, but there are a lot of fascinating problems to solve in this challenge. But when you don’t have a roadmap – which is almost always the case when working on legacy systems – you often end up just wandering around the code. Getting a good picture of where you want to go will help to keep everyone on a better path.


System Review / Code Review
Design the Ideal End State
Mini Spike Work
Add Some Unit Tests
Determine a Migration Strategy / Strangle
Segment the New from the Old
Start Over