モデル差し替えガイド

本ツールはモデル名を能力ロールで抽象化している。モデルの追加・変更・削除は
原則 policies/model-selection.yml の編集だけで完結する。

前提: 実行時のモデル解決順序

  1. CLI --runner <name> — 全ロールを指定 runner で強制上書き (例: --runner mock)
  2. 環境変数 AI_ORCH_RUNNER — 同上
  3. model-selection.yml の各ロール candidates を先頭から評価し、 利用可能 (isAvailable()) な最初の候補を採用
  4. 候補全滅 → fallback_role を再帰的に解決
  5. それでも不可 → defaults.final_fallback_runner (mock)

よくある差し替え

1. あるロールのモデルを変える

roles:
  strong_general_reasoner:
    candidates:
      - runner: claude
        model: claude-sonnet-5        # ← ここを書き換えるだけ

2. premium モデルを設定する / 外す

premium_reasoning_model は optional。未設定でも全 workflow は動作する。

# 環境変数で任意の最上位モデルを指定 (未設定なら候補はスキップされる)
export AI_ORCH_PREMIUM_MODEL="<利用可能な最上位モデル名>"

構築時は Fable 5 をこのロールで使用したが、実行時必須ではない。
使えなくなったら何も設定しなければよい — strong_general_reasoner に fallback する。

3. Antigravity CLI (Gemini 系) を有効化する

docs/antigravity-setup.md の手順でセットアップすると、long_context_model の
第一候補として自動的に使われるようになる (isAvailable が true になるため)。

4. 新しいプロバイダ (runner) を追加する

  1. src/runners/newmodel.ts を作成し Runner インターフェースを実装
  2. src/runners/index.ts の registry に登録
  3. model-selection.yml の該当ロール candidates に追加

orchestrator 本体・workflow・agent 定義の変更は不要。

5. AI なしで動作確認する

shirusu run tasks/sample.md --mode make --runner mock

mock runner は決定的な出力を返すため、workflow・プロンプト組み立て・
ログ保存・リトライ制御を AI 接続なしで検証できる。

差し替え時のチェックリスト