Skip to content

WordPress with Claude Code

· 6 min read

This autumn I rebuilt two WordPress sites with Claude Code: the website of AM Gebäudereinigung, a building cleaning firm near Stuttgart, and my own site, belambo.com. Claude Code is an AI assistant that works in the terminal. It reads the files, runs WP-CLI, takes screenshots and changes code.

It is fast. Without rules, it is also fast at making mistakes. These are the practices that kept both sites safe and the work good. Each one came from a real job, and most came from a mistake.

Start every WordPress change on a staging copy

Nothing touches the live site first. Both sites have a staging copy on my machine, run with DDEV, with its own git repository.

  • The copy is hidden from Google (noindex) and marked as staging in wp-config.php, so nothing leaks into search.
  • Outgoing mail is caught locally with Mailpit, so a test form never reaches a real inbox.
  • Git tracks only what I write: the theme, my own plugins and the design files. It does not track WordPress core, uploads or wp-config.php.

One rule matters most: never copy the whole database back to the live site. It would wipe the form entries and settings that changed in the meantime. Only the theme, the page contents, the menus and named settings move.

Give Claude Code one source of truth

An AI assistant forgets between sessions. A file does not. Each project has a CLAUDE.md that Claude Code reads at the start of every session. It points to one design file, DESIGN.md. That file holds every rule with an ID: colour and type tokens, layout, images, content, and a definition of done.

When I correct something, the correction becomes a numbered rule in that file. My own site has more than thirty of them now. The next session starts with all of them, so the same mistake does not come back.

Facts get the same treatment. The AM theme has one facts file: name, phone, hours, service area and insurance. Every value carries its source and the date it was checked. The header, the footer, the phone bar, the contact blocks and the structured data all read from it. No page has the phone number typed in.

Write a page brief before any code

My first rebuilt home page was made without a brief. It looked finished. A review then found 19 problems. The hero picture sat below the text instead of beside it. One column was a third the height of the others. Screenshots sat small inside large boxes, and the same images appeared twice.

Now every page starts as a short brief: who arrives, what the page must achieve, each section with its job and pattern, the images, and every fact with its source. Claude Code writes the brief. I approve it. Only then does code start.

Keep shared WordPress content in one place

On the old belambo.com, the strip of client logos was copied into 14 pages, blocks and templates. Removing one logo meant 14 edits. Missing one meant an old client stayed visible on some page.

The new theme keeps prices, steps, questions, projects and contact details in one file. Shortcodes print them wherever they are needed. One edit changes every page, and Claude Code cannot “fix” a copy it does not know about.

Measure every page instead of eyeballing it

Claude Code sees a page through screenshots, and screenshots can mislead. So the review is a script, and the script measures:

  • The first screen and the full page, taken separately. A full-page shot made by stretching the browser window changes every height set in screen units and moves fixed parts such as the phone bar.
  • Desktop, tablet and phone; light and dark mode; menus open and closed.
  • A rule report with pass or fail per rule ID: does the hero picture start level with the heading, does a grid leave an orphan column, does a screenshot fill its frame, is an image used twice, does a price appear where none belongs.
  • An overflow sweep from 320 to 1,600 pixels in 80-pixel steps, so no width scrolls sideways.
  • Before and after every CSS change, the same shots are compared pixel by pixel. Every changed shot gets opened, because a change nobody intended is a regression.

The report found that even my best pages missed a rule by a few pixels. They get fixed, not excused.

Check what the AI assistant actually sees

Two problems taught me this. During the design work, a small comparison switch sat in a corner of every staging page. The screenshot script was meant to hide it, but it looked for the wrong class name. The switch appeared in every review shot, and nobody noticed. Now the switch is gone, and the scripts hide nothing: a shot shows what a visitor sees.

The second problem was a token-saving tool that read images before Claude Code did. When a screenshot held mostly text, the tool passed on the text instead of the picture. Claude Code then judged a layout it had never seen. For design work, that setting is now off.

The rule that came out of both: report only what was looked at. If the assistant cannot show the screenshot, it did not check the page.

Record every live change with an undo

Every change to a live site gets its own folder: what changed, where, how to apply it, how to undo it and how to check it, with before and after copies. It also gets one row in a change log. Changes go out one at a time, and each one is approved first.

Before the AM website went live, there was a full backup with checksums, a dry run and a written undo: switch the theme back, or restore the backup.

Logs beat guesses. On my own site, the mail server had refused the contact form’s sender address for a long time. The mail log said so in one line. Reading it took a minute. The fix took two.

Let clients edit WordPress without breaking it

The owner of AM changes texts and photos himself, in the WordPress block editor. Every section was rebuilt in native blocks or in custom blocks with a live preview. The layout is locked to content-only editing, so he can change words, images and links, but cannot move or delete a section by accident.

  • He has an Editor account, not an administrator account: no plugins, themes or settings.
  • Every page keeps its revisions, and I get an email whenever he publishes.
  • A script exports the pages back into git.
  • From his first edit on, the database is the source of truth. My content files are used only for new pages, never over his edits.

Speed, privacy and forms: WordPress maintenance basics

  • Host the fonts on the site itself instead of loading them from Google. In Germany, that is a privacy question, not only a speed question.
  • Load plugin styles only where they are used. On belambo.com, the form plugin’s CSS went from 169 KB to 55 KB, and the site CSS from 21 KB to 10 KB.
  • Test that spam protection really runs. A spam filter switched on without its API key checks nothing, and real enquiries then drown in spam.
  • Run an accessibility test on every page, on phone and desktop. The AM site passed with zero violations on 21 pages.
  • Lint PHP with the PHP version the server really runs. A plain php command on a host can be far older than the one WordPress uses.

What Claude Code does not replace

Claude Code writes, builds and checks quickly. It does not decide what a business says, which client may be named, or whether a page is good enough. I approve every brief, every live change and every new rule. The assistant follows the files, and the files follow decisions made by people.

If your WordPress site needs this kind of care, write to me on WhatsApp.

Abdul Hannan sitting in an old armchair in front of a mural of a sparrow

Tell us about your project

A short message is enough.

Replies within one working day