A few months back a client showed up with a familiar mess: a custom WooCommerce extension running to thousands of lines of logic, with no documentation at all. Their lead developer had left and the new team was working blind. Out of desperation they had pointed an LLM at the codebase and asked it to write a manual. What came back invented hooks that did not exist and suggested filters that would have crashed the site on activation, all in a very confident tone. A manual that reads well and is wrong is worse than no manual at all.
My first thought was to do the same thing but better: feed the code to a higher-tier model with a bigger context window and get a clean README out of it. That did not work either. Without a strict AI documentation workflow and someone checking the output against reality, you get volume rather than documentation. Dumping code into a prompt does not produce a manual. You need a process that knows how WordPress does things.
Building an AI documentation workflow that holds up
The core team is working on this for the WordPress 6.9 release cycle, and the discussion on the Make WordPress AI blog divides the work the right way. The model produces the structure and a first draft against specific style guides. A human does the fact-checking, and that part is not optional.
On a complex project, “explain this code” is the wrong prompt. Tell the model exactly what to look for. I extract the relevant metadata programmatically first, so there is nothing left for it to guess at. This helper pulls hook names and descriptions out of a file before I write a single line of prompt.
function bbioon_extract_hook_metadata( $file_path ) {
if ( ! file_exists( $file_path ) ) {
return [];
}
$content = file_get_contents( $file_path );
$hooks = [];
// Simple regex to find apply_filters and do_action
preg_match_all( '/(apply_filters|do_action)\s*\(\s*[\'"]([^\'"]+)[\'"]/', $content, $matches );
if ( ! empty( $matches[2] ) ) {
foreach ( $matches[2] as $index => $hook_name ) {
$hooks[] = [
'type' => $matches[1][$index],
'name' => $hook_name,
];
}
}
return $hooks;
}That is the “Responsible AI” part of it. You are asking the model to organize information, not to come up with it. Hand it the real hook list, pulled out with PHP, and the “imaginary hook” problem goes away along with the reason nobody trusted the docs. The 6.9 proposal is after the same thing: structured, verifiable drafts that follow the official style guides.
Documentation as insurance
Writing docs feels like wasted time when there are features to ship. I have also watched a team spend three days reverse-engineering one “clever” function because nobody wrote down what it did, and that is real money. A working AI documentation workflow turns a 10-hour chore into a 1-hour editing session. The editing session is the part people skip, and it is the part that counts.
None of this is an argument for avoiding AI. It is an argument against being lazy with it. Treat the model like a junior intern who needs very specific instructions and it will get through a lot of work. Treat it like a magic “fix everything” button and you will spend longer cleaning up than you saved.
This gets complicated fast. If you would rather not spend your week debugging someone else’s mess, drop my team a line. We have probably seen it before.
