verifykit

verifykit

作成したばかりのフロントエンド機能を、ユーザーと同じように操作して、何が起きるかを記録します。show モードでは、セッション中にオペレーターへ渡すスクリーンショットをキャプチャします。「ボタンが移動したか」を確認するのに十分手軽です。proof モードでは、スクリーンショットと短いアニメーション GIF を作成し、プルリクエストにインラインで埋め込めるよう公開します。setup は、どちらのモードも使えるようにマシンとリポジトリを準備します。verifykit は、コードのレビューから PR を作成するまでの間に使います。レビューではソースを読みますが、verifykit は実行中の機能を動かして確認します。

これはドライバー兼レコーダーであり、それ以上のものではありません。テストは作成しません（それはテストスイートのスキルであり、インストール済みなら testkit が担当します）。人間が使うチェックリストも作成しません（それは手動 QA のスキルです）。また、独自のドライバー以外の環境も用意しません。与えられた UI を操作して、見たものを記録します。

起動するタイミング

フロントエンド機能の実装後に、その見た目を確認したい場合や、動作を証明したい場合に使います。視覚的に確認できる画面を持つ、実行中の機能をキャプチャします。変更がバックエンドまたは CLI のみで、操作対象がない場合は、フローをでっち上げずにその旨を伝え、手動テスト計画を作成する qakit（/qakit）を案内してください。qakit がない場合は、人が手動で試すべきコマンドとエンドポイントを示してください。

• show。 「見た目を見せて」「これをスクリーンショットに撮って」「今のページはどんな感じ」「ボタンが移動したか」など。ローカルパスにスクリーンショットを保存し、公開はしません。
• proof。 「この機能を検証して」「フローが動作する様子を記録して」「UI の変更を証明して」「PR 用の証拠をキャプチャして」、または証拠となる成果物が必要な PR の手順など。スクリーンショットと GIF をまとめて公開し、PR 本文に掲載できるようにします。
• setup。 「verifykit をセットアップして」「ブラウザードライバーをインストールして」「キャプチャできるようにこのマシンを準備して」など。不足しているものをインストールし、すでにあるものを報告します。

動詞の意味が曖昧な場合は、show を実行してください。 PR、証拠、記録、または証明を明示する呼び出しは proof です。それ以外はすべて show です。手軽で元に戻せるためです。proof への切り替えが必要になっても、一文伝えるだけで済みます。

人が実行する手動 QA 計画や、ソースを読むコードレビューとは別のものです。verifykit は自動で操作して記録するツールです。ユーザーが手動テスト用チェックリストやソースレビューを求めている場合は、キャプチャを行うのではなく、適切なスキルを案内してください。

共通手順

すべてのキャプチャモード（show と proof）で、最初に以下の手順を実行します。setup ではこれらを省略し、専用ファイルから開始します。

1. 機能の範囲を定め、エントリーポイントを見つける

実際に変更された内容に基づいて実行します。通常の git diff で表示されるのはステージされていない編集だけなので、変更対象全体を確認します。ステージ済みと未ステージの編集（git diff HEAD）、未追跡ファイル（git ls-files --others --exclude-standard。各ファイルを読み取ります）、ブランチでコミット済みのベースとの差分（git diff <base>...HEAD）を確認します。ベースは、インストールされていれば gitkit から取得します。そうでなければ、git symbolic-ref --short refs/remotes/origin/HEAD の結果から origin/ 接頭辞を削除したものを使い、それもなければ、解決できる main または master のうち先に見つかったものを使います。関連するイシューや計画があれば読みます。これらをもとに、変更がどの画面、ルート、コンポーネント、フローに影響するかを把握します。

操作を始める前に、テスト対象のリビジョンを記録します。アプリケーションのコミット（git rev-parse HEAD）と、作業ツリーの状態（git status --porcelain に何か出力される場合は yes、そうでなければ no）です。proof は両方をバンドルに書き込むため、後から確認する人はキャプチャがブランチと一致しているか判断できます。アプリの起動方法と機能へのアクセス方法、つまり開発サーバーのコマンドと URL を確認します。プロジェクトに起動方法の説明があれば、それに従います。なければ推測し、操作を始める前にエントリー URL を確認します。

この実行の スラッグを選びます。関連する イシュー番号があればそれを使い、なければブランチや差分から短い小文字のケバブケースの 機能スラッグを付けます（例：login-throttle）。各モードは、スラッグと実行の ISO 作成日から実行ディレクトリを作成します。

変更されたパス、ステージ済みのパス、未追跡のパス、コミット済みのパスがすべてビジュアル対象かどうか分類され、エントリー URL が確認され、コミットと作業ツリーの状態が記録されたら、このステップは完了です。

2. 操作するフローを選ぶ

差分から候補となるフローを、異なる ユーザーエントリーポイントとして導き出します。変更されたルートやページ、フォームやダイアログ、ユーザー操作に関連付けられたコンポーネントなどです。そのうえで、次のルールに従います。

• 明示的な指示を優先します。 呼び出しでフロー（「チェックアウトフローを確認して」「設定ページを見せて」など）が指定されている場合は、そのフローを操作します。
• 変更箇所が単一のフローに関係する場合 → 質問せず、そのフローを操作します。
• 変更箇所が複数のフローに関係する場合 → 候補を短いラベル付きで列挙し、どのフローをキャプチャするかユーザーに尋ねます（複数選択可）。選択された各フローを操作し、それぞれのキャプチャを別セクションとしてラベル付けします。「主要な」フローを勝手に推測してはいけません。

操作するすべてのフローが、呼び出し、唯一の候補、またはユーザーの選択によって特定されたら、このステップは完了です。

3. キャプチャのバックエンドを選ぶ（優先順位順）

利用可能なものを検出し、次の順で最適なものを使います。

1. URL を受け取り、スクリーンショットをディスクに書き込む PATH 上の CLI ブラウザードライバー（例：playwright-cli）。各バイナリを command -v で調べます。Bash から実行でき、アクセシビリティツリーがコンテキストに入らないため、優先します。
2. ブラウザー自動化 MCP（実際のブラウザーを操作し、スクリーンショットを撮影します）。
3. コンピューター操作／デスクトップ画面キャプチャ。
4. いずれも利用できない場合 → 手動に切り替えます。キャプチャを偽装してはいけません。クリックする場所と撮影するスクリーンショットを示した短い手動キャプチャ手順を出力し、ドライバーをインストールする次の手順として verifykit setup を案内して、終了します。キャプチャの実行中に setup を実行してはいけません。

引き継ぎ時に使用したバックエンドを記録します。バックエンドが選択されたとき、または手動手順が出力されて実行が終了したとき、このステップは完了です。

4. 認証と必要な状態を処理する

verifykit は状態を再利用します。状態を作り出すことはありません。次の順に確認します。再利用できる、すでに認証済みのセッション、保存済みのブラウザー状態ファイル、またはプロジェクトがすでに公開しているテスト用認証情報です。フローに認証が必要で、利用できるものがない場合は、エントリー URL と認証情報（または実行するシードコマンド）を一度だけ尋ねます。ユーザーが提供できない、または提供しない場合は、適切に対応を縮小します。認証が必要になる直前までキャプチャし、停止した箇所を記録します。渡されたシードコマンドは実行しますが、決して自分で作り出したり、データベースにシードを投入したり、マイグレーションを実行したりしません。

UI を操作する前に、状態を変更するフローの範囲を定めます。 UI の操作によってデータが書き込まれることがあります。作成、削除、送信、支払い、招待、メール送信などの操作は、ユーザーがアプリを使う場合と同様にデータを書き込みます。選択したフローにそのような操作が含まれる場合は、次のようにします。

• エントリー URL とアプリの設定から環境を特定します。ローカル、開発環境またはプレビュー環境へのデプロイ、共有環境、または本番ホストのいずれかです。
• フローで実行する、状態を変更する各操作と、それが対象とするレコードまたはアカウントを列挙します。
• テストデータを使ったローカル環境または使い捨て環境の場合に限り、確認を求めずに操作します。それ以外のホストでは、操作の一覧を示して一度確認し、ユーザーが許可した操作のみを実行します。
• ユーザーが許可しない場合は、その操作の直前までキャプチャし、境界となった箇所を記録します。

認証状態が再利用、提供、または境界として記録され、状態を変更するすべての操作が許可されるか、境界として記録された時点で、この手順は完了です。

モード

各モードの本文は modes/ 以下の個別ファイルにあります。When this fires に従ってルーティングし、該当するファイルを 1 つ読み、その指示に従ってください。この行より上の内容はすべてのモードに適用されるため、モードのファイルでは繰り返し説明していません。

• モード show → modes/show.md を読み、その指示に従います。
• モード proof → modes/proof.md を読み、その指示に従います。
• モード setup → modes/setup.md を読み、その指示に従います。

注意事項

• allowed-tools は主要な実行経路を対象とします。 Bash は CLI ブラウザードライバー、git、gh、ffmpeg、npm、同梱の verify-assets.sh を実行します。Read は差分とリンク先の issue を読み取ります。Write は proof バンドルを書き込みます。AskUserQuestion はフローの選択、認証に関する一度の質問、setup のインストール確認に使います。ブラウザー MCP のフォールバックはこのリストに含まれておらず、含めることもできません。サーバーが選ぶ名前（一般的には mcp__<server>__*）を持つ MCP ツールとして提供されるためです。allowed-tools を厳格に適用する環境で CLI ドライバーがインストールされていない場合は、これら 4 つに加えてブラウザー MCP も許可してください。そうしないと verifykit は、文書化された縮退動作として手動キャプチャ手順を表示して停止します。この縮退動作は正直な失敗であり、証拠を偽造することはありません。
• プロビジョナーではなく、ドライバー兼レコーダーです。 認証は再利用するか、ユーザーに確認します。また、渡されたシードコマンドは実行しますが、フィクスチャの作成、データベースへのシード投入、マイグレーションの実行は行いません。setup がインストールするのはドライバーだけで、プロジェクトに関するものは何もインストールしません。これにより、さまざまなプロジェクトで利用できます。ただし、読み取り専用というわけではありません。UI 上で作成、削除、送信を行うと、アプリを通してデータが書き込まれます。そのため、操作を始める前に認証と必要な状態を処理するで範囲を定めています。
• show が公開されることはありません。 GIF も、バンドルも、.gitignore の編集も、隠し ref もありません。画像はオペレーターに渡すだけで、それ以外の場所には置きません。
• mp4 はありません。 GitHub ではウェブコンポーザーからアップロードした動画しかレンダリングされないため、ホストされた mp4 は PR 本文にインラインで埋め込めません。そのため、証拠形式はスクリーンショットと GIF です。動画への対応は意図的に後回しにしています。
• プライベートリポジトリの場合。 インライン表示にはパブリックリポジトリが必要です。プライベートリポジトリでは verify-assets.sh check が失敗するため、proof は公開をスキップし、無効なリンクを埋め込む代わりに、手動で添付できるようローカルバンドルのパスを提示します。
• シェルもブラウザーもない、または操作対象がない場合。 アプリを実行したりキャプチャしたりする方法がない場合（例：自動化手段のないブラウザー専用エージェント）は、証拠を偽造しないでください。不足しているものを伝え、ユーザー自身が実行するための手動キャプチャ手順を表示します。