Claude CodeでPlugin Checkのreadme.txtエラーを申請前に直す

WordPress.orgへ申請する前に、wp plugin checkの結果をstrict-jsonで書き出し、その内容をClaude Codeの非対話モード(claude -p)へ渡せば、readme.txtとメインファイルの食い違いを機械的に直せます。Plugin Checkは「Stable Tagがバージョンと違う」「Tested up toが古いまま」といった申請で止まる原因を、結果コードごとに返します。コードを手がかりに「どのファイルのどの行を直すか」を決めれば、Claude Codeに渡す指示は短く済みます。

プラグイン本体の作り方はClaude CodeでWordPressプラグイン開発を始めるにあります。ここでは、書き終えたプラグインを申請前に検査して潰す工程に絞ります。

検査を回してClaude Codeに渡す最短手順

Plugin Check自体がWordPressプラグインなので、検査用のサイトにインストールして有効化しておきます。READMEは本番環境での利用を勧めていないため、ローカルかステージングのサイトを使います。そのうえで、WP-CLIから次のように実行します。

wp plugin check my-plugin --format=strict-json \
  --fields=file,line,type,code,severity,message > pcp-result.json

--formatにstrict-付きの形式を選ぶのがこのコマンドの要点です。--format=jsonは、指摘をファイルごとにまとめてFILE: readme.txtのような見出し行を挟んで出力します。ファイル全体が1つのJSONにならず、jqに渡すと失敗します。strict-jsonなら全件が1つの配列で出ます。fileは既定の出力項目に入らないため、--fieldsに明示しないと、どのファイルの指摘か分からなくなります。

my-pluginは検査したいプラグインの名前です。パスやZIPのURLも指定できるので、wp plugin check /path/to/pluginの形でも動きます。

結果ファイルができたら、標準入力経由でClaude Codeに渡します。非対話モードは標準入力を読めるため、ログをcatで流し込む使い方が公式の例にもあります。

cat pcp-result.json | claude -p \
  'この検査結果のうち readme.txt とメインPHPのヘッダーに関する
ERROR だけ直して。Tested up to は変更せず、現状と理由を報告して' \
  --allowedTools "Read,Edit"

--allowedTools "Read,Edit"を付けると、ファイルの読み取りと編集は確認なしで通ります。Bashは許可リストに入れていません。Manualモードのclaude -pでは、承認が必要な呼び出しを承認する仕組みがなければ拒否されます。申請前の修正はreadme.txtとヘッダーの編集で足りるため、この構成で十分です。非対話モードの全体像はclaude -pオプションとはにまとめています。

入力に流せる量は10MBまでです。Plugin Checkの結果が大きくなるときは、後述の--checksで検査を分けるか、--ignore-warningsで警告を外してから渡します。上限の扱いはclaude -pにログを渡すと10MB上限で止まるで詳しく扱っています。

結果コードで「直す場所」を決める

Plugin Checkの出力には、チェック名(check slug)と結果コード(result code)の2種類の名前が出てきます。--checksや--exclude-checksに渡すのは前者で、--ignore-codesに渡すのは後者です。混同すると指定が効かないので、JSONで受けるときはcodeの列を見て判断します。

各結果にはERRORかWARNINGの種別と、1から10の重大度が付きます。重大度を明示しない場合の既定値は5です。readme.txtを調べるplugin_readmeチェックの結果は、次のコードが中心です。

Stable Tagの3つは、メッセージが同じ趣旨です。Stable Tagはプラグインの安定版を指す値で、メインファイルのヘッダーにあるVersionと完全に一致させる必要があります。不一致だとWordPress.orgからユーザーが正しいファイルを取得できなくなる恐れがある、と検査側が説明しています。

Stable TagとVersionはどちらを正にするか

WordPress.orgのディレクトリは、まず/trunkのreadme.txtにあるStable Tagを読み、/tags/以下の該当フォルダ(1.2.3なら/tags/1.2.3/)を探します。表示されるバージョンは、フォルダ名ではなくメインPHPファイルのVersionで決まります。ダウンロードボタンの「Download Version 1.2.3」もその値です。

つまりVersionが正で、Stable Tagを合わせる側です。この前提をClaude Codeに伝えておかないと、Versionのほうを書き換える修正案が出ることがあります。プロジェクトのCLAUDE.mdに1行置いておくと安定します。

## WordPress.org 申請前の検査
- バージョンの正はメインPHPファイルの Version。readme.txt の Stable tag を合わせる
- Stable tag に trunk は書かない
- Tested up to は readme.txt にだけ書く。値は自分で動作確認した版に限る
- License は readme.txt とメインファイルで同じ識別子にする
- .claude/ と CLAUDE.md は配布ZIPに含めない

Stable tag: trunkは、検査でtrunk_stable_tagのERRORになります。ハンドブックも、新規プラグインでの使用を禁止する立場を取っています。

Tested up toだけはClaude Codeに決めさせない

Tested up toは、そのバージョンのWordPressで動作を試したという表明です。最新のWordPressより古い値だと、outdated_tested_upto_headerが出ます。メッセージによれば、最新版までテストされていないプラグインは検索結果に表示されなくなります。

Claude Codeは、実際にそのバージョンで試したわけではありません。結果コードに従って数字を上げる作業は機械的にできますが、数字を書き換える前にその版で動作確認を済ませる責任は人間側にあります。前節のプロンプトで「変更せず報告して」と書いたのはこのためです。確認が済んだら、値を指定して直させます。

readme.txt の Tested up to を 6.8 に更新して。
値は主要バージョンまでで、マイナー番号は書かない。

ハンドブックの記述では、この欄はマイナーバージョンを無視し、4.9のように数字だけで書きます。WP 4.9の形は不可です。Plugin Checkにも、最新版と同じ主要バージョンでパッチ番号まで書くとinvalid_tested_upto_minorで指摘する処理があります。

もう1つ注意があります。メインファイル側のヘッダーにTested up toが残っていると、plugin_header_tested_up_to_not_allowedのERRORになります。値が一致していても同じです。この欄はreadmeにだけ置く決まりなので、メインファイルの行を削除します。単一ファイルのプラグインはこの検査の対象外です。

Licenseの食い違いをそろえる

invalid_licenseは、readmeのLicenseが有効なSPDXライセンス識別子になっていないときに出ます。license_mismatchは、readmeとメインファイルのヘッダーで、正規化した値が違うときに出ます。どちらも重大度は9です。

直す方向は、GPL互換のライセンスをどれにするかという判断が先に立ちます。この判断はClaude Codeに任せず、決めた値を渡して揃えさせます。

ライセンスは GPL-2.0-or-later に決めた。
メインファイルの License と readme.txt の License を同じ識別子にして。

指示に値を入れておけば、片方だけが古い表記のまま残ることを防げます。License URIは任意項目ですが、珍しいライセンスを使うときはリンクを付けることが勧められています。

Claude Code自身の副産物が警告になる

読者が見落としやすい点が1つあります。Plugin Checkのfile_typeチェックは、隠しファイルや圧縮ファイルに加えて、AI開発用のディレクトリを検出します。対象は.cursor、.claude、.aider、.continue、.windsurf、.aiで、見つかるとai_instruction_directoryのWARNINGになります。重大度は9です。

ルート直下のMarkdownファイルにも制限があります。許可されているのはREADME.md、readme.txt、LICENSE、LICENSE.md、CHANGELOG.md、CONTRIBUTING.md、SECURITY.mdだけで、それ以外はunexpected_markdown_fileのWARNINGです。プラグインのルートに置いたCLAUDE.mdは、この許可リストに入っていないため警告の対象になります。

Claude Codeで開発すると、プロジェクト直下に.claude/やCLAUDE.mdが自然にできます。開発用リポジトリでは正しい構成ですが、WordPress.orgへ出すZIPには含めない運用に切り替える必要があります。

--use-pcpignoreで.pcpignoreを使う方法もありますが、これはローカルとCI向けの機能です。WordPress.orgのスキャンでは使ってはいけないと明記されています。除外に頼らず、ZIPの中身そのものを整えるほうが申請時の結果と揃います。

修正のループを回す

1回の修正で全部が消えるとは限りません。修正のたびに検査をやり直し、ERRORが空になるまで繰り返します。

すでに公開済みのプラグインを更新するときは、--mode=updateを付けます。同じoutdated_tested_upto_headerでも、新規審査(new、既定)では重大度7のERRORですが、更新モードではWARNING(重大度5)になります。更新前の検査では、モードを揃えて結果を比べます。

特定の領域だけを調べたいときは、--checks=plugin_readmeのようにチェック名で絞れます。wp plugin list-checksで、使えるチェックの一覧を確認できます。

よくあるつまずき

結果コードを--checksに入れてしまう問題があります。stable_tag_mismatchは結果コードなので--ignore-codesの領分で、--checksにはチェック名のplugin_readmeを渡します。

読み飛ばしやすいのは、readme.txtを編集しても/tags/側が古いままという状態です。ハンドブックによると、タグフォルダ内のreadme.txtにも正しいStable Tagが必要で、揃っていないと更新できなくなることがあります。Claude Codeが直せるのは作業ツリー内のファイルだけなので、SVNのタグ作成時に中身を再確認します。

もう1つ、Plugin Check自体に--aiオプションがあります。誤検知かどうかをAIで判定する機能で、WordPress 7.0以降とAIコネクターが必要です。結果コードの意味は、このオプションを使わなくても本記事の表で読み解けます。

まとめ

申請前のPlugin Checkは、ERRORを「結果コード、直す場所、直す側」の3点で仕分けると、Claude Codeに渡せる粒度になります。readme.txtの食い違いはVersionを正として機械的に揃えられます。一方でTested up toの値とライセンスの選択は、人が決めてから指示に入れる項目です。

最後に、配布ZIPから.claude/とCLAUDE.mdを外せているかを見ておくと、申請直前に警告で戸惑わずに済みます。