技術資料

Codexを使うと、既存のPHPやLaravelプロジェクトでも、調査から実装、テストまでをまとめて進められます。

ただし、既存プロジェクトの改修では、コードを書けることよりも「どこまで変更してよいか」を判断することのほうが重要です。画面の一部を使いやすくするだけのつもりが、API、バリデーション、ドメインロジック、データベースまで変更されると、確認すべき範囲が一気に広がります。

今回は、既存のPHP・Laravel・Vue.jsプロジェクトで、管理画面の利用者選択UIを検索できるPickerへ変更する例を使い、次の流れを整理します。

• AGENTS.md、Skills、仕様書、作業指示を確認する
• 変更対象と維持する既存の契約を決める
• Codexへ段階的に実装を依頼する
• テスト、ビルド、画面、Git差分を確認する
• 人が内容を確認してからGitHubへ反映する

新規プロジェクトを作る方法ではなく、すでに動いているコードを小さく安全に変更するための手順です。

既存プロジェクトの改修で最初に決めること

最初に、作業の目的と変更範囲を分けて考えます。今回の例では、利用者検索DBに登録されている候補者を、管理画面上で検索しやすくすることが目的です。

変更前の画面では、利用者候補をすべて表示するプルダウンを使っていました。候補者が増えると、目的の利用者を見つけるために長い選択肢をスクロールする必要があります。そこで、既存の候補データを使い、画面内で名前を検索できるPickerへ変更します。

このとき、次のように変更対象と対象外を先に決めておきます。

変更するもの	維持するもの
Vueコンポーネント、検索入力、候補一覧、共通CSS	既存の利用者IDを送るPayload
入力、選択、解除、候補なしなどの画面状態	保存処理、バリデーション、ドメイン処理
Pickerのコンポーネントテスト	API、Route、Controller、データベース構造

画面の変更だからといって、必ずBackendやデータベースまで変更するわけではありません。すでに画面へ候補データが渡され、保存時のIDも決まっているなら、まずはFrontendだけで解決できないかを検討します。

作業前にAGENTS.mdを確認する

既存プロジェクトでCodexに作業を依頼する場合、最初にプロジェクトのAGENTS.mdを確認します。AGENTS.mdには、技術スタック、仕様書の場所、ディレクトリ構成、テスト方法、変更時の禁止事項など、リポジトリ固有のルールを記録できます。

OpenAIの公式ドキュメントでは、Codexは作業前にAGENTS.mdを読み込み、プロジェクトのルートから作業ディレクトリまでの指示を組み合わせて適用すると説明されています。より深い階層にある指示は、同じ項目について上位の指示を補足または上書きできます。

AGENTS.mdの公式ドキュメントでは、プロジェクト固有の作業ルールをリポジトリへ置く方法と、階層ごとの適用方法が説明されています。

たとえば、既存のPHP・LaravelプロジェクトのAGENTS.mdでは、次のような内容を確認します。

• 開発環境と本番環境のPHP、Laravel、データベースのバージョン
• 仕様書や実装指示書を置くディレクトリ
• LaravelのAction、Query、FormRequest、Domain Serviceの責務
• BackendとFrontendで使うSkill
• PHPテスト、JavaScriptテスト、ビルドの実行方法
• 開発用データベースを初期化するコマンドの扱い
• .envや認証情報を編集・公開しないルール

ここを飛ばすと、プロジェクトが採用している責務分担や検証方法を知らないまま、一般的なLaravelの構成で実装してしまう可能性があります。

対象作業のSkillsを選ぶ

Skillsは、特定の作業を進めるための手順や補助資料をまとめたものです。OpenAIの公式ドキュメントでは、SkillのディレクトリにSKILL.mdを置き、必要に応じて参照資料、スクリプト、テンプレートなどを含められると説明されています。

Skillsの公式ドキュメントを確認すると、Skillsは単なる説明書ではなく、作業の流れや使うツールをCodexへ伝える仕組みだと分かります。

今回のようにVue.jsとLaravelにまたがる作業では、プロジェクト内のSkillを次のように使い分けます。

Skill	確認する内容
Frontendのワークフロー	Vueコンポーネント、状態管理、JavaScriptテスト、ビルド
Backendのワークフロー	PHP構文、Laravelの責務、Pint、Feature Test、DBの安全性
実装計画	調査、実装、統合、検証のPhase分割
エンコーディング安全性	日本語を含むファイルの編集方法と文字化け確認

Backendを変更しない作業でも、Backendの既存契約を確認する必要があれば、該当するSkillを参照します。Skillは「その領域を必ず変更する」という意味ではなく、「その領域に関係する判断基準を確認する」ためにも使えます。

仕様書、作業指示、既存コードを読む順番

AGENTS.mdとSkillsを確認したら、対象機能の仕様書と作業指示を読みます。個人的には、次の順番で確認すると、調査の抜けを減らしやすいと思います。

1. AGENTS.md
2. 今回の変更に関係するSkill
3. GitHub Issueや作業指示書
4. 関連する仕様書とアーキテクチャ方針
5. 変更対象のVueコンポーネントと呼び出し元
6. 保存処理、Request、Action、Domain、既存テスト

仕様書を読んだ後に、現在のコードが本当にその仕様どおりになっているかを確認します。仕様書とコードに差がある場合、どちらを今回の判断の根拠にするかを明確にしないまま実装を始めてはいけません。

仕様書の内容を実装へ反映することと、仕様書そのものを変更することは別の作業です。

実例：既存の利用者選択を検索Pickerへ変更する

ここからは、既存の利用者検索DBを参照する管理画面を例にします。元の画面には利用者候補をすべて表示するselectがあり、利用者を選択すると既存の利用者IDを保存処理へ渡します。

この例で確認したのは、次のような既存の状態です。

• 候補データは画面表示時にすでに取得されている
• 候補にはID、表示名、正式名、読み仮名が含まれている
• 保存処理が受け取る値は既存の利用者IDである
• 選択解除や未解決状態など、既存画面の状態がある

候補データがすでにブラウザへ届いているため、今回の検索はクライアント側で実行できます。候補数が増えたからといって、すぐに検索APIを追加する必要はありません。

作業指示では、次の範囲に変更を限定しました。

• 検索入力と候補一覧を持つVueコンポーネントを追加する
• 表示名、正式名、読み仮名を対象に検索する
• 選択、解除、候補なし、disabled状態を扱う
• 既存画面の操作と共通CSSへPickerを組み込む
• 既存のPayloadと保存処理をそのまま利用する

反対に、次の作業は今回の対象外です。

• サーバーサイド検索APIの追加
• Route、Controller、FormRequest、Action、Domainの変更
• Migrationやデータベース構造の変更
• キャッシュ機構の追加
• 同じPickerをプロジェクト全体へ一括展開すること

このように対象外を明記しておくと、Codexが「将来使えそうだから」という理由で、今回必要のない汎用コンポーネントやAPIまで作り始めることを防げます。

Codexへ実装前の調査を依頼する

いきなり「検索Pickerを作って」と依頼するのではなく、最初は調査だけを依頼します。実装前に変更予定のファイル、維持する契約、対象外を出力させるのがポイントです。

既存の利用者選択UIを、画面内検索に対応したPickerへ変更したい。

まずは実装せず、次の内容を調査してください。

- AGENTS.mdと今回関係するSkills
- 関連する仕様書と作業指示
- 対象画面のVueコンポーネントと呼び出し元
- 利用者候補のデータ構造と保存時のPayload
- 既存のテストと、追加が必要なテスト

調査結果では、次を分けて示してください。

1. 変更予定のファイル
2. 維持する既存の契約
3. 今回は変更しないファイル
4. 不明点と、実装前に確認が必要なこと

まだファイルは編集しないでください。

この依頼で、Codexが仕様書や既存コードを読まずに実装を始めることを防ぎます。調査結果に誤りがあれば、実装前に修正できます。

調査結果を確認して方針に問題がなければ、次のように実装を依頼します。

調査結果の方針で実装してください。

- 既存の利用者IDを送るPayloadは変更しない
- API、Route、Laravelの保存処理、DBは変更しない
- Vue側のPickerと必要なCSSに変更を限定する
- 検索、選択、解除、候補なし、disabledのテストを追加する
- 既存の命名とコンポーネント構成に合わせる

実装後に、変更ファイル、実行したテスト、未確認事項を報告してください。

複数の画面やテストにまたがる場合は、調査、Picker作成、画面統合、テスト・統合確認のようにPhaseを分けます。各Phaseで差分を確認してから次へ進めると、途中で方針を修正しやすくなります。

UI変更でも確認する状態を先に列挙する

検索入力を追加するだけに見えても、UIには複数の状態があります。少なくとも次の状態をテスト対象にします。

• 初期表示時に現在の選択値が表示される
• 表示名、正式名、読み仮名で検索できる
• 大文字・小文字や空白の扱いが意図どおりになる
• 候補を選択すると既存のIDへ反映される
• 選択を解除できる
• 候補がない場合に空状態が表示される
• disabled時に入力や選択ができない
• 候補件数を制限する場合に、制限値を超えた表示が崩れない

検索結果の見た目だけを確認して終わると、再表示時に選択状態が消える、保存値だけ更新されない、解除操作が元の画面と合わない、といった問題を見逃します。

PHP、JavaScript、画面を分けて検証する

検証コマンドは、プロジェクトのcomposer.jsonとpackage.jsonを確認してから実行します。一般的なコマンドを決め打ちするのではなく、そのプロジェクトで定義されているScriptを使うことが大切です。

PHP側の確認

PHPファイルを変更した場合は、まず構文を確認します。Laravelの責務や保存処理を変更した場合は、コード整形と関連するFeature Testも実行します。

php -l path/to/ChangedFile.php
vendor/bin/pint --test
php artisan test --filter=RelatedTest

今回はBackendを変更しない方針でも、既存の保存処理が壊れていないことを確認するため、関連するPHP Feature Testを回帰確認の対象にします。

JavaScript側の確認

Vueコンポーネントを変更した場合は、コンポーネントテストとビルドを確認します。今回参照したプロジェクトでは、package.jsonに次のScriptが定義されていました。

npm run test:js
npm run build

Picker単体のテストだけでなく、実際に組み込む画面で選択値が保存処理へ渡ることも確認します。コンポーネントテストが通っても、親コンポーネントのPropsやイベント名が合っていなければ、画面全体では動かないためです。

画面と日本語表示の確認

画面確認では、検索が成功するケースだけでなく、候補なし、disabled、選択解除、長い名前、スマートフォン幅などを確認します。日本語を含むファイルを変更した場合は、テスト結果だけでなく、実際の表示に文字化けがないことも確認します。

Git差分を確認してからGitHubへ反映する

テストが通った後も、作業完了とは考えません。まず、Codexを使う前から存在していた変更と、今回の変更を分けて確認します。

git status --short
git diff --stat
git diff
git diff --check

git diffでは、次の点を確認します。

• 対象外にしたAPI、Route、DB、Domainが変更されていないか
• 既存のPayload名やイベント名が変わっていないか
• 不要なリファクタや一括フォーマットが混ざっていないか
• 日本語の文字化けや、意図しない改行がないか
• .env、トークン、秘密鍵、個人情報が差分へ入っていないか
• 作業前から存在する変更を誤って含めていないか

特にgit add .を機械的に実行するのは避けます。変更対象が明確な場合は、ファイル単位で内容を確認してからStageへ進めます。

CodexやGitHubのレビューを使う

Codexには、作業ツリー、ベースブランチ、コミットなどを対象に変更をレビューする機能があります。Codexのコードレビューに関する公式ドキュメントでは、レビューは変更内容を確認するもので、作業ツリーを変更せずに問題を報告すると説明されています。

レビューを依頼するときは、「レビューしてください」だけではなく、今回の制約を伝えます。

今回の変更をレビューしてください。

重点的に確認する点:
- 既存の利用者IDとPayloadが維持されているか
- 検索、選択、解除、候補なし、disabledの状態に抜けがないか
- API、Route、Laravelの保存処理、DBへ不要な変更がないか
- 既存画面の他の操作を壊していないか
- テストとビルドの結果が変更内容を十分にカバーしているか

問題は重要度の高い順に、ファイルと理由を添えて示してください。

GitHub上のPull Requestでは、リポジトリの設定に応じて@codex reviewを使える場合があります。GitHub連携の公式ドキュメントにも、AGENTS.mdに書かれたレビュー方針を適用しながらPull Requestを確認する流れが説明されています。

ただし、Codexのレビューは人の確認やテスト、ブランチ保護、承認ルールの代わりにはなりません。レビューで問題が見つかったら、まず差分を確認し、必要なら作業指示やIssueへ戻って修正します。

既存プロジェクトの改修で起こりやすい失敗

既存コードを読む前に実装する

一般的なLaravelやVue.jsの実装を先に作ると、プロジェクト固有のAction、Query、FormRequest、コンポーネント規約から外れることがあります。最初にAGENTS.md、Skills、仕様書、既存コードを確認し、既存の責務に合わせて実装方針を決めます。

小さな画面変更にAPIを追加する

候補データがすでに画面へ渡されているなら、クライアント側の検索で解決できます。将来の拡張を理由にAPI、キャッシュ、DB変更まで追加すると、今回の目的に対して変更範囲が大きくなります。

単体テストだけで終わる

Picker単体のテストが通っても、親画面とのイベントやPayloadの接続が間違っている可能性があります。コンポーネントテスト、画面統合、関連するPHP Feature Test、ビルドを役割ごとに確認します。

Codexが変更したファイルだけをレビューする

作業ツリーには、Codexを使う前から存在していた変更が残っていることがあります。git statusと差分を先に確認し、今回の作業と既存の作業を分けてレビューします。

AGENTS.mdにルールを詰め込みすぎる

AGENTS.mdは便利ですが、すべての知識を一つのファイルへ集めると、重要なルールが見つけにくくなります。公式ドキュメントでは、プロジェクトの指示ファイルには読み込み上限があり、既定値は32KiBとされています。共通ルールはAGENTS.md、作業別の手順はSkills、機能仕様は仕様書へ分けると管理しやすくなります。

まとめ

既存のPHP・LaravelプロジェクトをCodexで改修するときは、コードを書く前の調査と変更範囲の制御が重要です。

1. AGENTS.mdから技術スタック、仕様書、作業規約を確認する
2. 対象作業に関係するSkillsを読み、検証方法を把握する
3. Issue、作業指示、仕様書、既存コード、テストを順番に確認する
4. 変更対象、対象外、維持するPayloadや責務を明記する
5. Codexへ調査、計画、実装を段階的に依頼する
6. PHP、JavaScript、画面、ビルド、Git差分をそれぞれ確認する
7. 人がレビューしてからcommit、push、Pull Requestへ進む

画面の一部を改善する作業でも、既存の契約を守りながら必要な範囲だけを変更できれば、確認すべき内容を小さく保てます。Codexへ任せる範囲を広げるほど、作業前のルール確認と作業後の差分確認が大切になります。

参考資料

• AGENTS.md - OpenAI公式ドキュメント
• Skills - OpenAI公式ドキュメント
• Codexのコードレビュー - OpenAI公式ドキュメント
• GitHub連携 - OpenAI公式ドキュメント
• Quickstart for pull requests - GitHub Docs