codex-goals

OpenAI Codex Goals のベストプラクティス

Codex 0.128.0 で導入された永続的な目標機能、Codex Goals の作成と管理に関するリファレンスです。ここでいう「ベストプラクティス」とは、Goal が適切な証拠に基づいて完了するか、それとも気付かないうちに誤った対象で完了してしまうかを左右するパターンとアンチパターンを指します。8 つのカテゴリにわたる 31 のルールを、Goal が正しく完了するかどうかへの影響が大きい順にまとめています。OpenAI 公式のクックブック記事「Codex で Goals を使用する」をもとにしています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• タスクに /goal を使うべきか、通常のプロンプトを使うべきか判断する
• /goal の呼び出しを作成または改善する
• 別の人が作成した Goal を有効化する前にレビューする
• Goal が誤った検証対象で完了した場合にデバッグする
• 正確な証明を得られない可能性がある調査用 Goal を設定する
• スレッドセッションをまたいで Goal のライフサイクル（一時停止、再開、クリア）を管理する
• 長時間実行する Goal の反復ポリシーや、ブロック時の停止条件を作成する
• Goal が完了せずに予算上限に達した場合の原因を調べる

優先度別のルールカテゴリ

優先度	カテゴリ	影響（最も重大なルール）	プレフィックス
1	Goal の適合性判断	CRITICAL	fit-
2	成果の定義	CRITICAL / HIGH	outcome-
3	検証対象	CRITICAL / HIGH	verify-
4	境界と反復	HIGH	bound-
5	ライフサイクルコマンド	HIGH	life-
6	証拠に基づく完了	HIGH	evidence-
7	効果的な Goal の作成	MEDIUM	craft-
8	調査用 Goal とアンチパターン	MEDIUM	research-

各ルールの影響度は、ルールごとのフロントマターに記載されています。

クイックリファレンス

1. Goal の適合性判断（CRITICAL）

• fit-when-to-use — ゴールは明確でも、そこに至る道筋が不確かな場合に Goal を使う
• fit-three-required-properties — Goal を設定する前に 3 つの特性を必須とする — 持続的な目標、証拠に基づくゴール、複数ターンにわたる道筋
• fit-prompt-vs-goal — 1 ターンで終わる作業にはプロンプトを、成果に基づいて継続する作業には Goal を選ぶ
• fit-skip-for-vague-targets — ゴールが曖昧な場合は Goal を使わない

2. 成果の定義（CRITICAL）

• outcome-measurable-end-state — 活動ではなく、測定可能な最終状態として成果を示す
• outcome-quantify-thresholds — 相対的な比較ではなく、数値でしきい値を明確にする
• outcome-narrow-but-discoverable — 監査できる程度に成果を絞りつつ、発見の余地を残す
• outcome-name-the-artifact — 生成する成果物について、名前と有効性の条件を明記する

3. 検証対象（CRITICAL）

• verify-name-the-surface — Goal の中で検証対象を必ず明記する
• verify-include-constraints — 主な指標に加え、悪化させてはならない制約も含める
• verify-multiple-checks-when-needed — 1 つのチェックでは不十分な場合、複数の検証対象を使う
• verify-surface-must-be-runnable — 検証対象は Codex が実際に実行または確認できるものでなければならない

4. 境界と反復（HIGH）

• bound-tools-and-files — Codex が使用できるファイル、ツール、リポジトリを制限する
• bound-iteration-policy — 反復ポリシーを定義する — Codex がターン間で次の実験をどのように選ぶか
• bound-blocked-stop-condition — ブロック時の停止条件を定義する — 正当化できる道筋が残っていない場合に何を報告するか
• bound-respect-budget — 予算上限は延長ではなく、停止して要約するものとして扱う

5. ライフサイクルコマンド（HIGH）

• life-set-with-slash-goal — /goal <text> で目標を設定する — Codex 0.128.0 以降で利用可能
• life-pause-during-detours — 無関係な寄り道をする前に目標を一時停止し、戻ったら再開する
• life-clear-stale-goals — 再開したスレッドで古い目標を消去する
• life-inspect-with-slash-goal — 続行する前に、引数なしの /goal を使って現在の目的と状態を確認する

6. エビデンスに基づく完了判定（HIGH）

• evidence-audit-before-completion — 目標を完了とする前に、具体的なエビデンスに照らして目的を監査する
• evidence-budget-is-not-completion — 予算上限に達することは、目的を達成することと同じではない
• evidence-honest-blockers — ブロッカーを明示する — 求められた主張の代わりに代替指標を使わない

7. 強い目標の作成（MEDIUM）

• craft-six-components — すべての強い目標に6つの要素を定義する — 成果、検証、制約、境界、反復ポリシー、ブロック時の停止
• craft-template-pattern — 標準の「…で検証し、…を維持する。…を使用する。反復の間は…する。ブロックされた場合は…する」というパターンを使う
• craft-let-codex-draft-it — 平易な説明から Codex に目標の草案を作成させ、その後、内容を絞り込む
• craft-strengthen-weak-goals — 最終状態、検証対象、制約を明示して、弱い目標を強化する

8. 調査目標とアンチパターン（MEDIUM）

• research-define-evidence-standard-first — 調査目標では、調査を始める前にエビデンスの基準を定義する
• research-build-claim-inventory — 調査目標を、エビデンスの情報源に対応づけた主張の一覧に分解する
• research-preserve-epistemic-ledger — 最終報告では、各主張の認識論的な水準を保持する — 構造化された台帳エントリーを使う
• research-anti-patterns — よくある3つの目標のアンチパターンを避ける — 続行を求めるだけの希望、不確実性の隠蔽、代替指標に基づく過大な主張

使い方

弱い Goal の文と強い Goal の文を比較する詳しい説明と具体例については、個々のリファレンスファイルを読んでください。

• セクションの定義 — カテゴリ構造と影響レベル
• ルールのテンプレート — 新しいルールを追加するためのテンプレート

各ルールファイルには、次の内容が含まれています。

• ルールが重要な理由を説明する2〜4文
• 弱い Goal またはアンチパターンの「不適切な例」
• 強化方法を示す「適切な例」
• 由来するクックブックのセクションへの参照

参照ファイル

ファイル	説明
AGENTS.md	build-agents-md.js によって生成された目次
references/_sections.md	カテゴリの定義と影響度の順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンと参照情報
gotchas.md	使用を通じて見つかった失敗しやすい点