Dev Webtest Plan

Dev Webtest Plan

dev-plan の出力（acceptance-criteria.md の Given/When/Then、タスクファイルの Test Strategy 等）から、dev-webtest が実行する Playwright 用 Web テスト計画ファイルを自動生成するスキル。画面仕様ドキュメント（Screen Spec）の変更差分から既存テスト計画を更新する差分更新モードも備える。

前提知識

dev-* スキルフロー内の位置

dev-context → dev-plan → [dev-webtest-plan] → dev-impl → dev-verify → dev-webtest
                              ↓                                           ↑
                    docs/dev/webtests/plans/*.md ─────────────────────────┘

dev-screen-spec → [dev-webtest-plan update] → dev-webtest
                        ↓ (差分更新)              ↑
              docs/dev/webtests/plans/*.md ───────┘

引数フォーマット

/dev-webtest-plan <dev-plan-name>          # 新規生成モード
/dev-webtest-plan update                   # 差分更新モード（全webtest計画対象）
/dev-webtest-plan update <plan-name>       # 差分更新モード（特定webtest計画のみ）

• dev-plan-name: 既存の Plan 名（docs/dev/plans/<dev-plan-name>/ が存在すること）
• update: 差分更新モードのキーワード
• plan-name: 更新対象のwebtest計画名（省略時は全計画を対象）

モード自動判定

引数で自動判定する（ユーザー質問不要）:

引数が "update" で始まる → 差分更新モード
それ以外 → 新規生成モード（現行通り）

新規生成モードのサブ判定

acceptance-criteria.md の存在で自動判定する:

差分更新モード

サブエージェント制約（重要）

サブエージェントは Task ツールを使用できない（ネスト不可のアーキテクチャ制約）。そのため:

• コード探索は Glob/Grep/Read を直接使用する
• TodoWrite は使用しない（TaskCreate/TaskUpdate で進捗管理する）
• サブエージェントに渡すのはファイルパスのみ。サブエージェントが自分で Read する

コンテキスト管理戦略

メインコンテキストの肥大化を防ぐため、中間ファイルとパス参照 を使用する:

• メインエージェントはファイルの全文を Read しない（パス存在確認・Grep での部分情報取得のみ）
• サブエージェントに渡すのはファイルパス。サブエージェントが自分で Read する
• Phase 間のデータ受け渡しは中間ファイル経由（tmp/webtest/plan/<plan-name>/）
• サブエージェントの返却はマーカー＋ファイルパス＋行数のみ

中間ファイル（新規生成モード）

tmp/webtest/plan/<plan-name>/
├── task-summary.md          # Phase 2a で生成（タスクサマリー）
├── explore-plan-result.md   # Phase 2a の出力（Plan 分析結果）
├── explore-code-result.md   # Phase 2b の出力（UI 要素情報）
└── design-result.md         # Phase 3 の出力（構造設計結果）

中間ファイル（差分更新モード）

tmp/webtest/update/
└── analyze-<plan-name>.md   # Phase 2 の出力（変更分析結果）

ワークフロー（新規生成モード）

以下は引数が update で始まらない場合のワークフロー。

Phase 1: コンテキスト確認と入力検証（メイン）

1. docs/dev/context.md の存在を確認する。存在しない場合は /dev-context の実行を案内して終了する
2. docs/dev/plans/<dev-plan-name>/ の存在を確認する。存在しない場合は /dev-plan の実行を案内して終了する
3. モード自動判定: docs/dev/plans/<dev-plan-name>/acceptance-criteria.md の存在を確認する
   • 存在する → Full-spec モード
   • 存在しない → Lightweight モード
4. Full-spec 時: acceptance-criteria.md, user-stories.md, requirements.md のパスを記録する（Read はしない）
5. docs/dev/plans/<dev-plan-name>/tasks/ 配下のタスクファイルパス一覧を Glob で取得する（Read はしない）
6. Grep で status: done のタスクがあるか確認する（Phase 2b 実行判定用）
7. タスクの Files セクションに記載されたファイルが実際に存在するか Grep + Glob で確認する（Phase 2b 実行判定用）
8. 既存 webtest plan との重複確認:
   • docs/dev/webtests/plans/ 配下を Glob で確認
   • 同一 source-plan の webtest plan が存在する場合は AskUserQuestion で上書き確認する
9. 中間ファイルディレクトリを作成する: mkdir -p tmp/webtest/plan/<plan-name>/

Phase 2: 画面・フロー・API分析（Explore サブエージェント x2 並列）

2a. dev-plan 分析（Explore, haiku）と 2b. 実装コード探索（Explore, haiku、オプション）を並列で実行する。API セットアップ/クリーンアップに必要なエンドポイント情報も同時に収集する。

2a. dev-plan 分析

1. references/explore-plan-prompt-template.md を Read で読み込む
2. テンプレートのプレースホルダーを置換する:
   • {{PLAN_MD_PATH}} ← plan.md の絶対パス
   • {{ACCEPTANCE_CRITERIA_PATH}} ← acceptance-criteria.md の絶対パス（Lightweight 時は「なし」）
   • {{TASK_FILE_PATHS}} ← 全タスクファイルの絶対パス一覧（1行1パス）
   • {{MODE}} ← "Full-spec" または "Lightweight"
   • {{TMP_DIR}} ← tmp/webtest/plan/<plan-name>/ の絶対パス
3. Explore サブエージェント（haiku）を起動する
4. 出力のマーカーを確認する:
   • EXPLORE_PLAN_SUCCESS → Phase 3 へ進む
   • EXPLORE_PLAN_FAILED → エラー理由をユーザーに報告して終了

2b. 実装コード探索（オプション）

以下のいずれかの条件を満たす場合のみ実行する:

• タスクファイルに status: done が1つ以上存在する
• タスクの Files セクションに記載されたファイルが実際に存在する（Glob で確認）

条件を満たさない場合はスキップし、Phase 3 で draft: true として設計する。

追加探索: API セットアップ/クリーンアップ用のエンドポイント情報も収集する:

• API仕様ファイルの自動探索（openapi.yaml, swagger.json 等）
• ルーティング定義からのCRUD APIエンドポイント抽出
• 認証フローの調査（ログインAPI、トークン取得方法）

1. references/explore-code-prompt-template.md を Read で読み込む
2. テンプレートのプレースホルダーを置換する:
   • {{CONTEXT_MD_PATH}} ← context.md の絶対パス
   • {{TARGET_FILES}} ← タスクの Files セクションから抽出したファイルパス一覧
   • {{TMP_DIR}} ← tmp/webtest/plan/<plan-name>/ の絶対パス
3. Explore サブエージェント（haiku）を起動する
4. 出力のマーカーを確認する:
   • EXPLORE_CODE_SUCCESS → Phase 3 へ進む
   • EXPLORE_CODE_FAILED → スキップ、draft: true で進行

Phase 3: webtest plan 構造設計（Plan サブエージェント）

API セットアップ/クリーンアップの設計も含む。Phase 2 の分析結果からAPIエンドポイント情報を活用し、各 webtest plan に実行可能な curl コマンドを設計する。

1. references/design-prompt-template.md を Read で読み込む
2. テンプレートのプレースホルダーを置換する:
   • {{MODE}} ← "Full-spec" または "Lightweight"
   • {{EXPLORE_PLAN_RESULT_PATH}} ← tmp/webtest/plan/<plan-name>/explore-plan-result.md の絶対パス
   • {{EXPLORE_CODE_RESULT_PATH}} ← tmp/webtest/plan/<plan-name>/explore-code-result.md の絶対パス（スキップ時は「なし」）
   • {{TASK_SUMMARY_PATH}} ← tmp/webtest/plan/<plan-name>/task-summary.md の絶対パス
   • {{WEBTEST_PLAN_FORMAT_PATH}} ← references/webtest-plan-format.md の絶対パス
   • {{TMP_DIR}} ← tmp/webtest/plan/<plan-name>/ の絶対パス
3. Plan サブエージェントを起動する
4. 出力のマーカーを確認する:
   • DESIGN_SUCCESS → Phase 4 へ進む
   • DESIGN_FAILED → エラー理由をユーザーに報告して終了

Phase 4: TaskCreate で並列生成タスク登録（メイン）

Phase 3 の中間ファイル tmp/webtest/plan/<plan-name>/design-result.md を Read し、webtest plan の一覧を抽出する。各 webtest plan ごとに TaskCreate を実行する:

TaskCreate:
  subject: "webtest-plan: <webtest-plan-name>"
  description: "<webtest-plan-name> の webtest plan ファイルを生成する"
  activeForm: "Generating webtest-plan: <webtest-plan-name>"

ID マッピングテーブルを構築する: {"login-form": "<TaskCreate_ID>", ...}

通常は依存関係なし（並列生成可能）。

Phase 5: webtest plan ファイル生成（general-purpose サブエージェント x N）

TaskList で status: pending のタスクを取得し、各タスクについて:

1. TaskUpdate で in_progress にする
2. references/generate-prompt-template.md を Read で読み込む
3. テンプレートのプレースホルダーを置換する:
   • {{WEBTEST_PLAN_NAME}} ← webtest plan 名
   • {{TARGET_URL}} ← target-url
   • {{DRAFT_FLAG}} ← true / false
   • {{MODE}} ← "Full-spec" または "Lightweight"
   • {{DESIGN_RESULT_PATH}} ← tmp/webtest/plan/<plan-name>/design-result.md の絶対パス
   • {{TASK_SUMMARY_PATH}} ← tmp/webtest/plan/<plan-name>/task-summary.md の絶対パス
   • {{EXPLORE_CODE_RESULT_PATH}} ← tmp/webtest/plan/<plan-name>/explore-code-result.md の絶対パス（ない場合は「なし」）
   • {{WEBTEST_PLAN_FORMAT_PATH}} ← references/webtest-plan-format.md の絶対パス
   • {{SIGNAL_GUIDELINES}} ← 信号機基準（Full-spec / Lightweight で異なる）
   • {{ACCEPTANCE_CRITERIA_PATH}} ← acceptance-criteria.md の絶対パス（Full-spec 時のみ、Lightweight 時は「なし」）
4. general-purpose サブエージェントを起動する
5. 出力のマーカーを確認する:
   • GENERATE_SUCCESS → TaskUpdate で completed にする
   • GENERATE_FAILED → エラー理由を記録、TaskUpdate で completed（レポートに失敗として記載）
6. 複数の webtest plan がある場合は並列で実行する（Agent ツールを複数同時起動）

Phase 6: 完了レポートと次ステップ案内（メイン）

ユーザーに以下のレポートを出力する:

## dev-webtest-plan 完了レポート

### 生成概要
- Source Plan: <dev-plan-name>
- モード: Full-spec / Lightweight
- 生成ファイル数: N

### 生成ファイル一覧

| ファイル | target-url | draft | シナリオ数 | 🔵 | 🟡 | 🔴 | APIセットアップ |
|---------|-----------|-------|----------|-----|-----|-----|--------------|
| login-form.md | http://app:8080/login | false | 5 | 3 | 1 | 1 | あり（共通1, 固有0） |
| dashboard.md | http://app:8080/dashboard | true | 3 | 0 | 2 | 1 | あり（共通1, 固有2） |

### 対象外タスク
- task-NNN: <理由（API のみ、バッチ処理等）>

### ⚠️ 🔴 警告
以下のシナリオは前工程に根拠がなく、AI が推論で追加しました。内容を確認してください:
- <ファイル名> シナリオN: <シナリオ名>

### 📋 draft ファイルの補完方法
draft: true のファイルは UI 要素名が推定です。
dev-impl 完了後に `/dev-webtest-plan <dev-plan-name>` を再実行すると、
実装コードから UI 要素を確認し draft: false に更新できます。

### 🚀 次のステップ
- 実装前の場合: `/dev-impl <dev-plan-name>` で実装を進める
- 実装後の場合: `/dev-webtest <webtest-plan-name>` でテストを実行する

レポート出力後、中間ファイルをクリーンアップする:

rm -rf tmp/webtest/plan/<plan-name>/

信号機基準（新規生成モード）

サブエージェント戦略（新規生成モード）

エスカレーション条件（新規生成モード）

以下の場合は自動処理を停止し、ユーザーに確認する:

1. context.md 不在: /dev-context を案内して終了
2. plan 不在: /dev-plan を案内して終了
3. 既存 webtest plan との重複: AskUserQuestion で上書き確認
4. Phase 2a 失敗: plan.md の情報不足を報告して終了
5. Phase 3 失敗: 設計不能の理由を報告して終了

マーカー文字列（新規生成モード）

ワークフロー（差分更新モード）

以下は引数が update で始まる場合のワークフロー。新規生成モードとは完全に独立。