diff --git a/.claude/skills/codex-director/SKILL.md b/.claude/skills/codex-director/SKILL.md index 30dfa85..05fe311 100644 --- a/.claude/skills/codex-director/SKILL.md +++ b/.claude/skills/codex-director/SKILL.md @@ -28,7 +28,7 @@ Claude Code を**ディレクターAI**として動かし、調査・実装・ 1. **整理**: 目的・制約を把握する。コードベースを見れば分かることは自分で調べ、重大な仕様判断だけユーザーに確認する。質問は増やしすぎない。 2. **発注設計**: モデルと推論量を選び（`references/model-routing.md`）、単体で完結する依頼文を組み立てる（`references/delegation-template.md`）。 -3. **発注前報告**: Codex を呼ぶ直前に、選んだ「モデル・推論量・選択理由」の3点をユーザーへ短く伝える。 +3. **発注前報告**: Codex を呼ぶ直前に、選んだ「モデル・推論量・選択理由」の3点をユーザーへ短く伝える。基準より1段下げた発注なら、下げた根拠と、落ちたときの切り分け方も添える。 4. **委任**: 下記コマンドで Codex を呼ぶ。 5. **検収**: 完了後、`references/review-checklist.md` に従って実際の差分とテストを確認する。 6. **最終報告**: 変更内容、選択モデルと推論量、実行した検査、確認した内容、残る制約・未確認事項を簡潔にまとめる。 @@ -37,13 +37,15 @@ Claude Code を**ディレクターAI**として動かし、調査・実装・ この環境では GPT-5.6 が利用可能。3役に次を割り当てる（詳細と検証結果は `references/model-routing.md`）。 -| 役割 | モデルID | 既定の推論量 | +| 役割 | モデルID | 推論量 | |---|---|---| -| 高速・低コスト | `gpt-5.6-luna` | `none`（定型）/ `low`（探索あり） | -| 標準 | `gpt-5.6-terra` | `medium`（デフォルト） | +| 高速・低コスト | `gpt-5.6-luna` | `none`（定型）/ `low`（探索あり）/ `medium`・`high`（設計確定済み） | +| 標準 | `gpt-5.6-terra` | `medium` | | 高性能 | `gpt-5.6-sol` | `high`（上限は `xhigh`） | -判断に迷ったら `gpt-5.6-terra` + `medium`。最大の推論量を常用しない。 +選ぶ順は作業量ではなく判断の持ち主で決める。正しさの判定が難しいか仮説の否定を求めるなら `sol`、設計や探索の余地を Codex に残すなら `terra`、判断がこちらで確定していて依頼文に書き切れているなら `luna` で推論量を上げる。最大の推論量を常用しない。 + +依頼文で迷う余地を消せたぶんはティアを下げられる。逆に、設計判断を渡さずにティアを上げても差し戻しは減らない。 **注意**: `--effort minimal` はプラグインのフラグ検証は通るが GPT-5.6 の API が 400 で拒否する。推論を最小にしたいときは `minimal` ではなく `none` を使う。`max`・`ultra` は rescue 経由では指定できない（フラグ上限が `xhigh`）。 @@ -132,7 +134,9 @@ Codex のサンドボックスはネットワークを閉じており、`127.0.0 試験運用中は、各タスクについて `~/.claude/codex-director/trial-log.md` へ追記する（初回はディレクトリごと作成）。この Skill ディレクトリは dotfiles リポジトリ配下なので、記録をこの中に置かない。ユーザーの許可なくリポジトリへ記録ファイルを追加しない。 -記録する項目: タスク概要 / 選択モデル / 推論量 / 一度で完了したか / 修正依頼の回数 / 最終的に合格したか / モデル選択は適切だったか。モデルの性能は自己評価でなく、実際の差分・テスト・差し戻し回数で判断する。項目は箇条書きで並べ、タスクごとに `## <日付> <リポジトリ>: <タスク名>` の見出しを立てる。 +記録する項目: タスク概要 / 選択モデル / 推論量 / 一度で完了したか / 修正依頼の回数 / 最終的に合格したか / モデル選択は適切だったか / 1段下げて発注したか。モデルの性能は自己評価でなく、実際の差分・テスト・差し戻し回数で判断する。項目は箇条書きで並べ、タスクごとに `## <日付> <リポジトリ>: <タスク名>` の見出しを立てる。 + +「1段下げて発注したか」には、下げた場合はその根拠（依頼文で埋めた判断）と結果を、下げなかった場合は上位ティアが必要だと考えた理由を書く。`luna` の `medium` 以上は未検証なので、試したら結果を必ず残す。ティアを下げられた実測が積まれない限り、判定基準は上位ティアへ戻っていく。 環境の制約や運用の失敗に気づいたら、ログに書くだけで終わらせない。同じ状況で再発するものはこの SKILL.md か `references/` へ昇格させる。ログは一度きりの記録で、次のタスクで読まれる保証がない。 diff --git a/.claude/skills/codex-director/references/delegation-template.md b/.claude/skills/codex-director/references/delegation-template.md index 954f06b..5b72068 100644 --- a/.claude/skills/codex-director/references/delegation-template.md +++ b/.claude/skills/codex-director/references/delegation-template.md @@ -61,6 +61,18 @@ Codex がこの Skill の基本規則に沿って動くよう、依頼文（主 `` は、目的を満たす実装が複数ありうるなら許容範囲まで書く。実運用では、判定条件を1つの数値に絞った依頼文のせいで、正しく動く実装を差し戻す無駄が発生した。検証したい振る舞いを書き、実装の選び方まで決めつけない。 +## 検証できない実装詳細を受入条件に書かない + +サンドボックスの外でしか確かめられない詳細を `` に書くと、Codex は確認できないまま従い、実行段階で落ちる。差し戻しの往復がそのまま増える。 + +実運用では、本番 D1 からローカル D1 へデータを移す実装で2回続けて起きた。「除外するのは `sqlite_%` と `d1_migrations`」と書いたら内部テーブル `_cf_KV` を拾って rowid 不在で落ち、「`BEGIN` / `COMMIT` を維持する」と書いたらローカル D1 が SQL のトランザクション文を拒否して落ちた。どちらもネットワークが要るため Codex 側では検証できない。 + +判断の順は次のとおり。 + +1. その詳細をディレクター側で確かめられるなら、先に実行して確認し、結果を `` に貼る。 +2. 確かめられないなら書かない。目的と満たすべき振る舞いだけを渡し、実装の詳細は Codex に決めさせる。 +3. どうしても方針を指定するなら「未検証の想定」と明示し、違っていたら報告するよう頼む。 + ## 検査コマンドの書き方 `` には、その環境で実際に使う検査コマンドを具体的に書く（例: 型チェック・lint・テストの各コマンド）。何を実行し、何が通れば完了かを Codex 側だけで判定できるようにする。書く前に次を確認する。 diff --git a/.claude/skills/codex-director/references/model-routing.md b/.claude/skills/codex-director/references/model-routing.md index 952179b..1b1bf81 100644 --- a/.claude/skills/codex-director/references/model-routing.md +++ b/.claude/skills/codex-director/references/model-routing.md @@ -19,57 +19,91 @@ GPT-5.6 が使えなくなった場合は、`~/.codex/models_cache.json`（`visi - したがって rescue 経由の実効レンジは `none, low, medium, high, xhigh`。「推論を最小に」は `minimal` ではなく **`none`** を使う。「`high` の一段上」は **`xhigh`**。 - `models_cache.json` の TUI 表示レベル（sol/terra は `ultra` まで、luna は `max` まで）は rescue 経由では届かない。`max`・`ultra` が本当に必要な難題は、この Skill の rescue ベースの範囲外（Codex を直接使う判断）になる。 -## 4段の使い分け +## ティアは判断の持ち主で決める -以下はコード作業を例に説明するが、判断の軸（探索の要否・判断の要否・リスク・完了条件を検証できるか）は非コード作業にも同じく当てはまる。調査を伴う文章や検証の要る技術文章も、この軸でティアを選ぶ。 +作業量ではなく、設計判断を誰が持っているかでモデルを選ぶ。ファイル数・行数はティアの根拠にしない（7ファイルの移行を `terra` + `medium` が一度で通した実測がある）。以下はコード作業を例に説明するが、軸は非コード作業にも同じく当てはまる。調査を伴う文章や検証の要る技術文章も同じ順で判定する。 -### 高速・低コスト（`gpt-5.6-luna`）+ `none` +発注前に次を順に問う。 -次をすべて満たすときだけ使う。 +1. 正しさの判定が難しいか。または仮説を根拠つきで否定してほしいか → `sol` + `high` +2. 設計判断や探索の余地を Codex に残すか → `terra` + `medium` +3. 判断はこちらで確定していて、依頼文に検証済みの事実として書けているか → `luna`。推論量で幅を調整する -- 変更対象または探索範囲が明示されている -- 実装方法がほぼ一意 -- 設計判断が不要 -- 完了条件をコマンドまたは差分で判定できる -- 失敗しても容易に巻き戻せる +2 と 3 の分かれ目は、依頼文を書き終えた時点で Codex に残る裁量の量である。対象ファイルの特定から任せる、実装方針が複数ありうる、境界や基準をこちらで決め切れていない、のいずれかが残るなら 2 になる。 -想定作業: 明示された識別子のリネーム、指定された API 変更への追従、既知のパッチ適用、formatter/lint の自動修正、コード生成コマンドの実行、指定ファイルへの機械的変更、指定された検査コマンドの実行。 +### 高速・低コスト（`gpt-5.6-luna`） -### 高速・低コスト（`gpt-5.6-luna`）+ `low` +| 推論量 | 使う場面 | +|---|---| +| `none` | 変更対象が明示され、実装方法が一意。リネーム、指定された API 変更への追従、既知のパッチ適用、formatter/lint の自動修正、コード生成コマンドの実行、指定した検査コマンドの実行 | +| `low` | 対象ファイルを探す必要がある。軽い判断を伴う。`none` で一度失敗した | +| `medium` | 複数ファイルにまたがるが、設計判断は依頼文で埋まっている。テストの追加位置や境界条件まで指示できている | +| `high` | 構造の理解が要る変更を、設計を確定させた状態で任せる。従来 `terra` + `medium` へ投げていた範囲 | -- 小規模だが対象ファイルを探す必要がある -- 軽い判断を伴う -- 単純作業と断定するには不確実性が残る -- `none` で一度失敗した +`none` と `low` は一度で合格した実測がある。`medium` 以上は未検証で、`terra` の射程をどこまで引き取れるかを測る段階にある。試すときは発注前報告でその旨を伝え、結果を trial-log に残す。推論量を上げれば消費トークンは増えるので、ティアを下げた効果は差し戻し回数と所要時間の両方で見る。 + +合格しなかったときにティアを上げる前に、原因を切り分ける。依頼文に書き切れていない判断があったなら、同じ `luna` で条件を書き足して出し直す。コードベースの構造理解が届いていないと判断できたときだけ `terra` + `medium` へ上げる。 ### 標準（`gpt-5.6-terra`）+ `medium` -通常の実装作業のデフォルト。モデル選択に迷ったらこれ。 +Codex 側に判断を残す通常の実装作業。 -- 複数ファイルの変更 +- 対象ファイルの特定を含む変更 - 一般的な機能追加 - 原因がある程度絞られた不具合修正 -- テスト設計を伴う変更 +- テスト設計の判断を伴う変更 - 小規模なリファクタリング -- コードベースの構造を踏まえた判断 ### 高性能（`gpt-5.6-sol`）+ `high` -- 原因不明の不具合 -- 設計変更を伴う -- 変更の影響範囲が広い -- 認証・権限・セキュリティに関わる -- 並行処理や競合状態を扱う -- データ消失や移行リスクがある -- 間違いを自動テストだけでは検出しにくい -- 標準モデルで合格ラインに達しなかった +次のいずれかに当たるときだけ使う。 + +- 正しさの判定が難しい実装（暗号・認証、時刻ずれや有効期間の境界、並行処理と競合状態、データ消失や移行のリスク） +- 一次資料と実装の広域照合。こちらの仮説を根拠つきで否定してほしい調査 +- 新規ファイルを含む大規模な実装で、構成そのものを組ませる + +次を理由に選ばない。実測で効果が出なかったか、別の手段で解くべき領域である。 + +- ファイル数・行数が多いだけ +- テスト網羅やテスト設計の不足を埋めたい（推論量を上げても解決しない） +- 完了誤認や事実と食い違う報告を防ぎたい（検収の型で防ぐ） +- 設計判断を丸ごと委ねたい（モデルに設計を任せているだけで、検収の負荷は下がらない） + +最大の推論量を常用しない。`sol` + `high` でも不足したときにだけ `xhigh` を検討する。 + +## 指示の質でティアを下げる + +ティアを1段下げられるかは、依頼文で Codex の迷う余地を消せたかで決まる。実測で確認できている（`terra` + `medium` が設計確定済みの発注を一度で通し、逆に判定条件を絞りすぎた依頼文が正しい実装を差し戻させた）。発注前に次を確認する。 + +- 設計判断（基準・境界・命名・分割の方針）を依頼文で決め切ったか +- 環境依存の事実（外部 API の応答、DB の制約、既定バージョン）を先に確かめて `` に貼ったか。確かめられない詳細は書かない（`delegation-template.md`） +- 禁止したい文字列や構文にバリアントがあるなら列挙したか。目的の記述は網羅性を保証しない + +これらを書けていない状態でティアを上げても差し戻しは減らない。書き切れたなら1段下げて発注し、結果を記録する。 + +## コスト差の扱い + +単価はティア選択の決め手にしない。動機の強さを測るために倍率だけ持っておく。 + +2026-07-30 の値下げ後、100万トークンあたりの出力単価は `luna` $1.2 / `terra` $12 / `sol` $30、入力は $0.2 / $2 / $5（[OpenAI の告知](https://openai.com/index/advancing-the-price-performance-frontier-with-gpt-5-6/)。2026-07-31 に確認）。値下げ幅は `luna` が80%、`terra` が20%で、`sol` は据え置き。倍率では `luna` が `terra` の約10分の1、`terra` が `sol` の約2.5分の1になる。改定前の `luna` は `terra` の約2.5分の1だったので、`luna` を試す動機はこの改定で強まった。 + +ただし発注1件のコストは、差し戻し1回で発生するディレクター側の検収サイクル（差分の読み直し、テストの再実行、追加の依頼文）より小さい。安いから下げるのではなく、依頼文で迷う余地を消せたから下げる。単価は判定の順序を覆さない。 + +単価は変わる前提で扱う。`models_cache.json` に単価は載っていないので、この節の数値は確認日つきの参考であり、判断に効くほどの差を感じたら出典を引き直す。サブスクリプション経由の実行では請求は単価ではなくクレジット消費になる（今回の改定でクレジット消費も減り、利用枠は増える）。 + +## 差し戻しのティア + +差し戻しでティアを上げるのは既定にしない。実測では、`sol` の初回出力に対する差し戻しが `terra` + `medium` で通り、`terra` の差し戻しが `luna` + `low` で通っている。範囲が限定された時点で必要な判断量は減っている。 -最大の推論量を常用しない。`sol` + `high` でも不足したときにだけ、一段上の `xhigh` を検討する。 +- 原因が依頼文の不備 → 同じティアで条件を書き直して出し直す +- 修正範囲が特定のファイル・関数に絞れた → 1段下げる +- 原因不明のまま2回落ちた → 上げる。この場合だけ `sol` を検討する ## 実測からの補正 試験運用（`~/.claude/codex-director/trial-log.md`）で分かった傾向。上の基準を実測で補正する。 +- 19発注の内訳は `sol` 7件・`terra` 9件・`luna` 2件で、上位ティアに偏っていた。ログ自身の評価でも `sol` を選ぶ必要がなかった発注が2件ある（調査タスクと workers プール導入）。`luna` の2件はどちらも一度で合格し、失敗例が1件もない。判定の順を「判断の持ち主」に組み替えたのはこの偏りへの対処である。 - `terra` + `medium` の射程は表の記述より広い。コード・設定・生成型・仕様書・テストにまたがる7ファイルの移行を、指示していない箇所を grep で見つけて直すところまで一度で通した。ファイル数の多さだけを理由に `sol` へ上げない。 - テスト網羅とテスト設計の不足は、推論量を上げても解決しない。`sol` + `high` でも「テストが書きにくい設計のまま提出する」「未カバーの分岐を残す」は起きた。必要なテストは依頼文で具体的に指定するか、検収で捕まえる。 - モデルの格上げで防げない失敗もある。workers プールの起動失敗を「完了」と報告した事例は `sol` で起きた。検収の型（件数を数える、実装を壊して確かめる）で防ぐ領域と、モデル選択で解く領域を混同しない。