WordPress runs a large share of the web and is the platform where agent-assisted development goes wrong most quietly. Not because the code is difficult, but because the code is only one of three things deciding what the site does. The files on disk, the rows in the database, and the plugins hooking your output all have a vote — and a tool that reads files can only see one of them.
This hub collects the guides that apply to WordPress work, starting with the platform guide and continuing into the audits that catch what a code review does not.
Who this is for
Developers maintaining WordPress sites that real people visit: client work, agency retainers, a store, a publication. It assumes you can read PHP and use a terminal. It does not assume you are a WordPress specialist — most of the material here is aimed precisely at the competent generalist who has inherited a WordPress install and would like not to break it.
If you are starting a new content site with no requirement to use WordPress, read the Astro hub first and make the choice deliberately. WordPress is the right answer often, and it is chosen by default far more often than that.
The shape of the problem
Every platform has a characteristic failure. On a static site it is stale build output. On Shopify it is a setting the platform silently discarded. On WordPress it is a change that appears to work and is not the change you made.
There are four common versions of it, and recognising which one you are in saves most of the debugging time:
-
The template you edited is not the template that renders. WordPress resolves templates by walking a hierarchy from most specific to least. Editing
index.phpto change a post page edits a file that is never reached. - A hook is modifying your output after your code runs. When the markup is right and the page is wrong, look for a filter before you look at the template again.
- The content is in the database, not in a file. Page builders store layouts in post meta. Site editor customisations to a block theme are stored as posts that override the file on disk entirely.
- A cache is showing you the past. The change shipped, the page did not update, so a second change goes in on top of the first.
None of those produces an error. All of them produce a confident report that the work is done.
And if the site is leaving WordPress — for Astro, for Shopify, for another host or domain — the guides here still apply to the source, and the move itself is a mapping and validation job: every URL inventoried, mapped and redirected, every title and image checked on the other side. The Website Migration & Replatforming System covers it, with a WordPress-to-Astro guide and a complete example.
The two rules worth enforcing
Most of the safety in WordPress work with an agent comes from two rules, and both belong in your project context file where they are read at the start of every session.
Never edit the parent theme. Changes there work, survive testing, and vanish at the next vendor update. Everything goes in the child theme or a plugin.
The agent does not write to the database. File changes are reversible with a git checkout. A search-and-replace across wp_posts with a slightly wrong pattern is not, and the only recovery is a backup you hopefully took. Reading is fine and useful; writing is proposed, reviewed, and run by you after an export. PHP serialisation makes this worse than it sounds — a naive SQL replace on a serialised option corrupts it silently, because the stored string lengths no longer match.
Verification, which matters more here
The general discipline behind everything on this site is that a check which has never failed is not evidence. On WordPress that principle has a specific and unusually cheap application: clear the cache before you verify anything. An agent reporting "the change is live" after reading a cached response has verified nothing at all, and the report will be perfectly confident.
Three checks worth running on any WordPress change, in order of how often they catch something:
-
Look at the rendered HTML, not the template.
curlthe page and grep for what you expect. Templates lie; output does not. -
Read
debug.log. WithWP_DEBUG_LOGon and display off, PHP notices accumulate in a file nobody opens. A change that adds notices is a change that is not finished. - Count the queries. A template edit that introduced a query inside the loop turns one page into forty round trips, and it is invisible until the site is under load.
Security is mostly two functions
Custom WordPress code fails security review in the same two places nearly every time: output that is not escaped, and a write handler that checks a nonce but not a capability. Those are different guarantees — a nonce proves the request came from your form, a capability proves this user is allowed to do the thing — and code that has one without the other is the most common real vulnerability in bespoke WordPress work.
Escaping is contextual and the wrong choice is worse than none, because it looks handled. Text inside an element takes esc_html(); an attribute takes esc_attr(); a URL takes esc_url(), which is the one that stops a javascript: href; editor content that must keep its formatting takes wp_kses_post(). That last one is the one agents drop, because it visibly strips things during testing and removing it makes the problem go away.
Deployment, and the direction things move
WordPress predates the assumption that a website is a repository, and its deployment story still shows it. The workable arrangement is that code moves up and content moves down: themes and custom plugins deploy from git to production; the database is copied from production to staging and never the reverse. Pushing a staging database to production destroys every order, comment and post created since the copy was taken.
Everything else — validation gates, preview environments, smoke tests, rollback — works the same way it does on any other platform. The CI/CD guide covers the general pipeline; for WordPress the deploy step is usually an rsync scoped to wp-content/themes and wp-content/plugins, with composer install --no-dev and a PHPCS run in front of it.
Where to go next
Start with the platform guide below. After that, the audits in this hub are not WordPress-specific but they are where WordPress sites most often fail: security, because custom handlers are written by hand; accessibility, because themes routinely undo core's defaults; and performance, because a page cache hides the problem until it does not.