MENU
3DCG・ゲーム開発の知見をゆるく深く
  1. ホーム
  2. AIエージェント解説
  3. Codex
  4. Codexプロンプト設計｜Goal・Context・Done whenの書き方

Codexプロンプト設計｜Goal・Context・Done whenの書き方

Codex
Codexプロンプト設計｜Goal・Context・Done whenの書き方

Codex は、短い依頼でもある程度動いてくれます。しかし、リポジトリが大きい場合や、バグ修正・テスト追加・設計変更のように失敗したくない作業では、プロンプトの書き方が結果の安定性を大きく左右します。

この記事では、OpenAI公式のCodex Best practicesで紹介されている Goal / Context / Constraints / Done when の考え方を、初心者向けに分解します。悪い依頼文と良い依頼文の比較、タスク別テンプレート、検証条件の書き方まで整理します。

夕宮たいだ

ふぁ……みんな〜、今日は Codex への頼み方を整えるよぉ。魔法の呪文じゃなくて、作業指示書を短く書く感じなんだぁ。

目次

1. なぜプロンプト設計が必要なのか

ひとことで：Codexに任せる範囲と完了条件を明確にすると、結果をレビューしやすくなります。

Codex は、コードを読み、ファイルを編集し、コマンドを実行できるAIエージェントです。つまり、ただ質問に答えるだけでなく、実際の作業を進めます。だからこそ、依頼文が曖昧だと、Codexが「どこまでやるべきか」を推測する範囲が広くなります。

たとえば、次の依頼は危険です。

ログイン画面をいい感じに直して。

この依頼では、何を直すのか、どのファイルが対象なのか、デザイン変更なのか、バグ修正なのか、完了条件は何なのかが分かりません。Codexが頑張ってくれても、結果をレビューする人間側が困ります。

一方で、次のように書くと、作業の範囲が見えます。

Goal:
ログイン画面のエラーメッセージを、ユーザーが原因を理解しやすい文言に改善してください。

Context:
対象は `src/pages/Login.tsx` と、既存のエラーメッセージ定義です。
文体は他のフォーム画面に合わせてください。

Constraints:
認証処理やAPI仕様は変更しないでください。
UIレイアウトも大きく変えないでください。

Done when:
文言変更の差分が最小限で、既存テストが通り、変更したメッセージの一覧を報告できたら完了です。

このように、Codexへの依頼は「お願い」ではなく、小さな作業指示書として書くと安定します。

夕宮たいだ

ほよ？「いい感じに」って、AIにもけっこう難しいんだねぇ。どこを、どう、どこまでやるかを書いてあげるのが大事なんだぁ。

2. 4要素：Goal / Context / Constraints / Done when

ひとことで：良いプロンプトは、目的・文脈・制約・完了条件の4要素で組み立てます。

OpenAI公式のCodex Best practicesでは、良いプロンプトの基本として、Goal、Context、Constraints、Done when の4要素が紹介されています。

日本語で覚えるなら、次の対応です。

公式用語日本語での意味書くこと
Goal目的何を変えたいか、何を作りたいか
Context文脈関連ファイル、エラー、仕様、参考例
Constraints制約変えてはいけないもの、守るルール、安全条件
Done when完了条件何が通れば完了か、どう確認するか
CodexプロンプトをGoal、Context、Constraints、Done whenの4要素で組み立てる図
図1：良いプロンプトは4要素で組み立てる

この4要素が揃うと、Codexは作業範囲を絞りやすくなります。また、ユーザー側も「この差分は依頼どおりか」を確認しやすくなります。

逆に、4要素のどれかが抜けると、次のようなズレが起きやすくなります。

  • Goalが曖昧：Codexが何を達成すべきか分からない
  • Contextが不足：関係ないファイルを探し回る、既存パターンに合わない
  • Constraintsがない：変更範囲が広がる、APIや設計を勝手に変える
  • Done whenがない：テストや確認なしで終わったように見える
夕宮たいだ

ていねいに整理するねぇ。Goal は目的、Context は材料、Constraints は守るルール、Done when はゴール判定なんだぁ。

3. 悪いプロンプトと良いプロンプト

ひとことで：良いプロンプトは、Codexが迷う余地を減らし、人間がレビューしやすい形にします。

悪いCodexプロンプトと良いCodexプロンプトの比較図
図2：曖昧な依頼より、構造化した依頼の方がレビューしやすい

まずは悪い例を見てみます。

このバグ直して。

これだけでは、Codexは何を見ればよいか分かりません。バグの内容、再現手順、期待結果、実際の結果、触ってよい範囲、検証方法がすべて抜けています。

良い例は次のようになります。

Goal:
設定画面で「保存しました」と表示されるのに、リロードすると設定が戻る不具合を修正してください。

Context:
再現手順:
1. `npm run dev` で起動する
2. `/settings` を開く
3. 「通知を有効にする」をONにする
4. 保存ボタンを押す
5. ページをリロードするとOFFに戻る

関連しそうなファイル:
`src/pages/Settings.tsx`
`src/api/settings.ts`

Constraints:
APIのリクエスト形式は変更しないでください。
修正は最小限にしてください。
可能であれば回帰テストを追加してください。

Done when:
再現手順で設定が保持されることを確認し、実行したコマンドと結果を報告してください。

この例では、再現手順、関連ファイル、変えてはいけないもの、完了条件が揃っています。Codexは何をすべきか判断しやすくなり、ユーザーも差分を確認しやすくなります。

4. Goal：目的を書く

ひとことで：Goalには「何を達成したいか」を1〜2文で書きます。

Goal は、Codexへの依頼の中心です。ここが曖昧だと、後ろの文脈や制約があっても作業の方向がぶれます。

悪いGoalの例です。

  • いい感じにして
  • 直して
  • きれいにして
  • もっと使いやすくして

これらは人間同士の会話でも曖昧です。Codexには、もう少し具体的に書きます。

良いGoalの例です。

  • ログイン失敗時のエラーメッセージを、原因別に分かりやすくしてください
  • 商品一覧ページの表示速度が遅い原因を調査してください
  • UserCard コンポーネントに、既存の書き方に合わせてユニットテストを追加してください
  • READMEのセットアップ手順を、現在のコマンドに合わせて更新してください

Goalを書くときは、「変更対象」と「達成したい状態」を入れると安定します。

Goal:
`UserCard` コンポーネントに、既存テストの書き方に合わせたユニットテストを追加してください。

「何となく改善」ではなく、「何がどうなればよいか」を書くのが基本です。

5. Context：文脈を書く

ひとことで：Contextには、Codexに見てほしい材料を渡します。

Context は、Codexが作業するときの材料です。公式のPromptingページでも、関連ファイルや画像など、Codexが使える文脈を含めることが案内されています。

Contextに入れるものは、次のような情報です。

  • 関連ファイルやフォルダ
  • エラーメッセージやスタックトレース
  • 再現手順
  • 参考にしてほしい既存実装
  • 守りたい文体やデザインパターン
  • 画像、スクリーンショット、仕様メモ

IDE extensionでは、開いているファイルや選択範囲が文脈に入りやすい一方、CLIではパスを明示した方が安全です。たとえば次のように書きます。

Context:
関連しそうなファイルは `src/components/UserCard.tsx` と `src/components/UserCard.test.tsx` です。
既存テストの書き方は `src/components/Button.test.tsx` を参考にしてください。

Contextを書くときのコツは、「全部見て」ではなく、「まずここを見て」と渡すことです。Codexは必要に応じて追加で探索できますが、入口を示すと作業が速くなり、意図も伝わりやすくなります。

夕宮たいだ

「全部見て〜」だと、ちょっと広すぎるんだねぇ。最初に見る場所を教えてあげると、Codexも迷いにくいんだぁ。

6. Constraints：制約を書く

ひとことで：Constraintsには、変えてはいけないものと守るルールを書きます。

Constraints は、Codexの暴走を防ぐための境界線です。ここがないと、Codexが良かれと思って大きなリファクタをしたり、API仕様を変えたり、関係ないファイルまで整えたりすることがあります。

よく使う制約は次のとおりです。

  • 変更は最小限にしてください
  • APIのリクエスト/レスポンス形式は変更しないでください
  • UIレイアウトは変えないでください
  • 既存の命名規則に合わせてください
  • 新しい依存パッケージは追加しないでください
  • 秘密情報や.envは読まないでください
  • まず方針を提示し、実装は確認後にしてください

たとえば、バグ修正では次のように書きます。

Constraints:
APIの形は変更しないでください。
修正は最小限にしてください。
新しい依存パッケージは追加しないでください。
実装前に変更方針を提示してください。

制約を書くと、Codexが「良い改善」を広げすぎるのを防げます。特に初心者のうちは、「最小限」「実装前に方針提示」「新規依存なし」の3つをよく使います。

夕宮たいだ

「ついでに全部きれいにして」は、最初はダメだよぉ。小さく直して、小さく確認するのが安全なんだぁ。

7. Done when：完了条件を書く

ひとことで：Done whenには、作業が終わったと言える条件を書きます。

Done when は、Codexがどこで作業を終えればよいかを示す条件です。OpenAI公式のPromptingページでも、Codexが自分の作業を検証できると出力品質が上がると説明されています。

完了条件には、次のようなものを書きます。

  • 指定したテストが通る
  • lintやformatが通る
  • 再現手順で不具合が起きない
  • READMEの手順どおりに起動できる
  • 変更ファイルと理由を報告する
  • 実行したコマンドと結果を報告する

たとえば、バグ修正なら次のように書きます。

Done when:
再現手順で不具合が起きないことを確認してください。
可能であれば関連テストを追加してください。
最後に、変更したファイル、実行したコマンド、確認結果を箇条書きで報告してください。

Done whenを書くと、Codexが「編集して終わり」ではなく、「確認して報告する」流れに入りやすくなります。人間側も、その報告をもとに差分を確認できます。

8. 段階的に依頼する

ひとことで：難しい作業は、調査、方針、実装、検証に分けて頼みます。

Codexへの複雑な依頼を調査、方針、実装、検証に分けるフロー
図3：難しい作業は段階的に依頼する

複雑なタスクを一度に頼むと、Codexの作業範囲が広がりすぎます。公式のBest practicesでも、複雑・曖昧な作業では、先に計画を作らせる方法が案内されています。

初心者は、次の4段階に分けると安全です。

  1. 調査してください
  2. 変更方針を提示してください
  3. 方針に沿って最小限で実装してください
  4. テスト・確認を実行し、結果を報告してください

一度に頼む場合でも、プロンプトの中で段階を明記します。

まず関連ファイルを調査してください。
次に、変更方針を箇条書きで提示してください。
方針に問題がなければ、最小限の修正を行ってください。
最後に、実行した確認コマンドと結果を報告してください。

大きな機能追加、影響範囲が分からないバグ、既存設計に不安がある作業では、最初から「実装して」ではなく「まず計画して」と頼みます。

夕宮たいだ

ほら、便利でしょ？「まず調査して」「次に方針」って分けるだけで、レビューしやすさがかなり変わるんだぁ。

9. タスク別プロンプトテンプレート

ひとことで：よく使う作業は、型として保存しておくと再利用できます。

最後に、すぐ使えるテンプレートを3つ紹介します。

コード理解

Goal:
この機能の処理の流れを理解したいです。

Context:
まず `src/feature/` 配下を見てください。
入口になりそうなファイルと、呼び出し元も確認してください。

Constraints:
ファイルは変更しないでください。
推測で断定せず、根拠になったファイル名を示してください。

Done when:
処理の流れを番号付きリストで説明し、関係する主要ファイルをまとめてください。
変更時に注意すべき点も2〜3個挙げてください。

バグ修正

Goal:
（不具合の内容）を修正してください。

Context:
再現手順:
1. （手順1）
2. （手順2）
3. （期待結果）
4. （実際の結果）

関連しそうなファイル:
`path/to/file`

Constraints:
修正は最小限にしてください。
API仕様は変更しないでください。
まず原因候補と変更方針を提示してください。

Done when:
再現手順で不具合が起きないことを確認してください。
関連テストまたは最小の確認コマンドを実行し、結果を報告してください。

テスト追加

Goal:
`関数名` または `コンポーネント名` に対するテストを追加してください。

Context:
対象ファイルは `path/to/target.ts` です。
既存テストの書き方は `path/to/example.test.ts` を参考にしてください。

Constraints:
実装コードは変更しないでください。
既存のテストライブラリと命名規則に合わせてください。

Done when:
正常系と代表的な異常系をカバーしてください。
追加したテストを実行し、コマンドと結果を報告してください。

テンプレートはそのまま使うより、プロジェクトに合わせて少し調整するのが大切です。特にContextとDone whenは、作業ごとに具体化してください。

10. 次に読む記事

ひとことで：次は、権限・承認・サンドボックスを理解して安全に使う段階です。

本記事では、Codexへの依頼文を Goal / Context / Constraints / Done when の4要素で設計する方法を解説しました。

次に読む記事は、CX-05「Codexの権限と安全設定｜承認・サンドボックス・Git管理」です。プロンプトが整っても、権限や承認の扱いを理解していないと、思わぬファイル変更やコマンド実行に戸惑うことがあります。安全設定を理解すると、Codexに任せられる範囲を自分で判断しやすくなります。

実務パターンをもっと見たい場合は、CX-06「Codex実践ワークフロー集」へ進みます。調査、実装、テスト追加、レビュー、ドキュメント更新など、よくある作業ごとの頼み方をまとめる予定です。

公式情報としては、Codex Prompting、Codex Best practices、Codex Workflows を確認しておくと、本記事の内容をより深く理解できます。

夕宮たいだ

ふぁ……これで頼み方の型はOKだよぉ。次は、権限まわりを見て、もっと安心して使えるようにしていこ〜。

この記事とあわせて読みたいCodex記事

ひとことで：この記事の理解を深めるための関連回です。

Codexシリーズ記事一覧

ひとことで：Codex編は、導入から専門機能まで順番に読めるシリーズです。

Codex
AIエージェントワークフロー CLI型エージェント プロンプト設計 ワークフロー 初心者向け
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

この記事を書いた人

怠惰のアバター 怠惰

関連記事

目次