はじめに
本記事はCodexの始め方と、より良い結果を得るための実証済みの方法を紹介します。
Codexやコーディングエージェントは昨今非常に多くの方から注目されており、多くの人が「とりあえず使ってみる」段階に入っています。
この記事は、そんな「とりあえず使ってみる」フェーズを超えて、使いこなすフェーズに入るためのガイドです。
CLI、IDE拡張、Codexアプリに共通して、プロンプト、計画、検証、MCP、Skills、Automationsまで、Codexをより効果的に使うための内容を記載しました。
Codexは、一度きりのアシスタントとして使うよりも、時間をかけて設定し、改善していくチームメイトのように扱うと非常にうまく機能します。
考え方としては、まず適切なタスク文脈を与え、継続的な指示はAGENTS.mdで管理し、Codexを自分のワークフローに合わせて設定し、MCPで外部システムを接続し、繰り返し作業はSkills化し、安定したワークフローはAutomationsで自動化する、という流れです。
それでは、Codexをより効果的に使うためのベストプラクティスを見ていきましょう🚀
文脈とプロンプトは最初から意識せよ
Codexは、たとえプロンプトが完璧でなくても、意図をいい感じに汲み取ってくれます。GPT-5.3-Codexなんて特に賢いですよね。
最小限の準備で難しい問題を渡しても、良い結果が返ってくることはよくあります。
ただ、特に大規模なコードベースや重要度の高い作業では、明確な指示があるほど結果の信頼性は高まります。
大きい、あるいは複雑なリポジトリで作業する場合、最大のポイントは、Codexに正しいタスク文脈と、何をしてほしいかの明確な指示を与えることが重要です。
プロンプトには、まず次の4つの要素を含めるのがおすすめです。
- Goal: 何を変更・構築したいか明確に
- Context: このタスクで重要なファイル、フォルダ、ドキュメント、サンプル、エラーは何か明確に
- Constraints: Codexが従うべき標準、アーキテクチャ、安全要件、慣習はあるか
- Done when: テストの通過、挙動の変更、不具合の再現停止など、完了時にどうなっていればよいか
これにより、Codexはスコープを保ちやすくなり、思い込みが減り、レビューしやすい成果物を出しやすくなります。
また、タスクの難しさに応じて推論レベルを選び、自分のワークフローに合う設定を試すことも重要です。
- Low: 速さ重視で、範囲が明確なタスク向け
- Medium / High: より複雑な変更やデバッグ向け
- Extra High: 長時間にわたる、エージェント的・推論重視のタスク向け
文脈をもっと素早く伝えたい場合は、Codexアプリ内の音声入力を使って、タイピングではなく口頭でやってほしいことを伝えるのも有効です。
難しいタスクでは、計画を立てて取り組む
タスクが複雑だったり、曖昧だったり、うまく説明しにくい場合は、Codexにいきなりコードを書かせるのではなく、まず計画を立てさせるのが有効です。
いくつか有効な方法があります。
Plan modeを活用
Plan modeでは、Codexが文脈を集め、必要に応じて確認質問をし、実装前により良い計画を作ります。/plan または Shift+Tab で切り替えられます。
Codexに質問役をさせる
やりたいことの大枠はあるが、どう説明すればいいか分からないときは、まずCodexにこちらへ質問させるのも有効です。
思い込みにツッコミを入れてもらい、ぼんやりしたアイデアを具体的な形にしてからコードを書かせる、という使い方です。
まさに壁打ち相手といったところですね。
PLANS.mdテンプレートを使う
より高度なワークフローでは、長時間または複数段階の作業に対して、CodexがPLANS.mdや実行計画テンプレートに従うよう設定できます。
AGENTS.mdで指示を再利用する
あるプロンプトのパターンがうまくいったら、次のステップはそれを毎回手で繰り返さないことです。
そこで役立つのが AGENTS.md です。
AGENTS.mdは、エージェント向けの自由形式READMEのようなものだと考えると分かりやすいです。
これは自動的にコンテキストに読み込まれ、リポジトリ内で自分やチームがCodexにどう動いてほしいかを定義する最適な場所です。
良いAGENTS.mdには、次のような内容が含まれます。
- リポジトリの構成と重要ディレクトリ
- プロジェクトの実行方法
- ビルド、テスト、lint のコマンド
- エンジニアリング上の慣習やPRの期待値
- 制約事項、やってはいけないこと
- 完了条件と検証方法
CLIの /init スラッシュコマンドを使うと、現在のディレクトリにスターター用のAGENTS.mdを素早く生成できます。
とても良い出発点ですが、チームの実際のビルド、テスト、レビュー、デプロイ方法に合わせて内容は編集すべきです。
AGENTS.mdは複数レベルで作成できます。
- 個人用のデフォルトとして
~/.codexに置くグローバルAGENTS.md - チーム共有用のリポジトリレベルAGENTS.md
- 特定ディレクトリ専用の、さらに細かいAGENTS.md
現在のディレクトリにより近い、より具体的なファイルがあれば、その指示が優先されます。
内容は実用的に保つのが大切です。
曖昧なルールを長々と書いたファイルより、短くて正確なAGENTS.mdのほうが役に立ちます。まず基本から始め、同じミスが繰り返されたときにだけルールを追加していきましょう。
AGENTS.mdが大きくなりすぎた場合は、本体は簡潔に保ち、計画・コードレビュー・アーキテクチャなど、タスク別のMarkdownファイルを参照する形にするとよいです。
Codexが同じミスを2回したら、振り返りをさせたうえでAGENTS.mdを更新しましょう。
人でもよくありますよね。
上司「これ読んでやってみて」ドキュメント ﾎﾟｲｯ
部下A「わからん」
上司「こここうやるんやで」ドキュメント 再度ﾎﾟｲｯ
部下A「わからん」
上司(ほな、ドキュメントが悪いんか...)
みたいな感じです。
Codexも人間も同じで、ドキュメントをUpdateしつつ、Codexが理解しやすい形でAGENTS.mdを改善していくのが大切です。
一貫性を貫く為にCodexの設定を活用する
設定は、セッションや利用場所をまたいでCodexの挙動を安定させる主要な方法のひとつです。
たとえば、モデル選択、推論量、サンドボックスモード、承認ポリシー、プロファイル、MCP設定などのデフォルトを指定できます。
おすすめの基本パターンは以下です。
- 個人用デフォルトは
~/.codex/config.tomlに記載- Codexアプリでは
Settings → Configuration → Open config.toml
- Codexアプリでは
- リポジトリ固有の挙動は
.codex/config.tomlに記載 - CLIを使う場合、コマンドライン上書きは一時的な場面だけに使う
config.toml では、MCPサーバー、プロファイル、マルチエージェント設定、実験的機能など、継続的に使う好みを定義できます。
直接編集してもよいですし、Codexに更新させることもできます。
Codexに更新させるのが、楽で且ついい感じにしてくれるのでおすすめです。
CodexにはOSレベルのサンドボックス機能があり、主に2つの重要な設定があります。
- Approval mode: Codexがコマンド実行前に許可を求めるタイミング
- Sandbox mode: Codexがディレクトリ内を読み書きできるか、どのファイルにアクセスできるか
コーディングエージェントに慣れていないなら、まずはデフォルト権限から始めるのが安全です。(私はもう全権限渡しちゃってますが...)
CLI、IDE、Codexアプリは、いずれも同じ設定レイヤーを共有します。できるだけ早い段階で、実際の環境に合わせてCodexを設定しておくのが大切です。
品質の問題に見えるものの多くは、実際には設定の問題です。たとえば、作業ディレクトリが違う、書き込み権限がない、モデルのデフォルトが不適切、必要なツールやコネクタがない、といったことです。
テストとレビューで信頼性を高める
Codexに変更だけさせて終わりにしないようにしましょう。
必要に応じてテストも作成させ、関連チェックを実行させ、結果を確認させ、受け入れる前にレビューもさせるのがGoodです。
Codexはこのループを回せますが、そのためには「何が良い状態なのか」を理解している必要があります。
その指針は、プロンプトかAGENTS.mdのどちらかで与えられます。
たとえば以下のような内容です。
- 変更に対するテストを書く、または更新する
- 適切なテストスイートを実行する
- lint、フォーマット、型チェックを確認する
- 最終的な挙動が依頼どおりか確認する
- 差分をレビューし、バグ、リグレッション、危険なパターンがないか見る
Codexアプリではdiffパネルを切り替えて、ローカルで変更を直接レビューできます。
特定の行をクリックしてフィードバックを与えると、それが次のCodexターンのコンテキストになります。
ここで便利なのが /review スラッシュコマンドです。
これを使うと、いくつかの方法でコードレビューができます。
- ベースブランチと比較してPR形式でレビューする
- 未コミット変更をレビューする
- 特定コミットをレビューする
- カスタムレビュー指示を使う
もしチームに code_review.md があり、それをAGENTS.mdから参照していれば、Codexはレビュー時にもその指示に従えます。
これは、レビューの振る舞いをリポジトリや担当者をまたいで統一したいチームにとって有効なパターンです。
Codexは単にコードを生成するだけの存在ではありません。
適切な指示があれば、テスト、確認、レビューまで支援可能です。
GitHub Cloudを使っている場合は、PRに対するコードレビューをCodexで実行する設定も可能です。
外部コンテキストにはMCPを使う
Codexに必要な文脈がリポジトリ外にある場合は、MCPを使うのが推奨です。
これにより、利用中のツールやシステムにCodexを接続できるため、毎回最新情報をコピー＆ペーストしてプロンプトに貼る必要がなくなります。
Model Context Protocol（MCP） は、Codexを外部ツールやシステムにつなぐためのオープン標準です。
MCPを使うべきなのは、次のような場合です。
- 必要な文脈がリポジトリ外にある
- データが頻繁に変わる
- 貼り付けた指示に頼るより、ツールを使わせたい
- ユーザーやプロジェクトをまたいで再利用できる統合が必要
Codexは、OAuth付きの STDIOサーバー と Streamable HTTPサーバー の両方をサポートしています。
Codexアプリでは Settings → MCP servers から、カスタムサーバーや推奨サーバーを確認できます。
必要なサーバーのインストールも、Codexに依頼すると支援してくれることがあります。
CLIでは codex mcp add コマンドを使って、名前やURLなどを指定してカスタムサーバーを追加できます。
ツールは、本当にワークフローを改善するものだけ追加しましょう。
最初から使っている全ツールをつなぎ込む必要はありません。まずは、日常的に繰り返している手作業を確実に減らせる1〜2個から始め、そこから広げていくのが良いです。
繰り返し作業はSkills化する
ここがなかなか重要だと筆者は感じています。
あるワークフローが繰り返し発生するようになったら、長いプロンプトや何度ものやり取りに頼るのはやめましょう。
Skill を使えば、SKILL.mdファイル、コンテキスト、補助ロジックをまとめて、Codexに一貫して適用させることができます。SkillsはCLI、IDE拡張、Codexアプリのすべてで使えます。
各Skillは1つの仕事に絞るのが大切です。
まずは具体的な2〜3個のユースケースから始め、入力と出力を明確にし、「何をするSkillか」「どんなときに使うか」が説明から分かるように書きましょう。実際にユーザーが言いそうなトリガーフレーズも含めるとよいです。
最初からすべての例外ケースをカバーしようとしなくて大丈夫です。
まずは代表的な1つのタスクをうまく動かし、そのワークフローをSkill化してから改善していくのが良いです。信頼性が上がる場合だけ、スクリプトや補助ファイルを追加しましょう。
目安として、同じプロンプトを何度も使っていたり、同じワークフローを何度も修正しているなら、それはSkillにすべきです。
Skillsは、特に次のような定型業務に有効です。
- ログのトリアージ
- リリースノートの下書き
- チェックリストに基づくPRレビュー
- 移行計画
- テレメトリやインシデントの要約
- 標準的なデバッグフロー
最初のSkill作成には $skill-creator Skill が最適で、ローカルへのインストールには $skill-installer Skill を使えます。
Skillで最も重要な要素のひとつが説明文です。何をするSkillなのか、どんなときに使うべきかが明確である必要があります。
個人用Skillsは $HOME/.agents/skills に保存され、チーム共有Skillsはリポジトリ内の .agents/skills に置くことができます。
これは新しく参加したメンバーのオンボーディングにも役立ちます。
繰り返し作業はAutomationsで自動化する
ワークフローが安定したら、今度はCodexにバックグラウンドで定期実行させることができます。
Codexアプリでは、Automationsを使って、プロジェクト、プロンプト、実行頻度、実行環境を選び、繰り返しタスクを設定できます。
ある作業が定型化してきたら、Codexアプリの Automationsタブ で自動化を作れます。
どのプロジェクトで動かすか、どのプロンプトを使うか（Skillsの呼び出しも可能）、どの頻度で走らせるかを選べます。
また、専用のGit worktreeで実行するか、ローカル環境で実行するかも選べます。詳細はGit worktreesのガイドを参照してください。
向いている用途の例は次の通りです。
- 最近のコミットの要約
- バグらしきもののスキャン
- リリースノートのドラフト作成
- CI失敗の確認
- スタンドアップ用サマリーの作成
- 定期的な分析ワークフローの実行
覚えやすいルールとして、Skillsはやり方を定義し、Automationsは実行スケジュールを定義する と考えるとよいです。
まだ人の細かな誘導が必要なら、まずSkill化するべきです。予測可能になったら、自動化が大きな効果を発揮します。
Automationsは、単なる実行だけでなく、振り返りや保守にも使えます。
最近のセッションを見直し、繰り返し発生している問題を要約し、プロンプトや指示、ワークフロー設定を改善していくのにも有効です。
セッション管理で長時間の作業を整理する
Codexのセッションは、単なるチャット履歴ではありません。
時間とともに文脈、意思決定、行動が蓄積される「作業スレッド」なので、うまく管理することが品質に大きく影響します。
CodexアプリのUIでは、スレッドをピン留めしたり、worktreeを作成したりできるため、スレッド管理がしやすくなっています。
CLIを使う場合は、次のスラッシュコマンドが特に便利です。
-
/experimental- 実験的機能を切り替え、config.tomlに追加する
-
/resume- 保存した会話を再開する
-
/fork- 元の会話履歴を保ったまま新しいスレッドを作る
-
/compact- スレッドが長くなったときに、以前の文脈を要約して圧縮する
- なお、Codexは自動で会話を圧縮することもあります
-
/agent- 並列エージェントを動かしているとき、アクティブなエージェントスレッドを切り替える
-
/theme- シンタックスハイライトのテーマを選ぶ
-
/apps- ChatGPTアプリをCodex内で直接使う
-
/status- 現在のセッション状態を確認する
基本として、ひとまとまりの作業ごとに1スレッド にするのがよいです。
同じ問題の延長であれば、同じスレッドに留まるほうが推論の流れが保持されるため有利なことが多いです。
作業が本当に分岐したときだけ fork しましょう。
また、Codexのマルチエージェント機能を使えば、限定的な作業をメインスレッドから切り離せます。
メインエージェントは中心課題に集中させ、探索、テスト、トリアージなどはサブエージェントに任せるとよいです。
よくある失敗
Codexを使い始めたばかりのときに避けたい、よくある失敗は次の通りです。
- 毎回使うルールをAGENTS.mdやSkillに移さず、プロンプトへ詰め込みすぎる
- ビルドやテストの実行方法を十分に伝えず、エージェントに自分の作業結果を確認させない
- 複数段階・複雑なタスクで計画を省く
- ワークフローを理解する前に、CodexへPC全体の権限を与える
- Git worktreeを使わず、同じファイルで複数のライブスレッドを走らせる
- 手動で安定していない定型作業を、早すぎる段階でAutomation化する
- Codexを逐一監視しなければならないもののように扱い、自分の仕事と並行して使わない
- プロジェクトごとに1スレッドにしてしまう
- 本来はタスクごとに1スレッドにすべきで、そうしないと文脈が膨れ、時間とともに結果が悪くなる
最後に
みなさんいかがだったでしょうか？
Codexは「魔法の自動化ツール」ではなく、文脈・ルール・検証を整えるほど強くなる実務パートナーです。
まずは小さく、Goal / Context / Constraints / Done when を意識した依頼から試して、うまくいった運用を AGENTS.md や Skill に積み上げてみてください。
この積み重ねが、チーム全体の開発速度と品質を確実に引き上げてくれます。
この記事が、みなさんのCodex活用の最初の一歩になればうれしいです。
それでは🖐️
参考文献
Discussion