name: scenario-design description: Codex 側のシナリオ設計作業プロトコル。必須要件、受け入れテスト観点、システムテスト分類、受け入れ条件、検証入口を task 内成果物 に固定する基準を提供する。
シナリオ設計
目的
scenario-design は作業プロトコルである。
designer agent が必須要件、シナリオ、受け入れ条件を固定するための、観測点、テスト語彙、fake / stub、検証コマンド、リスク の見方を提供する。
実行境界、正本、引き継ぎ、停止 / 戻し は design-bundle を参照する。
対応ロール
designerが使う。- 呼び出し元は
implement_laneまたは人間とする。 - 返却先は 人間レビュー または
implement_laneとする。 - 担当成果物は
scenario-designの出力規約で固定する。
入力規約
- task 内成果物: 呼び出し元から渡された設計成果物。
- 根拠参照: シナリオ設計の根拠にする要件、候補成果物、観測事実。
- 承認状態: 呼び出し元が渡す承認済みまたは未承認の状態。
外部参照規約
- エージェント実行定義と実行境界は designer.toml に従う。
- 要件正本: spec.md とする。
- architecture 正本: architecture.md とする。
- ER 正本: er.md と diagrams/er とする。
- 画面正本: screen-design とする。
- page 要件正本: detail-specs とする。
- scenario 正本: scenario-tests とする。
- シナリオ設計雛形: scenario-design.md
- 候補網羅 JSON 雛形: scenario-design.candidate-coverage.json
- 候補生成 観点別 skill: actor-goal、lifecycle、state-transition、失敗、external-integration、operation-audit
- 実行定義 skill: SKILL.md
- 外部成果物 が不足または衝突する場合は停止し、衝突箇所を返す。
内部参照規約
シナリオ候補生成
シナリオ 候補生成は implement_lane が designer の前に指揮する。
designer は候補生成器を再 起動 せず、作業計画フォルダに揃った 候補成果物 を統合する。
候補生成 agent は次の 6 体に固定する。
| agent | 出力ファイル | 観点 |
|---|---|---|
scenario_actor_goal_generator | scenario-candidates.actor-goal.md | アクター目的ベース |
scenario_lifecycle_generator | scenario-candidates.lifecycle.md | ライフサイクルベース |
scenario_state_transition_generator | scenario-candidates.state-transition.md | 状態遷移ベース |
scenario_failure_generator | scenario-candidates.failure.md | 異常系 |
scenario_external_integration_generator | scenario-candidates.external-integration.md | 外部連携 |
scenario_operation_audit_generator | scenario-candidates.operation-audit.md | 運用・監査 |
各 候補ファイル は、対応する観点別 skill の assets/scenario-candidates.viewpoint.md で書く。
必須項目は 根拠要件、観点、候補 シナリオ id、実行者、trigger、expected 結果、observable point、related detail requirement type、adoption hint とする。
designer は候補を読んで、最終 シナリオ表 の前に scenario-design.candidate-coverage.json を作る。
この JSON は 生成 agent、candidates、conflicts、final_mapping、unresolved_questions を持つ。
候補 の decision は次に固定する。
adoptedmergedrejectedconflictedneeds_human_decision
adopted と merged は final_scenario_id を持つ。
rejected は decision_rationale を持つ。
conflicted と needs_human_decision は question_id を持ち、質問票へ出す。
競合処理
競合は scenario-design.questions.md に流す。
質問票は詳細要求タイプ未決と シナリオ 候補競合を同じファイルにまとめる。
競合検知対象は次にする。
- 同じ要求から異なる正常系 結果 が出ている
- 状態遷移の前提が 生成 agent 間で矛盾している
- 異常系が正常系の受け入れ条件を否定している
- 外部連携の失敗扱いが lifecycle と矛盾している
- 運用・監査の保存対象が
security_requirement/data_requirementと衝突している - UI / API / lower-level の検証段階が シナリオ 間で食い違っている
未解決競合が 1 件でもあれば シナリオ 完了 にしない。
詳細要求タイプ
抽象要件は、シナリオ を作る前に詳細要求タイプへ展開する。 展開目的は「AI が推測で埋めた判断」を検出し、人間に確認すべき未決だけを質問票へ出すことである。
| 観点 | 問い | 要求タイプ |
|---|---|---|
| 正常系 | 何が成功すればよいか | success_requirement |
| 代替系 | 別ルートで成功する条件は何か | alternative_success_requirement |
| 例外系 | 何が失敗し、どう扱うか | failure_handling_requirement |
| 境界値 | 最小、最大、空、重複、期限はどう扱うか | boundary_requirement |
| 状態 | どの状態なら実行可能か | state_requirement |
| データ | 何を作成、更新、保存するか | data_requirement |
| 整合性 | どの結果が同時に成立すべきか | consistency_requirement |
| 権限 | 誰ができて、誰ができないか | authorization_requirement |
| セキュリティ | 漏洩、越権、改ざんをどう防ぐか | security_requirement |
| 競合 | 同時実行時にどうなるか | concurrency_requirement |
| 冪等性 | 再送、再実行でどうなるか | 冪等性_requirement |
| 観測性 | ログ、監査、メトリクスに何を残すか | observability_requirement |
| 回復 | 失敗後にどう復旧するか | recovery_requirement |
| 性能 | どの量、時間まで許容するか | performance_requirement |
| 回帰 | 既存仕様に何を壊してはいけないか | compatibility_requirement |
| テスト容易性 | どう検証できるべきか | testability_requirement |
要件種別ごとに、各詳細要求タイプを 必須、条件付き、optional、not_applicable に分類する。
常に全タイプを必須にせず、対象外にする場合も理由を明示する。
明示性判定
各詳細要求タイプは次のいずれかに分類する。
explicit: 根拠成果物 に明示されているderived: 明示情報から機械的に導出できるnot_applicable: 対象外の理由が明示されているdeferred: 延期理由、担当者、再確認条件が明示されているneeds_human_decision: AI が推測すれば埋められるが、人間判断が必要である
needs_human_decision が 1 件でも残る場合は シナリオ 完了にしない。
未決項目だけを質問票へまとめ、人間回答後に詳細要求タイプの明示状態を再評価する。
not_applicable と deferred は理由が空なら通さない。
repo-local 判定条件 は requirement_gate.py を使う。
active task 全体は python3 scripts/harness/run.py --suite scenario-gate で検査する。
単体ファイルは python3 scripts/scenario/requirement_gate.py docs/exec-plans/active/<task-id>/scenario-design.md --report-out docs/exec-plans/active/<task-id>/scenario-design.requirement-gate.md --questionnaire-out docs/exec-plans/active/<task-id>/scenario-design.questions.md で検査する。
scenario-design.requirement-coverage.json がある場合、判定条件 はその JSON を読む。
旧形式の fenced JSON は互換用に読めるが、新規 成果物 では使わない。
scenario-design.candidate-coverage.json は新規 成果物 で必須とする。
判定条件 は 6 生成 agent の出力、候補 採否、未解決競合、競合質問票を検査する。
質問票
質問票は、明示的ではない判断だけを対象にする。 人間が全 成果物 を読み直さなくても答えられるように、質問、やりたいこと、背景、選択肢、AI 推奨、推奨理由、不確実性、回答形式を添える。
scenario-design.requirement-coverage.json の needs_human_decision は次を持つ。
question_id:Q-001形式の連番question_title: 短い質問名unresolved_decision: 「質問」に出す判断user_goal: 「やりたいこと」に出す業務・操作reason: 「背景」に出す未決理由と影響options: 3 件の選択肢と影響。その他は 判定条件 が 4 番として末尾に追加するrecommended_option: AI 推奨の選択肢番号recommendation_reason: 推奨理由uncertainty: 推奨が外れる可能性after_answer_generates: 回答後に固定できる要求タイプまたは シナリオ
質問票の出力形式は次を固定形にする。
### [Q-001] <短い質問名>
質問:
<人間に決めてほしい判断>
やりたいこと:
<実現したい業務・操作>
背景:
<未決理由と影響>
選択肢:
1. <選択肢A>
2. <選択肢B>
3. <選択肢C>
4. その他
AI推奨:
<選択肢番号>
推奨理由:
<推奨理由>
不確実性:
<推奨が外れる可能性>
回答形式:
選択肢番号を選んでください。
4 の場合は、採用したい業務ルールを1〜3文で記入してください。
判断規約
-
必ず通す要件を先に固定する
-
シナリオ 候補母集団を
implement_lane由来の 6 種 候補成果物 から先に確認する -
抽象要件を シナリオ へ進める前に、詳細要求タイプごとの明示状態を確認する
-
候補の採用、統合、不採用、競合、要人間判断を
scenario-design.candidate-coverage.jsonに分ける -
人間判断が必要な暗黙要求は
needs_human_decisionとし、質問票へ集約する -
仕様網羅 JSON は
scenario-design.mdに埋め込まず、scenario-design.requirement-coverage.jsonに分ける -
質問票は
scenario-design.mdに埋め込まず、scenario-design.questions.mdに分ける -
未解決競合は シナリオ 完了にせず、
scenario-design.questions.mdへ集約する -
実装方針の迷いは要件にせず リスク として管理する
-
有料の実AI API を システムテスト 前提にしない
-
正常系だけにしない
-
観測点がない シナリオ を書かない
-
implementation-scope の承認済み実装範囲 を混ぜない
-
用語体系は
受け入れテスト > システムテスト > UI人間操作E2E / APIテストを正本にする -
E2Eは UI 人間操作起点だけを指す -
APIテストは 公開接点 起点の システムレベルテスト として扱う -
受け入れテストは全 シナリオ case で先に固定する
-
各 シナリオ case に
実行テスト種別と実行段階を必ず書く -
実行テスト種別はAPIテスト、UI人間操作E2E、lower-level onlyだけを使う -
実行段階は実装前、実装後、最終検証だけを使う -
APIテストでは、受け入れ条件、公開接点 / API 境界、入力開始点、主要 結果、主要観測点、契約固定 の有無を固定する -
UI人間操作E2Eでは、開始操作、入力方法、主要操作列、主要観測点、UI-visible 結果、fake / stub 方針を固定する -
UI が入口の機能では、裏側の直接呼び出しや 検証データ 直接投入だけで成立するものを UI人間操作E2E と呼ばない
-
必ず通す要件と リスク を分ける
-
implement_lane由来の 候補成果物 を統合してから シナリオ表 を作る -
詳細要求タイプの明示状態を シナリオ 前に確認する
-
候補網羅 と 競合 を JSON 別ファイルに分ける
-
needs_human_decisionは別ファイルの質問票に集約する -
仕様網羅 JSON は別ファイルにし、Markdown 本文へ埋め込まない
-
再現可能な 検証データ と fake provider を優先する
-
受け入れ条件 と 検証 を結びつける
-
正本化 対象 を記録する
-
APIテストとUI人間操作E2Eの必須情報を混同しない -
UI が入口の場合は、画面操作から得られる入力値を
UI人間操作E2Eの検証対象にする
非対象規約
- 人間判断が必要な暗黙要求や未解決競合を AI 判断で固定しない。
designerから候補生成器を再起動しない。- 実装方針、implementation-scope の承認済み実装範囲、プロダクトテスト実装詳細は扱わない。
- 有料の実API 前提や観測不能な期待結果は扱わない。
- 裏側の直接呼び出しだけの検証を UI 入口の
UI人間操作E2Eとして扱わない。
出力規約
- 判断結果: シナリオ設計の完了、未完了、停止の判定を返す。
- 根拠参照: シナリオ設計の根拠にした要件、候補成果物、観測事実を返す。
- 不足情報: シナリオ設計を固定できない不足項目を返す。
- 次判断材料:
designerまたはimplement_laneが次を判断できる材料を返す。 - 禁止事項: 出力にツール権限、エージェント実行定義、プロダクトコード変更の指示を含めない。
完了規約
- task 内成果物 が承認状態、根拠参照、未決事項を含んでいる。
- 人間レビュー が必要な判断を AI だけで完了扱いにしていない。
- 必ず通す要件と リスク を分けた。
- 抽象要件を詳細要求タイプへ展開した。
- 各詳細要求タイプを
explicit、derived、not_applicable、deferred、needs_human_decisionに分類した。 - 仕様網羅を
scenario-design.requirement-coverage.jsonに分離した。 needs_human_decisionだけをscenario-design.questions.mdへ集約した。- 利用者操作の流れ と シナリオ表 を分けた。
- 受け入れテストを全 シナリオ case で先に固定した。
- 各 シナリオ case に
実行テスト種別と実行段階を書いた。 - 開始条件、操作、期待結果、観測点を明示した。
APIテストでは受け入れ条件、公開接点、入力開始点、主要 結果、主要観測点、契約固定 を固定した。UI人間操作E2Eでは開始操作、入力方法、主要操作列、主要観測点、UI-visible 結果、fake / stub 方針を固定した。- fake / 検証データ / 検証コマンド を確認した。
停止規約
- 人間判断が必要な暗黙要求を AI 判断で固定する必要がある場合は停止する。
- 未解決競合を AI 判断で解消する必要がある場合は停止する。
designerから候補生成器を再起動する必要がある場合は停止する。- 観測不能な期待結果を書く必要がある場合は停止する。
- 停止時は不足項目、衝突箇所、戻し先を返す。