AI動作確認（デモ）

AI が Headed Playwright（可視ブラウザ）でアプリケーションを操作しながら、各ステップをナレーションします。ユーザーは画面を見て OK / NG を返すだけです。手動動作確認の負荷を肩代わりするためのスキルです。

/walkthrough は非推奨（旧称）です。今後は /demo を使用してください。

---

入力パラメータ

対象機能: $ARGUMENTS（Issue番号 / PR番号 / 機能名。なければユーザーに確認）

前提

• Playwright がプロジェクトに導入されていること（無ければ導入を提案）
• dev server / アプリの起動方法が CLAUDE.md から判別できること

---

手順

Phase 1: シナリオ設計

1. CLAUDE.md（テスト方針・起動コマンド・E2E設計書）を読む
2. 対象機能の完了条件・シナリオを把握する（Issue/PR/設計書から）
3. 動作確認するシナリオ（正常系のハッピーパス中心）と、完了条件とのトレーサビリティを提示する

## 動作確認シナリオ

| # | シナリオ | 対応する完了条件 |
|---|---------|----------------|
| 1 | ... | ... |

この内容で動作確認を進めてよいですか？

Phase 2: 環境準備

dev server とテストデータを整えたうえで、同梱スクリプトで Playwright(Headed) 環境を準備する。ブラウザ導入・OS依存・module 解決・runner はスクリプトが肩代わりするため、エージェントがアドホックに再実装しない。

スクリプトの実行形（重要）: 本スキルはプラグインとして配布されるため、スクリプトはユーザーのプロジェクトroot ではなく、プラグイン配下にある。実行は必ず PATH 上のランチャー経由で claude-harness-run skills/demo/scripts/<ファイル名> の形式（パス・バージョン・引用符を付けない。この形だけが Bash(claude-harness-run:*) の1行で allowlist できる）を用い、相対パス skills/demo/scripts/... では呼び出さないこと。環境変数（WALKTHROUGH_*）はコマンドの前に置かず、claude-harness-run --env KEY=VALUE ... で渡す（前置形は allowlist にマッチしない）。claude-harness-run: command not found になった場合のみ bash "<プラグインルート>/skills/demo/scripts/<ファイル名>"（.mjs は node）にフォールバックする（パスは引用符で囲む。プラグインルートはスキル起動時の「Base directory for this skill」から解決した絶対パス。${CLAUDE_PLUGIN_ROOT} は表記上のプレースホルダであり環境変数ではない）。フォールバックした場合はユーザーにランチャー導入を案内すること。cd はせず、dev server を起動したプロジェクトを cwd にしたままスクリプトを実行する（runner は cwd の git root から @playwright/test を解決する）。

<!-- 正本: docs/plugin-path-conventions.md -->

1. dev server / テストデータ

   • dev server をバックグラウンドで起動し、起動を確認する（BASE_URL を控える。既定 http://localhost:3000）
   • 必要なテストデータを投入する

2. セットアップスクリプトを実行

   • claude-harness-run skills/demo/scripts/walkthrough-setup.sh を実行する。
   • 内部で playwright install chromium を行い、uname で OS 判定して依存導入を分岐する（macOS は依存導入をスキップ／Linux は full chromium に対し ldd で不足を検出）。
   • 出力末尾の WALKTHROUGH_SETUP_STATUS=<ready|deps-missing|error> を確認する。
   • error の場合は再実行せず、まずセットアップログを確認して原因（Playwright 未導入など）を解消してから 2. をやり直す。

3. 不足があれば案内コマンドで導入

   • deps-missing の場合、スクリプトは sudo を勝手に実行せず、必要なコマンド（例: sudo <playwright> install-deps chromium）を表示して正常終了する。
   • 表示されたコマンドをユーザーに実行してもらうよう促す（非対話環境ではエージェントは実行できない）。導入後に再度 2. を実行する。

4. runner で起動

   • claude-harness-run skills/demo/scripts/run-walkthrough.mjs "/絶対パス/flow.mjs" をプロジェクトを cwd にしたまま実行する。 runner は createRequire で（cwd の git root 起点に）プロジェクトの @playwright/test を解決するため、プラグイン配下の場所から実行しても壊れない。
   • headed + slowMo + trace が既定 ON。ステップ実況ログ・スクショ・動画保存も runner が行う。
   • WALKTHROUGH_PAUSE_MS（任意）に正の整数msを指定すると、ctx.step / ctx.goto 完了直後に runner が自動でその時間だけ静止する（ゆっくり見せたい場合に使う）。未指定・不正値（0/負数/非数値・2147483647超過等）の場合は静止しない＝従来どおりの挙動。
   • BASE_URL / E2E_USERNAME / E2E_PASSWORD は env で渡す（E2E_* は /create-e2e と共通の命名）。操作手順は flow.mjs（export default async (ctx) => {...}）に書き、ctx.goto / ctx.step / ctx.shot / ctx.login を使う。flow ファイルは絶対パスで渡すこと（cwd 相対で解決される）。
   • 表示不可環境（Linux で DISPLAY 無し等）では runner が自動的に headless + スクショへフォールバックする。明示制御は WALKTHROUGH_HEADED=false（headless）/ WALKTHROUGH_HEADED=true（headed 強制）。WSL の Headed は WSLg（DISPLAY）前提。
   • 注意: trace は入力値も記録され得る（sources 有効）。認証情報を含む成果物の取り扱いに注意する。

Phase 3: デモ実行

各シナリオについて、Headed Playwright でブラウザを操作しながらステップを実況する:

1. 各操作の前に「これから何をするか」を一文で述べる（例:「ログイン画面を開きます」→「認証情報を入力します」→「ログイン成功を確認します」）
2. 操作を実行し、画面の結果を述べる
3. シナリオ完了後、ユーザーに確認を求める:

## シナリオ {N}/{総数}: {名前}

{実行したステップの要約}
→ 期待結果: {...}（達成 / 未達成）

画面の動作を確認してください（OK / NG / 修正点）。

ユーザー回答	アクション
OK	次のシナリオへ
NG + 詳細	問題を報告。実装側の修正が必要な場合はその旨を伝える
修正点	シナリオを調整して再実行

Phase 4: エビデンスと結果

• 各シナリオの trace / スクリーンショット / 動画の保存先を報告する
• 結果サマリー（確認済み / NG / スキップ）を提示する

Phase 5: E2Eテスト化（任意）

ユーザーが希望する場合、OK となったシナリオを E2Eテストとして永続化する:

• /create-e2e を呼び出し、確認済みシナリオを正常系テストケースとして実装する（create-e2e は非対話・仕様ベース）
• 動作確認はこのデモで完了しているため、確認済みシナリオをそのままテストケース化する

---

注意事項

• 破壊的操作（データ削除・外部送信）を伴う場合は、実行前にユーザーへ確認する
• 操作対象が見つからない場合は data-testid 等のセレクタを確認し、必要なら実装側に追加を提案する
• メール送信等の外部副作用は、送信トリガーまでの確認に留める