bare-eval

Bare Eval — 分離された評価呼び出し

プラグインのオーバーヘッドなしで高速かつクリーンに評価／採点するには、claude -p --bare を実行します。

CC 2.1.81 が必要です。 --bare フラグを指定すると、フック、LSP、プラグイン同期、スキルディレクトリの走査がスキップされます。

使用する場面

• スキルの出力をアサーションに照らして採点する
• トリガーの分類（プロンプトに一致するスキルの判定）
• 説明を反復的に最適化する
• プラグインを必要としないスクリプト化された -p 呼び出し全般

使用しない場面

• スキルのルーティングをテストする（--plugin-dir が必要）
• エージェントのオーケストレーションをテストする（完全なプラグインコンテキストが必要）
• 対話型セッション

前提条件

# --bare requires ANTHROPIC_API_KEY (OAuth/keychain disabled)
export ANTHROPIC_API_KEY="sk-ant-..."

# Verify CC version
claude --version  # Must be >= 2.1.81

クイックリファレンス

呼び出しの種類	コマンドパターン
採点	claude -p "$prompt" --bare --max-turns 1 --output-format text
トリガー	claude -p "$prompt" --bare --json-schema "$schema" --output-format json
ストリーミング採点	claude -p "$prompt" --bare --max-turns 1 --output-format stream-json
最適化	echo "$prompt" | claude -p --bare --max-turns 1 --output-format text
スキルの強制指定	claude -p "$prompt" --bare --print --append-system-prompt "$content"
プロンプト内の @ ファイル	claude -p "grade @fixtures/case-1.md against rubric" --bare (CC 2.1.113 Remote Control autocomplete)

長時間のハーネス実行（CC 2.1.199+）： 無人の評価バッチでは CLAUDE_CODE_RETRY_WATCHDOG=1 を設定してください。これにより、容量不足以外の一時的なエラーに対するデフォルトの再試行回数が 300 に引き上げられ、CLAUDE_CODE_MAX_RETRIES の上限 15 も解除されるため、夜間の採点実行が一時的な API の瞬断でバッチの途中に停止するのを防げます。

--output-format stream-json

トークン／ツール呼び出しごとに 1 つの JSON イベントを改行区切りで出力します。これにより、全応答を待たずに、ランナーが出力を段階的に採点したり、プローブの失敗時に早期終了したりできます。

claude -p "$prompt" --bare --max-turns 1 --output-format stream-json \
  | while IFS= read -r line; do
      # line is a single JSON event; inspect $.type == "content_block_delta"
      jq -r 'select(.type == "content_block_delta") | .delta.text' <<< "$line"
    done

次の場合は json より stream-json を使用してください。

• 長い出力を採点し、段階的に採点したい場合
• 別の CLI にステップごとにパイプする場合（例：ork:eval-runner）
• コンテンツに加えてトークンごとのタイミングデータが必要な場合

呼び出しパターン

詳細なパターンと例を読み込みます。

Read("references/invocation-patterns.md")

採点スキーマ

構造化された評価出力用の JSON スキーマ：

Read("references/grading-schemas.md")

パイプライン統合

OrchestKit の評価スクリプト（npm run eval:skill）はベアモードを自動検出します。

# eval-common.sh detects ANTHROPIC_API_KEY → sets BARE_MODE=true
# Scripts add --bare to all non-plugin calls automatically

ベア呼び出し： トリガー分類、スキルの強制指定、ベースライン、すべての採点。 ベアモードを使用しないもの： run_with_skill（ルーティングテストにはプラグインコンテキストが必要です）。

CC 2.1.119：--print がエージェントの tools: ／ disallowedTools: を適用（M122）

CC 2.1.119 より前は、--print モードではエージェントのフロントマターにある tools: と disallowedTools: の設定にかかわらず、デフォルトのツールセット全体が使用されていました。実質的に、ベア評価による採点には制限がなく、エージェントの定義で使用が制限されていても、採点エージェントは任意のツールを呼び出せる状態でした。

2.1.119 以降、--print はエージェントが宣言したツールの範囲を適用します。 評価の設計にあたっては、次の点に注意してください。

影響	対応
制限のないツールアクセスに依存していた評価の採点エージェントは、失敗する可能性があります	採点エージェントのプロンプトを確認して実際に必要なツールを特定し、エージェントの tools: フロントマターで明示的に許可してください
評価結果が対話型実行と一致します	サンドボックス化されていない --print で可能なことではなく、モデルが実際にできることを採点するため、再現性が向上します
--agent <name> も --print で permissionMode を適用します	権限で制限されたツール（Bash、Edit）を使うには、permissionMode: acceptEdits を設定するか、エージェントの定義で明示的な許可リストを指定する必要があります

移行テスト：

# Run an eval against an agent with a deliberately tight tools: list.
# Graders that previously called Read/Bash freely will now fail unless those
# tools are declared on the agent.
claude -p "$prompt" --bare --print --agent grader-test

採点エージェントが「tool not permitted」エラーで失敗した場合は、必要なツールをエージェントの tools: フロントマターに追加して、再実行してください。

CC 2.1.121：採点の決定性を高める CLAUDE_CODE_FORK_SUBAGENT=1（#1545）

CC 2.1.121 より前は、この環境変数は対話セッションでのみ機能していました。2.1.121 以降は、非対話型の実行経路（claude -p、SDK）でも有効になり、採点の呼び出しごとに新しいフォークされたサブエージェントのコンテキストが使われます。

これによって解消される、クロス評価での状態漏えいの問題：

フォークしない場合、連続して実行される claude -p --bare の採点処理は、ハーネスの状態を引き継ぎます。

引き継がれるもの	症状
メモリ MCP のクエリーキャッシュ	採点処理が前回の実行時の古いヒットを参照し、同じフィクスチャの採点結果が異なる
ディスク上の .claude/chain/*.json	「implement」の採点処理が「explore」はすでに実行済みだと思い込む（ファイルは前のテストのもの）
ToolSearch の遅延ツールキャッシュ	最初の採点処理で読み込まれた MCP が、次の採点処理のツールレジストリに混入する
モデル選択の設定	採点処理 N が、採点処理 N-1 の --model=opus を引き継ぐ

これにより、リトライ率が約 5～10％になり、スコアの再現性も失われていました。評価のベースラインが実行ごとに変動し、エンジニアは実際には存在しないリグレッションを追いかけていました。

修正： tests/evals/scripts/lib/eval-common.sh が CLAUDE_CODE_FORK_SUBAGENT=1 をエクスポートするため、このファイルを読み込むすべてのスクリプト（run-trigger-eval、run-quality-eval、run-agent-eval、optimize-description など）で、採点処理が自動的にフォークされます。CI ワークフローの .github/workflows/skill-eval.yml でも、ワークフローのレベルでこの変数を設定しています（前身の orchestkit-eval.yml は 2026-08-01 に廃止されました。採点フェーズでは動作ではなく、説明文を評価していたためです）。古い CC は環境変数を黙って無視します（何も起こりません）。

決定性の契約： 同じフィクスチャに対して同じ採点処理を連続して 2 回実行すると、同じスコアが得られます。tests/evals/scripts/test-grader-determinism.sh で検証済みです。

パフォーマンス

シナリオ	--bare なし	--bare あり	削減効果
1 回の採点呼び出し	起動に約 3～5 秒	約 0.5～1 秒	2～4 倍
トリガー（プロンプトあたり）	約 3～5 秒	約 0.5～1 秒	2～4 倍
評価全体（50 回の呼び出し）	オーバーヘッド約 150～250 秒	約 25～50 秒	3～5 倍

ルール

Read("rules/_sections.md")

トラブルシューティング

Read("references/troubleshooting.md")

動的ワークフローハーネス（スキル内テンプレート）

workflows/skill-fitness.js は、実行可能な動的ワークフローテンプレートです。静的な適合性採点処理（scripts/eval/conformance-check.mjs）をワークフローで補完します。スキルごとに分離されたコンテキストのエージェントを 1 つ起動し、適合度（鮮度／ルーターの明確さ／構造）を採点して、順位付きのスコアカードを作成します。静的な grep では検出できない定性的な変化（説明と本文の件数の不一致、見出しの重複、インストール固有の絶対パス、バージョンのずれなど）を検出できます。Workflow ツールで実行します。

Workflow({ scriptPath: "${CLAUDE_SKILL_DIR}/workflows/skill-fitness.js",
           args: ["assess", "commit", "doctor"] })

そのまま使えるスクリプトではなく、テンプレートとして扱ってください。用途に合わせて SKILLS リストと評価基準を調整してください。コストは実際にかかるため（スキルあたり約 50k トークン、約 112 件すべてを採点すると約 6M トークン）、args で明示的に対象バッチを指定してください。まず静的チェックを実行します。conformance-check.mjs（トークン消費なし）で対象を絞り込んでから、grep では判断できない内容をこのハーネスで評価してください。

ホールドアウトのベイクオフ採点

ホールドアウトへの昇格ゲートでは、同じ非公開ホールドアウトを使い、ベアモードのフォークされた採点処理でチャンピオンとチャレンジャーの SKILL.md を採点します。これは上記の決定性の契約を標準的に利用するものです。同じ採点処理、同じ ork-rubric/1.0、同じ非公開セットを使い、CLAUDE_CODE_FORK_SUBAGENT=1 を設定することで、テスト対象のバージョンだけが変数になります。どちらも --bare の制約が適用されます（ANTHROPIC_API_KEY が必要で、トークン料金が直接発生するため、オンデマンドまたは CI でのみ実行してください）。bash tests/evals/scripts/run-skill-eval.sh --holdout-promote <skill> で実行します。

関連項目

• eval:skill npm スクリプト — スキル評価を統合的に実行
• eval:trigger — トリガー精度のテスト
• eval:quality — A/B 品質比較
• optimize-description.sh — 説明文を反復的に改善
• バージョン互換性：doctor/references/version-compatibility.md