設定リファレンス

設定は2層をdeep mergeする

project configはrepositoryへcommitされる前提で扱います。GitHubとruntimeのsecretは環境変数、keychain、または~/.config/specrunner/credentials.jsonで解決します。詳しくは権限・認証・環境変数を参照してください。

merge規則。 objectは再帰的にmergeし、project localが勝ちます。arrayは連結せず、project localのarrayで全体を置き換えます。

設定の置き場所を分ける

.specrunner/*はignoreし、!.specrunner/config.jsonだけを追跡する設定がinitで追加されます。

Project configの実用例

自動検出に任せる項目は書かず、repositoryとして固定したい契約だけを宣言します。

{
  "version": 1,
  "verification": {
    "commands": [
      { "name": "typecheck", "run": "npm run typecheck" },
      { "name": "test", "run": "npm test" },
      { "name": "lint", "run": "npm run lint" }
    ]
  },
  "tests": {
    "placement": { "style": "sibling", "suffix": ".test.ts" }
  },
  "archive": {
    "protectedPaths": [".github/workflows/**"],
    "postMergeVerify": ["npm ci"]
  }
}

Step configは6段階で解決する

model、maxTurns、timeoutMsは各fieldごとに、最初に定義された値を使用します。

1. 1steps.<step>.byRequestType.<type>.<field>
2. 2steps.<step>.<field>
3. 3steps.defaults.byRequestType.<type>.<field>
4. 4steps.defaults.<field>
5. 5step hardcoded default
6. 6SDK default

{
  "version": 1,
  "steps": {
    "defaults": {
      "model": "claude-sonnet-4-6",
      "maxTurns": null,
      "timeoutMs": null
    },
    "design": {
      "byRequestType": {
        "spec-change": { "model": "claude-opus-4-6[1m]" },
        "chore": { "model": "claude-sonnet-4-6" }
      }
    }
  }
}

managed runtimeではmodel指定を実行に使いません。 managed agentは登録済みmodelを使用します。config effectiveは設定値を表示しますが、実行時に無視される旨も表示します。

built-in model、provider dispatch、custom modelの制約は対応プロバイダーを参照してください。

主要な設定キーと既定値

Verificationを言語非依存にする

workspace.setupとverification.commandsは、文字列または{ name?, run }の配列です。POSIX shellで順番に実行し、最初のnon-zeroで停止します。

{
  "verification": {
    "commands": ["npm run typecheck", "npm test"],
    "coverage": {
      "command": "npm test -- --coverage",
      "lcovPath": "coverage/lcov.info",
      "include": ["src/**"],
      "exclude": ["src/generated/**"],
      "minChangedLineCoverage": 0.8
    }
  }
}

coverage command失敗、lcovの欠落・空ファイル、対象fileのlcov欠落はfailです。

Archiveと任意連携

inboxは運用オプションです。 GitHub Issue起点の無人運用を前提にしません。CLIでrequestを投入する運用ではinbox設定は不要です。

archive guardの設計と実行順はPR・merge・archiveで確認できます。

認証・診断の環境変数

GitHub tokenの解決順はGH_TOKEN → GITHUB_TOKEN → gh auth token → credentials.jsonです。

runtime別の必須変数、GitHub最小権限、GHES、secretの受け渡しは権限・認証・環境変数を参照してください。

変更前後に解決結果を確認する

config effectiveはstandard agent stepのmodel・maxTurns・timeoutMsと、それぞれの取得元を表示します。config全体のdumpではありません。

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

確認範囲。 config変更後は構文だけでなく、対象request typeでどのstep値が採用されたかまで確認します。

目的別の最小例は設定レシピを参照してください。