Refactoring WordPress code without breaking other plugins

The common advice on refactoring WordPress code with an agent goes like this: your agent slows down and starts making mistakes because the codebase drifted, so you point Claude Code at the repo, ask for a plan, have it write tests first, and let it refactor. Eivind Kjosbakken makes that case on Towards Data Science, and most of it carries over to plugin and WooCommerce work. The part that does not carry is the definition of refactoring. In a standalone app, behavior preservation is defined by your own code. In WordPress, behavior other people depend on lives in your function names, filter tags and hook arguments, and some of those people have code you will never see.

So refactor, and use the agent for it. But every public name has to keep working until you ship a major version, and no agent does that on its own.

When is refactoring due?

The signals in the source hold here too. Tasks that used to take one pass now take three, the diff starts including edits nobody asked for, and bugs appear in files that were never touched. One WordPress-specific signal I would add: the agent starts calling functions with arguments from an older version, or invents method names that never existed. That usually means the codebase has drifted into several conventions at once and the model is guessing which one to follow.

The source also argues refactoring is now continuous rather than a scheduled cleanup, and I agree up to a point. Continuous refactoring is fine inside classes, private methods and helper functions, where only your code is affected. Anything wrapped in add_filter or add_action, or any function a child theme template might call directly, is a public API whether you meant it to be or not. Those names need a release cycle, a changelog and a deprecation period.

What do I tell the agent to do?

The mechanics transfer well: highest reasoning effort available, one refactor at a time, plan mode first, and run it in a git worktree while you do other work. On client sites I add a step before any of that: wp core verify-checksums and a clean local install with WP_DEBUG on, so the agent is reading a known good environment instead of diagnosing a broken one. An agent that finds a local install half broken will sometimes try to repair WordPress itself, which is not a refactor you want to review.

Two additions to the prompt that generic agent advice leaves out:

  • List the public names in writing. Name the filters, actions and template functions other code may rely on, and state that their signatures are frozen. An agent treats a rename as an obvious cleanup until you tell it the tag is load-bearing.
  • Give it one way to verify. Ideally that is PHPUnit or WP-CLI, run the same way before and after. If the plugin has no tests, the standard “write tests, run them before and after” advice needs a smaller version first: characterisation tests around just the code being moved. A WooCommerce checkout flow is a lot of surface to hand test after every refactor.

One more WordPress quirk worth putting in the prompt: the agent will want to split a single file into namespaced classes, which is usually right, but plugin files load in order and hooks fire in the order they were registered. If it moves code that used to run during plugin load into a hook callback, execution timing changes and something downstream can start seeing stale data. Tell it to preserve when things run as well as what they do.

How do I rename things other plugins depend on?

When the plan involves moving or renaming anything public, have the agent leave a shim instead of editing every caller, and let core’s deprecation machinery do the reporting:

<?php
function bbioon_get_price( $product_id ) {
    _deprecated_function( __FUNCTION__, '3.2.0', 'bbioon_product_price' );
    return bbioon_product_price( $product_id );
}

add_filter( 'bbioon_price_format', function ( $format ) {
    return apply_filters( 'bbioon_price_html', $format );
}, 10, 1 );

According to the core reference, _deprecated_function fires a deprecated_function_run action and raises a user error when WP_DEBUG is true, which is what you want on staging: sites that still call the old function log it loudly instead of white screening. The filter shim forwards the old tag to the new one, and anything still listening on the old name wins, which is the safe direction for one release. Bump the version in the plugin header, write the removal version in the changelog, then delete the shims at the next major.

On WooCommerce there is one more trap: template overrides live in the theme rather than the plugin. An agent can clean up a template file in the plugin all it likes, and the override in the child theme keeps rendering the old markup, so nothing visibly changes. Check wc_get_template calls against the theme’s woocommerce folder before you assume the refactor shipped. I’m not sure the same shim idea translates to block templates yet, since those get bundled and hashed at build time.

If you have a plugin that grew by copy-paste until agents started tripping over it, that cleanup, and the shim layer that should come with it, is work I take on. Send me the repo and I’ll tell you what can be refactored safely now and what has to wait for a major version.

Before any of this, check that you can run the site with WP_DEBUG on and Query Monitor active. The shims are only as good as the logs that catch them, and the alternative is learning about the breakage from a client three weeks later. And if nobody has a copy of the production code in git yet, fix that before letting an agent near it.

author avatar
Ahmad Wael
I'm a WordPress and WooCommerce developer with 15+ years of experience building custom e-commerce solutions and plugins. I specialize in PHP development, following WordPress coding standards to deliver clean, maintainable code. Currently, I'm exploring AI and e-commerce by building multi-agent systems and SaaS products that integrate technologies like Google Gemini API with WordPress platforms, approaching every project with a commitment to performance, security, and exceptional user experience.

Leave a Comment