are amazing at quickly implementing a lot of code. However, if you’ve ever worked a lot with coding agents, you’ll notice they start struggling after a while. Maybe you’ve spent a few days writing code with AI. Everything went perfectly and fast, and then you start noticing the tasks take longer, and the AI is making more and more mistakes.
This is a clear sign that you need to start refactoring the code. I believe that refactoring your codebase is going to be standard after you’ve implemented a lot of code with coding agents. Coding agents do make mistakes and don’t write perfect code. Also, if you don’t follow best practices in existing code, the AI will continue not following best practices in the new code it generates. Thus, you need to continuously refactor your repositories.
In this article, I discuss how to know when you need to refactor your code, what the signs are, and how to do it effectively using Claude Code or other coding agents.
Why refactor your code?
First of all, I always like to cover why you should care about the topic I’m discussing. Refactoring the code sounds like a boring task, and in reality, it used to be a very boring task that you had to do every now and then. Just a few years ago, humans had to manually go into the code repository to look for what needed to be refactored and start refactoring the code.
This would typically happen once, just after a lot of implementations in the code, because code naturally drifts away from a perfect state into a messier state simply by people interacting with the codebase and working on it. This happens even if humans are working on it or if AI agents are working on the codebase.
You need to refactor your code because if the code is messy, it simply takes more time to do implementations, and you’re more prone to errors.
Let me give a specific example. Let’s say we have a chatbot design implementation in your application where users can write to an AI bot and get a response back. This is basically just a chat box field where you show the AI responses and the user responses. A good code base would ensure that you have a single component that’s called chat, and this component is used in all the different places in the app where you display the chat. A poorly designed code base would have one version of this chat per different location in the app.
The problem then occurs once you want to make a change to the interface of the chat. For example, you want to update the color of the chat box or the icon of the AI. Naturally, you would want to update this in all places in the app where you display a chat, but that means that a human or AI editing the code has to edit the code in several different places.
If the code, however, was written well, you would only have to update the code in one single location because that’s a centralized code for how the chat should look. This is just a simple example of how well-written code can make implementations easier and less prone to errors.
When to refactor your codebase
Firstly, I’ll cover when you should refactor your codebase and what signs you should be looking for.
To put it simply, you should refactor your code when the coding agents are becoming slower at making implementations and when you start noticing the agents creating more bugs during an implementation. If you see issues appearing in unexpected places, or in code you didn’t touch, it is a clear sign that you should start refactoring.
Furthermore, I recommend you start refactoring earlier rather than later. Of course, working with code that needs refactoring takes more time and is more prone to errors, but it’s also very frustrating because you’ll notice that you start making changes, and the coding agents are not able to do exactly what you tell them to do.
There’s never a set time when this need for refactoring comes in. It doesn’t necessarily happen after x amount of days or x amount of lines of code written. It’s more of something that just happens over time. The need for refactoring simply happens after a lot of work has been done on a repository.
My theory is that this happens because some small piece of code starts to drift away from the ideal state, which can happen for many different reasons. Further work in this same area of the code will amplify the effects of the drift, and after a while, it will be noticeable when the coding agents or humans are less able to write the code there effectively.
Of course, you should try to avoid this as much as you can; however, I do believe that refactoring is not something you should strive to completely eliminate. I believe it’s a natural part of the evolution of a codebase. You should instead just embrace the fact that you’ll have to perform refactoring every now and then, and you should be aware of the signs for when you should start refactoring your code.
How to refactor code with Claude Code
Now that you know when you should refactor your codebase, I’ll start discussing how to refactor your codebase with Claude Code or any coding agent that you prefer.
There are a few simple rules that I follow whenever I start refactoring.
- Use the most advanced and high-effort reasoning you can. Refactoring is a task that requires a lot of intelligence, and you don’t want to make mistakes here. For example: Use the workflows feature from Claude Code, or xhigh thinking on GPT-5.5
- Only perform one refactoring at a time in your repository. It’s okay to refactor while doing other implementations as well, but you don’t want to have multiple refactoring tasks running at once
- If you are unsure of the optimal folder structure, compare or give the coding agent access to another code repository with a good structure that you like, and tell it to imitate that
- Refactoring takes time. Just have it as a task you run in the background while working on other stuff
Usually, when I start refactoring code, I use the following setup: I open my Claude Code in a new worktree in the repository, and I spin it up with the highest effort available in Claude Code, which is Ultracode.
If I know what to refactor, I tell Ultracode and Claude as much information as possible on what to refactor and why to refactor it. You might think that mentioning the why isn’t necessary, and in some cases, it’s not, but I find it really useful because then the AI is understanding why I’m doing what I’m doing, which helps it align with what I want to implement.
I then give the agent a lot of time to go through the entire repository, especially the part I want to refactor, and come up with a detailed plan on how to refactor. I do this in plan mode in Claude Code.
I then read through the plan to ensure it’s as I expect. Usually, the agents are better at refactoring than I am personally, so I find that the plans are usually ok on the first attempt.
An important part of the prompt that I use whenever I perform refactoring is that I tell the model to implement tests that it should run before and after. The tests should, of course, work beforehand, and they should, of course, all work again when it is done. This helps the model verify its work and ensure it does not introduce any new bugs when performing refactoring.
I’ve performed a lot of refactoring using Claude Code, and I would say it’s almost perfect at performing refactoring work. When I used the setup I described above, I very rarely experienced any issues, and it almost always had a significant increase in how well the coding agents were able to run in my repository.
Simply put: Refactoring code with Claude Code is very effective.
Conclusion
In this article, I discussed how to refactor code using Claude Code. I discussed why you should care about refactoring, highlighting how it can make your coding agents way more effective at implementations in the code repository. I then covered how to know when you need to refactor and how to refactor the code, which are the two most important points you should know when it comes to refactoring.
With AI and coding agents, I believe refactoring code is something you should simply do continuously in your code repository. You should often have an agent go through your code, check if anything needs refactoring, and start refactoring right away. Usually, the agent will be able to do this fully by itself, and you will not have to follow up much with it, but it is very simple to do. It is something you should continuously do to make coding agents as effective as possible in your repository.
👋 Get in Touch
👉 My free eBook and Webinar:
🚀 10x Your Engineering with LLMs (Free 3-Day Email Course)
📚 Get my free Vision Language Models ebook
💻 My webinar on Vision Language Models
👉 Find me on socials:
💌 Substack
🐦 X / Twitter
