codex-quota-optimizer

Codex クォータ最適化

回答を短くすることではなく、Codex の利用枠あたりに得られる有益な作業を最大化します。

0. 運用原則

受け入れ基準を満たせる範囲で、最もコストの低い実行経路を使います。より高コストの手段への切り替えは、低コストの手段では不十分だと証拠から判断できる場合に限ります。

現在の Codex クライアントまたはアカウントで確認できない限り、残りの利用枠を正確に断言してはいけません。利用枠の状態が重要な場合は、ユーザーに /status または利用状況ダッシュボードを確認するよう伝えたうえで、利用可能な最善の方法で作業を続けます。

ゼロ摩擦の不変条件

オプティマイザーが余計な負担になってはいけません。

• タスクの分類や予算設定だけを目的に、追加のモデル呼び出しを行わないでください。
• CQO の分類、記録、監査のためにネットワークリクエストを追加しないでください。
• 通常の Codex 実行を妨げる予算ゲートを設けないでください。
• ソフト予算を超過したというだけで、ユーザーに確認を求めないでください。
• CQO の代わりにサブエージェントを起動しないでください。
• オプションの cqo CLI がインストールも実行もされなくても、Skill が十分に役立つ状態を保ってください。

references/zero-friction.md を参照してください。

1. 必要なものだけを読む

広範囲な調査を始める前に、次の手順を実施します。

1. タスクの依頼、現在の差分、リポジトリの指示（AGENTS.md）を確認します。
2. 再帰的に読み進めるのではなく、対象を絞った検索（rg、ファイル単位の読み込み、マニフェスト、変更済みファイル）を優先します。
3. リポジトリに詳しくない場合は、多数のファイルを開く前に scripts/repo_snapshot.py --compact を一度実行します。
4. 矛盾が見つからない限り、現在のタスクで内容を把握済みの未変更ファイルを読み直さないでください。
5. 生成物、ベンダー、ビルドの各ディレクトリは、直接関係する場合にのみ読み込みます。

詳細な規則については、references/context-policy.md を参照してください。

2. 実行前にタスクを分類する

既存の推論ターン内で、内部的にクラスを 1 つ割り当てます。分類だけを目的に別のモデルを呼び出してはいけません。

• XS — 1 ファイルの機械的な変更で、受け入れ基準が明確。
• S — 1～3 ファイルの限定的な機能追加・修正で、既知のパターンがある。
• M — 複数ファイルにわたり、ある程度の設計判断や統合作業が必要。
• L — 横断的な変更、アーキテクチャが不明確な作業、移行、複雑なデバッグ。
• XL — リスクの高い再設計、複数システムにまたがる作業、セキュリティ上重要な作業、または曖昧なエンドツーエンドのタスク。

次に、要件を満たす最小限のモデル／推論経路を選択します。

• XS/S： Luna または利用可能な最速・最安の設定を優先し、推論レベルは低くします。
• M： Terra を優先し、推論レベルは低～中にします。
• L： まず Terra の中程度の設定を使い、未解決の設計・デバッグ上の複雑さがある場合に限り Sol に切り替えます。
• XL： Sol の中～高設定を使います。最も強力な複数ステップ／ツール推論が本当に必要で、アカウントで利用できる場合に限り Astra を使います。

利用可能なモデルはプランやクライアントによって異なります。指定されたモデルが利用できない場合は、同じ役割を担う、より低コストまたは高速なモデルを選択してください。

デフォルトで Max/Ultra を使わないでください。利用可能だというだけの理由でサブエージェントを起動しないでください。

references/model-routing.md を参照してください。

3. 実行予算を使う

重要度の高いタスクでは、次の内部予算を設定します。

• 調査予算： 変更対象を特定するために必要な読み込みと検索を行います。
• 編集予算： 受け入れ基準を満たすために必要な最小限のファイルだけを変更します。
• 検証予算： まず対象を絞ったチェックを行い、最終確認時または証拠から必要だと判断できる場合にのみ、広範なチェックを行います。

これらはソフト予算であり、実行を阻止するゲートではありません。

• 関連する依存関係の経路を把握した時点で、調査を終えます。
• 受け入れ基準を満たした時点で編集を終え、ついでのリファクタリングは避けます。
• 変更のリスクが高くない限り、関連するテスト、型チェック、Lint が通った時点で検証を終えます。
• 正確さのために別のファイル、テスト、推論ステップが必要な場合は、ユーザーを中断せずに続行します。
• 作業範囲が広がった場合は、内部で再分類して作業を続けます。最初の予算が小さすぎたというだけで、許可を求めないでください。

4. 計画を効率よく立てる

S／M／L／XL のタスクでは、次の項目を含む簡潔な計画を提示するか、維持してください。

1. 目標とする動作
2. 対象となる可能性が高いファイル
3. 最小限の検証
4. エスカレーションの条件

必要最小限のリポジトリ情報を確認する前に、推測に基づく長い計画を立てないでください。

コンテキストを読み込み直す細かなターンを繰り返すより、まとまりのある実装を一度のターンで行ってください。

5. 変更を最小限にする

• 変更する範囲は、まとまりのある最小限の部分にしてください。
• 既存のヘルパー、パターン、コンポーネント、テストを再利用してください。
• 関係のないファイルのフォーマットは変更しないでください。
• 必要な場合を除き、依存関係をアップグレードしないでください。
• 生成処理がタスクの一部でない限り、生成ファイルを変更しないでください。
• 同じファイルを何度も開いたり編集したりせず、論理的に関連する変更をまとめてください。

設定や小規模なローカルパッチで解決できる場合、フレームワークや抽象化レイヤーを導入しないでください。

6. 段階的に検証する

次の順序でチェックを実行してください。

1. 変更したファイルの構文／フォーマットチェック
2. 変更した動作に関する、対象を絞った単体テスト／コンポーネントテスト
3. 対象を絞った型チェック／リントチェック
4. 必要な場合のみ、パッケージ／アプリ全体のテスト
5. 複数箇所にまたがる変更やリスクの高い変更、またはリリース前のゲートの場合のみ、全テストスイート

小さな編集のたびに、同じ時間のかかる全テストスイートを繰り返し実行しないでください。広範なテストが無関係な既存の理由で失敗した場合は、その旨を記録し、対象を絞った検証を続けてください。

references/test-policy.md を参照してください。

7. コンテキストの肥大化を抑える

適切な区切りで、作業状況を簡潔な引き継ぎメモにまとめてください。メモには次の内容を含めます。

• 目標
• 決定事項
• 変更したファイル
• 実施したテストと結果
• 残っている問題

会話やリポジトリの履歴全体を言い直す代わりに、このメモを使ってください。

長期にわたるタスクでは、調査の繰り返しを防げる場合に限り、ローカルの簡単な作業メモを作成または更新してください。プロジェクトでコミットが求められていない限り、最終化する前に削除してください。

8. コストのかかるアンチパターンを避ける

次のことをデフォルトで行わないでください。

• 対象を絞った検索で機能の場所を特定できるのに、リポジトリ全体をスキャンする
• 必要がないのに、大きなロックファイル、圧縮済みバンドル、生成物、ベンダーツリーを開く
• 変更範囲を特定する前に、全テストスイートを実行する
• 日常的な編集に、高／xhigh／max／ultra の推論を使う
• 1つのエージェントで効率よく対応できるタスクに、複数のサブエージェントを使う
• パッチで十分なのに、Codex にファイル全体の書き換えを依頼する
• 現在のコンテキストにすでに含まれる情報を、何度も要約する
• ユーザーに価値をもたらさず、ついでに周辺コードをリファクタリングする
• リポジトリやローカルのドキュメントで十分なのに、ウェブを閲覧する
• 同等のクエリで検索を重複して実行する

references/anti-patterns.md を参照してください。

9. 必要に応じてエスカレーションする

次のいずれかに該当する場合に限り、モデル／推論／ツールの範囲を拡大してください。

• 対象を絞った試行を2回行っても、ローカルの情報では理由を説明できない形で失敗する
• アーキテクチャが曖昧で、誤った選択が広範な手戻りを招く
• 複数のサブシステムにまたがる障害である
• セキュリティ／データ損失／移行に関するリスクが無視できない
• 受け入れ基準が矛盾している
• 対象を絞った検証で、隠れた結合が判明する

エスカレーションの前に、判明していることを要約してください。上位モデルが同じ調査をやり直す必要がなくなります。

10. Plus と Pro の動作

プランの利用枠を判断に固定的に組み込まないでください。どちらのプランにも同じ効率方針を適用し、デフォルトの積極性だけを変えてください。

• Plus： デフォルトは economy の動作です。まず Luna／Terra を使い、対象を絞ってチェックし、範囲を厳密に管理します。
• Pro： デフォルトは balanced の動作です。まず Terra を使い、複雑さに応じて Sol を使います。ただし、Pro の利用枠にも限りがあり、他のエージェント機能と共有される場合があるため、無駄を避けてください。

ユーザーから利用枠がほぼ残っていないと伝えられた場合は、緊急モードに切り替えてください。

• 広範な調査を行わない
• 任意のリファクタリングを行わない
• サブエージェントを使わない
• 必要を満たす中で最も低コストのモデルを使う
• 実装方法は1つに絞る
• 対象を絞った検証のみを行う
• 現在のターンで完了できない場合は、簡潔な引き継ぎメモを作成する

11. ユーザー向けの出力

役立つ場合は、実行可能な項目のみを含む簡潔な 利用方法の選択肢 を最後に記載します。

• 「これはSタスクです。Luna/lowで十分です。」
• 「実装にはTerra/mediumを使用し、移行時の例外ケースにはSolを確保してください。」
• 「今すぐ対象を絞ったテストを実行し、全テストスイートは最終レビューまで保留してください。」

スキルがバックグラウンドで正常に動作している場合、すべての回答にクォータに関する説明を加えて冗長にしないでください。

12. 任意のローカル可観測性

cqo CLIは任意です。タスク単位の分類、ソフトバジェット、ローカルジャーナル、ローカル監査の機能を提供します。

• cqo start <task>
• cqo status
• cqo audit
• cqo history

ジャーナルは~/.cqo（またはCQO_HOME）にローカルでのみ保存されます。非公開のアカウントページを調べたり、非公開のクォータを推定したりすることはありません。

分析データを収集するためだけに、cqoを自動実行しないでください。 CLIは調査用のレイヤーであり、実行時の依存関係ではありません。ユーザーがCQOセッションを明示的に開始していない場合、CLIのオーバーヘッドなしで通常のスキル動作を続けてください。

13. 任意のヘルパースクリプト

• scripts/repo_snapshot.py --compact — リポジトリ全体を読み込まずに、簡潔なプロジェクトマップを作成します。
• scripts/change_scope.py — 現在のGit変更範囲を要約し、検証範囲を提案します。
• scripts/cqo.py — タスク単位の予算管理と監査を行う、ネットワーク通信を一切行わない任意のローカルCLIです。

スクリプトは、モデルコンテキストやツール呼び出しを節約できる場合、またはユーザーが可観測性を明示的に求めている場合にのみ使用してください。慣例的に実行しないでください。