Communitygithub.com

ハンドテスト

人が見て、聞いて、感じる変更を確認します。BEFOREとAFTERを1つのビデオと1つのボードで並べて表示し、エージェントが確認した後、承認者のOKを待ってから変更をマージします。ユーザーが「ハンドテスト」や「ビフォーアフター動画」、「PRの視覚的証拠」、「リリースレポート」、「変更点を見せて」と依頼したときに使用します。

ハンドテスト とは?

ハンドテストは、コードの動作が正しいことを証明する単体テストとは異なり、変更がユーザーにとって意図した通りに届くことを検証するためのスキルです。UIの変更、サウンド、動作のタイミングなど、人が知覚できるあらゆる変更に対して、第三者が短時間で判断できる客観的な証拠(BEFORE/AFTERの並列ビデオと比較ボード)を作成します。このスキルは主にClaude CodeなどのAIエージェント向けに設計されており、`scripts/handtest.py` というPythonツールを使用して、ビデオの録画、フレーム同期、証拠画像の生成を自動化します。変更は承認者のOKが出るまでマージされず、証拠はプロジェクトの `docs/agents/hand-test.md` に定義されたルールに従って管理されます。手順は、変更の分類、撮影計画の立案、BEFORE/AFTERの録画、証拠の作成、セルフレビュー、承認者への引き継ぎ、結果の記録という7つの段階で構成されています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GhostRoboticsLab/skills/tree/HEAD/skills/engineering/hand-test

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ハンドテスト は何をしますか?

テストはコードの動作を証明します。ハンドテストは、人が意図したものを得られることを証明します。人が見たり、聞いたり、感じたりする変更のたびに、第三者が1分で判断できる証拠を作成します。それは、1つのビデオと1つのボードで、BEFORE(赤バッジ)とAFTER(緑バッジ)を並べ、同じ場所で同じ操作を行い、1つの変更だけが異なるようにします。変更は、承認者がOKと言うまでマージされません。

プロジェクトの設定は、ユーザーのリポジトリ内の docs/agents/hand-test.md にあります。BEFOREの取得方法、この画面の操作とキャプチャ方法、デバイスルール、証拠の保存場所、承認者、OK/Not OKの処理などが定義されています。このファイルがない場合は、最初に SETUP.md に従ってください。

ツールは scripts/handtest.py です。uv run <このスキルのフォルダ>/scripts/handtest.py <コマンド> で実行します。各コマンドに --help を付けるとフラグの一覧が表示されます。ffmpeg と ffprobe が PATH に存在する必要があります。uv が Pillow を導入します。uv がない場合は、リポジトリ外に仮想環境を作成し(python3 -m venv <dir> && <dir>/bin/pip install pillow)、<dir>/bin/python でツールを実行します。

1. 変更を分類する

PRの説明(または変更が記述されている場所)に ## Hand test セクションを追加します。

  • yes: <何を確認するか>:人が見たり、聞いたり、感じたりするもの(UI、動作、タイミング、サウンド、コピー、デザイン)に対して。
  • no: <なぜ何も見えない、聞こえない、感じないのか>:ツール、ビルド、テスト、ドキュメント、または出力が同じリファクタリングに対して。

迷ったら yes にします。

完了条件: セクションが存在すること。no の場合はスキルを終了します。

2. 撮影を計画する

瞬間に名前を付けます。それは、変更が現れる1つのステップです。変更が最初のフレームから画面に表示される場合(色、ラベル、レイアウト)、その瞬間は画面が表示される瞬間、またはその後の最初のステップです。

実際のアプリを操作するスクリプトとして手順を記述します。両側で同一の手順にします(各画面のコマンドは CAPTURE.md を参照)。

  • アプリ自身のUIを通じて実際の入力を使用します。テスト用のショートカットは、ユーザーが触れるコードをスキップします。
  • 要素はラベルやロールで見つけ、座標では見つけないでください。レイアウトの移動自体が変更であることが多いためです。
  • 瞬間の前は、実際の状態(ラベルの表示、リクエストの完了)を待ち、固定タイマーは使用しないでください。瞬間の後は固定時間を保持します。
  • 両側で同じデバイス、ウィンドウサイズ、言語、データ、開始状態を使用します。
  • finally ブロックですべてを元に戻します。

BEFOREは実際の古い状態から取得します。ベースコミットのビルド、または実行時に変更をオフにした状態です。そのための保存ファイルの変更は不要です。

変更がスペース、時間、感触に関する問題で、ビルド前に誰も決めていなかった場合(大きさ、速さ、感触の感じ方)、停止してユーザーに伝えてください。それはビルド前のインタラクティブなスケッチで行うべきものです。ハンドテストは決定をチェックするものであり、決定を下すものではありません。

完了条件: スクリプトがBEFOREとAFTERの両方でドライラン(録画なし)で動作し、すべての要素を見つけ(またはスチルしか撮れないすべての状態に到達し)、デバイスとワーキングツリーを元の状態に戻し、ツリーのチェックサムが実行前後で等しいこと。

3. 両側を録画する

まずBEFORE、次にAFTERを、同じスクリプトで録画します。プロジェクトのデバイスルールに従います。テスト対象のアプリのみを操作し、何もアンインストールせず、システム設定を変更せず、テスト対象のアプリが前面にある間のみ入力を送信します。

完了条件: 2つの生録画が存在し、それぞれが瞬間を示しており、ワーキングツリーのチェックサムが一致すること。

4. 証拠を作成する

  1. init --out "$HANDTEST_ROOT/<group>" --id <N> --topic <kebab-case> --title "<plain words>" --base <sha> --head <sha> --ok "<...>" --not-ok "<...>"。グループ、OK、Not OK はプロジェクトファイルから取得します。シェルがコマンド間で HANDTEST_ROOT を保持しない場合があるため、同じコマンドで設定してください。
  2. find-change <raw> --from <s> --to <s> を各録画に対して、瞬間の前後で実行します。同期時間は、画像が変化するフレームであり、ステップのログ時間ではありません。
  3. pair --before <raw> --after <raw> --sync-before <s> --sync-after <s> --title ... --what ... --caption ... --out <folder>/<id>_<topic>.mp4。ビデオの時間を README.md と PACKAGE.md に書き込み、瞬間がビデオのどこにあるかを表示します。
  4. 各側につき1枚のスチルを、瞬間から少し後、生録画から取得します。stills <raw> --at <s> --out <scratch>/before、AFTERも同様に実行します。各ファイル名が表示されます。次に board --before <png> --after <png> --title ... --caption ... --out <folder>/<id>_<topic>_BEFORE_AFTER.png。
  5. すべての <fill in: ...> マークを埋めます。単語と数字のルールは EVIDENCE.md にあります。

完了条件: check <folder> が "ready for a person" と表示すること。

5. レビュアーパス

誰かが確認する前に、自分自身で第三者の立場でレビューします。ビデオからスチルを2回抽出します。stills <video> --every 1 --out <scratch>、次に stills <video> --at <t-0.5> <t> <t+0.5> --out <scratch>。ここで t はビデオ内の瞬間の時間であり、生録画の時間ではありません(pair が表示し、handtest.json に video.change_at として保存されます)。すべてのスチルとボードを確認します。

  • それぞれが、キャプションで確認するよう指示されているものを表示している必要があります。隠れている、空、間違った状態、間違った言語、変更の上にオーバーレイがある場合は、フォルダを archive し、ステップ3から再度録画します。README で悪い画像を説明するよりも、再度録画してください。
  • 数字は画像と一致している必要があります。一致しない場合、数字が間違っています。理由を調べてください。
  • 間違った画像が付いたグリーンテストはバグです。ユーザーに報告してください。

完了条件: すべてのスチルとボードがキャプションの主張を表示し、README のすべての数字が画像と一致すること。

6. 引き継ぎ

フォルダをプロジェクトの証拠の保存場所に配置します。PACKAGE.md を、プロジェクトファイルで指定された場所に投稿します。フォルダの相対パスのみを記載し、アカウント名や絶対パスは決して記載しないでください。PR の yes 行にそのパスと承認待ちの人を記入します(形式は EVIDENCE.md の "The PR section" にあります)。承認者に依頼します。変更は、ハンドテストがオープンな間はマージされません(PRがある場合はドラフトPRのまま)。

完了条件: パッケージが投稿され、PRの行がフォルダを指定し、承認者に依頼され、変更の何もマージされていないこと。

7. 評決を記録する

評決は承認者のものです。承認者が与えていないOKを決して記録しないでください。

  • OK:verdict <folder> --ok --by "<who>"(check に失敗したフォルダは拒否されます)。その後、プロジェクトファイルでOKの処理として定義されていることを行います(通常はPRを ready にします)。
  • Not OK:verdict <folder> --not-ok --by "<who>" --note "<what they said>"。同じブランチで修正し、フォルダを archive し、ステップ3に戻ります。やり直しで同じファイル名が再度作成されます。古いテイクは previous/ に移動します。init が新しい README.md を書き込んだら、previous/<stamp>_README.md からまだ有効な行をコピーします。pair が時間を書き換えます。

完了条件: handtest.json に人の評決が含まれ、トラッカーがそれと一致すること。

リリース

各ハンドテストのフォルダを、リリースごとに1つのグループフォルダの下に保管します。次に report <group> --title "<release>" を実行します。REPORT.md と1つの自己完結型の index.html が書き込まれ、保留中のハンドテストが最初に表示されます。EVIDENCE.md を参照してください。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル