qa-ui

UI QA Loop

ChromeDevTools MCPを使い、独立コンテキストのQAエージェントでUI検証を行う。 Generator-Evaluator分離: 実装した自分自身ではなく、別エージェントが画面を見て判定する。

Arguments

• $ARGUMENTS: 確認したい画面やURL（省略可）
  • 指定あり: 指定された画面を優先的に検証
  • 指定なし: ACファイルまたはgit diffから自動特定

ワークフロー

Step 1: ChromeDevTools MCP接続確認

mcp__chrome-devtools-direct__list_pages を呼び出す。

• 成功 → Step 2 へ
• 失敗 → 以下を表示して停止: 「ChromeDevTools MCPに接続できません。Chromeが起動しているか確認してください。」

Step 2: 検証対象 URL の決定 + 開発サーバー確認 + ログイン

1. 検証対象 URL の決定（URL のハードコード禁止）:
   • $ARGUMENTS に完全な URL が含まれる → そのまま採用
   • $ARGUMENTS がパスのみ（/teams/123/foo 等） → ベース URL をユーザーに尋ねて結合
   • $ARGUMENTS が空 → 以下を表示して停止し、ユーザーの返答を待つ: 「検証対象のベース URL を教えてください（例: http://localhost:3000 / staging URL 等）。」
2. mcp__chrome-devtools-direct__navigate_page で決定した URL にアクセス
3. mcp__chrome-devtools-direct__take_snapshot で画面状態を確認
4. 判定:
   • ログイン済み（「でログイン中」の文字列がある） → そのまま進行
   • ログイン画面が表示された → 以下を表示して停止し、ユーザーの返答を待つ: 「ブラウザで対象環境にログインしてから「ログインしました」と返答してください。検証はその後に再開します。」 ユーザーから合図を受けたら take_snapshot で再確認し、ログイン済みなら進行。
   • 接続失敗（net::ERR_CONNECTION_RESET 等） → 以下を表示して停止: 「対象サーバーに接続できません（{URL}）。サーバーが起動しているか、URL が正しいか確認してください。」
   • DB未起動（ActiveRecord::ConnectionNotEstablished） → 以下を表示して停止: 「PostgreSQLが起動していません。DBを起動してから再実行してください。」
   • Pending Migration画面（ActiveRecord::PendingMigrationError） → 「Run pending migrations」ボタンを click して待機後にリロードして再確認

⚠️ URL・認証情報のハードコード禁止。検証対象 URL は $ARGUMENTS またはユーザーへの質問で動的決定する。ログイン操作とテストユーザー選択はユーザーの責任で、エージェントは自動ログインを行わない。権限分岐 (admin / 一般等) の AC がある場合は、QA 開始時に「どの権限のアカウントで検証しますか？」と尋ねる。

Step 3: AC検証項目の特定

ACファイルがある場合

1. プランファイルパスの特定（セッションコンテキスト優先）:
   • 現在のセッションコンテキストに既出のプランファイルパス（典型的には ~/.claude/plans/*.md、/finalize-plan 等で作成されたもの）があれば、それを採用する
   • セッション内に見当たらない → 以下を表示して停止し、ユーザーに尋ねる: 「対応するプランファイルのパスを教えてください（プランが無ければ「無し」と返答 → AC 無しモードへ）。」
   • git checkout -b 文字列マッチによる自動探索は行わない（誤マッチ・古いプランへの誤紐付けを避けるため）
2. プランファイルに対応する *.analysis.md を Read で読み込む
3. UI関連のAC項目を抽出（「画面」「表示」「クリック」「遷移」「フォーム」等のキーワード）
4. UI関連のAC項目が0件 → AC無しモードにフォールバック

AC無しモード

1. git diff --name-only origin/develop...HEAD で変更ファイル取得
2. 変更ファイルが0件 → 以下を表示して完了: 「UI検証対象の変更ファイルがありません。フロントエンド変更を含むブランチで実行してください。」
3. .tsx, .jsx, .slim, .erb, .scss, .css の変更を特定
4. フロントエンド関連の変更が0件 → 以下を表示して完了: 「フロントエンド関連の変更がありません。UI検証は不要です。」
5. 変更されたView/Componentから対象画面URLを推論
6. 最低限の検証項目: 「画面が正常に表示されるか」「JSエラーが出ていないか」

$ARGUMENTS が指定された場合

上記のいずれかで特定した検証項目に加え、指定されたURLや画面を優先的に検証対象に含める。

Step 4: UI検証エージェント起動（ラウンド1）

Agent ツールで ui-evaluator を起動する。

Agent tool:
  subagent_type: general-purpose
  prompt: |
    あなたはUI検証エージェントです。
    以下の指示ファイルを読み、その内容に厳密に従って検証を実行してください。

    指示ファイル: ${CLAUDE_PLUGIN_ROOT}/skills/qa-ui/agents/ui-evaluator.md

    ## 入力
    - ACファイルパス: {ACファイルパス or "なし（AC無しモード）"}
    - 変更ファイル一覧: {git diff --name-only の結果}
    - ラウンド番号: 1
    - 前回の不合格理由: なし（初回）
    - 検証対象画面: {特定した画面URL一覧}

    指示ファイルのワークフローに従い、全AC項目を検証してください。
    結果は指示ファイルの「結果出力」フォーマットに厳密に従ってください。

Step 5: 結果判定

QAエージェントの結果を読み取り、判定する。

総合PASS の場合

以下を表示して完了:

## UI QA 完了

全AC項目がPASSしました。

### スクリーンショット
[QAエージェントが撮影したスクリーンショット一覧]

総合FAIL の場合

不合格項目の重大度を確認:

Critical が1件でも含まれる → 即エスカレート:

## UI QA エスカレート

Criticalな不合格が検出されました。人間の判断が必要です。

### 不合格項目
[QAエージェントの不合格詳細をそのまま表示]

Major/Minor のみ、かつラウンド3未満 → 自動修正:

1. QAエージェントの「修正の示唆」に基づいてコードを修正
2. Step 4 に戻り、ラウンド番号をインクリメントして再度QAエージェント起動

ラウンド2以降のAgent起動時は 前回の不合格理由 にQAエージェントの不合格詳細を含める。

ラウンド3でもFAIL → エスカレート:

## UI QA エスカレート

3回修正しましたが解消できません。

### 解消できなかった項目
[残りの不合格項目]

### 修正履歴
- ラウンド1: [何を修正したか]
- ラウンド2: [何を修正したか]
- ラウンド3: [何を修正したか]

併用推奨 skill

• /finalize-plan — QA 手順と AC の参照元となるプランを準備する
• /review-code-quality — UI 検証と並行して設計レベルの品質を確認する