scenario

シナリオスキル

動作検証用のホールドアウトシナリオを作成、管理します。シナリオでは、測定可能な受け入れベクトルと満足度スコアを用いて、システムが何をすべきかを物語形式で定義します。開発中に実装エージェントが参照できないよう、.agents/holdout/ に保存されます。

クイックスタート

# Initialize holdout directory
/scenario init

# Add a scenario from a description
/scenario add "user can authenticate with valid credentials"

# List all active scenarios
/scenario list

# Validate scenarios against the schema
/scenario validate

実行手順

ステップ 1：ホールドアウトディレクトリを初期化する

ao scenario init

ホールドアウトの分離ルールを説明する README.md を含む .agents/holdout/ を作成します。ディレクトリがすでに存在する場合は何も行いません。

README では、次の点を明確にします。

• 実装エージェントは .agents/holdout/ を読んではいけません
• シナリオを作成するのは評価エージェントと人間だけです
• フックによる制御で、実装エージェントがホールドアウトファイルにアクセスできないようにします

ステップ 2：シナリオを作成する

物語形式の説明を入力すると、このスキルがスキーマに準拠した JSON シナリオファイルを生成します。

ao scenario add "user can authenticate with valid credentials"

このスキルは次の処理を行います。

1. ID（s-YYYY-MM-DD-NNN）を生成します
2. 物語、期待される結果、受け入れベクトルの入力を求めるか、これらを推測します
3. 満足度のしきい値をデフォルト値（0.8）に設定します
4. .agents/holdout/s-YYYY-MM-DD-NNN.json に書き込みます

schemas/scenario.v1.schema.json に準拠した JSON を記述して、手動でシナリオを作成することもできます。シナリオスキーマリファレンスを参照してください。

ステップ 3：シナリオを検証する

ao scenario validate

.agents/holdout/ 内のすべての .json ファイルを schemas/scenario.v1.schema.json に照らして検証します。次の項目を報告します。

• スキーマ違反（必須フィールドの不足、型の誤り）
• 重複した ID
• 古いシナリオ（ステータスが "active" で、日付が 90 日より前）
• チェックコマンドのない受け入れベクトル

ステップ 4：シナリオを一覧表示する

ao scenario list

すべてのシナリオについて、次の情報を表示します。

• ID、目標、ステータス、ソース、日付
• 満足度のしきい値
• 受け入れベクトルの数

絞り込みオプション：

ao scenario list --status active
ao scenario list --status draft
ao scenario list --status retired

シナリオを GOALS.md の指示にリンクする

GOALS.md の指示にリンクされたシナリオは、実行可能な仕様の一部になります。ao goals scenarios --create "<goal>" --directive N は、昇格された仕様シナリオのひな形を作成し、双方向にリンクします。ao goals scenarios は各指示にリンクされたシナリオを一覧表示し、ao goals scenarios --lint はリンクグラフをチェックします。ao scenario add で作成したアドホックなホールドアウトシナリオは、昇格されるまでリンクされません。/goals スキルと docs/adr/ADR-0003 を参照してください。

リンクされた後は、シナリオの合否が指示の適合度に反映されます。ao goals measure は、リンクされたシナリオの結果を指示ごとの scenario_satisfaction 比率に集約します（しきい値未満の場合は RED）。また、ao goals trace は指示 → シナリオ → bead → 判定 → 学習の系譜を表示し、孤立した要素がないか監査します。どちらの機能についても、/goals スキルを参照してください。

ステップ 5：検証との統合

シナリオは /validation スキルの STEP 1.8 で使用されます。検証中、評価エージェントは次の処理を行います。

1. .agents/holdout/ から有効なシナリオをすべて読み込みます
2. 各受け入れベクトルのチェックコマンドを実行します
3. シナリオごとに満足度スコア（0.0～1.0）を算出します
4. スコアを集約して、全体のホールドアウトスコアを算出します
5. いずれかのシナリオがしきい値を下回った場合、検証ゲートを不合格にします

主なルール

ホールドアウトの分離

シナリオはホールドアウトデータです。実装エージェントは決してシナリオを見てはいけません。これにより、正しい一般的な動作を構築する代わりに、エージェントが特定のテストケースに過剰適合するのを防ぎます。

• シナリオはコードベースの外部にある .agents/holdout/ に保存されます
• フックによる制御で、実装エージェントがホールドアウトファイルを読めないようにします
• シナリオにアクセスできるのは、評価エージェント、人間、または /validation スキルだけです

満足度スコアリング

シナリオでは、合否の二択ではなく、連続的な満足度スコア（0.0～1.0）を使用します。これにより、次のことが可能になります。

• 未完成の実装にも部分点を付ける
• イテレーションを通じて傾向を追跡する
• 重要度に応じてシナリオごとにしきい値を調整する

各受け入れベクトルからスコアが算出され、シナリオ全体のスコアは、すべてのベクトルの加重平均になります。

作成ルール

• シナリオは人間または評価エージェントが作成します
• 実装エージェントは、自身のシナリオを作成してはなりません
• source フィールドには、出所として human、agent、または prod-telemetry を記録します
• 評価エージェントがシナリオを作成する場合は、実装の詳細にアクセスできない別のセッションで作業します

シナリオのライフサイクル

ステータス	意味
active	検証時にシナリオが評価されます
retired	シナリオは一貫して合格しており、参照用に保持されています
blocked	依存関係が不足しているため、シナリオを評価できません
draft	シナリオは未完成で、まだ評価されていません

参考ドキュメント

• シナリオスキーマのリファレンス -- シナリオスキーマの全フィールドのドキュメントとJSONの例
• references/scenario.feature — 実行可能な仕様：ホールドアウトシナリオの作成、スキーマ検証、GOALSディレクティブへの一覧表示とリンク、/validation への受け渡し（soc-qk4b）

トラブルシューティング

問題	原因	対処方法
validate でフィールド不足が報告される	スキーマのバージョンが一致していません	version フィールドがスキーマの要件と一致しているか確認します
シナリオが検証の対象にならない	ステータスが active ではありません	JSONで "status": "active" に設定します
実装エージェントがホールドアウトを読んだ	フックがインストールされていません	ao scenario init を実行してフックの設定を確認します
ID重複エラー	2つのシナリオが同じIDを使用しています	s-YYYY-MM-DD-NNN 形式で一方の名前を変更します
シナリオが古いという警告	active のシナリオが90日以上経過しています	シナリオを確認し、廃止するか更新します
スコアが常に0.0	チェックコマンドがゼロ以外を返しています	チェックコマンドを個別にデバッグします

関連項目

• /validation -- STEP 1.8でホールドアウト評価にシナリオを使用します
• /council -- マルチモデルレビューでシナリオの提案を生成できます
• /vibe -- コード品質の検証（動作シナリオを補完します）