ターミナル環境で大活躍するCodex CLIですが、日常の定型処理を自動化するときに「もっと柔軟にパラメータを渡せたら便利なのに」と感じることはありませんか。ネットのレビューや古い解説動画を見ていると、Codex CLIのカスタムコマンドは引数に対応していないという情報が流れていることもあって、諦めてファイルをごりごり量産している人もいるかもしれません。でも、実はこれって大きな誤解なんです。最新の仕様をしっかり盛り込めば、位置引数も名前付き引数もばっちり動かせます。開発現場でのルーティンワークを劇的に効率化するために、まずは基本となる設定方法や引数の設計構文について分かりやすく解説していきますね。
- Codex CLIでカスタムコマンドを自動検出させるためのファイル配置ルール
- 「引数が渡せない」という誤解を解消するフロントマターの正確な記述方法
- 位置引数（$1）や名前付き引数（KEY=value）をプロンプトへ組み込む構文
- 設定変更を反映させる手順と3,000文字超の入力で発生するバグの回避策
codexのカスタムコマンドで引数を使う方法
カスタムプロンプトの基本と設定
Codex CLIのTUI（Text User Interface）セッションを立ち上げて、スラッシュ（/）を入力すると色々な命令がポップアップしますよね。これがコマンド機能です。最初から用意されている「ビルトインコマンド」も便利ですが、自分だけの専用プロンプトを「カスタムコマンド」として登録すると、一気に作業が快適になりますよ。定型的なコード生成やレビューの自動化、あるいは特定のフレームワークに沿ったボイラープレートの出力など、日常的に繰り返すプロンプト入力をコマンド一つで呼び出せるようになるのが最大の魅力です。
カスタムコマンドをCodex CLIに認識させるには、特定のディレクトリにMarkdown形式（.md）でプロンプトファイルを保存する必要があります。自動検出の対象になる場所は、以下の2パターンの領域に分かれているので覚えておくと便利かなと思います。チーム全体やグローバル環境で共通して使いたいコマンドと、特定のリポジトリやプロジェクト内に閉じ込めておきたい個別ルールを綺麗に分離して管理することができる、非常に洗練された設計になっているんですね。
プロンプトファイルの配置場所
- グローバル領域（PC全体で共有）:
~/.codex/prompts/ - プロジェクトローカル領域（特定のリポジトリ専用）: 各作業リポジトリのルート直下にある
prompts/フォルダ
Codex CLIが起動するときに、これらのフォルダ内にあるMarkdownファイルがスキャンされて、自動的にコマンドとしてメモリに読み込まれます。ファイルの内部では、コマンド名や説明文、引数のヒントなどが構造化されて保持される仕組みです。ローカル領域に配置したプロンプトファイルは、Gitなどのバージョン管理システムにそのまま含めることができるため、チーム内で「開発規約に準拠したコードレビュー用コマンド」や「特定のAPIスタブ生成コマンド」を簡単に共有・デプロイできるというメリットもあります。
ここで1点だけ気をつけたいのが、ファイル名（＝コマンド名）の重複です。標準機能である「init」や「compact」「model」「approvals」といったビルトインコマンドと完全に同じ名前でカスタムファイルを作ってしまうと、衝突を避けるためにシステム側から無視されてしまいます。そのため、自分でファイルを作るときは「my-init.md」や「dev-review.md」のように、独自の接頭辞をつけてユニークな名前にするのが安全でおすすめです。また、アンダースコア（_）やハイフン（-）を効果的に使って、カテゴリごとにコマンドを分類するのも、後から管理しやすくなるコツかなと思います。
引数は渡せないという誤解の真相
初期の検証ブログやちょっと古いチュートリアルを見ると、「Codex CLIのカスタムコマンドは引数を直接処理できないから、やりたいこと別にファイルを分けるか、呼び出した後に手動でコンポーザーにパラメータを追記するしかない」と書かれているケースが散見されます。これを読んで「不便だな」「実用性が低いかも」と思った方もいるかもしれません。特に、海外のアーリーアダプターによる初期リポジトリのIssue報告などをそのまま翻訳した情報サイトでは、引数の非対応が確定仕様であるかのように語られていることが多々あります。
でも、「Codex CLIは引数を渡せない」というのは過去の情報、あるいは誤解です。現在の仕様では、Markdownファイルの冒頭に「フロントマター」と呼ばれるYAMLやJSON形式のメタデータを正しく記述してあげれば、スペース区切りの位置引数（$1〜$9や$ARGUMENTS）だけでなく、変数名を指定する名前付き引数（KEY=value）も完全にサポートされています。CLIの進化スピードは非常に早いため、ドキュメントのアップデートが追いついていないケースや、ユーザー側が古いパース仕様のまま試してしまって失敗しているケースがほとんどなんですよね。
ファイル呼び出しと同時に動的なパラメータをLLMのプロンプトに流し込めるので、わざわざ似たようなプロンプトファイルをいくつも量産する必要はありませんよ。例えば、「リファクタリング対象の関数名」や「ターゲットとするプログラミング言語」「厳格さのレベル」などを引数として外出しにすれば、1つのベースプロンプトファイルをあらゆるシチュエーションで使い回すことが可能になります。これにより、プロンプトのメンテナンスコストが劇的に下がり、ロジックの修正が必要になった際も1つのファイルを書き換えるだけで済むようになります。
フロントマターの書き方とルール
では、実際に引数を機能させるためのMarkdownファイルの具体的な書き方を見ていきましょう。肝心なのは、ファイルの最上部にメタデータを書く「フロントマター形式」をしっかりと遵守することです。3つのダッシュ（—）でメタデータブロックを上下に区切り、その下にプロンプトの本文を記述します。このフロントマター部分は、Codex CLIの内部システムがコマンドの挙動を制御するための「設計図」として解釈されるため、1文字のタイポやインデントのミスが原因でコマンド自体が認識されなくなることもあるので注意が必要です。
フロントマター内で設定する主なプロパティは、以下の3つが基本になります。これらを網羅することで、TUI環境との親和性が極めて高い洗練されたカスタムコマンドが完成します。
| プロパティ名 | 役割・表示場所 |
|---|---|
| name | スラッシュコマンドとして呼び出すときの固有の識別子（例: draftpr） |
| description | TUIのポップアップ画面で、選択肢の下部に表示される機能説明のテキスト |
| argument_hint | ユーザーに必要なパラメータを伝えるためのヒント（未入力時のプレースホルダー） |
設計の作法として、argument_hint に引数を書くときは、必須のパラメータを不等号括弧（<変数名>）、省略可能なオプションパラメータを角括弧（[変数名=初期値]）で表現するのが一般的です。これをしておくと、TUIでコマンドを選んだときに「何を入れればいいか」が一目で分かるようになるので、ツールとしての使いやすさが格段にアップします。また、JSON形式のフロントマターを好む開発者もいますが、可読性や編集のしやすさを考慮すると、基本的にはYAML形式（3つのダッシュで囲むスタイル）で記述するのが最もトラブルが少なく、コミュニティでも標準的なアプローチとされていますね。
位置引数と名前付き引数の構文
フロントマターの下に書くプロンプト本文の中で、動的に値を置き換えたい部分には専用のプレースホルダー（変数）を仕込みます。Codex CLIの内部パーサーが解釈してくれる構文のバリエーションを整理してみました。用途に合わせてこれらを適切に使い分けることで、LLMへの指示の解像度を極限まで高めることができます。
- $1 〜 $9: コマンドの後ろにスペース区切りで入力された値を、順番にそのまま展開します。引数の数が決まっていて、パパッと短い値を流し込みたいときに重宝します。例えば、
/review auth_service.py strictのように入力すれば、$1にファイル名、$2にレビュー方針が代入されます。 - $ARGUMENTS: コマンドの後に続く入力文字列を、スペースなども含めて丸ごとすべて展開します。自由な指示文や自然言語のメッセージをそのままプロンプトに統合したいときに最適です。一時的な追加のコンテキストや、その場限りの特殊な命令を付け加えたいときに非常に強力な威力を発揮します。
- $KEY（大文字の英字変数）:
KEY=valueの形式で指定された、対応するキーの値をピンポイントで展開します。引数の順番を気にせず、複数の動的変数を安全かつ確実に扱いたいときに向いています。記述が自己組織化されるため、後からプロンプトを見返したときにも、どの変数がどこにバインドされているのかが直感的に分かります。 - $$: リテラルとしての「$」マークです。プロンプトの中にシェルスクリプトの変数（例：
$PATHなど）やドル表記の金額が含まれている場合、システムに変数置換だと勘違いされないように保護するために使います。このエスケープ処理を忘れると、予期せぬパースエラーやプロンプトの欠落の原因になるので注意しましょう。
ここで、名前付き引数を使った実践的なカスタムプロンプトのファイル例を紹介しますね。Pull Requestの下書きを自動生成するエージェントの定義ファイルを想定しています。
カスタムプロンプトの実装例（~/.codex/prompts/draftpr.md）
---
name: draftpr
description: 変更内容を作業ブランチにコミットし、下書き用のPull Requestを起票します
argument_hint: FILES="..." PR_TITLE="..."
---
開発環境において以下の作業を順次実行してください。
1. 作業用の新規ブランチを作成します。
2. 名前付き引数 $FILES が提供されている場合は、対象ファイルのみをステージングしてください：
対象ファイル: $FILES
提供されていない場合は、Gitの差分を自動検知してコミット候補を選択してください。
3. 明確なメッセージを添えてコミットを確定させます。
4. 下書きPR（Draft PR）を開きます。タイトルには $PR_TITLE を優先的に使用し、指定がない場合は変更履歴から自動的に簡潔なサマリーを生成して適用してください。このファイルを配置した状態で、Codex CLIのTUIコンポーザーから以下のようにスラッシュコマンドを実行します。
/prompts:draftpr FILES="src/app.ts src/api.ts" PR_TITLE="APIローディング状態の実装"
こう入力して実行すると、内部のパーサーが $FILES を指定のファイル群に、$PR_TITLE を指定のタイトル文字列へと物理的に置き換えた上で、LLMに推論リクエストを投げてくれます。値の中にスペースを含めたいときは、上記の例のようにダブルクォーテーションで囲んであげればパースエラーにならず、きれいに処理されますよ。シングルクォーテーションだと環境によってはパースが不安定になることがあるため、文字列の括りはダブルクォーテーションで統一するのが確実かなと思います。
記述を変更した後の再起動手順
カスタムコマンドのMarkdownファイルを新しく追加したり、引数のプレースホルダーの書き換えを行ったりしたとき、起動しっぱなしのCodex CLIセッションにはその変更がリアルタイムで反映されません。ファイルシステムを常時監視（ホットリロード）しているわけではないため、内部メモリにキャッシュされた古いコマンド定義がそのまま使われてしまうんですよね。「書き換えたのにうまく引数が展開されないな」「新しく作ったファイルが候補に出てこない」と思ったら、一度セッションをコールドリスタートさせてみてください。
変更を有効化するには、TUIコンポーザー上で Ctrl+C を2回連続でポンポンと押すか、あるいは /exit もしくは /quit とコマンドを打ち込んで、エージェントループを完全に終了させます。その後、再びターミナルで codex と叩いて再起動すれば、最新のファイル内容がインメモリにしっかりとリロードされます。この再起動の手間を惜しんで「おかしいな」と悩み続けてしまう開発者が意外と多いので、プロンプトを編集したら「即座にCtrl+Cを連打して再起動」をセットで覚えておくのが、無駄な時間を使わないための鉄則かなと思います。
大容量テキスト入力時のパースエラー
カスタムコマンドの引数機能を使う上で、開発者コミュニティでもよく話題にのぼる重大なシステムバグ（仕様上の制限）があります。それが、引数に引き渡す入力情報のサイズ制限に起因する挙動の破綻です。これはターミナルのバッファサイズやエミュレーターのペースト処理の仕組みが深く絡んでいる問題です。
TUIの画面上で /prompts:my-command を入力した後、引数（$ARGUMENTSなど）として受け取らせるために、3,000文字を超えるような巨大なログデータや長大なソースコードをコンポーザーにコピー＆ペーストすることがあるかもしれません。その際、エミュレーターのバッファ制御によって、画面上の表示が [Pasted Content 3000 chars] という省略表示の文字列に置き換わってしまうことがあります。これはターミナルUIがフリーズするのを防ぐための親切心からくる機能なのですが、これが裏目に出てしまうんです。
巨大なテキストを引数に入れるとコマンドが壊れる？
この「省略表示」のトリガーが引かれてしまうと、Codex CLIのパーサーが行頭の / をスラッシュコマンドとして正しく認識できなくなるバグが発生します。結果として、せっかく書いたコマンド全体が単なる「普通の質問文（プレーンテキスト）」として扱われてしまい、中のプレースホルダー変数が置換されないままLLMへ送信されてしまいます。AIからは「$1という変数の意味がわかりません」といった的外れな返答が返ってくることになり、作業が中断してしまいます。
これを防ぐための対策として、長大なテキストやコード片をカスタムコマンドに渡したいときは、引数としてコンポーザーに直接貼り付けるのは避けるのが賢明です。代わりに、Codex CLIのファジーファイル検索機能（@ を使ったファイル添付機能）を利用して、該当ファイルをコンテキストとして直接横に添えてあげるアプローチをとると、パースエラーを起こさずに安定して処理させることができますよ。引数には「処理のモード」や「短い指示のキーワード」だけを渡し、重たい生データはファイル参照機能でLLMに読み込ませる、という役割分担がCLI自動化を成功させる重要なノウハウになります。
codexのカスタムコマンドと引数の活用術
ここまでCodex CLI単体での引数の扱い方を見てきましたが、「codex カスタム コマンド 引数」と調べている開発者の多くは、他の強力なAIコーディングツールと比べてどのような違いがあるのか、どちらが自分のワークフローに合っているのかをチェックしていることが多いかなと思います。ここからは、人気を集める「Cursor」や「Claude Code」といった競合ツールの引数設計思想を引っ張り出して比較しつつ、これからのAI自動化のトレンドについて深掘りしていきましょう。
cursorのコマンド仕様との違い
IDEベースのAIエディタとして圧倒的なシェアを持つ「Cursor」も、最近「Custom Slash Commands」という機能の仕様アップデートを行いました。チーム開発でプロンプトを共有しやすくなったと評判ですが、Codex CLIとは少し違ったアプローチをとっています。エディタのUIとシームレスに融合しているため、引数の渡し方やその後のコンテキスト処理において、より視覚的で直感的な操作が可能になっているのが特徴です。
Cursorの場合、リポジトリの直下に .cursor/commands/[コマンド名].md という形でファイルを保存すれば、チャットやComposerの画面からスラッシュコマンドとして呼び出せるようになります。引数の処理に関しては、入力された文字列全体をバインドする $ARGUMENTS 変数をサポートしています。ここまではCodex CLIと似ていますが、大きな違いはその解決方法にあります。
たとえば、/flutter-code-review full save のように呼び出すと、後ろにくっつけた「full（全体スキャンという意味）」や「save（レポートを保存するという意味）」といったスイッチパラメータを引数として丸ごと受け取れます。そして、プロンプト内に記述された「もし引数にfullが含まれていたら〜」という条件分岐の指示に従って、AIが動的に振る舞いを変えるという制御の仕方をします。変数を物理的に文字列置換するCodex CLIのスタイルに比べると、よりLLMのコンテキスト理解に頼った柔軟な設計になっているのが特徴ですね。物理的な置換がない分、構文エラーでプロンプト全体がクラッシュするリスクが低いのもCursorの強みと言えます。
tasks.jsonでの自動化連携
AIによる高度な文脈理解を必要としない、純粋なCLIツールの高速実行という意味では、Cursor（VS Code）ならではの「タスクショートカット（Task Shortcuts）」という代替アプローチも非常に強力です。これはAI機能ではなく、エディタが元々持っている .vscode/tasks.json を流用する仕組みになります。実は、すべての自動化をLLMに投げ出すのではなく、従来の決定論的なスクリプト実行と組み合わせることで、開発効率はさらに何倍にも跳ね上がります。
tasks.json の中に、${relativeFile} や ${fileBasename} といったVS Codeの内蔵環境変数を仕込んだシェルタスクを登録しておき、特定のキーバインドを割り当てます。すると、いま自分が開いて編集しているファイルパスを動的な引数として、ローカルのLinterやテストランナー、あるいは自作のスクリプトへ一瞬で引き渡すことができます。例えば、「現在開いているファイルに対してのみテストを実行する」といった処理は、AIに頼るよりもこの仕組みを使った方が遥かに高速で正確です。
AIエージェントに大局的なコード改修や複雑なロジック生成をお願いするワークフローと、こうした軽量で確実なターミナル自動化の仕組みを上手く二重構造で使い分けることこそが、開発者体験（DX）を最大化する鍵になるかなと思います。何でもかんでもAIに引数をパースさせるのではなく、適材適所でツールをマッピングする視点を持つことが大切ですね。
各種AIツールの機能比較一覧
それぞれのAIツールが備えているプロンプトの拡張機能や、引数のバインド機構について、仕様の違いを分かりやすく表にマッピングしてみました。自分の開発スタイルや、普段使っているメインのエディタ環境に合わせて、どれをどのように組み合わせるかの参考にしてみてください。
| 項目・仕様 | Codex CLI (Custom) | Cursor (Slash Cmd) | Cursor (Tasks) | Claude Code |
|---|---|---|---|---|
| 起動環境 | ターミナル (TUI) | IDEチャット/Composer | エディタ内蔵ターミナル | ターミナル (CLI) |
| 定義の場所 | ~/.codex/prompts/ | .cursor/commands/ | .vscode/tasks.json | .claude/commands/ |
| コマンド接頭辞 | /prompts:<name> | /<command> | キーバインド/パレット | /<command> |
| 引数の解決方法 | システムによる変数置換 | LLMによる条件判定 | VS Code変数のシェル展開 | インラインパース |
| 主な用途 | 定型プロンプトの高速実行 | 規約チェック・レビュー | ローカルツールのワンキー実行 | ターミナル自動化の短縮 |
今後の主流となるエージェントスキル
「Codexのカスタムコマンドの引数を使いこなしたい」と技術を深掘りしていくと、実はOpenAIが打ち出している大きなアーキテクチャの転換点に突き当たることになります。それが、従来のカスタムプロンプト形式の非推奨化と、新機能である「Agent Skills（エージェントスキル）」への移行方針です。AIテクノロジーの進化は恐ろしいほど早く、私たちが「便利なテクニック」として習得した構文が、翌年にはより高度な概念に上書きされることも珍しくありません。
公式の動向を追いかけていくと、これまで説明してきた「プログラムによる物理的な文字列置換（$1 や $ARGUMENTS などのバインド処理）」は、AIエージェントの進化における過渡期の技術として位置づけられており、今後はSkills機能への集約が推奨されています。ツールを長く使いこなすためにも、この先の移行ロードマップを意識しておくことはすごく大切かなと思います。開発コミュニティでも、今後のメジャーアップデートにおいて古いプレースホルダー置換は段階的に廃止され、より人間的な指示のやり取りができるSkillsがコアシステムになることが明言されています。
（出典：OpenAI Official Blog）
このパラダイムシフトに取り残されないようにするためには、単に「仕組みとして動くから」と古い構文に固執するのではなく、公式が提示するベストプラクティスを先取りして、プロンプトの設計思想自体を「エージェントファースト」に切り替えていく柔軟性が求められます。次章で解説する新しい引数の設計思想は、まさにその一歩となる重要なアプローチです。
自然言語による新しい引数設計
物理的置換からセマンティクス理解への大転換
なぜ物理的な置換から「Agent Skills」へ移行するのかというと、LLM自身の推論能力が飛躍的に向上したからです。以前のように、エージェントのシステム側で変数に文字を無理やり詰め込んでからLLMに送らなくても、関連する専門知識やベースの指示（SKILL.md）をそのままコンテキストに注入してあげれば、「ユーザーが追加で指定した情報（引数に相当するもの）」をLLM自身が自然言語の文脈から柔軟に判断して適用できるようになりました。この方が、パースエラーも起きにくく記述の自由度も圧倒的に高いんですね。
Agent Skillsにおけるタスクと引数の設計手順は、以下のように新しく定義されています。これまでの仕組みに比べて、人間が日常会話で指示を出すかのような滑らかさで、エージェントの振る舞いをコントロールできるようになっています。
Agent Skillsの設定手順と実践ファイル構成
まず、スキルはフォルダ単位で管理し、ファイル名は必ず SKILL.md に統一します。これにより、Codex CLIはフォルダ名をスキル名として自動認識し、内部のマークダウンファイルをスキル定義としてロードします。
~/.codex/skills/audit/SKILL.md
ファイル内では、カスタムプロンプトと同じようにフロントマターで名前や argument-hint を設定しますが、本文中では $1 などの置換用変数は使わず、以下のように自然言語で抽出ルールを記述します。置換マーカーを排除したことで、文章としての自然な可読性が大幅に向上していることが分かります。
---
name: audit
description: 特定モジュールの品質やセキュリティを監査します。
argument-hint: <target_module> [MODE=strict]
---
提供されたターゲットモジュールを対象に、静的解析を実行してください。
もし名前付き引数として MODE が "strict" で指定されている場合は、セキュリティの監査基準を最大まで引き上げてレポートを作成してください。呼び出すときは、TUIコンポーザーで $ を入力するとロードされているスキルの一覧が出現するので、以下のように指定して実行します。スラッシュコマンドではなく、ドルマークから始まるのがスキル呼び出しのサインです。
$audit src/controllers MODE=strict
これにより、Codex CLIは SKILL.md の中身をバックグラウンドの文脈に綺麗に滑り込ませます。LLMは、ユーザーが直に入力した実引数（src/controllers と strict）を高度なセマンティクス（意味理解）に基づいて解釈し、指示通りの挙動を自律的に組み立ててくれるようになります。まさに「脱・物理プロンプト置換」の技術シフトが始まっていると言えますね。これに慣れてしまうと、いちいち $1 や $2 の順番を気にしてプロンプトを組み立てていた頃が、随分と遠い昔のように感じられるはずです。
codexのカスタムコマンドと引数のまとめ
今回は、検索需要の高い「codex カスタム コマンド 引数」というテーマについて、基本的な設定方法から具体的な構文、そして次世代の設計思想であるエージェントスキルへの移行戦略まで一気にご紹介しました。情報が錯綜しがちなCLIツールの仕様ですが、構造を一つずつ紐解いていけば、決して難しいものではないことがお分かりいただけたかなと思います。
「カスタムコマンドでは引数が使えない」というのは古い情報であり、フロントマターとプレースホルダー（$1 や $KEY）を活用すれば、現在でも動的で強力な定型ワークフローを組むことが可能です。ただし、長文入力時のパースバグなどCLI特有の制約もあるため、状況に応じてCursorのSlash CommandsやVS Codeの tasks.json といった周辺ツールを使い分けるのが賢い選択かなと思います。ツールの仕様に自分を合わせるのではなく、実現したい自動化の特性に合わせて最適な道具を選択する視点が、エンジニアとしては一番大切です。
さらに一歩進んだ自動化を目指すなら、今後の主流となる「Agent Skills」を見据え、物理的な文字列置換から「LLMの自然言語理解に引数の解釈を委ねる」という新しい設計スタイルに少しずつ慣れていくのがおすすめです。設計の抽象度を上げることで、ツールのアップデートに左右されない堅牢なプロンプト資産を築くことができます。ぜひ、今回紹介した仕様をベースにして、日々のコーディング自動化をより快適なものにアップデートしてみてくださいね。
