From 3a61ccb16c01f13b08f830d84bd0e221b0c8c3db Mon Sep 17 00:00:00 2001 From: 9uiLe Date: Thu, 10 Sep 2026 14:05:49 +0900 Subject: [PATCH 1/2] docs(model-strategy): bound advisor discussions and context growth --- CHANGELOG.md | 4 ++++ plugins/model-strategy/README.md | 19 +++++++++++++-- .../references/03-cost-levers.md | 24 +++++++++++-------- .../skills/model-effort-guide/SKILL.md | 20 ++++++++++++---- 4 files changed, 50 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b447d6c..0461987 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ ## [Unreleased] +### Changed + +- **model-strategy**: 指定されたアドバイザーのモデル・effortを尊重し、重要な判断に相談を集約。根拠に基づく再相談条件と終了条件、待機ループの抑制、初期入力と蓄積履歴を区別したコンテキスト管理を追加。Orca公式スキルを変更せずに使える依頼例を掲載。 + ## [0.7.0] - 2026-09-08 ### Added diff --git a/plugins/model-strategy/README.md b/plugins/model-strategy/README.md index 101e49c..43943c0 100644 --- a/plugins/model-strategy/README.md +++ b/plugins/model-strategy/README.md @@ -42,7 +42,7 @@ codex plugin add model-strategy@9uile-plugins ## 実行方針 -モデルを選ぶ前に、不要なコンテキストの蓄積と反復送信を抑えます。作業の区切りでは `/clear`、継続情報を残したい場合は状態を保存して `/compact` を使います。探索・検証は同じ目的の依頼にまとめ、待機には実行環境の wait / monitor 機能を使います。 +モデルを選ぶ前に、不要なコンテキストの蓄積と反復送信を抑えます。作業の区切りでは決定事項・検証結果・残作業を保存し、必要に応じて新規セッションや `/compact` を使います。開始時から入力が大きい場合は内訳を調べ、圧縮を繰り返しません。探索・検証は同じ目的の依頼にまとめ、待機には実行環境の完了通知や wait / monitor 機能を使います。 日常の作業は、次の区分で担当を決めます。 @@ -54,7 +54,22 @@ codex plugin add model-strategy@9uile-plugins | R3 | 対象、期待結果、変更範囲、検証方法が確定した実装 | 実装担当に委譲する | | R4 | 設計、曖昧さの解消、デバッグ、レビューの統合 | メインで判断する | -委譲は、作業が独立し、最初の依頼だけで完結でき、起動や結果統合を含めても利用量が減る場合に行います。小さな既知操作は直接実行します。 +ユーザー指定のモデル・effort・アドバイザー利用を優先します。指定のない追加委譲は、作業が独立し、最初の依頼だけで完結でき、起動や結果統合を含めても利用量が減る場合に行います。小さな既知操作は直接実行します。 + +### Orca アドバイザーを使う依頼例 + +作業内容に次を添えて使えます。Orca 公式 `orchestration` が起動・待機・完了手順を担い、`model-effort-guide` は相談範囲と終了条件を補います。 + +```text +model-effort-guide と orchestration スキルを利用し、Codex gpt-6-astra（effort: medium）をアドバイザーとして使ってください。 +あなたが実装と最終判断を担当し、重要な設計判断・リスク・見落としをまとめて相談してください。 + +相談には目的・制約・検討案・具体的な質問・必要なファイルや差分を渡し、回答は重要な指摘・根拠・推奨案・未解決事項に絞ってください。 +指摘は事実や検証結果に照らして採否を判断し、新しい証拠・重大な未解決点・結論に影響する変更がある場合だけ、差分をまとめて再相談してください。合意のためだけの往復は不要です。 + +待機は公式 orchestration の現行ガイドに従い、完了通知や待機機能を使ってください。sleep・端末読込・状態確認だけでモデルを繰り返し呼び出さず、待機中は独立した作業を進めてください。 +最後に、採用・不採用にした重要な指摘と理由、残る未解決事項を簡潔に報告してください。 +``` ### 同梱サブエージェント diff --git a/plugins/model-strategy/references/03-cost-levers.md b/plugins/model-strategy/references/03-cost-levers.md index 0c237c8..5424985 100644 --- a/plugins/model-strategy/references/03-cost-levers.md +++ b/plugins/model-strategy/references/03-cost-levers.md @@ -1,38 +1,42 @@ # モデル選択以外のコストレバー -> **典拠**: platform.claude.com — Prompt Caching / Batch Processing docs (claude-api skill 経由、2026-06-04 時点キャッシュ)。 +> キャッシュ仕様: [Claude Code Prompt Caching](https://code.claude.com/docs/en/prompt-caching)（2026-09-10確認）。会話の区切り・相談範囲・待機方法は総利用量を抑えるための運用方針であり、製品上限ではない。 モデルと effort の前に、送信コンテキスト量と turn 数を最適化する。長いセッションではモデル差よりこちらが支配的になる。 -## §1 プロンプトキャッシュを温存する (input 約 90% 減) +## §1 キャッシュ読み取りと作成を区別する -キャッシュは**プレフィックス一致**。読み取りは base input の約 0.1 倍、TTL は 5 分。 +キャッシュは**プレフィックス一致**。TTL は5分・1時間があり、契約・設定・リクエスト種別に依存する。APIの読み取り単価は通常入力の約0.1倍だが、総 token 数をそのまま料金やサブスクリプション利用率に換算しない。実測では `input_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens`、`output_tokens` を分ける。thinking が出力に含まれる場合は二重加算しない。 Claude Code での実践: - キャッシュ維持を目的に keep-alive、`sleep`、メッセージ送信を行わない。1 turn 発生するたびに常駐コンテキストを再送するため逆効果になりうる -- 1 つの作業単位は連続して行い、PR / Phase の完了時は `/clear` する。途中状態が必要なら退避して `/compact` する +- 長い休止後の再開では大きな履歴の再キャッシュが発生し得る。次の作業に過去の詳細が不要なら、下記の引き継ぎ情報で新しい会話を始める。単なる再開ごとに clear / compact を強制しない - 巨大ファイルの不要な読み込みを避ける。コンテキストに入れたものは以後毎ターン課金対象(キャッシュされても 0.1 倍 × 毎ターン) ## §2 コンテキスト衛生 (input/output 両方に効く) -- 関係ないファイルを読ませない。探索はサブエージェントに出し、**結論だけ**回収する -- 話題が変わったら `/clear`。前タスクの残骸コンテキストは毎ターンの input 課金になる -- 約 150k tokens を越えたら、モデル変更や追加探索より先に `/compact` を検討する。閾値は絶対的な製品仕様ではなく、長文脈 turn の反復を避ける運用上の目安 +- 関係ないファイルを読ませない。探索の委譲は起動・文脈複製・結果統合まで含めて有利な場合に限り、**結論と証拠の場所**を回収する +- 作業の区切りで、目的・決定事項・対象ファイル・検証結果・残作業を短く保存する。過去の詳細が不要なら新規セッション、継続性が必要なら `/compact` を検討する。圧縮にも処理とキャッシュ再構築の負担があるため毎回は実行しない +- 約150k tokens は内訳を見直す目安であり、圧縮の必須閾値ではない。開始時から大きい場合は `/context` 等でツール・常駐指示・メモリを確認する。同じモデル・初回依頼で、MCP構成や起動経路を一つずつ変えて比較し、原因を確かめる。履歴の圧縮を繰り返して初期入力の問題を隠さない - 長大な出力(全文ダンプ、巨大 diff)を会話に貼らせない。ファイルに書かせてパスだけ受け取る +- 撮影・テスト・集計などの定型処理は可能なら一括実行し、終了状態・結果要約・失敗箇所だけ返す。モデルを各ステップの進行係にしない ## §2.5 turn を発生させない待機と失敗停止 -- 長時間処理は runtime の wait / monitor / wakeup、または Orca の wait 系機能を使う。`sleep N; echo tick` の反復は禁止 +- 長時間処理は完了・失敗・判断が必要な変化で通知する。Orca の起動・待機・完了手順は公式 `orchestration` の現行ガイドに従い、コマンドやフラグを推測しない +- 通知を受けられない場合、利用可能な実行環境で期限付きの待機処理を一つにまとめ、結果だけを返す。`sleep N; echo tick` の反復、短い待機ジョブの多重起動、通知と端末読込の二重監視でモデルの応答を増やさない - 同じ tool-not-found、権限拒否、wrapper 引数エラーを繰り返さない。2 回目の実行前に設定・権限・正しい呼び出し例を確認する -- 待機中の状態が変わらないこと自体はエラーではない。新しい turn を作らず、完了または意味のある状態変化で再開する +- 待機中は回答に依存しない作業を進める。タイムアウトは失敗や完了の証拠ではない。無変化のタイムアウトを繰り返して再照会せず、必要時だけ状態を診断する。復旧できない場合は未取得の回答と影響を明記し、取得済みとして扱わない ## §3 タスクの前渡し (往復削減) -Opus 4.8 / Fable 5 は「最初のターンで完全な仕様を渡して高 effort で走らせる」のが最も効率的(典拠: Migration Guide)。曖昧な指示を小出しにすると、ターンごとの再思考でトークン効率も品質も落ちる。 +依頼の小出しを避け、判断に必要な情報を最初にまとめる。モデル・effort はユーザー指定を尊重し、情報不足を高 effort だけで補おうとしない。 - 目的・制約・受け入れ条件・対象範囲を最初のメッセージに書き切る - 「なぜやるか」も渡す(意図が分かると無駄な探索が減る) +- アドバイザーには検討案と具体的な質問、対象のファイル・差分を渡す。会話全文は複製しない。重要な指摘・根拠・推奨案・未解決事項だけ返してもらう +- 初回の回答はメインが検証する。重大な未解決点、新しい証拠、結論に影響する変更がある場合だけ差分をまとめて再相談する。相互の同意を得るだけの往復は行わず、採否と理由、残るリスクを記録する ## §4 Batches API (API 直叩きのみ、50% off) diff --git a/plugins/model-strategy/skills/model-effort-guide/SKILL.md b/plugins/model-strategy/skills/model-effort-guide/SKILL.md index 40f1c8f..9e641ef 100644 --- a/plugins/model-strategy/skills/model-effort-guide/SKILL.md +++ b/plugins/model-strategy/skills/model-effort-guide/SKILL.md @@ -7,20 +7,23 @@ description: "Choose a cost-effective main model, effort, and bounded delegation 目的はモデル単価ではなく、タスク完了までの**総利用量**を下げること。概算は次で考える。 -`総利用量 ≈ 各 turn の送信コンテキスト量の合計 + サブエージェントの全リクエスト` +`総利用量 ≈ メイン・委譲先の全リクエストの入力 + 出力（thinking を含む）` + +これは課金式ではない。効果測定では通常入力・キャッシュ作成・キャッシュ読み取り・出力を分け、総 token 数をそのまま料金や利用枠に換算しない。 高価なモデルを判断に、安価なモデルを量のある定型作業に使う。ただし、巨大コンテキストの反復送信や過剰なサブエージェント起動は、モデル差より高くつく。 `PLUGIN_ROOT` は Claude Code では `${CLAUDE_PLUGIN_ROOT}`、Codex ではこの `SKILL.md` の 2 階層上にある `model-strategy` ディレクトリを指す。 +以下の `README.md`、`references/`、`scripts/` は `PLUGIN_ROOT` からの相対パス。 ## 1. まずセッションを軽く保つ モデル選択より先に次を適用する。 - このスキルは**セッション冒頭または方針変更時に 1 回**使う。同じ方針のままタスクごとに再実行しない -- PR 1 本、Phase 1 つなど作業単位が終わったら `/clear`。継続情報が必要なら作業状態をファイルに保存してから `/compact` -- コンテキストが約 150k tokens を超えた、または探索結果やログが累積したら、新しい探索・委譲を増やす前に `/compact` を優先する -- 待機は runtime の wait / monitor / wakeup、または Orca の wait 系機能を使う。`sleep` とメッセージ送信を繰り返すポーリングは禁止 +- 作業単位の完了や目的の変更時は、目的・決定事項・対象ファイル・検証結果・残作業だけを保存する。不要な履歴を持ち越すなら新規セッション、継続性が必要なら compact を選ぶ。Claude Code の `/clear` / `/compact` など、実行環境にある機能を使い、毎ターンの区切りにはしない +- コンテキストが約 150k tokens を超えた、またはログが累積したら内訳を確認する。150k は見直しの目安。開始時から大きい場合はツール・常駐指示・メモリを調べ、履歴の圧縮だけで解決しようとしない +- 待機は実行環境の完了通知や wait / monitor を使い、意味のある状態変化で再開する。`sleep` の完了通知、端末の再読込、状態確認だけでモデルを反復起動しない。利用できる待機方法は現行ガイドで確認する - 同じ権限拒否・存在しない tool・壊れた wrapper を再試行しない。原因となる設定か呼び出し方を直してから 1 回だけ再試行する - 生ログ、全文、巨大 diff は会話へ戻さず、必要箇所・結論・ファイル参照だけを残す @@ -44,7 +47,7 @@ R0 は、委譲の起動と結果統合より直接実行の方が短い場合 ## 3. 委譲の損益分岐 -次を全て満たすときだけ委譲する。 +ユーザー指定のモデル・effort・アドバイザー利用を優先する。指定のない追加委譲は、次を全て満たすときだけ行う。 1. 作業が独立しており、戻り値を短くできる 2. 仕様・制約・受け入れ条件・対象範囲を最初の依頼に書き切れる @@ -58,6 +61,13 @@ R0 は、委譲の起動と結果統合より直接実行の方が短い場合 - 並列実行は壁時計短縮が必要な独立タスクだけ。通常はキューし、同時稼働セッションを増やさない - 委譲後の追加質問を常態化させない。情報不足ならメインで契約を固め直し、1 回だけ再依頼する +### アドバイザーを指定された場合 + +- 最終判断と実装はメインが担当し、アドバイザーには重要な設計判断・リスク・見落としの検証をまとめて依頼する。定型操作ごとに相談しない +- 目的・制約・検討案・具体的な質問・必要なファイルや差分だけを渡し、調査範囲を定める。返答は重要な指摘、根拠、推奨案、未解決事項に絞る +- 初回の回答を検証し、新しい証拠・重大な未解決点・結論に影響する変更がある場合だけ、同じ相手へ差分をまとめて再相談する。合意そのものを目標にせず、追加の根拠が出なければ採否と理由をメインが決める。受け入れ条件を満たせない問題は未解決と明記する +- Orca を使う場合、実際の起動・待機・完了処理は公式 `orchestration` の現行ガイドに従う。このスキルは相談範囲と終了条件を補い、公式スキルやランタイムを変更しない。相談依頼の例は `README.md`、待機の代替策は `references/03-cost-levers.md` を必要時だけ読む + ## 4. メインモデルと effort - 短い運用作業、既知手順、定型 PR 作成は Sonnet 級から始める From 71cfb6e3bfc0f082655fa3156ccd9024d00137b6 Mon Sep 17 00:00:00 2001 From: 9uiLe Date: Thu, 10 Sep 2026 14:25:57 +0900 Subject: [PATCH 2/2] refactor(model-strategy): define cohesive execution and context policy --- CHANGELOG.md | 3 +- plugins/model-strategy/README.md | 136 +++++++++--------- .../references/03-cost-levers.md | 88 ++++++------ .../references/04-large-codebase.md | 79 ++++------ .../references/06-context-monitor.md | 91 +++++------- .../scripts/context-statusline.sh | 15 +- .../skills/model-effort-guide/SKILL.md | 106 ++++++-------- .../tests/context-statusline.test.mjs | 46 ++++++ 8 files changed, 285 insertions(+), 279 deletions(-) create mode 100644 plugins/model-strategy/tests/context-statusline.test.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index 0461987..f01795b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,8 @@ ### Changed -- **model-strategy**: 指定されたアドバイザーのモデル・effortを尊重し、重要な判断に相談を集約。根拠に基づく再相談条件と終了条件、待機ループの抑制、初期入力と蓄積履歴を区別したコンテキスト管理を追加。Orca公式スキルを変更せずに使える依頼例を掲載。 +- **model-strategy**: モデル・コンテキスト・委譲の実行方針を整備。担当の責任、根拠に基づく相談と受け入れ、完了通知による待機、会話の区切りと利用量計測を定義。README に導入方法、Orca アドバイザーの利用条件と依頼例、任意の監査・警告・表示機能を掲載。 +- **model-strategy**: コンテキスト表示の警告をウィンドウ使用率に基づく内訳確認とし、大規模探索・状態表示の資料を同じ判断基準で整備。 ## [0.7.0] - 2026-09-08 diff --git a/plugins/model-strategy/README.md b/plugins/model-strategy/README.md index 43943c0..93d1276 100644 --- a/plugins/model-strategy/README.md +++ b/plugins/model-strategy/README.md @@ -1,13 +1,15 @@ # model-strategy -Claude Code / Codex で、タスク完了までの総利用量を抑えるためのプラグインです。モデル選択に加え、会話のコンテキスト量、やり取りの回数、サブエージェントへの委譲コストを考慮して実行方針を決めます。 +Claude Code / Codex のモデル・effort（推論に割く労力）・委譲方針を決めるプラグインです。必要な品質を満たしながら、会話履歴の反復処理、相談の往復、エージェントの起動と結果統合を含む総利用量を抑えます。 -次のような場合に使います。 +## 利用する場面 -- タスクに合うモデルと effort（推論に割く労力）を選びたい -- 長い会話や繰り返しの探索による利用量を抑えたい -- メインで実行する作業と、サブエージェントに任せる作業を決めたい -- 操作ごとの担当を記録し、監査可能な形で実行したい +- タスクに合うモデルと effort を選ぶ +- 長い会話や繰り返しの相談による消費を抑える +- メイン、実装担当、アドバイザーの担当範囲を決める +- 操作の割当と受け入れ判断を監査可能な形で記録する + +通常のコーディング依頼だけでは自動起動しません。モデル選択・利用量・委譲方針を明示的に相談するか、`model-effort-guide` を指定して使います。 ## インストール @@ -16,107 +18,113 @@ Claude Code の会話内: ```text /plugin marketplace add 9uiLe/plugins /plugin install model-strategy@9uile-plugins - ``` -Codex 用のターミナルコマンド: +Codex のターミナル: ```bash codex plugin marketplace add 9uiLe/plugins codex plugin add model-strategy@9uile-plugins ``` -## 使い方 - -モデル選択や利用量、委譲方針を明示的に相談すると、`model-effort-guide` スキルが起動します。 +## 基本的な依頼 ```text -このタスクに最適なモデルと effort を選んで -利用上限を節約して、この機能を実装して -委譲方針を決めて +model-effort-guide を使って、このタスクに合うモデル・effort・委譲方針を決めてください。 ``` -推奨を求めた場合は、モデル・effort・必要な委譲先、選択理由、会話を区切るタイミングを返します。実行も依頼した場合は、最初に方針を共有してから作業を進めます。 +作業内容を添えて実行も依頼できます。推奨だけを求めた場合は、担当とモデル、判断理由、会話を区切る条件を返します。実行も求めた場合は、開始時に方針を共有して作業を進め、成果物・検証結果・未解決事項を報告します。 + +ユーザーが指定したモデル・effort・アドバイザー利用を優先します。セッション冒頭や方針変更時に使い、同じ方針が続く間は繰り返し呼び出す必要はありません。 + +## 作業の進め方 -通常のコーディング依頼だけでは自動起動しません。同じ方針が続く間は繰り返し呼び出さず、セッション冒頭や方針変更時に使います。 +1. **会話の内訳を確認する。** 開始時のツール・常駐指示・メモリと、作業中に蓄積したファイル・ログ・議論を区別します。 +2. **作業単位で担当を決める。** 小さな既知操作は直接実行し、独立した探索や実装は起動・統合の負担を含めて委譲を判断します。 +3. **依頼と回答をまとめる。** 目的・対象範囲・受け入れ条件を渡し、結果と検証の根拠を受け取ります。 +4. **完了または状態変化を待つ。** 実行環境の通知や待機機能を使い、待機中は結果に依存しない作業を進めます。 +5. **成果物を検証して区切る。** 決定事項・対象ファイル・検証結果・残作業を保存し、継続性に応じて会話の継続・圧縮・分離を選びます。 -## 実行方針 +圧縮の要否は token 数だけで決めません。初期入力が大きい場合は構成を調べ、不要な履歴が蓄積した場合は新規セッションや compact を検討します。計測では入力のキャッシュ作成・読み取りと出力を区別し、総 token 数を請求額や利用枠へそのまま換算しません。 -モデルを選ぶ前に、不要なコンテキストの蓄積と反復送信を抑えます。作業の区切りでは決定事項・検証結果・残作業を保存し、必要に応じて新規セッションや `/compact` を使います。開始時から入力が大きい場合は内訳を調べ、圧縮を繰り返しません。探索・検証は同じ目的の依頼にまとめ、待機には実行環境の完了通知や wait / monitor 機能を使います。 +詳細は [コンテキスト・往復・待機の管理](./references/03-cost-levers.md) を参照してください。 -日常の作業は、次の区分で担当を決めます。 +## 担当とモデル -| 区分 | 作業 | 担当方針 | +メインはユーザーへの応答と成果物の受け入れを担います。実装担当は指定範囲の作業を行い、アドバイザーは判断材料を返します。 + +| 区分 | 作業 | 担当候補 | | --- | --- | --- | -| P0 | 外部への書き込み、破壊的操作、履歴改変 | 実行権限を確認する | -| R0 | 既知ファイルの短い読み取り、単発の状態確認 | メインで直接実行する | -| R1 / R2 | 複数ファイルの探索、広域抽出、独立した検証 | 範囲を定めた探索・検証担当にまとめて依頼する | -| R3 | 対象、期待結果、変更範囲、検証方法が確定した実装 | 実装担当に委譲する | -| R4 | 設計、曖昧さの解消、デバッグ、レビューの統合 | メインで判断する | +| P0 | 外部への書き込み、破壊的操作、履歴改変 | 承認済みの範囲と実行権限を確認 | +| R0 | 既知ファイルの短い読み取り、単発の状態確認 | メイン | +| R1 / R2 | 複数ファイルの探索、広域抽出、独立した検証 | 探索・検証担当 | +| R3 | 対象・期待結果・変更範囲・検証方法が確定した実装 | 実装担当 | +| R4 | 設計、曖昧さの解消、デバッグ、レビューの統合 | メイン。アドバイザーの根拠も検証して判断 | -ユーザー指定のモデル・effort・アドバイザー利用を優先します。指定のない追加委譲は、作業が独立し、最初の依頼だけで完結でき、起動や結果統合を含めても利用量が減る場合に行います。小さな既知操作は直接実行します。 +Claude Code 向けに次のエージェント定義を同梱しています。Codex では利用可能なモデルと委譲機能に応じて担当を選びます。 -### Orca アドバイザーを使う依頼例 +| Agent | モデル | 用途 | +| --- | --- | --- | +| `haiku-scout` | Haiku | 探索・独立検証 | +| `sonnet-implementer` | Sonnet | 仕様が確定した実装 | +| `judge` | Opus | 高保証モードの独立判定 | +| `judge-fable` | Fable 5 | 高保証モードの難しい判断や、Opus judge で解決できない問題の独立判定 | -作業内容に次を添えて使えます。Orca 公式 `orchestration` が起動・待機・完了手順を担い、`model-effort-guide` は相談範囲と終了条件を補います。 +モデルと effort が未指定なら、作業に必要な能力と手戻りのリスクに合わせて選択します。料金・対応モデル・推論設定の詳細は、各参照資料の確認日と公式リンクを参照してください。 -```text -model-effort-guide と orchestration スキルを利用し、Codex gpt-6-astra（effort: medium）をアドバイザーとして使ってください。 -あなたが実装と最終判断を担当し、重要な設計判断・リスク・見落としをまとめて相談してください。 +## Orca でアドバイザーを利用する -相談には目的・制約・検討案・具体的な質問・必要なファイルや差分を渡し、回答は重要な指摘・根拠・推奨案・未解決事項に絞ってください。 -指摘は事実や検証結果に照らして採否を判断し、新しい証拠・重大な未解決点・結論に影響する変更がある場合だけ、差分をまとめて再相談してください。合意のためだけの往復は不要です。 +Orca と公式 `orchestration` スキルを利用できる環境が必要です。Orca はこのプラグインには同梱されていません。 -待機は公式 orchestration の現行ガイドに従い、完了通知や待機機能を使ってください。sleep・端末読込・状態確認だけでモデルを繰り返し呼び出さず、待機中は独立した作業を進めてください。 -最後に、採用・不採用にした重要な指摘と理由、残る未解決事項を簡潔に報告してください。 -``` +`model-effort-guide` が相談範囲と判断基準を定め、`orchestration` がエージェントの起動・待機・完了処理を担います。通常のアドバイザー利用に高保証モードの設定は不要です。 -### 同梱サブエージェント +作業内容に次の依頼を添えます。モデルと effort は用途に合わせて指定してください。 -Claude Code 向けに、モデルを固定した次のエージェント定義を同梱しています。Codex では、利用可能なモデルと委譲機能に応じて担当を読み替えます。 +```text +model-effort-guide と orchestration スキルを利用し、Codex gpt-6-astra（effort: medium）をアドバイザーとして使ってください。 +あなたが作業と最終判断を担当し、重要な設計判断・リスク・見落としをまとめて相談してください。 -| Agent | モデル | 用途 | -| --- | --- | --- | -| `haiku-scout` | Haiku | 探索・独立検証 | -| `sonnet-implementer` | Sonnet | 仕様が確定した、まとまりのある実装 | -| `judge` | Opus | 高保証モードでの独立判定 | -| `judge-fable` | Fable 5 | 高保証モードで、難しい判断や Opus judge の失敗後に使う独立判定 | +相談には目的・制約・検討案・具体的な質問・必要なファイルや差分を渡し、回答は重要な指摘・根拠・推奨案・未解決事項に絞ってください。 +指摘は事実や検証結果に照らして採否を判断し、新しい証拠・重大な未解決点・結論に影響する変更がある場合だけ、同じ相手へ差分をまとめて再相談してください。 +同じ論点で新しい根拠が出なくなったら往復を終え、採否と理由、残る未解決事項を記録してください。 -モデル価格、effort の対応、選択条件は[価格資料](./references/00-pricing.md)、[effort 資料](./references/01-effort-levels.md)、[Codex 向け資料](./references/07-codex.md)にまとめています。各資料の確認日と公式リンクを参照してください。 +待機は公式 orchestration の現行ガイドに従い、完了通知や待機機能を使ってください。sleep・端末読込・状態確認だけでモデルを繰り返し呼び出さず、待機中は結果に依存しない作業を進めてください。 +最後に、成果物と検証結果、重要な指摘の採否と理由、未解決事項を簡潔に報告してください。 +``` -## 任意機能 +## 任意の監査・警告・表示 -### 監査と独立判定 +### 高保証モード -監査可能なルーティングや独立判定を明示的に求めた場合は、高保証モード（conductor mode）を使います。操作ごとの割当をマニフェストに記録し、変更可能な範囲を基準線として保存し、必要に応じて judge に判定を委譲します。 +割当と受け入れ判断の記録が必要な場合は、監査可能なルーティングや独立判定を明示的に依頼します。高保証モード（conductor mode）では、操作ごとの割当マニフェストと変更可能範囲の基準線を保存し、必要に応じて judge に独立判定を委譲します。 -[`scripts/route-policy.mjs`](./scripts/route-policy.mjs) が詳細な振り分けルールの正本です。`route` サブコマンドで操作を判定し、`audit` で割当マニフェストを監査します。詳細は[ルーティング規則](./references/02-decision-matrix.md)と[高保証モードの手順](./references/08-conductor-mode.md)を参照してください。 +[`route-policy.mjs`](./scripts/route-policy.mjs) が詳細な分類の正本です。`route` で操作を分類し、`audit` で割当を監査します。条件と手順は [ルーティング規則](./references/02-decision-matrix.md) と [高保証モード](./references/08-conductor-mode.md) を参照してください。 ### 警告 hook -Claude Code 向けの hook は、対応する環境変数を設定した場合に有効になります。 +Claude Code 向けの hook は、対応する設定がある場合に有効になります。 -| Hook | 有効化条件と動作 | +| Hook | 条件と動作 | | --- | --- | -| [`route-warn.mjs`](./hooks/route-warn.mjs) | `MODEL_STRATEGY_ROUTE_WARN=1` で、メインが探索担当に相当する操作を直接実行すると委譲検討を促します。状態を保存できる場合、セッション・ツール名ごとに最初の 1 回に抑えます。 | -| [`scope-guard.mjs`](./hooks/scope-guard.mjs) | `MODEL_STRATEGY_MODE=conductor` と基準線ファイルがある場合に、`Edit` / `Write` / `NotebookEdit` の書き込み先が範囲外なら警告します。 | +| [`route-warn.mjs`](./hooks/route-warn.mjs) | `MODEL_STRATEGY_ROUTE_WARN=1` で探索担当に相当する直接操作に委譲検討を促す。状態を保存できる場合はセッション・ツール名ごとに最初の1回 | +| [`scope-guard.mjs`](./hooks/scope-guard.mjs) | `MODEL_STRATEGY_MODE=conductor` と基準線ファイルがある場合、`Edit` / `Write` / `NotebookEdit` の範囲外書き込みに警告 | 警告は操作をブロックしません。`scope-guard` は Bash 経由の書き込みを検出できません。 ### 使用状況の表示 -[`context-statusline.sh`](./scripts/context-statusline.sh) はメインセッションのコンテキスト使用率を、[`subagent-statusline.sh`](./scripts/subagent-statusline.sh) は委譲先タスクの状態を表示するスクリプトです。設定方法と測定上の限界は[コンテキスト監視の資料](./references/06-context-monitor.md)を参照してください。 +[`context-statusline.sh`](./scripts/context-statusline.sh) はメインセッションのコンテキスト使用率を、[`subagent-statusline.sh`](./scripts/subagent-statusline.sh) は委譲先タスクの状態を表示します。設定方法と測定上の限界は [コンテキスト監視](./references/06-context-monitor.md) を参照してください。 ## 参照資料 -| 資料 | 内容 | +| 資料 | 読む場面 | | --- | --- | -| [価格](./references/00-pricing.md) | モデル価格、キャッシュ・バッチ価格、確認日と公式リンク | -| [effort](./references/01-effort-levels.md) | 推論労力の選び方とモデル別の対応 | -| [ルーティング規則](./references/02-decision-matrix.md) | 操作の分類、git 操作、委譲時に渡す情報 | -| [利用量を抑える方法](./references/03-cost-levers.md) | キャッシュ、コンテキスト管理、避けたい運用 | -| [大規模コードベース](./references/04-large-codebase.md) | 探索とコンテキスト量の制御 | -| [リポジトリ索引](./references/05-repo-index.md) | 必要な情報を引き出す索引の設計 | -| [コンテキスト監視](./references/06-context-monitor.md) | 状態表示の設定と測定方法 | -| [Codex](./references/07-codex.md) | モデル、reasoning effort、委譲の読み替え | -| [高保証モード](./references/08-conductor-mode.md) | マニフェスト、独立判定、範囲警告、運用上の限界 | +| [価格](./references/00-pricing.md) | モデル・キャッシュ・バッチ処理の料金と適用条件を確認する | +| [effort](./references/01-effort-levels.md) | 推論量とモデルごとの対応を選ぶ | +| [ルーティング規則](./references/02-decision-matrix.md) | 厳密な分類や実装依頼の条件を確認する | +| [コンテキスト・往復・待機](./references/03-cost-levers.md) | 入力の増加、反復呼び出し、計測方法を調べる | +| [大規模コードベース](./references/04-large-codebase.md) | 探索範囲と戻り値を絞る | +| [リポジトリ索引](./references/05-repo-index.md) | 必要な情報を取り出す索引を設計する | +| [コンテキスト監視](./references/06-context-monitor.md) | 状態表示を設定し、計測の限界を確認する | +| [Codex](./references/07-codex.md) | モデル・effort・委譲をCodexで適用する | +| [高保証モード](./references/08-conductor-mode.md) | 割当監査・独立判定・範囲警告を設定する | diff --git a/plugins/model-strategy/references/03-cost-levers.md b/plugins/model-strategy/references/03-cost-levers.md index 5424985..caf4442 100644 --- a/plugins/model-strategy/references/03-cost-levers.md +++ b/plugins/model-strategy/references/03-cost-levers.md @@ -1,59 +1,63 @@ -# モデル選択以外のコストレバー +# コンテキスト・往復・待機の管理 -> キャッシュ仕様: [Claude Code Prompt Caching](https://code.claude.com/docs/en/prompt-caching)（2026-09-10確認）。会話の区切り・相談範囲・待機方法は総利用量を抑えるための運用方針であり、製品上限ではない。 +メインと委譲先の入力・出力を合わせて評価し、必要な品質を保ちながらタスク完了までの利用量を抑えるための判断基準。担当やモデルの選択には `skills/model-effort-guide/SKILL.md` を使う。 -モデルと effort の前に、送信コンテキスト量と turn 数を最適化する。長いセッションではモデル差よりこちらが支配的になる。 +## §1 計測とキャッシュ -## §1 キャッシュ読み取りと作成を区別する +次の値を分けて記録する。 -キャッシュは**プレフィックス一致**。TTL は5分・1時間があり、契約・設定・リクエスト種別に依存する。APIの読み取り単価は通常入力の約0.1倍だが、総 token 数をそのまま料金やサブスクリプション利用率に換算しない。実測では `input_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens`、`output_tokens` を分ける。thinking が出力に含まれる場合は二重加算しない。 +| 指標 | 確認すること | +| --- | --- | +| 応答数 | 作業量に対して相談・状態確認・再試行が増えていないか | +| 通常入力 | キャッシュを使わず処理した入力 | +| キャッシュ作成 | 初期入力やプレフィックスの再構築に使った量 | +| キャッシュ読み取り | 再利用された入力の量 | +| 出力 | 回答と推論に使った量。thinking が含まれる場合は二重加算しない | +| 検証結果・手戻り | 利用量の低下と引き換えに品質が低下していないか | -Claude Code での実践: +保存ログでは同じ応答が複数の記録に分かれる場合がある。応答識別子で重複を除き、比較期間・対象モデル・作業内容を揃える。単純な日別合計だけでなく、同程度の作業あたりの量も比較する。ログで取得できない利用分は計測範囲外として明記する。 -- キャッシュ維持を目的に keep-alive、`sleep`、メッセージ送信を行わない。1 turn 発生するたびに常駐コンテキストを再送するため逆効果になりうる -- 長い休止後の再開では大きな履歴の再キャッシュが発生し得る。次の作業に過去の詳細が不要なら、下記の引き継ぎ情報で新しい会話を始める。単なる再開ごとに clear / compact を強制しない -- 巨大ファイルの不要な読み込みを避ける。コンテキストに入れたものは以後毎ターン課金対象(キャッシュされても 0.1 倍 × 毎ターン) +Claude のプロンプトキャッシュは入力のプレフィックスを再利用する。TTL は5分・1時間があり、契約・設定・リクエスト種別に依存する。APIの読み取り単価は通常入力の約0.1倍だが、キャッシュ読み取りも処理量に含まれる。総 token 数は料金やサブスクリプション利用率を表さない。 -## §2 コンテキスト衛生 (input/output 両方に効く) +休止後の再開で大きなキャッシュ作成が発生した場合は、TTL とプレフィックスの変化を確認する。キャッシュ維持だけを目的にメッセージや keep-alive を送らない。 -- 関係ないファイルを読ませない。探索の委譲は起動・文脈複製・結果統合まで含めて有利な場合に限り、**結論と証拠の場所**を回収する -- 作業の区切りで、目的・決定事項・対象ファイル・検証結果・残作業を短く保存する。過去の詳細が不要なら新規セッション、継続性が必要なら `/compact` を検討する。圧縮にも処理とキャッシュ再構築の負担があるため毎回は実行しない -- 約150k tokens は内訳を見直す目安であり、圧縮の必須閾値ではない。開始時から大きい場合は `/context` 等でツール・常駐指示・メモリを確認する。同じモデル・初回依頼で、MCP構成や起動経路を一つずつ変えて比較し、原因を確かめる。履歴の圧縮を繰り返して初期入力の問題を隠さない -- 長大な出力(全文ダンプ、巨大 diff)を会話に貼らせない。ファイルに書かせてパスだけ受け取る -- 撮影・テスト・集計などの定型処理は可能なら一括実行し、終了状態・結果要約・失敗箇所だけ返す。モデルを各ステップの進行係にしない +仕様の根拠: [Claude Code Prompt Caching](https://code.claude.com/docs/en/prompt-caching)（2026-09-10確認）。具体的な料金は [価格資料](./00-pricing.md) の適用条件と確認日を参照する。 -## §2.5 turn を発生させない待機と失敗停止 +## §2 コンテキストの内訳と会話の区切り -- 長時間処理は完了・失敗・判断が必要な変化で通知する。Orca の起動・待機・完了手順は公式 `orchestration` の現行ガイドに従い、コマンドやフラグを推測しない -- 通知を受けられない場合、利用可能な実行環境で期限付きの待機処理を一つにまとめ、結果だけを返す。`sleep N; echo tick` の反復、短い待機ジョブの多重起動、通知と端末読込の二重監視でモデルの応答を増やさない -- 同じ tool-not-found、権限拒否、wrapper 引数エラーを繰り返さない。2 回目の実行前に設定・権限・正しい呼び出し例を確認する -- 待機中は回答に依存しない作業を進める。タイムアウトは失敗や完了の証拠ではない。無変化のタイムアウトを繰り返して再照会せず、必要時だけ状態を診断する。復旧できない場合は未取得の回答と影響を明記し、取得済みとして扱わない +| 観測 | 対応 | +| --- | --- | +| 開始時から入力が大きい | ツール定義・常駐指示・メモリを調べる | +| 読み取りや議論のたびに入力が増える | 次の判断に不要な生ログ・全文・過去の検討を会話へ持ち込まない | +| 完了した作業の履歴を別の作業へ引き継いでいる | 必要な結論を保存し、新規セッションを検討する | +| 作業は継続するが過去の詳細が不要 | 必要な状態を保存し、compact を検討する | -## §3 タスクの前渡し (往復削減) +Claude Code では `/context` 等で内訳を確認する。初期入力を切り分ける際は同じモデル・初回依頼を使い、MCP構成や起動経路などを一つずつ変えて比較する。入力の大きさだけで原因を断定しない。 -依頼の小出しを避け、判断に必要な情報を最初にまとめる。モデル・effort はユーザー指定を尊重し、情報不足を高 effort だけで補おうとしない。 +会話を分離・圧縮する前には、目的・決定事項・対象ファイル・検証結果・残作業を短く保存する。会話経緯の再現ではなく、次の担当が作業を再開できる情報を残す。圧縮には要約処理とキャッシュ再構築が伴うため、固定の token 数だけで繰り返し実行しない。 -- 目的・制約・受け入れ条件・対象範囲を最初のメッセージに書き切る -- 「なぜやるか」も渡す(意図が分かると無駄な探索が減る) -- アドバイザーには検討案と具体的な質問、対象のファイル・差分を渡す。会話全文は複製しない。重要な指摘・根拠・推奨案・未解決事項だけ返してもらう -- 初回の回答はメインが検証する。重大な未解決点、新しい証拠、結論に影響する変更がある場合だけ差分をまとめて再相談する。相互の同意を得るだけの往復は行わず、採否と理由、残るリスクを記録する +探索の委譲は、起動・文脈複製・結果統合を含めて有利な場合に選ぶ。結果は結論・証拠の場所・失敗箇所を中心に受け取り、必要な原文はファイル参照から確認する。 -## §4 Batches API (API 直叩きのみ、50% off) +## §3 相談と定型処理の往復 -対話不要・24 時間以内でよい大量処理(分類、一括変換、評価)は Claude Code でやらず Batches API に出す。Haiku + Batch で Opus 対話比 **1/10 以下**になる。 +実装や探索は、目的・対象範囲・受け入れ条件・検証方法を最初に渡す。短い読み取りやコマンドごとにエージェントを起動せず、同じ目的の処理をまとめる。 -## §5 アンチパターン +アドバイザーには検討案と具体的な質問を添える。回答の重要な指摘・根拠・推奨案・未解決事項をメインが検証し、新しい証拠や重大な未解決点があるときに差分をまとめて再相談する。採否の判断には受け入れ条件を使い、相互の同意だけを目的に往復しない。 -| アンチパターン | 何が起きるか | -| --- | --- | -| 単発の `git status` 級まで委譲する | 往復オーバーヘッド > 直接実行 (`02-decision-matrix.md` §5 の R0 参照) | -| 全部メインセッション(高性能モデル)でやる | 探索・定型まで最高単価で課金 | -| Fable 5 を常用する | Opus 4.8 比で約 2 倍 + 思考常時オンで週次クォータを速く消費(`00-pricing.md` §4)。差が出るタスクは限られる | -| Fable 5 で effort xhigh/max を常用する | low〜medium でも従来モデルの xhigh 級。枠・クレジットの浪費 | -| effort max を常用する | 過剰思考で収穫逓減(公式記載)。コストだけ増える | -| サブエージェントに小出しで指示する | 往復ごとにコンテキスト再送 | -| 高価な親モデルを継承する Explore / general-purpose / fork をコスト削減目的で使う | サブエージェント化しても単価が下がらず、親文脈複製分が増える | -| 1 コマンド・1 Read ごとにサブエージェントを起動する | 起動・結果統合の固定費が直接実行を上回る | -| 探索結果の生ログをメインに持ち帰る | 以後毎ターンの input 課金が膨らむ | -| こまめに新しいセッションを立てる | キャッシュミスの連続 + コンテキスト再構築 | -| `sleep` とメッセージでポーリングする | 状態が変わらなくても巨大な常駐コンテキストを turn ごとに再送する | +撮影・テスト・結果集計などの定型処理はスクリプトで一括実行し、終了状態と要約を返す。失敗時は該当箇所を返し、モデルが次の判断を行えるようにする。対話が不要な大量処理をAPIで行う場合は、応答期限や結果取得方法を踏まえてバッチ処理も検討する。価格と適用条件は [価格資料](./00-pricing.md) を参照する。 + +## §4 待機と障害への対応 + +待機には実行環境の完了通知や wait / monitor を使う。Orca の起動・待機・完了手順は公式 `orchestration` の現行ガイドを参照する。 + +- 完了・失敗・判断が必要な状態変化でモデルを再開する +- 通知を受けられない場合は、利用可能な期限付き待機処理にまとめる。短い待機ジョブを多重起動したり、通知と端末読込で二重監視したりしない +- 待機中は結果に依存しない作業を進める。sleep の完了通知や変化のない状態確認でモデルを反復起動しない +- タイムアウトだけで成否を判断しない。必要な診断で復旧できなければ、取得できていない回答と作業への影響を明記する +- 権限拒否・ツール名や引数の誤りは原因を直してから再試行する。同じ条件で同じ失敗を繰り返さない + +## §5 改善効果の判断 + +変更前後で作業の難しさや対象範囲を揃え、応答数・入力の内訳・出力量・検証結果・手戻りを比較する。少ない呼び出しで大きな履歴を処理する場合もあれば、委譲によって合計呼び出しが増えても親の入力を減らせる場合もある。単一の指標やモデル単価だけで成否を判断しない。 + +この資料の会話管理・相談・待機方針は運用上の判断基準であり、製品のコンテキスト上限や削減率を保証するものではない。 diff --git a/plugins/model-strategy/references/04-large-codebase.md b/plugins/model-strategy/references/04-large-codebase.md index 65ec3f4..d66ba7e 100644 --- a/plugins/model-strategy/references/04-large-codebase.md +++ b/plugins/model-strategy/references/04-large-codebase.md @@ -1,69 +1,48 @@ -# 大規模コードベースのコスト制御 +# 大規模コードベースの探索とコンテキスト管理 -> **典拠**: 本書は `00-pricing.md` のコスト構造と `03-cost-levers.md` のレバーを、コードベース規模が大きい場合に特化して体系化したもの。価格・キャッシュ前提は両ファイルに従う。 +複数モジュールの調査や大量の検索結果を扱うときに、判断に必要な情報を絞るための資料。会話の区切りと計測方法は [コンテキスト・往復・待機の管理](./03-cost-levers.md) に従う。 -`00`〜`03` は主に「1 トークンの単価」(どのモデルで処理するか) を最適化する。本書は**トークンの量、特にメインセッションに常駐するコンテキスト量**を制御する。コードベースが大きいほど後者が支配的になる。 +## §1 反復処理する入力を見積もる -## §1 なぜコストが「加速度的」に膨らむのか +メインと委譲先の入力処理量は、各応答で処理するコンテキスト量の合計になる。 -input は**毎ターン、その時点の常駐コンテキスト全量が課金対象**になる (キャッシュが効いても base input の約 0.1 倍 × 毎ターン)。作業を進めるほどファイルを読み込んで常駐量が増えるため、累積 input は概算で: - -``` -累積 input コスト ≈ Σ(各ターンの常駐コンテキスト) ≒ ターン数 × 平均常駐量 +```text +累積入力 token 数 = 各応答の入力 token 数の合計 + = 応答数 × 平均入力 token 数 ``` -常駐量がセッション中に単調増加すると、累積は**おおよそ二次関数的**に膨らむ。コードベースが大きいほど 1 回の探索で引き込むファイルが多く、この曲線が急になる。 - -**帰結: モデル単価をいくら下げても、常駐量の増え方を抑えなければコストは頭打ちになる。** 単価最適化 (`02`) と量制御 (本書) は直交する別レバーであり、大規模時は後者が効く。 - -## §2 原則 +これは課金式ではない。料金はモデル・キャッシュ作成・キャッシュ読み取りなどの区分に依存する。毎応答で一定量の情報を追加し続ける場合、入力の累積は応答数に対して二次的に増えるが、情報の絞り込みや会話の区切りによって増え方は変わる。 -> **コストをコードベースの大きさではなく「実際にやった作業量」に比例させる。そのためにメインセッションの常駐コンテキストを平坦 (フラット) に保つ。** +## §2 探索範囲を決める -コードベースの巨大さは、必要な場合に限ってモデル固定の使い捨てサブエージェントへ吸収させ、高単価のメインセッションには持ち込まない。メインに残すのは「結論」だけにする。既知パスの短い範囲 Read まで委譲して起動回数を増やさない。 +作業目的から対象ディレクトリ・機能・検索語を選び、まず候補の場所を特定する。検索結果が多い場合は条件を狭め、関連ファイルを読んで依存関係と変更箇所を確認する。正しい修正に必要な範囲を確保しつつ、無関係な全文の取り込みを避ける。 -## §3 大規模時の規定 (広域探索を隔離する) +既知パスの短い読み取りや、結果が小さい単発コマンドはメインで実行する。複数モジュールにまたがる調査は、起動と結果統合を含めて有利なら探索担当へまとめて依頼する。 -`02-decision-matrix.md` の R1/R2 のうち、複数モジュールにまたがる探索・大量出力が見込まれる検証を委譲対象とする。既知パスの短い範囲 Read、単発 status、結果が小さい既知コマンドは R0 のまま直接実行する。 +## §3 探索担当との契約 -| 規定 | 内容 | 効くレバー | -| --- | --- | --- | -| 広域探索を有界に委譲 (context firewall、R1/R2 参照) | 対象範囲・検索語・打ち切り条件を 1 回で `haiku-scout` に渡す。高価な親を継承する Explore は使わない | メイン常駐量とサブエージェント起動回数の両方を抑える | -| 戻り値は `file:line + 1 行結論` のみ | 生ログ・全文・巨大 diff をメインに持ち帰らせない | 以後毎ターンの input 課金を抑制 | -| 「読む」を「引く」に変える | リポジトリ索引 (`CLAUDE.md`・repo map) を引いて該当箇所を特定 → そこだけ範囲読み | 盲目的な grep + 全読みのトークンを削減 | -| 編集対象だけ精密読み | 全文読みを避け `offset/limit` で必要範囲のみ。行番号はサブエージェントの戻り値を使う | 1 ファイルあたりの常駐量を削減 | -| 作業単位の境界で `/clear` | PR / Phase の完了・話題転換で clear。細かなサブタスクごとには切らず、途中継続は `/compact` を使う | 二次曲線の主因を断ちつつ再構築を抑える | -| 出力はファイルへ | 生成物はファイルに書かせ、会話にはパスだけ回収 | output と以後の input 両方を抑制 | - -## §4 判定: 何を「大規模」とみなすか - -厳密な閾値ではなく、次のいずれかに当てはまれば本書の規定を適用する目安: +| 項目 | 指定する内容 | +| --- | --- | +| 目的 | 解決したい疑問と、結果を使う判断 | +| 対象 | ディレクトリ・機能・検索語・必要な検証 | +| 範囲 | 読み取り対象、変更可否、打ち切り条件 | +| 回答 | 結論、証拠のファイルと行、未確認事項 | -- 関係ファイルの全体像が 1 回の探索で把握しきれない (ディレクトリ階層が深い・モジュールが多い) -- 1 つの作業で複数モジュールを横断する -- セッションが長くなり、常駐コンテキストが単調増加していると感じる -- 常駐コンテキストが約 150k tokens を超えた -- grep のヒット件数が多く、どれが該当か絞り込みが必要 +コスト削減目的の委譲では担当モデルを明示し、親会話を複製する場合の負担も見積もる。生ログや巨大な差分は成果物ファイルに残し、回答には判断に必要な要約と参照を含める。メインは受け入れに必要な証拠を確認する。 -## §5 アンチパターン (大規模特有) +## §4 会話を区切る -| アンチパターン | 何が起きるか | -| --- | --- | -| メインで広域 grep して全ヒットを読む | 関係ないファイルまで常駐し、以後毎ターン課金。二次曲線が急になる | -| 索引を整備せず毎回ゼロから探索 | 同じ探索コストを作業のたびに再支払い | -| 1 セッションでタスクを次々こなす (clear しない) | 残骸コンテキストが累積し input が膨張 | -| サブエージェントに生ログを返させる | firewall が穴だらけになり委譲の意味が薄れる | -| 巨大ファイルを全文読みして数行だけ編集 | 常駐量が編集量に比例しなくなる | +次の状態では、入力の内訳と作業範囲を見直す。 -## §6 恒久資産: リポジトリ索引 +- 関連ファイルを絞れず広域検索を繰り返している +- 作業範囲が複数モジュールへ広がり、当初の依頼だけでは完結しない +- 読み込んだログや過去の議論が次の判断に不要になっている +- 作業が完了し、別の目的のタスクへ移る -大規模コードで最も効く一度きりの投資。`CLAUDE.md` に以下を整備しておくと、エージェントが「読む」前に「引ける」ようになり、探索トークンが構造的に下がる。 +必要な状態を保存し、新規セッションや compact の有効性を判断する。初期入力が大きい場合はツール・常駐指示・メモリを調べ、履歴の圧縮だけで解決しようとしない。 -- ディレクトリ地図 (主要ディレクトリと責務の 1 行説明) -- 主要モジュール / エントリポイントの所在 -- 「この機能はここ」という機能 → ファイルの索引 -- 横断的な規約 (命名・レイヤ境界) で盲目的探索を不要にする情報 +## §5 リポジトリ索引 -索引引き → 該当ファイルだけ範囲読み、という流れを既定動線にする。 +同じ探索を繰り返す場合は、主要ディレクトリの責務、エントリポイント、機能とファイルの対応を索引にする。更新責任と検索手段を決め、対象ファイルを読むための入口として使う。 -→ 索引は**コンテキストに常駐させず外部からオンデマンドで引く (pull)** のが原則。queryable 外部索引を第一に、薄い `CLAUDE.md` 地図をゼロインフラのフォールバックとする方針・要件は `05-repo-index.md` に体系化している。 +大きな索引は必要な部分だけ取得できる形にし、起動時に全文を読み込ませない。小規模な構成では短いディレクトリ地図でもよい。設計条件は [リポジトリ索引](./05-repo-index.md) を参照する。 diff --git a/plugins/model-strategy/references/06-context-monitor.md b/plugins/model-strategy/references/06-context-monitor.md index 585844c..6ab1448 100644 --- a/plugins/model-strategy/references/06-context-monitor.md +++ b/plugins/model-strategy/references/06-context-monitor.md @@ -1,28 +1,29 @@ -# コンテキスト量の可視化 +# コンテキストと委譲先の状態表示 -> **典拠**: statusLine の入力スキーマは Claude Code 公式ドキュメント (statusline.md) に従う。本書は `04-large-codebase.md` §1 の二次曲線を、セッション中に可視化して `/clear` の判断を促す仕組み。 +同梱スクリプトは Claude Code から標準入力で受け取ったJSONを表示する。自動でモデルを変更したり、会話を消去・圧縮したりはしない。 -`04` の量制御は「常駐コンテキストを平坦に保つ」のが要だが、**いま常駐量がどれだけ増えているかは人には見えない**。二次曲線に入ってから気づくと手遅れになる。statusLine に使用率を出して、タスク境界で `/clear` する判断材料にする。 +## §1 メインの表示 -## §1 同梱スクリプト +`scripts/context-statusline.sh` は現在のコンテキスト使用率、入力量、ウィンドウサイズ、提供されたコスト値を1行に表示する。 -`scripts/context-statusline.sh` は statusLine の stdin JSON を読み、1 行で表示する。 - -``` -Claude Opus 4.8 ⊙ ctx 78% ▓▓▓▓▓▓▓░░░ 156k/200k $1.92 ⚠ /clear 推奨 +```text +Claude ⊙ ctx 78% ▓▓▓▓▓▓▓░░░ 156k/200k $1.92 ⚠ コンテキスト内訳を確認 ``` -- `ctx NN%` + 10 セグメントバー: コンテキストウィンドウ使用率 (`context_window.used_percentage`) -- `156k/200k`: 常駐 input トークン / ウィンドウサイズ -- `$1.92`: セッション推定コスト (`cost.total_cost_usd`) -- 色: 緑 <50% / 黄 50〜閾値 / 赤 ≧閾値 または 200k 超過 (`exceeds_200k_tokens`) -- 赤になると `⚠ /clear 推奨` を表示 +| 表示 | JSON項目 | +| --- | --- | +| 使用率と10区画のバー | `context_window.used_percentage` | +| 入力量 / ウィンドウサイズ | `context_window.total_input_tokens` / `context_window.context_window_size` | +| コスト | `cost.total_cost_usd` | +| モデル名 | `model.display_name` | + +使用率が50%未満なら緑、50%以上なら黄、警告閾値以上なら赤で表示する。閾値は `MODEL_STRATEGY_CTX_WARN` で指定し、既定は75%。固定の token 数ではなく、モデルのウィンドウに対する使用率を使う。 -## §2 配線 (ユーザー/プロジェクトの settings.json) +現行仕様では `total_input_tokens` は現在の入力コンテキスト量を表し、通常入力・キャッシュ作成・キャッシュ読み取りの合計に相当する。項目の意味と利用可能性は実行中のClaude Codeの仕様を確認する。[公式 statusline 仕様](https://code.claude.com/docs/en/statusline#context-window-fields)（2026-09-10確認）。 -> **注意**: プラグインは statusLine を自動注入できない (Claude Code の仕様)。利用者が自分の `settings.json` に 1 度だけ配線する。 -> -> さらに、`statusLine` は**プラグイン実行コンテキストの外**で動くため、`${CLAUDE_PLUGIN_ROOT}` は**展開されない**。必ずスクリプトの**絶対パス**を指定すること。 +## §2 設定 + +Bash と `jq` が必要。利用するスクリプトの実在する絶対パスを、Claude Code のユーザーまたはプロジェクト設定に指定する。 ```json { @@ -33,42 +34,37 @@ Claude Opus 4.8 ⊙ ctx 78% ▓▓▓▓▓▓▓░░░ 156k/200k $1.92 ⚠ } ``` -絶対パスの決め方: - -- **リポジトリ checkout がある場合 (推奨)**: checkout 内の `plugins/model-strategy/scripts/context-statusline.sh` を指す -- **marketplace インストールのみの場合**: 実体は `~/.claude/plugins/cache//model-strategy//scripts/context-statusline.sh` に展開されるが、**version 付きパスはプラグイン更新のたびに変わる**。更新後に statusline が壊れたらパスを貼り直すこと (この理由から checkout パスの直接指定が確実) +リポジトリのチェックアウトを使う場合は `plugins/model-strategy/scripts/` 内を指定する。インストール先のパスにバージョンが含まれる場合は、更新後も設定先が存在することを確認する。空白を含むパスはコマンド文字列内で引用する。 -Codex でこのファイルを参照する場合は、この `references/` ディレクトリの 1 階層上をプラグインルートとして読み替える。 +## §3 警告の読み方 -## §3 依存と設定 +警告は入力の内訳を確認するきっかけとして使う。 -- **`jq`** が必要 (未インストールなら案内メッセージのみ表示し、セッションは妨げない) -- 警告閾値は環境変数 **`MODEL_STRATEGY_CTX_WARN`** (既定 `75` = 使用率%) で変更可。早めに区切りたいなら `60` 等に下げる +- 開始時から大きい場合は、ツール・常駐指示・メモリを調べる +- 作業中に増えた場合は、読み込んだファイル・ログ・議論が継続に必要かを確認する +- 作業の区切りで必要な状態を保存し、会話の継続・圧縮・分離を選ぶ -## §4 閾値の考え方 (04 との接続) +使用率だけで clear や compact を実行しない。具体的な判断基準は [コンテキスト管理](./03-cost-levers.md#§2-コンテキストの内訳と会話の区切り) と [大規模探索](./04-large-codebase.md) を参照する。 -二次曲線の主因は「常駐量がセッション中に単調増加すること」(`04` §1)。使用率そのものより、**タスクが一区切りしたタイミングで赤に近ければ `/clear`** という運用が効く。閾値は「区切りで切る判断を促す」目安であって、ハード制限ではない。 +## §4 表示の限界 -- 黄 (50%〜): そろそろ次のタスクは新セッションを検討 -- 赤 (≧閾値 / 200k 超過): 区切りがついたら `/clear`。続行するなら常駐を増やさない (探索は委譲・出力はファイルへ) +表示は入力JSONに依存する。メインのスクリプトは使用率・入力・コストが未提供なら0、ウィンドウサイズが未提供なら200kを表示するため、セッション開始直後などの値を確定値として扱わない。`jq` がなければ案内メッセージを表示する。 -## §5 限界 +使用率はメインの会話を表し、委譲先全体の利用量ではない。コスト値も請求書や利用枠の残量を示すものではない。全体の比較には対象範囲を明示した利用記録を使う。 -- statusLine は**表示のみ**。自動で `/clear` はしない (判断は人 or メインセッション) -- hook ペイロードにはトークン量が無いため、hook での自動警告は実装できない (公式仕様)。可視化は statusLine が唯一の面 -- 表示値は Claude Code が提供する推定値。厳密な課金額ではなく傾向把握に使う +## §5 計測との使い分け -## §6 関連 +状態表示は会話を管理するための判断材料、利用記録の集計は施策を評価するための資料として使う。ログや計測機能から取得できる通常入力・キャッシュ作成・読み取り・出力を分け、同じ応答を重複集計しない。計測方法は [利用量の評価](./03-cost-levers.md#§1-計測とキャッシュ) を参照する。 -- 常駐量を増やさない具体策: `04-large-codebase.md` §3 -- 探索委譲・コンテキスト衛生: `03-cost-levers.md` §2 -- 組み込みの内訳確認: `/context` コマンド (どの要素が常駐量を食っているかの診断) +## §6 関連資料 -## §7 委譲の可視化 (subagentStatusLine) +- [公式 statusline 仕様](https://code.claude.com/docs/en/statusline): 入力JSONと設定 +- [コンテキスト・往復・待機](./03-cost-levers.md): 会話の区切りと効果測定 +- [大規模コードベース](./04-large-codebase.md): 探索範囲と回答の絞り込み -`subagentStatusLine` は `statusLine` とは**別のトップレベルキー**で、委譲先タスク (サブエージェント) ごとの状態を表示できる。同梱スクリプト `scripts/subagent-statusline.sh` は stdin の `tasks[]` を読み、タスクごとに 1 行の NDJSON `{"id":"","content":""}` を出力する。 +## §7 委譲先の表示 -配線 (ユーザー/プロジェクトの settings.json。`statusLine` とは別キーとして追加): +`scripts/subagent-statusline.sh` は `tasks[]` を読み、タスクごとに1行のNDJSON `{"id":"","content":""}` を返す。名前・モデル・状態・tokenCountの提供値を表示し、`columns`（既定80）で文字数を切り詰める。 ```json { @@ -79,17 +75,4 @@ Codex でこのファイルを参照する場合は、この `references/` デ } ``` -絶対パスの制約は §2 と同じ (`statusLine` 同様、プラグイン実行コンテキストの外で動くため `${CLAUDE_PLUGIN_ROOT}` は展開されない。checkout パスの直接指定を推奨)。 - -バージョン要件: `tasks[].model` (解決済みモデル ID) は **v2.1.205+**、`tasks[].effort` は **v2.1.214+** のみ提供される (それ未満のバージョンではフィールド自体が存在しない)。 - -限界: プラグインは `agent` / `subagentStatusLine` の 2 キーのみをサポートする同梱 `settings.json` を提供できる (公式仕様上サポートされる) が、その内部で `command` 中の `${CLAUDE_PLUGIN_ROOT}` が展開されるかは未確認のため、確証が取れるまで本バージョンではプラグイン同梱によるデフォルト提供を見送り、ユーザー手動配線をベースラインとする。 - -## §8 実測手段と限界 - -- `/cost` は**セッション合算値**であり、委譲したサブエージェント分のコストも含む -- 通常の `statusLine` (§1〜§2) は**メインセッションの推定値のみ**を示す。サブエージェントの消費は `subagentStatusLine` 側の `tasks[]` でしか見えない -- モデル別の内訳は **OTel (OpenTelemetry) 連携でのみ**取得できる。ルール別 (R0〜R4) の実施状況を示す面は委譲マニフェストの実効記録のみ -- タスク構成 (作業量) を揃えないセッション前後比較では、ルーティングの効果と仕事量そのものの差を分離できない - -上記は観測手段の**粒度の事実**であり、特定の比較プロトコル (何をいつ・どう比較すべきか) は本書では規定しない。 +この設定は `subagentStatusLine` に対応するClaude Code環境で使う。パスと依存ツールはメインの表示と同じ。`tasks[]` の未提供フィールドは表示できず、IDがない項目はスキップする。`jq` がない場合は何も出力しない。タスクの表示値だけから全モデルの課金額や利用枠を推定しない。 diff --git a/plugins/model-strategy/scripts/context-statusline.sh b/plugins/model-strategy/scripts/context-statusline.sh index 7c2afd4..4404d74 100755 --- a/plugins/model-strategy/scripts/context-statusline.sh +++ b/plugins/model-strategy/scripts/context-statusline.sh @@ -2,14 +2,14 @@ # # model-strategy: コンテキスト量ステータスライン # -# セッションの常駐コンテキスト使用率を可視化し、二次曲線に入る前に -# /clear を促す。詳細は references/06-context-monitor.md を参照。 +# 現在のコンテキスト使用率を表示し、内訳を確認する判断材料にする。 +# 詳細は references/06-context-monitor.md を参照。 # # 配線 (ユーザー/プロジェクトの settings.json): # { # "statusLine": { # "type": "command", -# "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/context-statusline.sh" +# "command": "/absolute/path/to/model-strategy/scripts/context-statusline.sh" # } # } # @@ -26,13 +26,12 @@ if ! command -v jq >/dev/null 2>&1; then fi # タブ区切りで値を取り出す (model 表示名に空白が含まれうるため IFS=tab) -IFS=$'\t' read -r pct used size cost over model < <( +IFS=$'\t' read -r pct used size cost model < <( printf '%s' "$input" | jq -r ' [ (.context_window.used_percentage // 0) , (.context_window.total_input_tokens // 0) , (.context_window.context_window_size // 200000) , (.cost.total_cost_usd // 0) - , (.exceeds_200k_tokens // false) , (.model.display_name // "model") ] | @tsv' ) @@ -48,10 +47,10 @@ bar="" for ((i=0; i=warn% または 200k 超過 +# 色: 緑 <50% / 黄 50-warn% / 赤 >=warn%。モデルごとのウィンドウに対する使用率。 reset=$'\033[0m' -if [[ "$over" == "true" ]] || (( pct_int >= warn_at )); then - color=$'\033[31m'; nudge=" ⚠ /clear 推奨" +if (( pct_int >= warn_at )); then + color=$'\033[31m'; nudge=" ⚠ コンテキスト内訳を確認" elif (( pct_int >= 50 )); then color=$'\033[33m'; nudge="" else diff --git a/plugins/model-strategy/skills/model-effort-guide/SKILL.md b/plugins/model-strategy/skills/model-effort-guide/SKILL.md index 9e641ef..943bcc5 100644 --- a/plugins/model-strategy/skills/model-effort-guide/SKILL.md +++ b/plugins/model-strategy/skills/model-effort-guide/SKILL.md @@ -3,94 +3,80 @@ name: model-effort-guide description: "Choose a cost-effective main model, effort, and bounded delegation plan for Claude Code or Codex when the user explicitly asks about model choice, usage cost, delegation, or operation routing. Do not invoke for routine coding merely because a task could be delegated. Japanese triggers: 「このタスクに最適なモデルは」「コスパよく実行して」「モデルと effort を選んで」「利用上限を節約して」「委譲方針を決めて」「操作をルーティングして」." --- -# モデル / effort 使い分けガイド +# モデル・コンテキスト・委譲の実行方針 -目的はモデル単価ではなく、タスク完了までの**総利用量**を下げること。概算は次で考える。 +必要な品質を満たしながら、タスク完了までにメインと委譲先が処理する入力・出力を抑える。モデル単価に加え、会話履歴の反復処理、依頼と回答の往復、エージェントの起動と結果統合を考慮する。 -`総利用量 ≈ メイン・委譲先の全リクエストの入力 + 出力（thinking を含む）` +メインはユーザーへの応答と成果物の受け入れを担う。実装担当は範囲を定めた作業を行い、アドバイザーは判断材料を返す。アドバイザーの回答を採用する責任はメインにある。 -これは課金式ではない。効果測定では通常入力・キャッシュ作成・キャッシュ読み取り・出力を分け、総 token 数をそのまま料金や利用枠に換算しない。 +## 1. 依頼条件を確認する -高価なモデルを判断に、安価なモデルを量のある定型作業に使う。ただし、巨大コンテキストの反復送信や過剰なサブエージェント起動は、モデル差より高くつく。 +ユーザーが指定したモデル・effort・アドバイザー利用を優先し、未指定の部分を選ぶ。指定された機能が利用できなければ制約を説明し、別のモデルや実行環境へ無断で置き換えない。 -`PLUGIN_ROOT` は Claude Code では `${CLAUDE_PLUGIN_ROOT}`、Codex ではこの `SKILL.md` の 2 階層上にある `model-strategy` ディレクトリを指す。 -以下の `README.md`、`references/`、`scripts/` は `PLUGIN_ROOT` からの相対パス。 +セッション冒頭または方針変更時にこのスキルを使い、同じ方針が続く間は再実行しない。外部への書き込みなどは、会話内の承認と実行環境の権限に従う。 -## 1. まずセッションを軽く保つ +## 2. 会話を作業単位で管理する -モデル選択より先に次を適用する。 +- 開始時の入力が大きい場合は、ツール・常駐指示・メモリの内訳を確認する。作業中に増えた場合は、読み込んだファイル・ログ・過去の議論が次の判断にも必要かを確認する +- 作業の区切りで目的・決定事項・対象ファイル・検証結果・残作業を短く保存する。不要な履歴を切り離すなら新規セッション、継続性を保って履歴を縮めるなら compact を選ぶ。実行環境で利用可能な機能を使い、圧縮と再構築の負担も考慮する +- 読み取りは対象範囲を絞り、結果は結論・証拠の場所・失敗箇所を中心に返す。定型コマンドは同じ目的の処理をまとめ、生ログや巨大な差分を会話へ持ち込まない -- このスキルは**セッション冒頭または方針変更時に 1 回**使う。同じ方針のままタスクごとに再実行しない -- 作業単位の完了や目的の変更時は、目的・決定事項・対象ファイル・検証結果・残作業だけを保存する。不要な履歴を持ち越すなら新規セッション、継続性が必要なら compact を選ぶ。Claude Code の `/clear` / `/compact` など、実行環境にある機能を使い、毎ターンの区切りにはしない -- コンテキストが約 150k tokens を超えた、またはログが累積したら内訳を確認する。150k は見直しの目安。開始時から大きい場合はツール・常駐指示・メモリを調べ、履歴の圧縮だけで解決しようとしない -- 待機は実行環境の完了通知や wait / monitor を使い、意味のある状態変化で再開する。`sleep` の完了通知、端末の再読込、状態確認だけでモデルを反復起動しない。利用できる待機方法は現行ガイドで確認する -- 同じ権限拒否・存在しない tool・壊れた wrapper を再試行しない。原因となる設定か呼び出し方を直してから 1 回だけ再試行する -- 生ログ、全文、巨大 diff は会話へ戻さず、必要箇所・結論・ファイル参照だけを残す +詳細な切り分けと計測は `references/03-cost-levers.md`、大規模リポジトリの探索は `references/04-large-codebase.md` を必要時に読む。 -詳細なコンテキスト対策が必要な場合だけ `references/03-cost-levers.md` を読む。大規模リポジトリで探索範囲を制御するときだけ `references/04-large-codebase.md` を読む。 +## 3. 担当とモデルを選ぶ -## 2. 軽量ルーティング +次の表は担当候補を選ぶためのもの。指定のない追加委譲は、作業が独立し、目的・対象範囲・受け入れ条件を一度に渡せて、起動・文脈複製・結果統合を含めても直接実行より有利な場合に行う。 -日常利用では、タスク全体を細かな操作列へ分解してマニフェスト化しない。次の表で、意味のある作業塊ごとに最初に該当する行を選ぶ。 +| 区分 | 作業 | 担当候補 | +| --- | --- | --- | +| P0 | 外部への書き込み、破壊的操作、履歴改変 | 承認済みの範囲と実行権限を確認 | +| R0 | 既知ファイルの短い読み取り、単発の状態確認 | メインで直接実行 | +| R1/R2 | 複数ファイルの探索、広域抽出、独立した検証 | 範囲を定めた探索・検証担当 | +| R3 | 対象・期待結果・変更範囲・検証方法が確定した実装 | 実装担当 | +| R4 | 設計、曖昧さの解消、デバッグ、レビューの統合 | メイン。指定されたアドバイザーの根拠も検証して判断 | -| 区分 | 条件 | Claude Code | Codex | -| --- | --- | --- | --- | -| P0 | 外向き・破壊的・履歴改変操作 | 実行直前の権限確認 | 実行直前の権限確認 | -| R0 | 既知パスの短い Read、単発 status、短い既知コマンド | main-direct | main-direct | -| R1/R2 | 複数ファイルの探索、広域抽出、独立した既知検証 | `haiku-scout` | cheap scout + low | -| R3 | 対象・結果・変更範囲・検証方法が確定した、まとまりのある実装 | `sonnet-implementer` | implementation model + medium | -| R4 | 設計、曖昧さ解消、デバッグ、レビュー統合 | main | capable main model | +Claude Code では探索・検証に `haiku-scout`、仕様が確定した実装に `sonnet-implementer` を利用できる。Codex では利用可能なモデルと委譲機能に合わせる。コスト削減目的の委譲ではモデルを明示し、親会話を継承する fork の文脈複製も見積もる。短い操作ごとに起動せず、並列化は独立作業の所要時間短縮に価値がある場合に選ぶ。 -R0 は、委譲の起動と結果統合より直接実行の方が短い場合に使う。R1/R2 も 1 コマンドずつ別エージェントにせず、同じ目的の探索・検証を 1 回の有界な依頼へまとめる。 +モデル・effort が未指定なら、既知手順や定型実装は Sonnet 級、複雑な判断はより高性能なモデルを候補にする。必要な推論量に合わせて effort を選び、能力不足や手戻りの証拠に応じて引き上げる。Fable や最大 effort の起動自体を品質保証とみなさない。 -厳密な述語、git 操作、R3 の契約が必要な場合だけ `references/02-decision-matrix.md` を読み、必要なら `scripts/route-policy.mjs route` を使う。 +厳密な分類・git 操作・実装依頼の条件は `references/02-decision-matrix.md`、価格と effort の根拠は `references/00-pricing.md` と `references/01-effort-levels.md`、Codex 固有の対応は `references/07-codex.md` を必要時に読む。 -## 3. 委譲の損益分岐 +## 4. 依頼と受け入れをまとめる -ユーザー指定のモデル・effort・アドバイザー利用を優先する。指定のない追加委譲は、次を全て満たすときだけ行う。 +実装・探索の依頼には目的、対象、変更可能範囲、受け入れ条件、検証方法を渡す。回答は結果、検証の根拠、未完了事項に絞る。追加依頼は不足情報を整理し、対象の差分をまとめて渡す。 -1. 作業が独立しており、戻り値を短くできる -2. 仕様・制約・受け入れ条件・対象範囲を最初の依頼に書き切れる -3. 起動・親文脈の複製・結果統合を含めても、メインで直接行うより利用量が減る +アドバイザーには重要な設計判断・リスク・見落としの検証を依頼する。 -追加規則: +- 目的・制約・検討案・具体的な質問・必要なファイルや差分を渡し、調査範囲を定める。回答は重要な指摘・根拠・推奨案・未解決事項に絞る +- メインが事実や検証結果と照合する。新しい証拠、重大な未解決点、結論に影響する変更がある場合に限り、同じ相手へ差分をまとめて再相談する +- 合意の有無ではなく、受け入れ条件と根拠で採否を決める。同じ論点で新しい根拠が出なくなったら往復を終え、理由と残るリスクを記録する。受け入れ条件を満たせない点は未解決として扱う -- `haiku-scout` / `sonnet-implementer` のようにモデルを固定した役割を使う。高価な親モデルを継承する Explore、general-purpose、fork 型はコスト削減目的では使わない -- R1/R2 は対象ディレクトリ、検索語、コマンド、打ち切り条件を指定する。結果は結論と `file:line` 程度に制限する -- R3 は対象、観測可能な結果、変更可能範囲、検証方法を 1 回で渡す。対象ファイルが広い、または設計判断を残す依頼は R4 に戻す -- 並列実行は壁時計短縮が必要な独立タスクだけ。通常はキューし、同時稼働セッションを増やさない -- 委譲後の追加質問を常態化させない。情報不足ならメインで契約を固め直し、1 回だけ再依頼する +Orca を使う場合、このスキルが相談範囲と判断基準を定め、公式 `orchestration` の現行ガイドがエージェントの起動・待機・完了処理を定める。Orca のコマンドやフラグは現行ガイドで確認する。利用者向けの依頼例は `README.md` にある。 -### アドバイザーを指定された場合 +## 5. 完了または状態変化を待つ -- 最終判断と実装はメインが担当し、アドバイザーには重要な設計判断・リスク・見落としの検証をまとめて依頼する。定型操作ごとに相談しない -- 目的・制約・検討案・具体的な質問・必要なファイルや差分だけを渡し、調査範囲を定める。返答は重要な指摘、根拠、推奨案、未解決事項に絞る -- 初回の回答を検証し、新しい証拠・重大な未解決点・結論に影響する変更がある場合だけ、同じ相手へ差分をまとめて再相談する。合意そのものを目標にせず、追加の根拠が出なければ採否と理由をメインが決める。受け入れ条件を満たせない問題は未解決と明記する -- Orca を使う場合、実際の起動・待機・完了処理は公式 `orchestration` の現行ガイドに従う。このスキルは相談範囲と終了条件を補い、公式スキルやランタイムを変更しない。相談依頼の例は `README.md`、待機の代替策は `references/03-cost-levers.md` を必要時だけ読む +完了通知や runtime の wait / monitor を利用し、待機中は結果に依存しない作業を進める。sleep の完了通知・端末読込・状態確認だけでモデルを繰り返し呼び出さない。 -## 4. メインモデルと effort +通知を受けられない場合は、実行環境が対応する期限付きの待機処理にまとめる。タイムアウトは完了や失敗の証拠ではない。必要な状態診断を行い、復旧できなければ取得できていない結果と作業への影響を明記する。 -- 短い運用作業、既知手順、定型 PR 作成は Sonnet 級から始める -- 通常の設計・レビュー・デバッグは Opus 級の medium〜high を基本にする -- Fable と xhigh/max は、アーキテクチャ級の判断、長時間自律実行、または下位モデルでの実証済み失敗が再実行コストを上回る場合に限定する -- セッションが既に巨大なら、モデルを切り替えて同じ文脈を引きずる前に compact / clear を選ぶ +権限拒否・存在しないツール・引数の誤りは、同じ条件で再試行しない。原因を直した場合だけ再試行し、同じ失敗が残れば未解決として報告する。 -価格や effort の根拠をユーザーが求めた場合だけ `references/00-pricing.md` と `references/01-effort-levels.md` を読む。Codex 固有のモデル対応が必要な場合だけ `references/07-codex.md` を読む。 +## 6. 方針と結果を報告する -## 5. 高保証モードは明示 opt-in +推奨だけを求められた場合は、次の形式で短く答える。 -通常タスクでは割当マニフェスト、完了監査、judge を使わない。ユーザーが監査可能なルーティング、独立判定、conductor mode を明示的に求めた場合だけ `references/08-conductor-mode.md` を読み、マニフェスト表示・baseline・`route-policy.mjs audit` を適用する。 +```text +推奨: <メインモデル / effort / 必要な委譲先> +理由: <品質・コンテキスト量・往復回数の判断根拠> +区切り: <会話を継続・圧縮・分離する条件> +``` -`judge` / `judge-fable` はコスト削減用の既定経路ではない。高影響な判断に独立レビューが必要な場合だけ使い、日常の diff 受け入れには起動しない。 +実行も求められた場合は方針を開始時に一度共有し、作業を進める。完了時は成果物と検証結果に加え、重要な指摘の採否・理由・未解決事項を報告する。利用量を計測する場合は通常入力・キャッシュ作成・キャッシュ読み取り・出力を区別し、総 token 数を料金や利用枠に換算しない。 -## 6. 出力 +## 任意の監査 -推奨だけを求められた場合は、詳細な操作表を作らず次の 3 行で答える。 +ユーザーが監査可能なルーティング、独立判定、conductor mode を求めた場合に `references/08-conductor-mode.md` を読み、割当マニフェスト、変更範囲の基準線、`scripts/route-policy.mjs audit` を使う。`judge` / `judge-fable` は高保証モードで独立判定を担う。通常のアドバイザー相談だけではこのモードを有効にしない。 -```text -推奨: <メインモデル / effort / 必要なら委譲先> -理由: <総コンテキスト・turn 数・品質のトレードオフを 1〜2 文> -区切り: -``` +## 資料の場所 -実行も求められた場合は、この方針を作業開始時に 1 回だけ共有し、その後は通常の作業報告に戻る。 +`PLUGIN_ROOT` は Claude Code では `${CLAUDE_PLUGIN_ROOT}`、Codex ではこのスキルのディレクトリから2階層上にある `model-strategy` ディレクトリ。本文中の `README.md`、`references/`、`scripts/` はこのルートからの相対パス。 diff --git a/plugins/model-strategy/tests/context-statusline.test.mjs b/plugins/model-strategy/tests/context-statusline.test.mjs new file mode 100644 index 0000000..bbd9118 --- /dev/null +++ b/plugins/model-strategy/tests/context-statusline.test.mjs @@ -0,0 +1,46 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; + +const script = fileURLToPath(new URL('../scripts/context-statusline.sh', import.meta.url)); + +function render({ used, size, over = false, warn = 75 }) { + const result = spawnSync('bash', [script], { + encoding: 'utf8', + env: { ...process.env, MODEL_STRATEGY_CTX_WARN: String(warn) }, + input: JSON.stringify({ + model: { display_name: 'Test Model' }, + context_window: { + used_percentage: used / size * 100, + total_input_tokens: used, + context_window_size: size, + }, + exceeds_200k_tokens: over, + cost: { total_cost_usd: 1.92 }, + }), + }); + assert.equal(result.status, 0, result.stderr); + return result.stdout; +} + +test('large window: 250k input at 25% does not trigger a capacity warning', () => { + const output = render({ used: 250000, size: 1000000, over: true }); + assert.match(output, /25%.*250k\/1000k/); + assert.ok(!output.includes('\x1b[31m')); + assert.ok(!output.includes('⚠')); +}); + +test('high occupancy prompts inspection without prescribing conversation clearing', () => { + const output = render({ used: 156000, size: 200000 }); + assert.match(output, /78%.*156k\/200k/); + assert.ok(output.includes('\x1b[31m')); + assert.ok(output.includes('⚠')); + assert.ok(!output.includes('/clear')); +}); + +test('configured warning threshold applies at its boundary', () => { + const input = { used: 120000, size: 200000 }; + assert.ok(!render(input).includes('⚠')); + assert.ok(render({ ...input, warn: 60 }).includes('⚠')); +});