Codex プロンプトベストプラクティス

プロンプトのテクニックを習得して、Codexがあなたの意図をより正確に理解し、効率的にタスクを完了させましょう。

プロンプトの基本構造

良いプロンプトには以下の要素が含まれます：

基本要素

要素説明例
タスクの説明何をしたいか「ユーザーログイン機能を実装する」
コンテキスト関連する背景情報「既存のauthモジュールを使用する」
制約条件制限と要件「既存のAPIと互換性が必要」
期待する結果具体的な成果物「JWTトークンを返す」

構造化プロンプト

完全なプロンプト例

# タスクの説明
ユーザーログインAPIエンドポイントを実装する

# コンテキスト
- プロジェクトはFastAPIフレームワークを使用
- 既存のauthモジュールが認証ロジックを処理
- データベースはPostgreSQLを使用

# 制約条件
- 既存のJWTツールを使用してトークンを生成
- パスワードはbcryptで検証
- リクエストログの追加が必要

# 期待する結果
- パス：POST /api/auth/login
- リクエストボディ：{"email": "...", "password": "..."}
- 成功レスポンス：{"token": "...", "user": {...}}
- 失敗レスポンス：{"error": "..."}

タスク分解の原則

複雑なタスクは小さなステップに分解して、段階的に完了させるべきです。

分解の原則

  • 各ステップに明確な目標がある
  • ステップ間の依存関係が明確である
  • 各ステップ完了後に結果を検証する
  • 問題が発生したらロールバックできる

分解の例

タスク分解

# 大きなタスク
「完全なユーザー認証システムを実装する」

# 小さなタスクに分解
ステップ1：「ユーザーテーブルとトークンテーブルを含む認証システムのデータ構造を設計する」
ステップ2：「パスワード暗号化と検証を含むユーザー登録機能を実装する」
ステップ3：「JWTトークンを生成するユーザーログイン機能を実装する」
ステップ4：「トークン検証ミドルウェアを実装する」
ステップ5：「ユーザーログアウト機能を実装する」
ステップ6：「認証システムのテストを作成する」
ステップ7：「APIドキュメントを更新する」

/plan モードを使用すると、Codexが複雑なタスクを自動的に分解できます。

コンテキスト情報の提供

十分なコンテキストにより、Codexはプロジェクトの状態をより正確に理解できます。

重要なコンテキスト

種類説明いつ提供するか
技術スタックフレームワーク、言語、ライブラリのバージョン初回のタスクまたは新しいモジュール
プロジェクト構造モジュールの場所、命名規則複数ファイルの修正に関わる場合
既存のコード関連する関数、クラス、モジュール互換性や拡張が必要な場合
制約条件互換性、パフォーマンス要件特別な制限がある場合

コンテキストの提供方法

コンテキストの提供

# 直接説明
「プロジェクトはDjango 4.2を使用し、データベースはPostgreSQL 15です」

# 既存コードの参照
「src/utils/validator.py の検証ロジックを参照する」

# ファイルの指定
「src/api/users.py を修正し、他のAPIと一貫したスタイルを保つ」

# AGENTS.md による自動提供
AGENTS.md ファイルを作成すると、Codexがプロジェクト規範を自動的に読み取ります

エラーメッセージの処理

Codexはエラーメッセージに基づいて問題を素早く特定できます。

完全なエラーメッセージの提供

エラー処理

# 完全なエラーを提供
「テスト実行時にエラーが発生しました：

AssertionError: Expected status 200 but got 500
  at test_login.py:45
  in test_successful_login
  Full traceback:
  ...

原因を分析して修正してください」

# スクリーンショットによる補助
エラーのスクリーンショットを添付すると、Codexが直接確認できます

エラーメッセージの要素

  • エラータイプとメッセージ
  • 完全なスタックトレース
  • 発生条件（どのような操作をしたか）
  • 期待する結果 vs 実際の結果

画像入力

Codexは画像入力をサポートしており、視覚的な情報伝達に適しています。

適用シーン

シーン説明
エラースクリーンショットエラー画面やログを示すスクリーンショット
デザイン案UIデザイン案をコードに変換する
アーキテクチャ図アーキテクチャ図を説明して実装する
データチャートチャートデータを分析する

画像入力の方法

画像の使用

# CLI
codex -i screenshot.png
codex --image design.png 「デザイン案に基づいてページを実装する」

# App/IDE
画像をダイアログ領域に直接貼り付けるかドラッグ＆ドロップする

# 複数の画像
codex -i img1.png -i img2.png 「この2つのデザイン案の差異を比較する」

反復的な最適化

反復を通じてコード品質を段階的に最適化します。

反復の流れ

  1. Codexが初期実装を完了する
  2. 結果を確認し、改善点を提案する
  3. Codexがフィードバックに基づいて調整する
  4. 改善効果を検証する
  5. 満足するまで繰り返す

反復的な最適化

# 初期実装
「ページネーションをサポートするユーザー一覧APIを実装する」

# 確認後の改善提案
「作成時間順のソートをサポートする並べ替え機能を追加する」

# さらに最適化
「ユーザー名での検索をサポートする検索機能を追加する」

# パフォーマンス最適化
「クエリパフォーマンスを最適化し、インデックスを追加する」

曖昧さの回避

明確なプロンプトは誤解と手戻りを減らします。

曖昧な例

曖昧さの回避

# 曖昧なプロンプト（良くない）
「あの関数を修正して」

# 明確なプロンプト（良い）
"src/utils/helper.py の format_date 関数を修正する"

# 曖昧なプロンプト（良くない）
"それを高速化する"

# 明確なプロンプト（良い）
"query_users 関数を最適化し、クエリ時間を 500ms から 100ms 以内に短縮する"

# 曖昧なプロンプト（良くない）
"機能を追加する"

# 明確なプロンプト（良い）
"ユーザー API に一括削除機能を追加し、ユーザー ID リストを受け取る"

参考例の使用

参考コードやドキュメントを提供し、Codex が期待するスタイルを理解できるようにする。

参考の提供

# 既存のコードスタイルを参考にする
"src/api/products.py のスタイルを参考にして、ユーザー API を実装する"

# ドキュメントを参考にする
"OpenAPI 仕様ドキュメント docs/api-spec.yaml に従って実装する"

# 参考例
"この形式でレスポンスを返してください："
{
  'success': true,
  'data': {...},
  'message': '...'
}"

一般的なプロンプトテンプレート

機能開発テンプレート

機能開発

[モジュールパス] に [機能名] 機能を追加する

要件：
- [技術/ライブラリ] を使用する
- [既存システム] と互換性を持たせる
- [境界処理] を含める
- [レスポンス形式] を返す

参考：[既存の類似機能パス]

Bug修正テンプレート

Bug修正

問題の説明：[Bug の症状]

発生条件：[どのような場合に発生するか]

エラーメッセージ：
[完全なエラースタック]

期待される動作：[正しい結果はどうあるべきか]

原因を分析して修正してください。他の機能に影響を与えないでください。

コードレビューテンプレート

コードレビュー

/review [範囲] for [重点]

# 例
/review src/auth/ for security issues
/review HEAD~5..HEAD for performance regressions

ベストプラクティスのまとめ

核心原則

  • 明確かつ具体的にし、曖昧な表現を避ける
  • 十分なコンテキストを提供する
  • 複雑なタスクは分解して実行する
  • 反復して最適化し、段階的に完成度を高める
  • 結果を検証し、正確さを確保する

効率化のヒント

  • AGENTS.md を使用して重複する説明を減らす
  • Skills を利用してよく使うプロンプトをカプセル化する
  • 画像を使用して視覚的な情報を伝える
  • エラー情報を提供するときは完全な情報を提供する

よくある質問

Q: Codexが誤って理解した場合はどうすればよいですか？

より明確な説明を提供し、コンテキストを補足するか、参考例を使用してください。

Q: Codexにプロジェクト規範を守らせるにはどうすればよいですか？

AGENTS.md ファイルを作成して規約を定義すると、Codex が自動的に従います。

Q: 複雑なタスクはどう処理すればよいですか？

/plan モードを使用して計画を立て、段階的に実行して検証してください。

Q: 画像入力に制限はありますか？

PNG、JPG、WebP 形式をサポートしています。解像度は適度なものを推奨します（小さすぎたり大きすぎたりしないように）。

その他の拡張