WordPress プラグイン・テーマ開発で生成 AI を活用する際のコーディングスタンダード活用法

2025年現在、GitHub Copilot や Claude などの LLM ベースのコーディングアシスタントは開発現場に広く浸透しています。これらのツールはコード生成速度を劇的に向上させる一方で、「理解負債(Comprehension Debt)」と呼ばれる新しい問題を生み出しています。

理解負債とは何でしょうか。チームがコードを理解するよりも速くコードを生成してしまうことで蓄積される技術的負債を指します。例えば、AI が数分で生成した100行のコードを、チームメンバーが理解するのに数時間かかるような状況です。理解負債という概念を提唱した Jason Gorman 氏は、この問題を「時限爆弾」と表現しました。AI 生成コードは動作するかもしれませんが、後日そのコードを修正する必要が生じた際、開発者は理解に多大な時間を費やすことになります。

この記事では、「誰かが作ったコードを理解する」ステップの負担を軽減させるため、オープンソースプロジェクトの取り組みを活かせないか検証してみましたので、紹介します。

WordPress Core はコメントやドキュメントでコード理解を支援する

「各開発者がコードを理解する速度よりも早くコードが増えるもの」という枠組みで考えると、巨大な OSS（オープンソースソフトウェア）についても同様の現象が起きている可能性があります。ここでは WordPress Core のコードをみてみましょう。

WordPress は20年以上の歴史を持つオープンソースプロジェクトです。そして WordPress Core のコードを見ると、ほぼすべての関数やファイル・フォルダーなどに詳細な PHPDoc 形式のコメントが付与されています。これらのコメントには、関数の目的、想定される入力パラメータ、返却値、そして具体的な使用例が含まれます。例えば wp-includes/cron.php では、最初の関数が登場するまでの38行にはぎっしりとコメントが記載されています。

これは WordPress の一部ドキュメントがコードのコメントから生成されていることも背景にあります。先ほど紹介した関数 wp_schedule_single_event() の関数リファレンスをチェックすると、コメントに記載されていた内容が表示されていることがわかります。

「ドキュメントのデータソースに利用されるレベルで、詳細かつ洗練されたコメントがあるプロダクトを参考にすれば、少しでも AI が生成したコードの認知負荷を軽減できるのではないか」このように考え、実際にコード生成をさせてみることにしました。

既存のコードにコメントを書かせてみる

実験では AI コーディングツールに、「このファイルを参考にコメントを書いてください」と指示を出して、生成されるコメントについてチェックします。ここでは Devin を利用しました。開発チームの要望を追加で取り入れ、コードへのコメントだけでなく、プラグインの概要を README.md に反映させる試みも同時に実施します。

プロンプトではコメントや README.md の生成指示に加えて、「お手本となるファイル」として WordPress Core のファイルをいくつか共有します。より厳密に実施するならば、規約の説明なども追加するべきですが、実験としてまず簡潔な指示に止めました。

もしこれだけの説明で期待したコメントが生成されるのであれば、プロンプトの作成や管理の手間を大幅に省くことが出来ます。

生成されたコードには、詳細な PHPDoc が追加

社内向けの WordPress プラグインで実行した結果、以下のような PHPDoc 形式のコメントが各ファイルに追加されました。関数の目的、パラメータの説明、返り値の型、そして作成日時などが追加されています。

/**
 * Register custom post type for documentation
 *
 * Creates a custom post type 'doc' with support for title, editor,
 * and custom fields. This post type is used to manage internal
 * documentation within the WordPress admin.
 *
 * @since 2023-05-12
 * @return void
 */
function register_doc_post_type() {
    $args = array(
        'public' => true,
        'label'  => 'Documentation',
        'supports' => array( 'title', 'editor', 'custom-fields' ),
    );
    register_post_type( 'doc', $args );
}

@since （作成日時を示す PHPDoc タグ）に設定されている年月日については、Devin のナレッジで「git を使って調査した上で設定すること」を細かく設定しています。デフォルトでは実行日時もしくは生成 AI が思う「今」の日付、package.json などのバージョン番号が設定されますので、要件に合わせて調整しましょう。

README.md についても、プラグインの機能や使用方法が簡潔にまとめられています。

# Internal Documentation Plugin

## Description
This plugin provides custom post type functionality for managing 
internal documentation within WordPress admin.

## Features
- Custom post type 'doc' for documentation
- Support for title, editor, and custom fields
- Admin interface integration

## Installation
1. Upload the plugin files to `/wp-content/plugins/internal-docs`
2. Activate the plugin through the 'Plugins' menu in WordPress

簡単な実験として行ったタスクでしたが、作成したアプリの紹介ドキュメント生成や、引き継いだコードベースの理解を支援するツールとして有用といえるレベルではないかと感じています。

ライセンスに関する重要な注意

今回の手法は、WordPress Core のコード(GPL v2 以降でライセンス)を参考にさせました。そのため、GPLの継承要件(派生物もGPLでライセンスする必要がある)を満たす可能性があり、この手法で生成したコードはGPLでライセンスする必要性が生まれるリスクがあります。

よってWordPress以外、特にGPLでライセンスする必要のないプロジェクト(プロプライエタリソフトウェアやMIT/Apache等のライセンスを採用しているプロジェクト)では、WordPress Core を参考にするのではなく、そのプロジェクトのライセンスと互換性のあるコードベースを参考にすることを推奨します。

AIによるコード生成とライセンスの関係については、まだ法的判例が少なく不確実性が残る領域です。この手法を採用する際は、プロジェクトのライセンス要件を十分に確認してください。

今後について

この手法は WordPress が長年培ってきた手法や経験知をベースに、ドキュメント生成やコードの理解を目指しています。プロンプトの詳細や例示の手間を省ける反面、プロジェクトの特性や理解したい領域が WordPress のカバーしている範囲かどうかを知る必要があることには注意が必要です。

場合によっては WordPress のコードベースを分析し、コメントやドキュメント生成のルールを生成した上で、コーディングエージェントのルールやナレッジに設定することも検討しましょう。

まとめ

本記事では、生成 AI の普及によって顕在化した「理解負債」という新たな課題に対し、WordPress コーディングスタンダードがその軽減に貢献する可能性について検証しました。WordPress が20年以上の歴史の中で培ってきた、詳細な PHPDoc 形式のコメントやドキュメント生成の仕組みは、プラグインやテーマ開発において AI 生成コードの認知負荷を低減する上で非常に有効であることが示唆されました。

Devin を用いた実験では、WordPress Core のファイルを参考にコメント生成や README.md の作成を指示した結果、関数の目的やパラメータ説明、プラグインの機能説明など、高品質な PHPDoc とドキュメントが自動生成されることを確認しました。これは、プロンプト作成や管理の手間を大幅に削減し、開発チームの生産性向上に寄与する可能性を秘めています。

今後、この手法をプロジェクトの特性に合わせて調整し、WordPress のコードベースからコメントやドキュメント生成のルールを抽出し、コーディングエージェントのルールやナレッジに設定することで、より効果的な理解負債軽減策を確立できるでしょう。WordPress の経験知をベースとしたこのアプローチは、AI 時代におけるプラグイン・テーマ開発の新たな道を切り開くものとして期待されます。