設定レシピ

置き場所と確認方法を固定する

ここでは、再現できる運用目的がある5ケースだけを扱います。全キー、既定値、deep merge規則はConfigurationを参照してください。

読み方。 各レシピは「目的 → 最小設定 → 確認command → PASS / STOP」の順です。既存configへは必要なobjectだけをmergeします。

利用できるprovider、built-in model、local / managedの対応差は対応プロバイダーを参照してください。

1. Anthropicだけでlocal実行する

初回だけinit --provider anthropicを使います。生成されるuser global configの中心は次の内容です。

npx specrunner init --provider anthropic
npx specrunner config effective
npx specrunner doctor

{
  "version": 1,
  "agents": {},
  "steps": {
    "defaults": {
      "model": "claude-sonnet-4-6",
      "maxTurns": null,
      "timeoutMs": null
    }
  }
}

initは既存global configを変更しません。 fileがすでに存在する場合はscaffoldをskipします。providerを切り替える場合は、現在値を保全してsteps.defaults.modelを明示的に編集します。headless実行ではclaude setup-token後にspecrunner login --provider claudeで保存します。

2. OpenAIだけでlocal実行する

OpenAI scaffoldは軽量modelを既定にし、designだけ上位modelへ分けます。--runtime localは現在のinitでは不要で、指定するとargument errorです。

npx specrunner init --provider openai
codex login
npx specrunner config effective
npx specrunner doctor

{
  "version": 1,
  "agents": {},
  "steps": {
    "defaults": {
      "model": "gpt-5.4-mini",
      "maxTurns": null,
      "timeoutMs": null
    },
    "design": {
      "model": "gpt-5.5"
    }
  }
}

CODEX_API_KEYをSpecRunnerのSDK認証として扱いません。 現行revisionはOPENAI_API_KEYを読み、Codex SDKのapiKeyへ明示的に渡します。通常はcodex loginの保存済み認証を使います。

3. stepごとにProviderを混成する

local runtimeはeffective modelをbuilt-in registryで解決し、AnthropicまたはOpenAI runnerへdispatchします。built-in modelだけならmodels追加は不要です。

{
  "version": 1,
  "steps": {
    "defaults": {
      "model": "claude-sonnet-4-6"
    },
    "design": {
      "model": "gpt-5.5"
    },
    "code-review": {
      "model": "gpt-5.4"
    }
  }
}

npx specrunner config effective --json
npx specrunner doctor

認証はstepごとではなく実行環境へ用意します。途中で初めてOpenAI stepへ到達してから失敗しないよう、run前に両方を確認します。

4. 重いrunだけ上限を広げる

通常値を無制限にせず、spec-changeだけturnと時間を広げます。次の例はlocal Anthropic向けです。

{
  "version": 1,
  "steps": {
    "defaults": {
      "model": "claude-sonnet-4-6",
      "maxTurns": 30,
      "timeoutMs": 1800000,
      "byRequestType": {
        "spec-change": {
          "maxTurns": 60,
          "timeoutMs": 3600000
        }
      }
    },
    "design": {
      "byRequestType": {
        "spec-change": {
          "model": "claude-opus-4-6[1m]",
          "maxTurns": 80,
          "timeoutMs": 3600000
        }
      }
    }
  }
}

npx specrunner config effective --type spec-change
npx specrunner config effective --type chore

maxTurnsをOpenAIのコスト上限にしません。 現行Codex runnerはmaxTurnsを解決・表示しますが、SDK実行へ渡していません。OpenAI stepではtimeoutMsとusage実績を運用境界にします。

5. merge前後の安全設定を固定する

待機時間、auto-mergeを止めるpath、merge後に必ず動かすcommandをproject configへ置きます。

{
  "version": 1,
  "archive": {
    "mergeWaitTimeoutMs": 1200000,
    "mergeWaitPollIntervalMs": 15000,
    "protectedPaths": [
      ".github/workflows/**",
      "infra/production/**",
      "migrations/**"
    ],
    "postMergeVerify": [
      { "name": "install", "run": "npm ci" },
      { "name": "test", "run": "npm test" }
    ]
  }
}

archive commandのidentity確認と再実行順はPR・merge・archiveを正とします。

config変更後の共通確認

1. 01
   通常typeを確認

   config effectiveでmodel・maxTurns・timeoutMsと取得元を確認。

2. 02
   対象typeを確認

   --typeを付け、byRequestTypeが意図したfieldだけを変えるか確認。

3. 03
   runtimeを診断

   doctorのrequired failureを解消し、warningは採用する運用と照合。

npx specrunner config effective
npx specrunner config effective --type spec-change
npx specrunner config effective --type spec-change --json
npx specrunner doctor

実行条件。 expected valueだけでなくsource pathまで一致した場合にrunへ進みます。config effectiveはprovider疎通そのものを保証しません。