Claude CodeでWordPressプラグイン開発を始める — 作成手順とPHPの指示例

WordPressプラグインの作成は、wp-content/plugins配下にPHPファイルを1つ置き、先頭にPlugin Nameを含むヘッダーコメントを書けば始められます。Claude Codeを使うなら、このPHPファイルの生成から、フックの実装、php -lでの構文確認までを会話で進められます。ヘッダーの仕様はWordPressのPlugin Handbookに定義されていて、Claude Codeに渡すとそのままコードとして再現できる粒度です。以下では必須項目を起点に、Claude Codeに何を指示すればプラグインの骨格が組めるかを扱います。テーマ側でLPを組む作業はClaude CodeでLPをCMSに実装するにあります。ブロックエディター向けのブロック開発はClaude CodeでGutenbergブロックを作るにあります。

Claude CodeでWordPressプラグインを作るとは

Claude CodeでWordPressプラグインを作るとは、WordPressのサイト機能を拡張するPHPコードを、Claude Codeに読み書きさせながら組み立てる作業を指します。ここでいうプラグインはWordPress側の概念で、Claude Code自体にSkillやMCPサーバーを追加する「プラグイン」機能とは別物です。名前が同じなだけで、扱うファイルも設置場所も異なります。WordPress.comのサイトをClaudeから会話で操作したい場合は、ClaudeとWordPress.comを連携する方法が別の入口です。

Claude Codeはカレントディレクトリのファイルを読み書きするコーディングエージェントです。WordPressのwp-content/plugins配下に作業ディレクトリを合わせれば、PHPファイルの生成や既存プラグインの改修をそのまま任せられます。事前に必要なのはWordPress環境(ローカルでもレンタルサーバーでも可)とClaude Codeのセットアップだけです。Claude Codeを未導入の場合はClaude Code install完全ガイドにOS別の手順があります。作ったあとに規約へ合わせ続けるhookはWordPress規約をphpcsで直させる設定にあります。WordPress.orgへの申請前検査はPlugin Checkのreadme.txtエラーを直す手順で扱います。PHP 8へ上げる前の互換性検査はPHPCompatibilityWPで洗う手順にあります。

最小構成のプラグインをClaude Codeに書かせる

プラグインとして認識される最低条件は、PHPファイルにWordPress形式のヘッダーコメントを含めることだけです。最小構成ではPlugin Nameさえ書かれていれば、WordPressはそのファイルをプラグイン一覧に表示します。

作業ディレクトリを用意し、Claude Codeにヘッダーコメントの生成を頼む流れは次の通りです。

cd wp-content/plugins
mkdir my-first-plugin
cd my-first-plugin
claude

Claude Codeが起動したら、作りたいプラグインの概要とWordPressのヘッダー仕様を伝えます。

my-first-plugin.phpを作成して。WordPressのプラグインヘッダー
コメントとして、Plugin Name・Description・Version・
Requires at least・Requires PHP・Author・Licenseを含めた
最小限のPHPファイルにして。

指示どおりに生成されると、次のようなファイルになります。

<?php
/*
 * Plugin Name:       My First Plugin
 * Description:       Claude Codeで組み立てた最小構成のプラグインです。
 * Version:           0.1.0
 * Requires at least: 6.4
 * Requires PHP:      7.4
 * Author:            Your Name
 * License:           GPL v2 or later
 */

ヘッダーコメントは、同じプラグインフォルダ内の1ファイルにだけ書く決まりです。複数のPHPファイルを持つプラグインでも、ヘッダーを置くのは1つだけにします。

ヘッダーフィールドを仕様に合わせて充実させる

Plugin Name以外のフィールドは任意ですが、配布や審査を見据えるなら埋めておく価値があります。Plugin Handbookが挙げる主なフィールドは次の通りです。

ほかにPlugin URIやAuthor URI、翻訳ファイルの場所を示すDomain Path、ネットワーク全体での有効化に限るNetwork、依存先を示すRequires Pluginsが定義されています。Plugin URIはプラグイン固有のURLにする決まりで、WordPress.orgのURLは使えません。Requires PluginsにはWordPress.org形式のスラッグをカンマ区切りで並べ、my-plugin/my-plugin.phpのようなパス形式は使えません。

ヘッダーの下にPHPDocのブロックを置きたい場合は、@wordpress-pluginの行を挟んで両方を同じコメントに収める書き方が示されています。Claude Codeにはこの書き方も指示できます。

バージョン番号の大小はPHPの関数が決める

WordPressはプラグインのバージョン比較にPHPのversion_compare()を使います。ハンドブックには「1.02は1.1より大きい」とあります。version_compare()は、戻り値が1なら左が大きく、-1なら右が大きいことを示します。

php -r 'echo version_compare("1.02", "1.1"), "\n";'
php -r 'echo version_compare("1.2", "1.10"), "\n";'

1行目は1、2行目は-1を返します。1.02は小数ではなく「1」と「2」のセグメントとして読まれるため、1.1より大きくなります。1.2から1.10への更新は意図どおり新しい版と判定されます。更新通知が出ないといった事故を避けるには、Claude Codeにバージョンを上げさせたあとで、この比較を自分で走らせておくのが手軽です。

フックで機能を追加する

ヘッダーコメントだけのファイルは、WordPressに存在を認識させる器にすぎません。実際の機能はフック(アクションとフィルター)を通じて追加します。アクションはWordPressの動作に処理を追加・変更するためのもの、フィルターは表示前のコンテンツを書き換えるためのものです。

プラグインの基本となるフックは3つあり、動くタイミングと任せる仕事が違います。

依頼文で「無効化で設定を消す」と書くと、データが意図せず失われる実装になりかねません。

Claude Codeにフックの実装を頼むときは、どのタイミングで何をするかを具体的に伝えます。

register_activation_hook()を使って、有効化時に
wp_optionsテーブルへデフォルト設定を1件追加する
処理を追加して。無効化時に一時データを消す
register_deactivation_hook()も合わせて実装して。

有効化フックの定番の使い道は、カスタム投稿タイプを登録したあとにパーマリンクを更新することです。これを省くとカスタム投稿タイプのURLが404になります。ハンドブックの例は次の形です。

function pluginprefix_setup_post_type() {
	register_post_type( 'book', [ 'public' => true ] );
}
add_action( 'init', 'pluginprefix_setup_post_type' );
 
function pluginprefix_activate() {
	pluginprefix_setup_post_type();
	flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'pluginprefix_activate' );

このregister_activation_hook()の第1引数は、ヘッダーコメントを書いたメインファイルを指します。フックの登録を別のPHPファイルに分けた場合は、__FILE__のままだとそのファイル自身を指してしまうため、メインファイルを指すように書き換える必要があります。Claude Codeにファイルを分割させたときに、この引数がずれていないかを見直すと安全です。

独自のフックポイントをdo_action()で公開すれば、ほかの開発者が自分のプラグインからこのプラグインの動作を拡張できます。逆に既存のフックへ登録された処理をremove_action()で外すときは、元のadd_action()と同じコールバックを指定します。外す処理は元の登録より後に実行されなければならず、優先度の指定が効いてきます。ほかの処理との相互作用が読みにくいので、頻繁にテストすることがハンドブックでも勧められています。

車輪の再発明を避けたい場面では、WordPressが用意するAPI群も選択肢になります。設定値の保存にはOptions API、外部通信にはHTTP APIが使え、フック自体の使い方はPlugin APIにまとまっています。Claude Codeにこれらの名前を伝えれば、対応する関数を踏まえた実装を提案させやすくなります。

名前の衝突を避けるルールをClaude Codeに守らせる

グローバル名前空間に置いた関数・変数・クラスは、ほかのプラグインと同名になると上書きされる恐れがあります。Plugin Handbookの対策は、公開される名前すべてに固有の接頭辞を付けることです。接頭辞は4文字以上で、5文字が推奨されています。wp_や__、_始まり、WordPressといった、WordPress本体と衝突しやすい接頭辞は避けます。

接頭辞が必要なのは、関数・クラス・インターフェース・トレイト・名前空間・グローバル変数と、オプション名・トランジェントです。関数やクラスは名前空間に入れれば接頭辞が要りません。

メインファイルのように関数やクラスの外に処理を書くファイルでは、直接アクセスを防ぐ1行も推奨されています。

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly
}

is_admin()は管理画面かどうかを判定するだけで、認証や権限の確認にはなりません。権限が要る処理には、capability checkを別に書きます。

これらの規約は毎回の依頼文に書くより、CLAUDE.mdに置いておくほうが漏れません。

# プラグイン規約
- 関数・クラス・定数・オプション名は `myfpl_` で始める
- `wp_` や `_` で始まる名前は使わない
- メインファイルの先頭に ABSPATH の確認を置く
- ヘッダーコメントはメインファイルだけに書く
- 削除時のデータ消去は削除フックに書く

1ファイル構成とフォルダ構成のどちらを選ぶか

WordPressはpluginsフォルダとそのサブフォルダを走査して、ヘッダーコメント付きのPHPファイルを探します。プラグイン全体が1つのPHPファイルで完結するなら、Hello Dollyのようにpluginsフォルダ直下に単体ファイルを置くだけでも認識されます。複数のPHPファイルや画像・CSSを伴う一般的なプラグインでは、プラグイン名を付けた専用フォルダにまとめるのが想定されている構成です。

ハンドブックはフォルダ内の構成として、ルートにplugin-name.phpと任意のuninstall.phpだけを置き、残りをサブフォルダに分けるよう示しています。サブフォルダの例は/languages・/includes・/adminなどです。Claude Codeに新規プラグインを作らせる際は、最初に次の3つのどれにするかを伝えておくと、後から分割するときの手戻りが減ります。

Claude Codeに任せる作業の向き不向き

WordPressプラグイン開発の中でも、Claude Codeが得意な作業と人の判断が要る作業は分かれます。Symfonyベースで命名規則や本体バージョン差が絡むCMSの例は、Claude CodeでEC-CUBEのプラグインを開発するにあります。

権限モードと既存の資料を使い分ける

複数ファイルにまたがるプラグインを育てるなら、CLAUDE.mdにライセンスの方針やText Domainの命名規則、コーディング規約を足していくと、毎回同じ前提のコードを書かせやすくなります。CLAUDE.mdは起動時にカレントディレクトリから読み込まれる設定ファイルです。書き方の具体例はCLAUDE.mdを実用に引き上げる10のパターンにあります。nonceやesc_*の抜けを点検する手順はClaude CodeでWordPressのnonce・権限・エスケープ漏れを洗い出すにまとめています。

生成されたコードを1件ずつ確認しながら進めたい場合と、レビュー済みの変更を一気に反映したい場合とでは、権限モードの使い分けで効率が変わります。--permission-modeの選択肢はacceptEdits・auto・bypassPermissions・manual・dontAsk・planの6つです(v2.1.287のclaude --help)。ヘッダーコメントやフックの雛形のような反復編集にはacceptEditsが向いています。起動方法はClaude Codeの--permission-modeで起動モードを指定するにあります。

プラグインにAI機能(問い合わせ内容の要約やコンテンツ提案など)を組み込み、PHPから直接Claude APIを呼び出す場合、PHP SDKの動作要件はPHP 8.1以上です。WordPress側のRequires PHPはもっと低い値にできるため、SDKを使う機能だけPHPバージョンの前提がずれることがあります。詳細はClaude PHP SDKの値オブジェクトとバージョン運用にあります。

よくあるつまずき

• Text Domainを設定し忘れる: 翻訳文字列をText Domainに紐づけていないと、後から多言語対応を追加する際に文字列を洗い出す作業が発生します。
• Update URIを設定しないまま公開する: WordPress.orgに名前の似たプラグインがあると、更新の取り違えが起こりえます。自分のサイトなど固有のURLをUpdate URIに設定しておくと避けられます。
• すべての関数をfunction_exists()で包ませる: 衝突対策になりそうに見えますが、同名の関数を持つ別のコードが先に読み込まれると、自分の関数は定義されず動作が壊れます。ハンドブックは、if-existsで関数やクラスを置き換える書き方を共有ライブラリだけに限っています。
• クラスにまとめれば衝突を考えなくてよいと思う: クラスにしても、同名のクラスがすでにあるかの確認は必要です。ハンドブックの例はclass_exists()で包んだ形で、残りはPHPが面倒を見ます。

まとめ

ヘッダーコメントや基本フックのように仕様が文章で定まっている部分は、Claude Codeに任せて手早く形にできます。ライセンスの選定と本番サイトでの動作確認は人の判断として残ります。テストの書かせ方はwp-envでPHPUnitを回す手順にあります。他のプラグインとの競合が出たときの調査はClaude CodeでWordPressのプラグイン競合を切り分けるにあります。