What an AI Coding Agent Actually Does

An agent does not hand you code, it works in a loop of reading, editing and running commands. The work moves to reading diffs and deciding what counts as proof.

Ask someone who has never used one what a coding agent does and you will get a description of autocomplete with better manners: you type, it suggests, you press Tab. That model is wrong in a way that costs real money, because it tells you the agent is a productivity feature rather than a second pair of hands with no memory of your site and no ability to check its own work.

What actually happens is a loop. The agent reads a file, edits it, runs a command, reads the output, and decides what to do next. Nothing about that loop requires the agent to be right. It requires only that each step is cheap enough to attempt and that the output of the last step is legible to the next decision. When the output is legible and true, the loop converges on working code. When the output is missing, the loop converges on confident code that has never been executed.

That distinction is the whole course. On a WordPress site it decides whether you get a plugin that activates, or a plugin that activates and then fatals on a page nobody tested.

Every agent is four capabilities in a loop

Strip away the interface and the marketing tiers and you are left with a program that can do four things: read files from your repository, write files into it, execute commands on your machine, and feed the results back into its next decision. The order matters less than the presence of the fourth step. An agent that reads and writes but never executes is a generator with a file handle, and its tests are whatever it believes tests are.

The loop is why agents restructure code you did not ask them to touch. To make an edit compile, the agent explores outward: it reads the caller, then the class, then the bootstrap file. Exploration is how it builds a model of your repository, and the model includes whatever it happened to read. Point it at a repository with no instructions in it and the model is filled in from training data, which for WordPress means pattern-matching against tutorials of varying age rather than against your theme.

The verification step is the part worth paying for

A loop that runs php -l and stops has verified that your PHP parses. That is all it has verified. Syntax checking is a real gate and a weak one: it will not notice a function that does not exist, a hook name with a typo in it, or an argument passed in the wrong order. Neither will npm run build on a block plugin, because the WordPress packages are externalised to the browser globals in window.wp and the build never asks whether the export you imported is still there.

What the agent needs instead is something that fails. A real WordPress installation that returns a fatal error is the most useful thing in the loop, and it is the thing most agent setups do not have. The rest of this course is largely about building it, which is why the next module exists before any code gets written.

A green build means the bundler finished

Treat a successful build as evidence about your toolchain, never as evidence about WordPress. It says the files compiled. It says nothing about whether the APIs inside them exist in the version you are running.

No vendor's documentation mentions WordPress at all

Here is the finding that should change how you read every agent comparison you find online. Research covering the documentation sets of Claude Code, OpenAI Codex, OpenCode, Cursor, GitHub Copilot, Devin and Antigravity searched for WordPress, WooCommerce, WP-CLI, Gutenberg, block editor, theme.json and PHP. The result was nothing. Not a thin section, not a tutorial: no mention in any of the vendor documentation reviewed.

Absence is not incapacity. Agents write working WordPress code, and one documented run produced a Gutenberg block plugin that installed, activated, registered its block and passed a hostile-input escaping check in real WordPress. But that capability comes from public training data, not from vendor engineering. There is no WordPress-aware linter offered by any of these vendors and no vendor benchmark that tests PHP at all. The most widely cited agent benchmark, Aider's polyglot set, covers C++, Go, Java, JavaScript, Python and Rust. PHP is not in it, which means the number everyone quotes tells you nothing about the language you use.

WordPress built the layer itself, in five artifacts

The gap was filled from the other direction, and this is the most useful material in the course because almost nobody has written it up. The WordPress project publishes, officially:

An MCP server for the plugin directory, run as npx -y @wporg/mcp, which exposes plugin guidelines, readme validation and submission status. It auto-configures the MCP clients it can find, currently Claude Desktop, Claude Code, Cursor and VS Code. That client list is the closest thing to a vendor-endorsed WordPress workflow that exists, and WordPress wrote it.
AI contribution guidelines published on 1 February 2026. Disclosure of meaningful AI assistance is required, contributions must stay GPLv2-or-later compatible, and the failure modes are named in the project's own voice: hallucinated references such as APIs, hooks and functions; large unreviewed code dumps; over-architected code where a simple solution would do. Maintainers may reject contributions that look like "AI slop".
AGENTS.md files in WordPress's own repositories. WordPress/gutenberg ships a 104-line one, and wp-cli/wp-cli ships a 140-line one that is the most directly useful WordPress agent file in existence for plugin work.
The WordPress/agent-skills repository, distributed as agent skills, including an official wp-playground skill for running WordPress through the Playground CLI, plus wp-env, wp-phpstan and wp-plugin-development. The README is explicit that the skills were generated with AI and then reviewed and edited by WordPress contributors.
A documented convention for how those files are written: the root AGENTS.md is loaded in every session and routes to the contributor documentation, directory-level files load only when the agent works in that directory, and agent files are expected to point at canonical docs rather than copy them.

Read that list again as a set of instructions to yourself. If your agent is guessing at WordPress, it is not because a vendor failed you. It is because you have not given it the files WordPress already publishes.

The products, and the three changes that make older articles wrong

The agent line-up is real and mostly stable: Claude Code from Anthropic, Codex from OpenAI, OpenCode under the Anomaly organisation, Cursor, GitHub Copilot, Antigravity from Google, and Devin. Three things have changed recently enough that anything written a quarter ago is unsafe to follow.

Windsurf no longer exists as a product. The domain redirects to Devin's desktop page and the documentation domain redirects with it. If you are reading a comparison that prices Windsurf, it was written before the absorption and its other facts are suspect too.

Gemini CLI was replaced by Antigravity CLI. Google's own repository states that unpaid-tier and Google One users lost Gemini CLI on 18 June 2026, and directs them to Antigravity. Enterprise customers on the paid Code Assist tiers kept access.

Cursor is sold inside a subscription bundle. The pricing page is now dominated by benefits for other products in the same bundle, and the entry tier at $8 per month includes Cursor's own models only. Frontier third-party models need a higher tier and billing at API list price.

Aider is a separate case: still installable, last release August 2025, and its README still leads with a model list roughly a year out of date. Its PHP support is real but its benchmark coverage is not, so it is a tool to pin a version on rather than adopt fresh.

The experiment worth running before you read further

Everything above is documentation and observation. You can add your own observation in about ten minutes, and it will teach you more about your agent than any comparison table.

Lab 20 minutes

Take the agent you already have. In an empty directory, give it this prompt and nothing else:

Write a WordPress plugin that registers a shortcode called [acme_badge].
It must escape all output and be safe with the WordPress Coding Standards.
Tell me which WordPress functions you used and why each one is the right choice.

Let it finish. Then answer four questions in writing, with the actual transcript in front of you rather than your memory of it:

How many files did it read before it wrote anything, and were any of them real WordPress files?
How many commands did it run, and what did it do with the output?
Did it verify that the functions it named exist, or did it assert that they exist?
Pick the one function you are least sure about and check it yourself against the WordPress developer reference or a real install.

Run the same prompt a second time from a copy of the directory that contains only an empty file named AGENTS.md. Note what changes. Then write down the complete loop the agent ran, in order, as a numbered list of actions.

Show what to look for, and the reasoning

The four answers are usually the same, and the pattern is the point. A typical run reads zero WordPress files, because there are none in an empty directory. It runs zero commands, or runs php -l and treats the result as a passing test. It asserts the functions exist, because from inside the model they do. And when you check the function you were least sure about, you find either that it exists with a different signature than the agent used, or that it never existed at all.

The second run is the interesting one. An empty AGENTS.md changes little, which is the correct outcome: the file is an instruction channel, not a knowledge base, and an empty one carries no instructions. What you have demonstrated is that the agent's WordPress behaviour comes from training data that you cannot inspect, and that the only lever you hold is what you put in the repository.

Your numbered list of actions should look something like this: read the prompt, list the directory, search for existing plugin structure, read whatever files matched, write acme-badge.php, optionally run a syntax check, optionally run a lint script, write a summary. Notice how many of those steps are optional in your run. Every optional step is a place where the loop can stop early and report success anyway.

The reason to write the list rather than remember it is that the summary an agent prints at the end is a claim, not a log. It is generated from the same model that wrote the code, so it inherits the same wrong beliefs. The transcript of what the agent did is the evidence. The paragraph it writes about what it did is marketing with your project's name in it.

One honest caveat about this exercise: a single run on a single prompt tells you about one agent's behaviour on one task type, and a shortcode registration is close to the most common WordPress pattern in existence. Treat the result as a sample. The method, though, works on every task you will ever hand an agent, and it takes minutes.

Progress

Mark this lesson done and it stays marked in this browser.

Next →Choosing an Agent for PHP and WordPress Work