user-acceptance

ユーザー受け入れの証拠

運用概要

このスキルが起動したら、その機能ブランチ、チケット、または PR が動作することを示す実際の証拠を収集します。依頼の意図は、「機能を実際に動かして、人が確認できる成果物を作成し、完了した作業を証明すること」と捉えてください。

受け入れの証拠は、実体験に基づき、再現可能なものである必要があります。

• UI の変更では、可能であれば動画を撮影し、その後、重要なチェックポイントでスクリーンショットを撮影します。動画では、タイミング、遷移、フォーカス、エンドツーエンドのフローを記録できます。
• CLI および TUI アプリでは、ターミナルの記録、スクリーンショット、録画、生成ファイル、終了コードを保存します。
• API および SDK では、リクエスト、レスポンス、出力ファイル、ログ、実行可能な小規模な例を保存します。
• Electron 系アプリを含むネイティブアプリでは、Agent Browser または Playwright を優先して使い、ブラウザー自動化のインターフェイス（Electron CDP または埋め込み Web ビュー）を通じてアプリを操作し、通常のユーザーに見える動作で受け入れ基準を検証します。

ウォークスルーによる検証を最初に行います。Agent Browser または Playwright によるウォークスルー検証の後、新機能のプロダクト領域を網羅するエンドツーエンドテストを作成します。これらのテストを主な証拠とし、ウォークスルーの成果物は補足的な証拠として扱います。既存のテストだけでは、ウォークスルーの代わりになりません。

対応対象

次の用途でこのスキルを使用します。

1. Web アプリ
2. CLI および TUI アプリ
3. API および SDK
4. Electron 系アプリを含むネイティブアプリ

依頼された対象がこのリストにない場合は、可能な範囲で証拠を集める計画を立てて進めてもよいか、ユーザーに確認します。

必須条件

1. 最初にスコープを確定する

   • UAT Scope: <ticket/PR/branch scope only> から始めます。
   • スコープが不明確な場合は、ブランチの差分、PR、チケットを確認するか、ユーザーに尋ねます。

2. 推奨の前に証拠を集める

   • 要約、静的コードレビュー、またはテストの成功だけを根拠にマージを推奨してはいけません。
   • 変更された動作を実際に確認し、成果物を保存します。

3. UI の変更では、目に見える証拠として動画を優先する

   • Web、TUI、ネイティブアプリの作業では、可能であれば動画を撮影します。特に、変更が操作、レイアウト、遷移、状態変更、エラー処理に影響する場合は撮影してください。
   • また、レビュー担当者が静的な状態を確認できるよう、重要なチェックポイントでスクリーンショットを撮影します。
   • 動画を撮影できない場合は、撮影を省略した理由を記載します。

4. 手動実行の手順を必ず記載する

   • 人が自分で実行できる手順を必ず含めます。
   • UI の作業では、主な手順として、通常のプロダクトユーザーが行う操作を使います。
   • CLI、TUI、API、または SDK の作業では、コピーして実行できるコマンドやコードスニペットと、期待される結果を含めます。

5. 人による明示的な承認なしに GO 判定を出さない

   • ユーザーが確認するまでは、Recommendation: Pending user sign-off を使用します。
   • ユーザーが明示的に承認した後にのみ、GO または GO with follow-ups を使用します。

6. 受け入れ完了を独断で宣言しない

   • 証拠の収集は、受け入れを支援するものです。
   • 受け入れを決定するのは人です。

7. 証拠を批判的にレビューする

   • サブエージェントを利用できる場合は、収集した証拠を仕様、受け入れ基準、要件、PR の説明、またはチケットと照合するよう、少なくとも 1 人の批判的なレビュアーに依頼します。
   • レビュアーは各基準に対して Pass または Fail を示し、その判断を裏付ける成果物のパスまたはログ行を引用する必要があります。
   • サブエージェントを利用できない場合は、同じレビューをインラインで行い、Inline adversarial review と明記します。

ツールの選択

対象に最適なスキルまたは CLI を読み込んで使用します。UI が対象の場合は、Agent Browser または Playwright を優先してください。必要なスキルを利用できない場合は、次のコマンドでインストールします。

npx skills add vercel-labs/agent-browser --skill agent-browser -y
npx skills add microsoft/playwright-cli --skill playwright-cli -y

次に、選択したスキルで必要となる基盤の CLI を確認します。

対象	優先ツール	取得する証跡
Web アプリ	agent-browser（優先）、リポジトリですでに Playwright を使用している場合、トレースが役立つ場合、または agent-browser でフローを完了できない場合は playwright、ユーザーの承認があり、すでに開いている Chrome ページの場合に限り chrome-cdp	動画、スクリーンショット、DOM／アクセシビリティのスナップショット、コンソール／ネットワークのメモ、E2E テストの実行結果
CLI アプリ	シェルコマンド、script、生成された出力ファイル、視覚的な証跡が役立つ場合は script、VHS、または asciinema によるターミナル動画／GIF	ターミナルの記録、終了コード、出力ファイル、JSON、インタラクティブなフローのスクリーンショット／動画
TUI アプリ	script、VHS、または asciinema によるターミナル録画、可能であればターミナルの記録	動画／GIF、スクリーンショット、記録、設定／出力ファイル
API	curl、HTTP クライアント、リポジトリのスクリプト、ログ	リクエスト／レスポンスの JSON、ステータスコード、ログ、保存したペイロード
SDK	対象言語で実行できる最小限の例、補足としてリポジトリのサンプル／テストのみ	ソースの抜粋、コマンド出力、生成ファイル、ログ
Electron 系を含むネイティブアプリ	アプリがブラウザー自動化または CDP を公開している場合は、agent-browser による Electron／CDP 自動化（優先）。リポジトリですでに Playwright を使用している場合、または agent-browser でフローを完了できない場合は、playwright による Electron 自動化。Web ビューのない純粋なネイティブアプリの場合は、OS のスクリーンショットとアクセシビリティのスナップショット	ウィンドウの動画、スクリーンショット、アクセシビリティ／DOM のスナップショット、ログ、E2E テストの実行結果

インストールの確認：

command -v agent-browser || true
command -v playwright || true

対象と無関係なツールはインストールしないでください。

証跡のワークスペース

可能な場合は、同梱のヘルパーを使用します。スクリプトのパスは、このスキルのディレクトリを基準に解決します。

# Create the evidence directory and starter manifest.
node <skill-dir>/scripts/init-evidence.mjs --target electron --scope "validated behavior"

# Run commands while saving logs, exit codes, and manifest entries.
node <skill-dir>/scripts/run-capture-command.mjs --evidence <dir> --name focused-vitest -- pnpm test

# Capture a CDP-accessible web/Electron page when agent-browser screenshots fail.
node <skill-dir>/scripts/cdp-capture-page.mjs --evidence <dir> --cdp http://127.0.0.1:9222 --title "Kata Desktop" --screenshot screenshots/start.png --text logs/start-text.txt

# Generate and check final artifacts before responding.
node <skill-dir>/scripts/write-report.mjs --evidence <dir>
node <skill-dir>/scripts/verify-evidence.mjs --evidence <dir>

ヘルパーは判断の代わりにはなりません。終了コードの欠落、空のレポート、無効な evidence.json、UI のスクリーンショット／動画の不足、保存されていないコマンド出力など、証跡に関するよくあるミスを防ぐためのものです。

生成した証跡は、リポジトリ内の次のフォルダーに保存します。

uat-evidence/<target>-<YYYYMMDD-HHMMSS>/

必要に応じて、次の成果物を作成します。

evidence.json          # machine-readable manifest
evidence.md            # concise human report
screenshots/           # PNG/JPG checkpoints
recordings/            # MP4/GIF terminal or UI recordings
responses/             # JSON/API/SDK outputs
logs/                  # command logs, server logs, console excerpts
outputs/               # generated files from the feature
tests/                 # end-to-end tests covering the new feature product area

証跡のパスは一貫して保ち、最終回答に記載してください。uat-evidence/ が git の無視対象になっていない場合、ユーザーが成果物のコミットを明示的に希望している場合を除き、コミット前に無視対象にする必要があることを伝えてください。

evidence.json に最低限含める内容：

{
  "scope": "validated behavior",
  "target": "web|cli|tui|api|sdk|native|electron",
  "timestamp": "ISO-8601",
  "git_commit": "short sha",
  "artifacts": [
    {"type": "video|screenshot|json|log|output", "path": "relative/path", "description": "what it proves"}
  ],
  "commands": [
    {"command": "command run", "exit_code": 0, "output_path": "logs/example.log"}
  ],
  "slices": [
    {"name": "slice name", "result": "Pass|Fail", "evidence": ["relative/path"]}
  ]
}

ワークフロー

1. スコープ、対象、受け入れ項目を特定する

• 必要に応じて、ブランチの差分、PR の説明、チケット、README、パッケージスクリプト、アプリのエントリーポイントを確認します。
• UAT Scope: ... を宣言します。
• Target: web | cli | tui | api | sdk | native | electron | mixed を宣言します。
• スコープを2～5個の受け入れ項目に分割します。
• 各項目について、目視で判定できる合格／不合格の基準を定義します。

2. アプリまたはサービスを準備する

• ウォークスルーに必要な開発サーバー、サービス、CLI、TUI、API、SDK のフィクスチャ、またはネイティブ／Electron 系アプリを起動します。
• モックよりも、実際のローカルでの動作を優先します。
• Web およびネイティブ／Electron 系の対象では、起動前にポートと既存プロセスを確認します。後片付けの内容は logs/ に記録します。
• 製品のスモークテストには、ユーザーが通常使用する製品コマンドを使います。CDP、トレース、または決定的なスクリーンショットが必要な場合は、計測用の経路を別途実行し、その旨を明記します。
• 9222 を前提とせず、空いているデバッグポートを選びます。ポートが使用中の場合は、リスナーの証跡を保存し、別のポートを選びます。
• 認証情報、サービス、ハードウェア、または権限が証跡の取得を妨げる場合は、その阻害要因を記録し、最も再現性の高い代替手順を提示します。ブロックされた項目を合格として扱わないでください。

3. 機能のパスを実行する

該当するプレイブックを使用します。

• Web アプリの UI フロー：references/web-playbook.md
• ネイティブ／Electron 系の UI フロー：references/native-electron-playbook.md
• CLI、TUI、API、SDK：references/cli-api-sdk-playbook.md

ネイティブ／Electron 系アプリのウィンドウを検証する場合は、ユーザーに見える実際のアプリ画面を証拠に反映できる Agent Browser（Electron CDP）または Playwright を優先してください。

複数の種類の作業が混在する場合は、まずユーザー向けのパスを実行し、次に同じ結果に関連する技術的な証明を行ってください。

4. 製品領域のエンドツーエンドテストを作成する

Agent Browser または Playwright によるウォークスルー検証の後、新機能の製品領域をカバーするエンドツーエンドテストを作成してください。これらのテストを主な受け入れ証拠とします。

• 実用上可能であれば、ウォークスルーと同じツールを使用します。Web および Electron の対象には Playwright を使用し、既存の e2e フレームワークがリポジトリにある場合はそれを使用します。
• プロジェクトの慣例に従い、テストを uat-evidence/<target>-<timestamp>/tests/ またはリポジトリの e2e ディレクトリに配置し、選択したパスを evidence.md に記録します。
• 各受け入れスライスには、単なるユニットレベルのアサーションではなく、ユーザーに見えるフローを実行する e2e テストを少なくとも 1 つ対応させます。
• テストを実行し、実行結果（スライスごとの成功／失敗、終了コード、利用可能な場合はトレースまたは HTML レポート）を logs/ または tests/ に保存します。
• ウォークスルーはパスを実証し、テストはそれを主な証拠として固定します。先行するウォークスルーなしに、テストだけでスライスを受け入れてはいけません。

5. 永続的な証拠を記録する

• 成果物を uat-evidence/<target>-<timestamp>/ に保存します。
• 実用上可能であれば、Web、ネイティブ／Electron 系、TUI の動画を記録します。
• 開始時、主要な状態変化時、最終的な成功状態のスクリーンショットを記録します。
• tee、script、または scripts/run-capture-command.mjs を使ってコマンド出力を記録し、必ず終了コードを保存します。
• API／SDK の JSON レスポンスと生成された出力ファイルを保存します。
• エンドツーエンドテストの実行結果（スライスごとの成功／失敗、終了コード、トレースまたは HTML レポート）を、ウォークスルーの成果物と並べて主な証拠として保存します。
• バグ修正の UAT では、以前の不具合が存在しないことを示す否定的証拠を記録します。以前のエラー文字列をログから検索し、削除されたフラグや古いコマンドをアクティブなソースやドキュメントから検索して、一致件数ゼロの結果を保存します。
• 失敗したチェックを分類します。ブランチで変更されたファイルまたは動作に起因する場合、そのスライスは失敗として扱います。ブランチの差分範囲外であれば、ファイル／エラーの証拠を添えて、無関係な検証失敗として報告します。
• evidence.json と evidence.md を作成し、回答する前に scripts/verify-evidence.mjs を実行します。

6. 敵対的な証拠レビューを実施する

• 利用可能な場合は、仕様、受け入れ基準、要件、PR の説明、またはチケットと保存済みの成果物を敵対的レビュー用サブエージェントに提示します。
• 各基準について、正確な証拠パスを引用しながら Pass または Fail を判定するようレビュアーに依頼します。
• 欠落、不明瞭、またはアクセス不能な成果物は、該当する基準の失敗として扱います。
• レビュアーが不足を指摘した場合は、追加の証拠を収集するか、報告前に該当スライスを失敗とします。

7. 結果を報告する

次の順序で報告します。

1. UAT Scope: ...
2. Target: ...
3. Slice-by-slice result
4. Evidence
5. End-to-end Tests
6. Adversarial Review
7. Manual Run Instructions
8. Recommendation: Pending user sign-off
9. Please reply: accept / reject

報告は簡潔にします。成果物のパスにリンクし、それぞれの成果物が何を証明するかを説明してください。

出力の要件

すべての UAT の回答に、以下のセクションを含めてください。Agent Browser または Playwright を使用したウォークスルー（Web およびネイティブ／Electron 系のターゲット）の場合は、End-to-end Tests セクションを含めてください。

UAT Scope: <scope>
Target: <web|cli|tui|api|sdk|native|electron|mixed>

Slice-by-slice result:
- Pass/Fail: <slice> - <one-line evidence summary>

Evidence:
- <artifact path> - <what it proves>

End-to-end Tests:
- <test path> - <slice it covers> - Pass/Fail (run: <log/report path>)

Adversarial Review:
- Pass/Fail: <criterion> - <artifact-backed reason>

Manual Run Instructions:
1. <human step or command>
   Expected: <visible result or output>

Recommendation: Pending user sign-off
Please reply: accept / reject

UI ターゲットでは、手動の手順は実行中のアプリでの通常のユーザー操作から始めてください。自動化コマンドやテストハーネスは、明確にラベルを付けた Fallback (Engineering Only) セクションにのみ記載してください。

CLI、TUI、API、SDK のターゲットでは、手動の手順にコマンドやコードスニペットを含めてもかまいませんが、期待される出力と必要な環境変数を必ず記載してください。

チケット更新のガイダンス

チケットまたは PR が判明している場合は、以下の内容でステータスを更新するか、更新を提案してください。

• 検証した範囲
• 使用したターゲットとツール
• スライスごとの合格／不合格の概要
• 証拠のパスまたはリンク
• 手動での実行手順
• 現在の推奨事項

ユーザーが明示的に承認する前は、更新に Pending user sign-off とラベルを付けてください。明示的な承認後は、プロジェクトのワークフローで必要な場合、最終判定を記録してください。

回答前のセルフチェック

回答する前に、以下を確認してください。

• 対象範囲が明記されている。
• ターゲットが明記されている。
• 各スライスに合格／不合格のステータスが付いている。
• 証拠となる成果物が存在するか、阻害要因が明確に示されている。
• evidence.json が有効で、evidence.md が空でない。
• UI の証拠には、実用上可能な場合、動画とスクリーンショットが含まれている。または、動画を省略した理由が記されている。
• UI のスクリーンショット／動画ファイルが存在し、読み取り可能である。
• ネイティブ／Electron 系アプリの検証で Agent Browser（Electron CDP）または Playwright を使用している。または、別のツールを使用した理由が説明されている。
• 新機能の対象領域を網羅するエンドツーエンドテストが作成・実行され、スライスごとの合格／不合格と実行出力が主要な証拠として保存されている（UI ターゲットの場合）。
• 敵対的レビューで、すべての基準を証拠と照らし合わせ、合格／不合格の判定が行われている。
• コマンドログに終了コードが含まれている。
• 修正を検証する場合、以前のバグを示す否定的な証拠が保存されている。
• UAT のために起動した開発サーバー、ネイティブ／Electron 系アプリ、またはバックグラウンドプロセスが終了している。または、ユーザー向けに起動したままにしていることが明記されている。
• 手動での実行手順が含まれている。
• ユーザーが承認するまでは、推奨事項が Pending user sign-off のままである。

よくある間違い

• ウォークスルーや、対象領域を網羅する新しいエンドツーエンドテストを実施せず、既存テストだけを実行する。
• 成果物を添付せずに、コードの概要だけを報告する。
• UI 作業で、説明なしに動画やスクリーンショットを省略する。
• Playwright やテストのコマンドを、UI の主要な手動操作手順として提示する。
• TUI の視覚的な証拠を忘れる。
• API のリクエストファイルとレスポンスファイルを省略する。
• ユーザーが承認する前に GO と判定する。
• ターゲットに最適なツールを選ばず、あらゆるツールをインストールする。