▶おぢでも分かる
Codexを使ったプラグイン開発

ブラウザのChatGPTにファイルを上げると、そのファイルはOpenAI側に送られた「写し」になります。あなたのPCの中にある本物とは、その瞬間に切り離されます。

ここから、よくある3つの困りごとが全部説明できます。

• AIが「直しました」と言っても、手元のファイルは何も変わっていない
• 自分が手元で直しても、AIは古い写しを見続けている
• 写しを最新にするには、また上げ直すしかない

プラグインが何十個もある状態でこれをやると、手元とAIの認識がじわじわズレていきます。「なんだこれ間違えまくってんぞ」の正体はだいたいこれです。AIは自分の持っている写しに対しては正しいことを言っていて、その写しが古かった、というだけの話。

リポジトリ

プロジェクトのフォルダそのもの。SRPGスタジオのプロジェクトを保存しているフォルダ一式のことだと思ってください。「リポジトリごと渡す」＝「そのフォルダを作業場所として開かせる」。

エージェント

質問に答えるだけでなく、自分でファイルを探して、開いて、直して、動かすAI。Codexはこれです。ブラウザのチャットは「相談相手」、Codexは「作業者」。

コンテキスト

AIが一度に頭に入れておける量。会話の履歴も、読んだファイルも、全部ここを食います。ここが一杯になると、いわゆる「急にバカになる」が起きます。

AGENTS.md

AI向けの取扱説明書。プロジェクトフォルダの中に置いておくテキストファイルで、Codexは作業を始める前にこれを必ず読み、書かれたルールに沿って動きます。この手引きの山場はここです。

入れるもの

GitHubは要りません。アカウントも登録も不要です。手元のフォルダだけで成立します。

• VS Code（無料のエディタ）を入れて、拡張機能から Codex を追加する。これが一番素直な入口です。
• あるいはChatGPTデスクトップアプリから。2026年7月9日にCodexとChatGPTのデスクトップアプリが統合され、「Chat」「Work」「Codex」の3モードを切り替えられるようになりました。従来のChatGPTアプリのほうは「ChatGPT Classic」という名前に変わっています。

先に守るもの

Codexは本物のファイルを書き換えます。ということは壊せるということです。始める前に必ず。

• SRPGスタジオのプロジェクトフォルダを丸ごとコピーして、別の場所に置く（日付を名前に入れておくと分かりやすい）
• そのコピーには絶対にCodexを近づけないと決める
• 今動いている状態のゲームを一度起動して、「壊れる前はこうだった」を自分の目で見ておく

モデルを選ぶ

Codexは、処理に使うモデルを自分で選べます。さらに「推論レベル」も選べます。推論レベルは、答える前にどれだけ考え込むかの設定です。

ChatGPTのモデルは、数字が世代、名前がグレードという二階建てになっています。GPT-5.6の世代なら上から Sol（最上位）／Terra（標準）／Luna（軽量・高速）。さらに上の世代として2026年9月に GPT-6 Astra が出ています。

プラグインの依存関係を追うような仕事は考える量が多いので、上のグレードを選んでください。Lunaは要約や下書き向けです。ここでケチると、遠回りして結局トークンを食います。

Codexにはいくつかの動作モードがあります（呼び名は使う場所で多少変わりますが、中身はこの3つです）。

• 読み取り専用：コードを読んで説明はできるが、ファイルの修正もコマンド実行もできない
• エージェント：プロジェクトの中のファイルを直せる。ただし許可なしにプロジェクトの外は変更できない
• エージェント（フルアクセス）：PC上のどこでも直せて、コマンドもほぼ制限なく走らせられる

最初は読み取り専用にしてください。これなら何を頼んでも事故が起きません。「AIに勝手に壊されるのが怖い」という気持ちは、この設定で丸ごと解決します。

やること

1. Codexを読み取り専用モードにする
2. SRPGスタジオのプロジェクトフォルダを開く（zipにしない。フォルダのまま）
3. 下の質問を投げる

このフォルダはSRPG Studioというツールで作っているゲームのプロジェクトです。
私はプログラムが分かりません。

まず、次のことを調べて、専門用語をなるべく使わずに説明してください。

1. このプロジェクトにプラグインがいくつあるか
2. それぞれのプラグインが何をしているか（一行ずつ）
3. どのプラグインが、どのプラグインに依存していそうか
4. 読み込む順番に決まりがありそうな箇所はどこか
5. 競合しそうだと感じた箇所

まだ何も直さないでください。読んで報告するだけにしてください。

zipを渡していたときと違って、AIは必要なファイルだけを自分で探して開きます。だから「全部読ませたら容量で落ちる」ということが起きません。

返ってきた説明を、あなたが読んで、合っているか判定してください。

プログラムが分からなくても、これはできます。「このプラグインは戦闘アニメの再生を担当している」が合っているかどうかは、書いた本人・使っている本人にしか分かりません。AIには判定できません。

合っていたら

土台ができた証拠です。次に進みます。

ズレていたら

それが今の到達点です。落胆する場面ではなく、どこを教えれば動くようになるかが分かった場面です。ズレていた箇所をメモしておいてください。次の工程でそのまま使います。

AGENTS.md は、AIエージェント向けの説明書です。人間向けの README がプロジェクトの概要や使い方を書く場所だとすると、AGENTS.md はAIに作業時のルールと前提知識を伝えるためのファイル。Codexは作業を始める前に必ずこれを読みます。

置き場所はプロジェクトフォルダの一番上（ルート）に1ファイル。それで十分です。規模が大きくなってきたら、サブフォルダごとに置き分けることもできますが、最初から凝る必要はありません。

作り方

1. Codexに「さっき説明してくれた内容を AGENTS.md にまとめて、ルートに置いて」と頼む
2. できあがったファイルを自分で開いて読む
3. 工程②でズレていた箇所を、自分の手で書き直す
4. 「本人しか知らない前提」を足す（このプラグインは触るな、この順番は絶対、など）

書き出しの雛形

【 】の部分は、工程①②で分かったことに置き換えてください。分からない項目は、消さずに「未確認」と書いておくほうが安全です。AIに「ここはまだ分かっていない」と伝わります。

# AGENTS.md

## このプロジェクトについて
SRPG Studio で制作しているゲームのプロジェクトです。
プラグインはJavaScriptで書かれ、【プラグイン用フォルダのパス】に置かれています。

作業を依頼している人間はプログラムを読めません。
専門用語を使うときは、必ず一言で説明を添えてください。

## 絶対に守ること
- 依頼されていないファイルを変更しない
- 一度に複数のプラグインを直さない。必ず1個ずつ
- 直す前に「何をどう変えるか」を日本語で説明し、承認を待つ
- 既存の挙動を変える変更は、変える前に必ず確認を取る
- 動作確認は人間が SRPG Studio 上で行う。「動くはず」で完了にしない

## プラグインの構成
【工程①でAIが調べ、工程②であなたが直した内容をここに書く】

例：
- aaa.js … 戦闘アニメの再生を担当。bbb.js より後に読み込む必要がある
- bbb.js … アニメ用のデータを読み込む。最初に読み込まれる前提
- ccc.js … 【未確認】

## 読み込み順の決まり
【分かっている範囲で。分からなければ「未確認」と書く】

## 触ってはいけないもの
- 【自作で気に入っている部分、動いているので触りたくない部分】

## 過去に起きた事故
【同じ失敗を繰り返させないために、起きたことを書き足していく】

いきなり新しいプラグインを作らせるのではなく、「今あるプラグイン同士がぶつかっていないか調べる道具」を先に作らせます。

理由は単純で、プラグインを増やしてから壊れると、増やしたせいなのか元から壊れていたのか分からなくなるからです。先に検査の道具があれば、「入れる前は通っていた／入れたら落ちた」が確認できます。

AGENTS.md の内容を前提に、次のものを作る案を3つ出してください。

目的：今あるプラグイン同士が競合していないかを確認する仕組み

条件：
- 私はプログラムが読めないので、結果は日本語で読める形にしてほしい
- できるだけ単純な作りにしてほしい
- どれを選ぶかは私が決めるので、まだ実装はしないこと

3案それぞれについて、何ができて何ができないかを書いてください。

いきなり「作れ」ではなく複数案を出させて人間が選ぶ。これはCodexに限らず、AI全般に有効なやり方です。一発目の案が最良である保証はどこにもないので。

この段階まで来ると、AIは次の状態になっています。

• プロジェクトの構造を（あなたが答え合わせした形で）知っている
• 触ってはいけないものを知っている
• 作業前に必ずAGENTS.mdを読み直す
• 壊れたかどうかを確かめる道具がある

ここでようやく、エージェントモードに切り替えて、実際に書かせます。

1回の依頼を小さくする

「アニメーションシステムを作って」ではなく、「この一箇所を、こう動くように直して」。大きく頼むほど、確認する場所が増えて、どこで間違えたか分からなくなります。

直してもらったら、毎回SRPGスタジオを起動して自分の目で確認。ここは人間にしかできない工程です。

失敗したら戻す

変更が気に入らなければ元に戻せます。戻し方が分からなくなったら、準備工程で取ったバックアップから該当ファイルを戻せば済みます。バックアップを取っておいた意味がここで出ます。

長く作業を続けると、AIの調子は落ちます。これはCodexでも同じで、避けられません。過去の全部のやり取りを抱えたまま進むと、コスト・速度・品質のすべてで不利になるからです。

違うのは、対処法が用意されていることです。ブラウザだと「急に解析できなくなってますね」で初めて気づくしかありませんが、Codexには目盛りと道具があります。

3つのコマンド

• /status … 今どれだけコンテキストを使っているか確認する。時々これを見る癖をつける
• /compact … 会話を圧縮する。重要な情報だけ残して、続きを進めやすくする
• /model … 今どのモデルを使っているか確認する

この圧縮は、ただの要約ではありません。人間向けのきれいな要約は読みやすい代わりに、作業を続けるのに必要な細かい状態を落としがちですが、Codexの圧縮はそこを残すように作られています。実測でも、複数回の圧縮をはさみながら最初の方針や制約を保ったまま完走した、という報告があります。

それでも重くなったら

1. 「今回分かったことをAGENTS.mdに追記して」と頼む
2. セッションを終了する
3. 新しいセッションを立てる

AGENTS.mdがあるので、引き継ぎメモを毎回作る必要はありません。新しいセッションが勝手に読みます。「セッション移行したら新しいAIが直しまくってた」という状態は、この仕組みができていれば起きません。

zipを解析させるとエラーが出る

そもそもzipを渡す必要がなくなります。フォルダを開かせてください。ブラウザのアップロード枠は、大量のファイルを一度に押し込む場所として作られていません。

途中から急にトンチンカンになった

/status でコンテキストの使用量を確認。多ければ /compact。それでもダメならAGENTS.mdに追記してセッションを切り替え。

言うことを聞かない・同じ間違いを繰り返す

AGENTS.mdに書いてください。会話の中で何度言っても、セッションが変われば消えます。ファイルに書いたものだけが残ります。

Codexの画面が見当たらない

順次配信の途中である可能性があります。VS Codeの拡張機能から入るのが確実です。

怖くて手が出ない

読み取り専用モードで、ひたすら質問だけしてください。何も壊れません。「このファイルは何をしているの」を10回聞くだけでも、プロジェクトの理解が進みます。

Codex

OpenAIのコーディング用エージェント。ChatGPTに課金していれば使えます。VS Codeの拡張、デスクトップアプリ、CLI（黒い画面）など、いくつかの入口があります。

VS Code

無料のテキストエディタ。Codexの拡張を入れる土台として使います。プログラムを書かなくても、ファイルを開いて読む道具として十分役に立ちます。

モード（読み取り専用／エージェント／フルアクセス）

Codexにどこまで許すかの設定。読み取り専用なら読むだけ、エージェントならプロジェクト内を直せる、フルアクセスならPC全体。慣れるまでは上の2つで足ります。

推論レベル

答える前にどれだけ考え込むかの設定。上げると時間はかかりますが、複雑な問題に強くなります。

トークン

AIが文章を数える単位。だいたい文字数だと思っておけば実用上は困りません。コンテキストの残量はこれで数えられています。

compaction（圧縮）

長くなった会話を畳んで、必要な部分だけ残すこと。/compact で実行できます。

セッション

一続きの会話。切ると記憶は消えますが、AGENTS.mdに書いたものは残ります。

Sol / Terra / Luna / Astra

ChatGPTのモデルのグレード名。GPT-5.6世代では上からSol・Terra・Luna。Astraはその次の世代（GPT-6）です。数字が世代、名前がグレードという二階建て。