Refactoring with AI?

A developer has added migration and refactoring skills to the Polylith tooling for Python, enabling AI agents to convert legacy single-repo projects into an agent-friendly Polylith Monorepo. The skills automate steps such as extracting application code, restructuring, and splitting large components, and have been tested with Claude and Mistral models. The developer argues that code simplicity is crucial for AI agents, similar to humans, and that the Polylith Architecture supports both human and agentic development.

With Agentic Engineering there's an opportunity to refactor legacy code, but this aspect of AI isn't that that much talked about and seems to be overlooked by teams out there. So far, the main thing with AI and agents has been to build new things in a fast pace. After several months of practicing Agentic Engineering, I've realized that code quality - or code health - is more important than ever. Agents get confused by complexity, just like humans. You've probably seen it I have too and now there is also research https://codescene.com/resources/research-and-insights backing it up. Keeping code simple is a good guideline also in the agentic era. This is where I believe the Polylith Architecture is a good fit, for both humans and agents. The original idea of Polylith was to keep things simple and great Developer Experience for Humans. As a nice side effect, Agents will probably like this setup too. An agent will have the context it needs to build new features from the existing well-organized code in the Monorepo. Since before, the Polylith tool for Python includes a set of agent skills about the commands and about Polylith in general. But what about migrating an entire existing single-repo project into a Polylith Monorepo? With AI, many steps could be automated here. I recently added additional skills https://github.com/DavidVujic/python-polylith/discussions/449 to the Polylith tooling that are focused on migrating and refactoring an existing Python project into an Agent friendly Monorepo. The migration skills handles the extracting of application code, restructuring and also refactoring of large components into smaller ones. The agentic flow for the migration of a project is: - discover - analyze-imports - extract-to-base - update-imports - prepare-project - verify-stability - isolate-base-and-big-component - split-big-component - extract-standalone-modules - isolate-shared-and-project-logic - distribute-wiring - split-component-internals - refactor-tests - definition-of-done Also, the project-specific tooling such as Project & Dependency management, linting and type checking is migrated and converted according to what’s already in the monorepo. Example: you use uv and ruff in the Polylith Monorepo, and migrate a project that uses Poetry and flake8 . The migration will convert those to uv and ruff . I have tested the skills with Claude Opus 4.7 and 4.8 and Mistral mistral-large and devstral . One of the tests I ran was converting the FastAPI repo just for fun and to test the skills out into Polylith. Before running the prompt, I copied the contents of the FastAPI repo into the Polylith projects folder. I also removed the existing .git folder in there, to avoid any confusion during the agentic work. Hint : the more unit tests the project to migrate has, the better The skills are part of the polylith-cli, and you can copy the contents of the .agents file or use a tool like library-skills to add them to your monorepo. Agents are unpredictable and different models behave differently. If you decide to try this thing out, please let me know how the skills works for you. You'll find info about Polylith for Python here https://davidvujic.github.io/python-polylith-docs/ . Top Photo by