【第10回】長期運用プラグインの開発ルールをUbuntuへ引き継ぐ

Cuerda-Feed-Totalとは

Cuerda-Feed-Totalは、WordPressの投稿を外部メディア向けのRSSへ変換して配信するためのプラグインです。

配信先ごとに異なるRSSの仕様へ対応し、本文、画像、カテゴリ、カスタムフィールドなどを、各サービスが定める形式で出力します。

通常のWordPressプラグインと同様に管理画面やデータベースを使用しますが、最終的な出力は外部の配信先が読み取るRSSです。

そのため、WordPressの画面が正常に表示されることだけでなく、生成されたXMLの構造、本文の変換、不要な要素の除去、ライセンスの状態なども確認する必要があります。

Ubuntuへ移行した時点の主な情報は次のとおりです。

Ubuntuのローカル開発サイトはWordPress 7.0.1、PHP 8.5.4で動作しているため、プラグインが定める最低要件を満たしています。

一方、PHP 8.5は比較的新しいバージョンです。以前の環境では表面化しなかった警告や互換性上の問題が見つかる可能性もあるため、移行後の確認が重要になります。

長期運用プロジェクトの移行は単純な複製ではない

新しいプロジェクトであれば、GitHubからリポジトリを取得し、必要な依存関係を導入すれば、比較的簡単に開発を始められます。

しかし、長期間運用しているプロジェクトには、ソースコード以外にも多くの情報があります。

• 過去の不具合と修正理由
• 配信先ごとの仕様と注意事項
• 変更してよい範囲と変更してはいけない範囲
• 構文検査やコーディング規約の実行方法
• ローカルWordPressとの接続方法
• ライセンスや外部通信を伴う確認手順
• Codexへ作業を依頼する際のルール
• WindowsやWSLを前提としたパス

ソースコードだけをUbuntuへ移しても、これらの前提が失われると、以前と同じ品質や安全性で開発できません。

今回の移行では、ファイルを動かすことだけでなく、プロジェクトに蓄積された開発方法を新しい環境へ引き継ぐことを目的としました。

GitHubからリポジトリを取得する

Cuerda-Feed-Totalのリポジトリは、他の実案件と同じプロジェクト用ストレージへ配置します。

/mnt/studio317-data/development/projects

今回のプロジェクトディレクトリは次の場所です。

/mnt/studio317-data/development/projects/cuerda-feed-total

GitHubからリポジトリを取得した後、対象ディレクトリへ移動します。

cd /mnt/studio317-data/development/projects/cuerda-feed-total

最初に、Gitの基準状態を確認しました。

printf '%s\n' '--- repository root ---'
pwd

printf '%s\n' '--- remote ---'
git remote -v

printf '%s\n' '--- branch and status ---'
git status --short --branch

printf '%s\n' '--- latest commit ---'
git log -1 --oneline --decorate

プロジェクトの保存場所、GitHubの接続先、現在のブランチ、未コミットの変更、最新コミットを確認します。

長期間運用しているプロジェクトでは、似た名前の作業用コピーや過去のリポジトリが残っていることがあります。

ディレクトリ名だけで判断せず、GitHubの接続先と最新コミットまで確認してから作業を始めます。

以前のWSL環境との違い

WindowsとWSLで開発していた際、Cuerda-Feed-Totalのリポジトリは次の場所にありました。

/var/www/html/shared-plugins/cuerda-feed-total

Ubuntuへ移行した後は、次の場所で管理します。

/mnt/studio317-data/development/projects/cuerda-feed-total

ソースコード内でWordPressの標準関数を使用している限り、プロジェクトの保存場所が変わっても通常は問題ありません。

一方、開発用の指示書、検査コマンド、補助スクリプトなどに絶対パスが書かれている場合は、そのままでは利用できません。

そのため、PHPコードを変更する前に、リポジトリ内の文書や開発ツールにWSL固有のパスが残っていないかを確認します。

プロジェクト固有の指示書を確認する

Cuerda-Feed-Totalのリポジトリには、Codexへプロジェクト固有のルールを伝えるためのAGENTS.mdがあります。

/mnt/studio317-data/development/projects/cuerda-feed-total/AGENTS.md

AGENTS.mdには、プロジェクトの概要、主なディレクトリ、検査方法、変更時の注意事項などを記載できます。

Codexがリポジトリ内で作業する際に、毎回すべてのルールを依頼文へ書かなくても、基本方針を共有できます。

今回確認した主な項目は次のとおりです。

• プラグインの目的と主要機能
• よく変更するソースコードの場所
• PHPの構文確認方法
• PHPCSの実行方法
• テストや動作確認の範囲
• 外部APIやライセンス確認の扱い
• コミットやpushの権限
• 環境固有のパス

ソースコードが正しくても、Codexが古い環境の指示に従えば、存在しないディレクトリでコマンドを実行したり、異なるコピーを編集したりする可能性があります。

AIを開発に利用する場合は、コードだけでなく、AIへ渡す作業ルールも保守対象になります。

主なソースディレクトリの記述を確認する

AGENTS.mdには、Codexがよく確認するソース領域として、複数のディレクトリが記載されています。

例えば、次のような領域です。

includes/
admin/
rss/
ynf/

この一覧は、プロジェクトの主な構成を把握するためには役立ちます。

ただし、一覧に書かれていないディレクトリを、すべて作業対象外と解釈してよいとは限りません。

長期間開発しているプロジェクトでは、機能追加や構成変更によって、次のような領域が後から加わることがあります。

cli/
helpers/

「主なソース領域」と「変更を許可する範囲」は、意味が異なります。

主なソース領域

頻繁に確認する代表的なディレクトリを示します。一覧にない場所も、依頼内容によって調査対象になります。

変更を許可する範囲

今回の作業で実際に変更してよいファイルやディレクトリを示します。

Codexへ変更を依頼する際は、AGENTS.mdの代表的な一覧だけに頼らず、今回変更してよい範囲を依頼文で具体的に指定します。

Codex用の専用スキルを確認する

Cuerda-Feed-Totalでは、Codexへ検査手順を伝えるための専用スキルも用意しています。

以前のWSL環境では、次のファイルを参照していました。

/var/www/html/shared-plugins/cuerda-feed-total/.codex/skills/wp-ver4-check/SKILL.md

Ubuntuでは、プロジェクトの保存場所が変わるため、対応する場所は次のようになります。

/mnt/studio317-data/development/projects/cuerda-feed-total/.codex/skills/wp-ver4-check/SKILL.md

このスキルには、WordPressプラグインの変更を確認する際に使用するコマンドや、結果の報告方法などを記載しています。

AGENTS.mdがプロジェクト全体のルールを示すのに対し、SKILL.mdは特定の作業を行う際の手順書として利用します。

ファイルが存在しているだけではなく、Codexがその内容を読み取り、現在の環境で利用できることを確認する必要があります。

古い絶対パスを探す

WSL環境を前提とした絶対パスが残っていないか、リポジトリ全体を検索します。

cd /mnt/studio317-data/development/projects/cuerda-feed-total

grep -RIn 
--exclude-dir=.git 
--exclude-dir=vendor 
'/var/www/html/shared-plugins/cuerda-feed-total' 
.

検索対象から.gitとvendorを除外し、開発用の文書や設定ファイルに古いパスが残っていないかを確認します。

絶対パスが必要な記述については、Ubuntuの新しいパスへ更新します。

一方、特定の保存場所に依存する必要がない手順は、可能な限りプロジェクトのルートから実行する相対パスへ変更します。

cd /mnt/studio317-data/development/projects/cuerda-feed-total

composer phpcs

相対パスを利用すれば、将来プロジェクトの保存場所が変わった場合でも、指示書を修正せずに利用できる可能性が高くなります。

環境固有の情報とプロジェクト共通の情報を分ける

開発用の文書には、すべての環境で共通する情報と、特定のパソコンだけで有効な情報があります。

プロジェクト共通の情報は、Gitリポジトリ内のAGENTS.mdやSKILL.mdで管理できます。

環境固有の情報は、できる限り相対パスへ置き換えるか、ローカル専用の文書として分離します。

秘密情報はGitへ保存せず、ChatGPTやCodexへの報告にも含めません。

特にCuerda-Feed-Totalでは、ライセンスや外部配信先に関係する情報を扱うため、ソースコードと秘密情報の境界を明確にします。

Composerの依存関係を導入する

リポジトリを取得した直後は、通常、vendorディレクトリが含まれていません。

PHP_CodeSnifferなど、Composerで管理している開発ツールを利用するため、依存関係を導入します。

cd /mnt/studio317-data/development/projects/cuerda-feed-total

composer install

composer installは、composer.lockに記録されているバージョンをもとに依存パッケージを導入します。

新しいバージョンへ更新することが目的ではないため、環境移行時は原則としてcomposer updateではなくcomposer installを使用します。

導入後、Composerの状態を確認しました。

composer validate
composer check-platform-reqs

UbuntuのPHPバージョンと拡張機能が、プロジェクトの依存関係を満たしていることを確認します。

PHPCSの設定を確認する

Cuerda-Feed-Totalでは、PHP_CodeSnifferを利用してコーディング規約を確認します。

プロジェクト独自の検査設定は、リポジトリ内のphpcs.xml.distに記載されています。

/mnt/studio317-data/development/projects/cuerda-feed-total/phpcs.xml.dist

このファイルでは、適用するコーディング規約、検査対象、除外するディレクトリなどを指定できます。

一般的に、次のような場所は検査対象から除外します。

• vendor
• node_modules
• 配布用に生成されたファイル
• 外部ライブラリ
• 画像や翻訳など、PHPコードではない資材

一方、プラグイン本体やincludes以下のPHPコードは、主要な検査対象です。

設定ファイルを明示して特定のファイルだけを検査する場合は、次のように実行できます。

./vendor/bin/phpcs \
-n \
--standard=phpcs.xml.dist \
includes/rss/class-feed-generator-ynf.php

-nは警告を省略し、エラーを中心に表示する指定です。

プロジェクト全体の検査には、Composerへ登録されているスクリプトを使用します。

composer phpcs

まず一つのファイルで検査環境を確認する

新しい環境でいきなりプロジェクト全体の検査を実行すると、多数の結果が表示され、検査環境自体の問題と既存コードの指摘を区別しにくくなることがあります。

そこで、最初に対象を一つのPHPファイルへ限定しました。

php -l includes/rss/class-feed-generator-ynf.php

php -lでPHPの構文に問題がないことを確認した後、同じファイルへPHPCSを実行します。

./vendor/bin/phpcs \
-n \
--standard=phpcs.xml.dist \
includes/rss/class-feed-generator-ynf.php

この確認により、次の項目を一度に確認できます。

• PHP 8.5で対象ファイルを読み取れること
• Composerで導入したPHPCSを実行できること
• phpcs.xml.distが読み込まれること
• WordPressのコーディング規約を認識できること
• ファイルパスがUbuntuでも有効であること

限定した検査が正常に動作してから、プロジェクト全体の検査へ進みます。

プロジェクト全体のPHPCSを実行する

個別ファイルの検査環境に問題がないことを確認した後、プロジェクト全体のPHPCSを実行しました。

composer phpcs

この段階で重要なのは、指摘件数をただちにゼロにすることではありません。

長期間運用しているプロジェクトでは、既存コードに過去からの指摘が残っている場合があります。

環境移行時に確認する主な点は次のとおりです。

• PHPCS自体がエラーなく起動すること
• WordPressのコーディング規約を読み込めること
• 想定しているファイルが検査対象になっていること
• vendorなどが適切に除外されていること
• WindowsとUbuntuで検査範囲が変わっていないこと
• 新しいPHP環境に起因する実行エラーがないこと

既存の指摘をすべて今回の移行作業で修正すると、環境移行とコード改善が混在してしまいます。

今回は検査環境が再現できることを確認し、コードの修正は個別の目的として別に行う方針としました。

Codexが指示書を認識しているか確認する

AGENTS.mdと専用スキルを配置していても、Codexが実際にどの指示を認識しているか確認する必要があります。

最初はファイルを変更させず、現在の認識だけを報告してもらいました。

このリポジトリでは、まず調査だけを行ってください。

次の内容を確認して報告してください。

・現在のリポジトリルート
・読み込んだAGENTS.mdの場所
・利用可能なプロジェクト固有スキル
・wp-ver4-checkのSKILL.mdの場所
・現在のブランチとGit状態
・PHP、Composer、PHPCSの利用可否
・検査に使用する主なコマンド

ファイルの変更、WordPressの操作、
データベース変更、外部通信、
ライセンス情報の出力、コミット、pushは行わないでください。

Codexから報告されたパスが、Ubuntu上の次の場所を指していることを確認します。

/mnt/studio317-data/development/projects/cuerda-feed-total

古いWSLのパスや、別のコピーを参照している場合は、コードの変更を依頼する前に設定を見直します。

WordPress開発サイトから参照できるようにする

前回までと同様に、Gitリポジトリをソースコードの正本とし、WordPressからはシンボリックリンクで参照します。

WordPressのプラグインディレクトリは次の場所です。

/var/www/studio317/wordpress-dev/public/wp-content/plugins

Cuerda-Feed-Totalへのリンクを作成します。

ln -s \
/mnt/studio317-data/development/projects/cuerda-feed-total \
/var/www/studio317/wordpress-dev/public/wp-content/plugins/cuerda-feed-total

リンク先を確認します。

readlink -f \
/var/www/studio317/wordpress-dev/public/wp-content/plugins/cuerda-feed-total

Apacheがメインのプラグインファイルを読み取れることも確認します。

sudo -u www-data \
test -r \
/mnt/studio317-data/development/projects/cuerda-feed-total/cuerda-feed-total.php \
&& echo "Apache can read plugin file"

これにより、Visual Studio CodeとCodexが編集するGitリポジトリを、WordPressが直接実行できる構成になります。

有効化前にプラグインの構造を確認する

Cuerda-Feed-Totalは、起動時に複数のPHPファイルを読み込みます。

主要なファイルが存在しない場合や、必要なクラスや関数を読み込めない場合は、管理画面へ通知を表示して処理を停止する安全策があります。

有効化する前に、プラグインのメインファイルと主要な読み込み先が存在することを確認します。

test -r cuerda-feed-total.php
test -r includes/admin/class-admin.php
test -r includes/loader.php
test -r includes/init.php

続いて、PHPファイルの構文を確認します。

find . \
-type f \
-name '*.php' \
-not -path './vendor/*' \
-print0 \
| xargs -0 -n1 php -l

構文エラーがないことを確認してから、WordPress上での有効化へ進みます。

最初の確認では外部配信を行わない

Cuerda-Feed-Totalは、外部配信先向けのRSSを生成するプラグインです。

また、配信先によってはライセンスの確認も行います。

そのため、ローカルWordPressへプラグインを有効化するだけでも、どの機能が外部通信やライセンス情報に関係するのかを把握しておく必要があります。

今回の環境移行では、まず次の範囲に限定しました。

• WordPressがプラグインを認識すること
• PHPの構文エラーがないこと
• PHPCSを実行できること
• 管理画面を表示できること
• プラグインの基本的な読み込みが完了すること
• Gitの作業ツリーが意図せず変更されないこと

外部配信先へのアクセス、実際のライセンスキーを使用した確認、本番データを利用したRSS生成などは、環境移行とは別の目的として扱います。

ライセンスキー、トークン、外部APIのレスポンスなどは、CodexやChatGPTへの報告へそのまま含めません。

WordPressがプラグインを認識するか確認する

シンボリックリンクとファイルの読み取り権限を確認した後、WP-CLIからプラグインの状態を確認します。

cd /var/www/studio317/wordpress-dev/public

wp plugin list
wp plugin status cuerda-feed-total

WordPressがCuerda-Feed-Totalを認識していることを確認した後、必要な条件を整えて有効化します。

wp plugin activate cuerda-feed-total

有効化後は、次の項目を確認しました。

• WordPressのトップページを表示できること
• 管理画面へログインできること
• プラグイン一覧を表示できること
• Cuerda-Feed-Totalが有効と表示されること
• プラグインの管理画面を表示できること
• PHPの致命的エラーが発生していないこと

この段階では、RSSの内容や配信先ごとの細かな仕様までは確認しません。

まずは、新しいUbuntu環境でプラグイン本体を安全に読み込めることを確認します。

移行作業でソースコードを変更しない

今回の目的は、Cuerda-Feed-Totalの機能を変更することではありません。

リポジトリ、Codex向けの指示、Composer、PHPCS、WordPressとの接続をUbuntuで再現することが目的です。

そのため、確認の途中で既存コードの改善点やPHPCSの指摘が見つかっても、すぐには修正しません。

作業後、Gitの状態を確認します。

cd /mnt/studio317-data/development/projects/cuerda-feed-total

git status --short --branch
git diff
git diff --check

環境移行に伴って指示書などを変更した場合は、その差分だけを確認します。

プラグインのPHPコードに意図しない変更がないことを確認し、機能修正と環境移行を混在させないようにします。

ChatGPT、Codex、人間の役割を整理する

長期運用しているプロジェクトでは、AIへ渡す情報も多くなります。

今回も、ChatGPT、Codex、人間の役割を分けました。

ChatGPT

移行する情報の整理、WSLとUbuntuの違い、開発ルールの見直し、Codexへの依頼内容を検討します。

Codex

リポジトリ内のAGENTS.mdや専用スキルを読み、プロジェクトの構成、Git状態、検査環境を確認します。

Visual Studio Code

指示書、設定ファイル、Codexの変更、Git差分を人間が確認します。

Git

環境移行に伴って変更した文書や設定を記録し、PHPコードへ意図しない差分がないことを確認します。

人間

ライセンス、外部通信、データベース、WordPress上の動作など、影響範囲の大きい操作を判断します。

Codexへプロジェクトのルールを登録していても、すべてを自動的に任せるわけではありません。

特に、外部配信、ライセンス、データ削除、コミット、pushなどは、依頼ごとに許可する範囲を明確にします。

今回の到達点

今回は、長期間開発と運用を続けているWordPressプラグイン「Cuerda-Feed-Total」をUbuntuへ移しました。

Gitリポジトリを/mnt/studio317-data/development/projects/cuerda-feed-totalへ配置し、GitHubの接続先、ブランチ、作業ツリー、最新コミットを確認しました。

以前のWSL環境で使用していた/var/www/html/shared-plugins/cuerda-feed-totalというパスと、Ubuntu上の新しいパスの違いも整理しました。

Codexへプロジェクト固有のルールを伝えるAGENTS.mdと、検査手順をまとめたwp-ver4-checkのSKILL.mdを確認し、古い絶対パスや作業範囲の解釈を見直しました。

Composerの依存関係を導入し、PHPの構文確認、個別ファイルのPHPCS、プロジェクト全体のPHPCSをUbuntu上で実行できる状態も整えました。

さらに、GitリポジトリをシンボリックリンクでWordPressの開発サイトへ接続し、WordPressがプラグインを認識して基本画面を表示できることを確認しました。

これにより、ソースコードだけでなく、長期間蓄積してきた開発ルールと検査方法もUbuntuへ引き継ぐことができました。