Refactoring legacy code is never only about changing code. First, you need to understand what the system does today. You need to know the rules, the edge cases, and the hidden decisions that are already inside the project.
AI can help a lot with this work, but only if you guide it well. If you ask AI to rewrite code too early, it may miss important details. My workflow is different. I use AI first to understand the code, then to plan, and only after that to implement.
In this post, I will share a simple workflow I use when I want to refactor legacy code with AI. You will read about how to onboard AI with documentation, how to explore possible solutions, how to use agentic coding with a clear goal, and how to keep the documentation updated after the work is done.
Step 1: Onboard AI with Documentation
Before any refactoring starts, I ask AI to help me document the current state of the code. At this step, I do not mention refactoring, rewriting, or improving the code. The goal is only to understand what exists today.
This is important because AI needs context. If it does not understand the current system, it may suggest changes that look good but break real behavior.
I usually create a new folder called ai-docs. Inside this folder, I add documentation for the specific feature or part of the code I want to work on.
For example, if I want to refactor the payment flow, I create:
ai-docs/payment-flow.md
Then I ask AI to inspect the related files and write documentation about the current state. The document should explain what the feature does, which files are involved, what data moves through the system, and what edge cases already exist.
The document should describe the software as it is today. It should not include a plan for refactoring yet.
Step 2: Understand the Possibilities
After the documentation is ready, I use it as the base for a conversation with AI.
At this step, I still do not edit code. The goal is to understand what is possible. I ask questions like:
- What parts of this feature are risky to change?
- What edge cases should I protect?
- What would be the simplest refactoring approach?
- What should stay the same from the user's point of view?
- Which tests or manual checks would give me confidence?
This step is about planning. I share my goal with AI and ask it to suggest a path. Then I challenge the plan. I ask for simpler options, smaller steps, and possible problems.
For small refactors, one planning round may be enough. For larger refactors, I iterate on the plan several times. The more important the feature is, the more time I spend here.
A good plan should be clear enough that the next step feels almost mechanical.
Step 3: Implement with a Clear Goal
Now it is time to edit the code.
At this point, AI already has the current-state documentation and the refactoring plan. This makes agentic coding much more useful. Instead of saying, "refactor this code", I give AI a clear goal and a clear path.
For example:
Refactor the payment flow based on ai-docs/payment-flow.md.
Follow the plan we agreed on.
Keep the external behavior the same.
Make small, focused changes.
Run the related checks after each important step.
This keeps the work controlled. The AI is not guessing from zero. It knows the current behavior, the goal, and the path.
With this setup, the implementation is usually much faster. The hard thinking already happened before the code changed.
Step 4: Update the Documentation
After the refactor is done, I update the documentation in ai-docs.
This step is easy to skip, but it matters. The documentation should describe the new state of the project or feature. It should not keep the old legacy version as the main source of truth.
Keeping old documentation can confuse AI later. If the document still describes the legacy structure, the next AI session may use old information and suggest the wrong changes.
So I keep the documentation clean. It should explain how the code works now, after the refactor.
Final Thoughts
For me, AI refactoring works best when I treat AI like a teammate that needs onboarding.
First, I give it context. Then I explore the options. After that, I let it help with implementation. Finally, I update the documentation so the next round of work starts from the right place.
This workflow is slower at the beginning, but it saves time later. It reduces guessing, protects important behavior, and makes legacy code easier to improve step by step.