Article
Codexの使い方まとめ ～サブエージェント・Skills・便利なスラッシュコマンド～
OpenAIのCodexを使う際に知っておきたい基本的な考え方と、サブエージェント、オーケストレーション、Skills、便利なスラッシュコマンドの使い方をまとめる。
目次
はじめに
最近、OpenAIのCODEXを使ってコードの実装や調査を進める機会が増えてきた。
Codexは、単に「コードを書いてくれるツール」として使うだけでも十分便利だが、実際にはそれ以上に、既存コードの読解、設計方針の相談、複数タスクの並列化、定型作業の再利用、コードレビューなど、かなり幅広い用途で活用できる。
特に便利だと感じるのが、サブエージェント、Skills、そしてスラッシュコマンドである。簡単に導入できる割に成果が目に見えてわかるので一度試してみるのが良いかと思う。
本記事では、Codexの基本的な使い方から、実際に使いやすいコマンドや考え方までまとめる。
Codexとは何か
Codex CLIは、ターミナル上で動作するOpenAIのコーディングエージェントである。 ローカルのリポジトリを読み取り、ファイルの変更、コマンドの実行、レビュー、調査などを対話的に進められる。
普段の使い方としては、プロジェクトのディレクトリでCodexを起動し、自然言語でやってほしいことを伝える形になる。
たとえば、以下のような依頼ができる。
- このエラーの原因を調べてほしい
- Rustの認証処理を整理してほしい
- LaravelからAxumへ移行するときの差分を確認したい
- テストが落ちている箇所を修正したい
- PR前に変更内容をレビューしてほしい
このように、実装だけでなく、調査、整理、比較、検証まで一通り任せられるのが特徴である。
まず押さえておきたい使い方
Codexを使うときは、最初から大きな依頼を一気に投げるよりも、段階を分けて依頼したほうがうまくいきやすい。
例えば、以下のような順番で進めるとよい。
- まず状況を説明する
- 次に調査だけさせる
- 方針を出させる
- 実装させる
- 最後にテストやレビューをさせる
たとえば、いきなり「認証機能を全部作って」と依頼するよりも、
- 既存のログイン処理を読んで整理してほしい
- Laravel Sanctum相当の構成をAxumでどう考えるべきか提案してほしい
- その方針で最低限の実装を入れてほしい
- テスト観点も挙げてほしい
のように分けたほうが、意図に沿った結果になりやすい。
この性質に合わせて最適化した仕組みが後述するサブエージェントやSkillsである。
サブエージェントとは何か
サブエージェントは、メインのCodexが作業を分担するために起動する補助エージェントである。 大きなタスクを分解し、それぞれ別の観点で調査や処理を進めるときに役立つ。
例えば、以下のようなケースで有効である。
- 1人は認証処理を調べる
- 1人はDB周りを調べる
- 1人はフロントエンドの影響範囲を調べる
- 1人はテスト失敗原因を調べる
このように、複数の視点を並列で動かしたいときにサブエージェントが便利である。
ただし重要なのは、Codexは勝手に大量のサブエージェントを乱発するわけではなく、明示的に依頼したときに起動するという点である。 そのため、普段は通常の単独作業として使い、必要な場面だけ並列化するのが基本になる。
サブエージェントが向いている場面
サブエージェントが特に使いやすいのは、次のような場面である。
影響範囲の広い調査
たとえば「この修正を入れるとどこに影響するか」を見たいとき、 バックエンド、フロントエンド、テスト、設定ファイルを別々に調べさせると効率がよい。
複数案の比較
たとえば認証設計で、
- Cookieベース
- JWTベース
- セッションベース
のように複数案を比較したいときに、案ごとに分担させると整理しやすい。
並列でレビューしたいとき
実装後に、
- セキュリティ観点
- パフォーマンス観点
- 保守性観点
のようにレビューの軸を分ける使い方も便利である。
サブエージェントの使い方の考え方
サブエージェントをうまく使うコツは、丸投げしないことである。 「なんとなくいい感じにやって」ではなく、役割を明示するとよい。
例えば以下のように依頼すると分担が明確になる。
- サブエージェント1は既存の認証フローだけ調べて要約してほしい
- サブエージェント2はDBスキーマ変更の必要性だけ確認してほしい
- サブエージェント3はフロントエンドへの影響だけ調べてほしい
このように分けると、メインのCodexが最後に結果を統合しやすくなる。
逆に、全員に同じ曖昧な依頼をすると、似たような結果が返ってきてあまり意味がないことが多い。
オーケストレーションとは何か
オーケストレーションとは、複数の作業を整理し、順序や依存関係を管理しながら進める考え方である。 Codexにおいては、どの作業を誰に任せ、どの順番で進め、最後にどう統合するかを制御するイメージである。
サブエージェントが「作業する人」だとすると、オーケストレーションは「仕事の段取り」である。
例えば、以下のような流れがオーケストレーションに近い。
- 既存コードを読む
- 問題点を洗い出す
- 複数案を比較する
- 方針を決める
- 実装する
- テストする
- 差分をレビューする
Codexは、こうした流れの中で必要に応じてサブエージェントを起動し、結果を待ち、最後にまとめることができる。
オーケストレーションが有効な場面
大きな改修
認証、画面、API、DBが絡むような改修では、いきなり実装に入ると失敗しやすい。 まず調査を並列化し、その結果をまとめてから方針を決めるほうが安全である。
複数ステップの定型作業
例えば、以下のような作業である。
- issueの内容を読む
- 影響範囲を調査する
- 実装する
- テストする
- diffを確認する
- レビューコメント用の要約を作る
これらを毎回同じ流れで進めるなら、オーケストレーションを意識して依頼すると再現性が上がる。
複数の観点を同時に満たしたいとき
実装だけでなく、セキュリティ、性能、移行性、可読性も考慮したい場合、1回で全部求めるより、観点ごとに調査やレビューを分けるほうが整理しやすい。
Skillsとは何か
Skillsは、Codexに特定の作業手順や知識を再利用可能な形で持たせる仕組みである。 単なるメモではなく、あるタスクを安定して実行するための指示書、補助資料、必要に応じたスクリプトなどをまとめたパッケージと考えるとわかりやすい。
例えば、以下のようなものをSkill化しやすい。
- PRレビュー時の確認観点
- Laravelのマイグレーション確認手順
- Rustでのテスト失敗時の切り分け手順
- SQLレビュー時の観点
- デプロイ前チェックリスト
- 障害調査時の初動フロー
毎回同じ説明を長く書いているなら、それはSkill向きである可能性が高い。
実際のイメージが湧きにくい場合は、SKILL.md を以下のように考えるとよい。
先頭の name と description を --- で囲む部分は、Skillの概要を表す一般的な書き方である。
---
name: laravel-review
description: LaravelのPR差分をレビューするときに使う
---
# LaravelレビューSkill
## 目的
- Laravelアプリの差分レビューを安定した観点で行う
- 命名、責務分割、バリデーション、例外処理、テスト観点の漏れを減らす
## 基本手順
1. まず変更ファイルを一覧化する
2. Controller、Service、Request、Modelごとに責務の分離を見る
3. バリデーションがFormRequestなどに適切に寄っているか確認する
4. N+1、認可漏れ、例外処理漏れがないか確認する
5. 最後に重大度順で指摘をまとめる
## 出力ルール
- 指摘は重大度順に並べる
- 問題がなければその旨を明記する
- 推測で断定しない
- 必要なら確認観点だけを補足で列挙する
## よく見るポイント
- Fat Controllerになっていないか
- 認可処理が漏れていないか
- Eager Loading不足でN+1が起きないか
- 例外時のレスポンスが不自然でないか
- テスト追加が必要そうかこのように、
目的、手順、出力ルール、確認ポイントをまとめておくと、単なるメモよりかなり再利用しやすい。
特に、毎回レビュー観点や調査手順を説明している人ほど効果を感じやすいと思う。
なお、Skillは英語で書いている人も多いが、最初のうちは日本語で書いても問題ないと思う。
トークン量の削減を意識しやすく、運用ルールも自分やチームの言葉でそのまま書けるため、慣れるまでは日本語で整理したほうが扱いやすい場面も多いと感じている。
Skillsのメリット
指示のばらつきが減る
毎回同じ品質で依頼しやすくなる。 特にレビューや調査のように、観点漏れが起きやすい作業で有効である。
コンテキストを節約しやすい
Skillsは、必要なときに読み込まれる前提で設計されている。 そのため、毎回長い前提説明を会話に貼り付けなくても済みやすい。
チーム内で再利用しやすい
個人用メモにとどまらず、チームで共通の手順として扱いやすい。 運用が固まっている作業ほど相性がよい。
どういうSkillを作るとよいか
実際に作るなら、以下のようなものから始めると扱いやすい。
コードレビューSkill
- 可読性
- 命名
- 責務分割
- バリデーション
- 例外処理
- テスト有無
- セキュリティ観点
などをチェックさせる。
例えば、以下のように依頼できる。
- review-skillを使って、このPR差分をレビューしてほしい
- 命名、責務分割、バリデーション、例外処理の観点を優先して見てほしい
- 指摘は重大度順に整理し、修正したほうがよい箇所だけ簡潔にまとめてほしい
調査Skill
- まず再現条件を確認する
- ログを見る
- 関連ファイルを洗い出す
- 変更履歴を確認する
- 仮説を複数出す
- 最後に要約する
といった手順を固定化する。
例えば、以下のような依頼がしやすい。
- investigate-skillを使って、この500エラーの原因を調べてほしい
- まず再現条件を確認し、関連ログと直近変更ファイルを洗い出してほしい
- 仮説を2つ以上出したうえで、最も可能性が高い原因を最後に要約してほしい
記事執筆Skill
自分のブログ運用とも相性がよい。 例えば、
- 文末は「である」調にする
- 太字を使わない
- 見出し構成を先に整理する
- 具体例を入れる
- まとめで読者向けの一言を入れる
のようなルールをSkill化すれば、毎回同じ文体で記事を書かせやすくなる。
例えば、以下のように依頼できる。
- blog-writing-skillを使って、Laravel 13アップグレード手順の記事案を書いてほしい
- 文末は「である」調、太字は使わず、見出し構成を先に出してから本文を書いてほしい
- 初学者でも読めるように、実際のコマンド例と注意点を必ず入れてほしい
Skillsとサブエージェントの関係
Skillsとサブエージェントは別物であるが、組み合わせると便利である。
例えば、 調査用Skillを持ったサブエージェントにログ調査だけを担当 レビュー用Skillを持ったサブエージェントに差分確認だけを担当 後にメインのCodexが結果を統合する といった形である。
このように、サブエージェントは役割分担、Skillsは作業品質の安定化に寄与する。 組み合わせると、複雑な作業でも進めやすくなる。
便利なスラッシュコマンド
ここからは、実際によく使うスラッシュコマンドを紹介する。 スラッシュコマンドは、対話の途中で素早く設定変更や状況確認を行うための機能である。
特に使いやすいものを中心に見ていく。
/model
使用するモデルを切り替えるコマンドである。 作業内容に応じてモデルを変えたいときに使う。
例えば、
- 重い設計相談や複雑な読解では高性能なモデル
- 軽い整形や単純な修正では高速なモデル
のように使い分ける。
長い調査や重要なレビューでは、ここを意識すると結果の質が変わりやすい。
/fast
高速なモデルへ一時的に切り替えたいときに便利である。 軽い確認、ちょっとした整形、簡単な質問などでは十分である。
例えば、
- この関数名だけ候補を出してほしい
- このエラーメッセージの意味だけ教えてほしい
- この文章を少し短くしたい
のような用途では、まず/fastでよいことが多い。
一方で、複雑な調査や慎重な修正では、速さだけで進めると精度が落ちる可能性がある。
/permissions
Codexがどこまで自動で行動してよいかを切り替えるコマンドである。 かなり重要なコマンドであり、最初に確認したほうがよい。
例えば、
- 読み取りだけに制限したい
- 実行前に毎回確認してほしい
- 自動で進めてほしい
といった制御に使う。
慣れないうちは厳しめにしておき、安心して任せられるときだけ緩めるのがよい。 特に、既存の大きなリポジトリや本番系に近い環境では慎重なほうがよい。
/agent
エージェントや作業モードの確認、切り替えに使うコマンドである。 今どのような設定で動いているかを把握したいときに便利である。
サブエージェントを使う場面や、途中でモードを変えて進めたいときに確認すると混乱しにくい。
/status
現在のセッション状態を確認したいときに使う。 モデル、権限、その他の現在設定をすぐ見たいときに便利である。
作業途中で
「今どの設定だったか」
がわからなくなったときに、とりあえず/statusを見る習慣をつけるとよい。
/compact
会話が長くなってきたときに便利なコマンドである。 長いやり取りを圧縮し、重要な流れを保ちながらコンテキストを整理したいときに使う。
長い調査や複数ラウンドの実装をしていると、会話履歴がかなり膨らむ。 そういうときに/compactを使うと、重要な流れを保ったまま整理しやすい。
特に、
- 長時間の調査
- 何度も方針変更した作業
- 複数ファイルにまたがる修正 で有効である。
/diff
変更差分を確認したいときに便利である。 どこをどう変えたのかを見たいときに使う。
実装後は必ず見たほうがよいコマンドの1つである。 Codexに任せたあと、そのまま終わるのではなく、/diffで変更点を確認すると安心である。
特に、
- 想定外のファイルまで触っていないか
- 命名やコメントが不自然でないか
- 不要な整形が入っていないか
を確認しやすい。
/review
差分レビューや問題点の洗い出しに便利なコマンドである。 自分で実装したコードをCodexにレビューさせる使い方もよい。
例えば、
- セキュリティ上の懸念がないか
- テスト観点が足りているか
- 責務分割に無理がないか
- 例外処理が弱くないか
といった観点を見てもらえる。
実装担当とレビュー担当を擬似的に分ける感覚で使うとよい。
/init
リポジトリや作業環境の初期理解を助けるコマンドである。 新しいプロジェクトでCodexを使い始めるときに役立つ。
最初に/initを使っておくと、プロジェクト構成や基本情報を整理しやすい。 まだCodexに文脈がない状態でいきなり複雑な依頼をするより、まず現場を見てもらう感覚で使うとよい。
/mcp
MCP関連の設定や状態を扱うコマンドである。 外部ツールや追加の文脈と連携しているときに使う。
普段はあまり触らないかもしれないが、
- 社内ツール連携
- 外部サービス連携
- 独自の補助環境 などを使うなら重要になる。
/personality
応答スタイルや振る舞いの傾向を調整したいときに使う。 レビューを厳しめにしたい、説明を簡潔にしたい、などの調整に役立つ。
常用必須ではないが、作業内容によっては便利である。 例えば、記事執筆やレビューなど、出力スタイルが重要な作業では使いどころがある。
どのスラッシュコマンドをよく使うか
個人的には、最初のうちは以下だけ覚えておけば十分だと感じる。
- /status
- /permissions
- /model
- /fast
- /diff
- /review
- /compact
特に、 実装前に/statusと/permissionsを確認し、 実装後に/diffと/reviewを行う、 会話が長くなったら/compactを使う、 という流れはよく使用する。
実際の使い方の例
例えば、既存のLaravelアプリをRustへ段階的に移行したい場面を考える。
このとき、以下のように進めるとよい。
- /initでプロジェクトを把握する
- 既存の認証実装を調べさせる
- 必要ならサブエージェントを使って、バックエンド側とフロントエンド側を分けて調査する
- Laravel Sanctum相当をRust側でどう考えるべきか案を出させる
- 方針が決まったら実装させる
- /diffで変更点を確認する
- /reviewで不安点を洗い出す
- 会話が長くなったら/compactで整理する
この流れにレビューSkillや調査Skillを組み合わせることでより安定する。
まとめ
Codexは、単にコードを書かせるツールではなく、調査、整理、実装、レビューを一通り支援できるコーディングエージェントである。 その中でも、サブエージェント、オーケストレーション、Skills、スラッシュコマンドを理解して使うことで、開発作の効率化、成果物の安定化に繋がると感じた。
特に最初は、
- /statusで状態確認
- /permissionsで安全性調整
- /modelや/fastで作業速度調整
- /diffで差分確認
- /reviewで最終チェック
この流れを習慣化していき、作業が複雑になってきたらサブエージェント、繰り返し作業が見えてきたらSkills、という使い方が現状は良いようだ。使っているといつの間にかそんな感じになっていた気がする。
新しい情報や機能が出たら引き続き記事を更新、修正等をしていきたいと思う。
参考サイト等
前後の記事
関連記事
フレームワークや言語のアップデートを行うことで設計やロジックの勉強になる
簡単とみなされがちかつ業務として避けられがちなフレームワークや言語のアップデートを行うことで結構設計やロジックの勉強になるということ。
Axios改ざん事件を整理する
2026年3月末に発生したAxiosのnpm配布物改ざんについて、何が起きたのか、どう混入したのか、今すぐ確認すべき点と今後の予防策をまとめる。
PHP 8系の新機能を整理する。trait・enum・パイプ演算子は何が違うのか
PHP 8系で注目したい機能を、PHP 7系以下との違いがわかる具体的なコード付きで整理する。traitの位置づけ、enum、match、Attributes、そしてPHP 8.5で追加されたパイプ演算子までまとめて紹介。