beraki/my-code-factory-skills

エビデンス駆動テスト

動作の注釈付き証拠を記録し、PRや課題トラッカーに添付します。

録画は、あなたがコンピューター操作でアプリをテストしている様子をキャプチャしたものです。レコーダーを起動し、自分でアプリを操作（クリック、入力、ナビゲート）して各テスト対象を実行します。動画内のすべてのアクションは、テストがライブで実行されていることを示します。録画は、そのインタラクティブなセッションが表示されなければ証拠として価値がありません。ハーネスにコンピューター操作用ツールがないがGUIが存在する場合は、代わりに cua-driver でアプリを操作してください（下記参照）。それでもライブセッションであることに変わりはありません。

バンドルされているレコーダー scripts/evidence.py は、Linux、macOS、WindowsでFFmpegを使用してディスプレイをキャプチャし、テスト中に追加する各注釈にタイムスタンプを付け、停止時にそれらを動画に焼き付け、ffprobeで結果を検証します。セッションフォルダーに evidence.mp4、report.md、manifest.json を書き込みます。

入力

• テスト対象（必須）: 検証する動作やフローを、テスト可能なステートメントで記述します。
• PR / 課題（オプション）: エビデンスを投稿する場所。省略した場合は、リクエスターにのみ配信します。

レコーダー

EVIDENCE は、このスキルのフォルダー内にある scripts/evidence.py へのパスを示します（スキルがインストールされている場所、例: ~/.claude/skills/evidence-driven-testing/scripts/evidence.py）。必要なのはPython 3とFFmpegのみです。

• 事前確認: python3 $EVIDENCE doctor — ffmpeg、ffprobe、libx264、ass フィルター（ready）を確認し、次にこのマシンで動作する画面キャプチャソース（capture_ready とソース auto が選択します）を確認します。ツールチェーンがない場合のみ非ゼロで終了します。録画前に capture_ready を確認してください。

• プラットフォーム（--source auto は利用可能な最初のものを選択）:

  OS	ソース	必要条件
  Linux X11 / XWayland	x11 (x11grab)	DISPLAY が設定されていること
  Linux Wayland	wayland (wf-recorder)	WAYLAND_DISPLAY が設定されていること、wf-recorder がPATHに存在すること、wlr-screencopyをサポートするコンポジター（既知のwlrootsベース: Sway、Hyprland、river、Wayfire、labwc、dwl、niri、または wayland-info で確認）が必要。GNOMEとKDE Waylandはこの方法ではキャプチャできません。doctor がその旨を伝えます。X11アプリの場合はXWayland経由で x11 を使用するか、フォールバックレコーダーを使用します。--source wayland でも強制されます
  macOS	avfoundation	ターミナル/エージェントホストアプリに画面収録の許可が与えられていること。doctor が --screen-index 用の画面インデックスを一覧表示します
  Windows	gdigrab	標準のffmpegビルド。プロセスチェック用に powershell

  デフォルトでは全画面をキャプチャします。--geometry WxH と --offset X,Y で、x11、wayland、gdigrabで領域を切り抜きます。XWaylandはX11ウィンドウしか認識しないため、テスト対象のアプリがWaylandネイティブの場合は wayland ソースを優先してください。

• クラッシュセーフな生キャプチャ: 生の録画はMPEG-TS（raw.ts）であるため、レコーダーが強制終了されたりクラッシュしても、キャプチャされたものはプローブおよびレンダリング可能です。stop はそれを標準の evidence.mp4 にリマックスまたは再エンコードします。

• 停止方法: Linuxでは、レコーダーはpidfdを介してシグナルを受け取ります。macOSとWindowsでは、start がffmpeg子プロセスを所有する小さなスーパーバイザープロセスを起動し、stop は（セッションフォルダー内の stop.request を介して）スーパーバイザーに中断、終了、強制終了を要求します。完了すると recorder-exit.json を書き込みます。ベアPIDにシグナルを送ることは決してないため、リサイクルされたPIDにヒットすることはありません。レコーダーの実行中にスーパーバイザーが停止した場合、stop は拒否し、手動で停止するPIDを通知します。スーパーバイザーが、どのプロセスを開始したかを記録する前に停止した場合、stop は、自分で迷子のレコーダーを確認し、--accept-untracked-recorder を付けて再実行するまでブロックされたままになります。レポートにはその注意書きが記載されます。

• フォールバックレコーダー（doctor がキャプチャソースを報告しない場合、例: wf-recorderのないWayland）: cua-driver recording start <dir> / stop（cua-driverセクションを参照）、またはOSのレコーダー（macOS: screencapture -v out.mov）。これらのパスでは注釈オーバーレイがないため、注釈プロトコルをファイルとして保持します。assertions.md に各 setup / test_start / assertion とその結果、およびおおよその動画タイムスタンプを、ヘッドレスパスとまったく同じようにリストします。

• 決して --source test（合成パターンジェネレーター）をUIエビデンスとして提示しないでください。これはツールチェーンのスモークテスト用に存在します。リポジトリの tests/test_evidence.py でテストされています。

手順

1. 画面を準備する

• ブラウザ/アプリのウィンドウを最大化します。ポップアップ、通知、余分なパネルを閉じます。
• セットアップ自体がテスト対象でない限り、録画前に開始状態（ログイン済み、正しいページ）に移動します。
• テスト対象の正確なリビジョンを記録します: git rev-parse HEAD と git branch --show-current（またはデプロイURL）— レコーダーはこれらをレポートにスタンプします。

2. 録画を開始する

• 最初の意味のあるアクションの前に画面録画を開始します:

  python3 $EVIDENCE start \
    --output .artifacts/<task-name> \
    --title "<検証内容>" \
    --commit "$(git rev-parse HEAD)" --branch "$(git branch --show-current)" \
    --environment "<OS / ブラウザ / ディスプレイ / デプロイ>"
  

  これにより、session パスと選択された source を含むJSONが出力されます。後続のすべてのコマンドのためにパスを保持します（SESSION=...）。ソースは自動検出され、画面全体がキャプチャされます。--source、--geometry、--offset、--display/--xauthority（X11）、--screen-index（macOS）、--output-name（Wayland）は、doctor や状況で必要な場合にのみ渡します。

• 開始コンテキストを説明する setup 注釈を追加します:

  python3 $EVIDENCE annotate "$SESSION" --type setup \
    --message "ログイン済み、コネクターページに移動中"
  

3. コンピューター操作でテストし、その都度注釈を付ける

• すべてのインタラクションをライブアプリでのコンピューター操作を通じて実行します。録画はあなたのセッションをキャプチャするため、テストとエビデンスは同じ行為です。見やすいペースで作業します。各アクションの後にUIが落ち着くまで待ち、状態変化が動画で確認できるようにします。

• 各名前付きテストの開始時に、Jestスタイルで test_start 注釈を追加します:

  python3 $EVIDENCE annotate "$SESSION" --type test_start \
    --message "権限が'always'の場合、ツールを直接実行できるべき"
  

• 各チェックの後に、--result passed、failed、または untested を指定して assertion 注釈を追加します:

  python3 $EVIDENCE annotate "$SESSION" --type assertion --result passed \
    --message "ツールが権限プロンプトなしで実行された"
  

• アサーションのルール:

  • 意味のある状態変化ごとに1つのアサーション。統合し、UIラベルごとに注釈を付けないでください。
  • "前提条件: ..." アサーションを使用して開始状態を確立します。
  • 80文字未満、シグナル強度高（レコーダーは長いメッセージを拒否します）。
  • テストを実行できない場合（前提条件不足、認証期限切れなど）、理由とともに untested とマークします。黙ってスキップしないでください。
  • タイムスタンプは、アサートした時刻を記録し、その真偽は記録しません。passed を選択する前に画面を確認してください。

4. 停止して確認する

• 最後のアサーションの後に録画を停止します:

  python3 $EVIDENCE stop "$SESSION"
  

  これにより、キャプチャが停止され（正常に、レコーダーがフラッシュするように。要求を無視した場合のみエスカレーション）、注釈が evidence.mp4 に焼き付けられ、結果がプローブされ、その隣に report.md と manifest.json が書き込まれます。成功時には "verified": true を出力します。レンダリングに失敗した場合、セッションは finalization_failed とマークされます。報告された原因を修正し、stop を再実行します（再試行ではレコーダーに2回シグナルを送りません）。レコーダープロセスに安全にシグナルを送れなくなった場合（プロセスが終了した、またはそのPIDが別のプロセスに属している場合）、セッションは recorder_lost とマークされます。再度 stop を実行すると、キャプチャされた動画がファイナライズされますが、それはレコーダープロセスが確実に終了した場合のみです。プロセスがまだ生きている場合は、先に停止してください。そうしないと、動画が書き込み中にレンダリングされる可能性があります。

• 共有する前に、録画が重要な瞬間を捉えていることを確認します。各アサーションのタイムスタンプでフレームを抽出し（ffmpeg -ss <t> -i evidence.mp4 -frames:v 1 frame.png）、状態とラベルが表示されていることを確認します。

• report.md の注意事項セクションに記入します。プレースホルダーを残さないでください。

5. エビデンスを投稿する

• report.md がレポートです。テスト内容、環境と正確なコミット、テストごとの合格/不合格、注意事項。ゼロから書き直すのではなく、拡張してください。
• 動画とサマリーをPRコメントとして投稿します（あなたのPRの場合はPR説明に埋め込みます）。gh pr comment はローカル動画を添付できません。認証済みブラウザでPRのコメントボックスから evidence.mp4 をアップロードするか、ホストにアップロードしてリンクします（例: before-and-after アップロードアダプター）。コメントを再度開き、動画が再生されることを確認してから、投稿したと主張してください。
• 同じ動画を1行の結果とともに課題トラッカー（Linear/Jira）に添付します。
• レポートと録画をリクエスターに送信します。

ガードレール

• 動画は、実際のテストセッションがライブで駆動されている様子を示さなければなりません。スクリプト再生、編集されたクリップ、合成映像を録画として提示しないでください。ハーネスにコンピューター操作用ツールがないがGUIが存在する場合は、cua-driver を介して駆動します。GUIがまったくない場合は、代わりにヘッドレスパスを使用します。
• 半分覆われた、またはタイル表示されたウィンドウを録画しないでください。最初に最大化します。
• 秘密、トークン、顧客データ、支払い情報が表示されている画面を録画しないでください。フローでそれらが必要な場合は、untested とマークし、理由を述べます。
• 修正を検証する場合は、新しい成功とともに古い失敗を表示または参照します。
• テスト対象の正確なコミット/ブランチ/デプロイを常に明記します。

コンピューター操作用ツールがない場合（GUIあり）

ディスプレイは存在するが、エージェントに組み込みのコンピューター操作機能がない場合は、cua-driver（macOS / Windows / Linux）をアクチュエーターとして使用します。それでもあなたがアプリをライブでテストしていることには変わりません。録画ルールは変更されません。入力メカニズムのみが異なります。

• 録画前に cua-driver doctor でセットアップを確認します。cua-driver スキルがインストールされている場合は、それを読み、そのプロトコルに従います。アクション前のスナップショットの不変条件は必須です。
• インタラクションごとにループします: launch_app → get_window_state（アクセシビリティツリー + スクリーンショット）→ element_token で操作（click、type_text、press_key）→ verify_state で期待される事後条件を確認。各 verify_state チェックは、assertion 注釈に1対1でマッピングされます。
• doctor が capture_ready: yes を報告する場合は、上記のバンドルレコーダーを動画と注釈に引き続き使用します。cua-driverは入力を提供するだけです。
• それ以外の場合、cua-driver recording start <output-dir> / cua-driver recording stop がレコーダーです（出力ディレクトリが必要で、デーモンが実行中である必要があります: cua-driver serve）。動画キャプチャはデフォルトでオンで、停止時に <output-dir>/recording.mp4 にファイナライズされます。ただし、Windows/Linuxではffmpegをシェルアウトするため、ffmpegまたはディスプレイがない場合は、ターンごとの軌跡フォルダー（before/afterスクリーンショット、action.json、click.png）のみが生成され、動画はありません。停止後、recording.mp4 が存在することを確認してから参照します。存在しない場合は、レコーダーを修正するか、ヘッドレスプロトコルに従って、ターンごとのbefore/afterスクリーンショットを番号付きキャプチャとして提示します。
• このパスで注釈オーバーレイが利用できない場合は、プロトコルをファイルとして保持します。assertions.md に各 test_start / assertion とその結果を、ヘッドレスパスとまったく同じようにリストします。

ヘッドレスパス（GUIなし）

エージェントに録画可能なデスクトップがない場合は、同じアサーション規律を維持し、レコーダーをスクリプトキャプチャに置き換えます:

• すべてを .artifacts/<task-name>/ に保存します（gitignoreしてください。エビデンスはアップロードされ、コミットされることはありません）。キャプチャスクリプトをキャプチャの横に置き、実行が再現可能になるようにします。

• スクリーンショット: before-and-after CLI（@vercel/before-and-after）はURLまたは要素をキャプチャし、そのペアはPR埋め込みに直接フィードされます。Chromeが「使用可能なサンドボックスがありません」で失敗するコンテナ/VMでは、AGENT_BROWSER_ARGS="--no-sandbox" を設定します。

• 動画 / マルチステップフロー: 使い捨てのPlaywrightスクリプト。プロジェクトの依存関係にplaywrightを追加せずに実行します:

  npx --yes --package=playwright node record.mjs
  

  （単なる npx playwright node record.mjs は失敗します。node はPlaywright CLIコマンドではありません。--package=playwright によってモジュールがパスに配置されます。）最小限の record.mjs:

  import { chromium } from "playwright";
  const browser = await chromium.launch();
  const context = await browser.newContext({
    recordVideo: { dir: ".artifacts/<task-name>/" },
  });
  const page = await context.newPage();
  await page.goto("http://localhost:3000/path-under-test");
  // ...フローを駆動、ステップごとに意味のある状態変化を1つ...
  await context.close(); // .webmをファイナライズ
  await browser.close();
  

  ファイルが大きい場合は、ffmpegでトリミングまたは圧縮します。

• 注釈プロトコルはファイルになります: キャプチャをテスト順に番号付けし、アサーションを名前に含めます。01-precondition-signed-in.png、02-it-saves-on-blur-passed.png。アーティファクトフォルダーに assertions.md を保持し、各 test_start / assertion とその結果（passed / failed / untested + 理由）をリストします。

非UI変更にもエビデンスが必要

• API / パフォーマンス: 測定値を含むスクリプトプローブ。フェーズごとのリクエスト数、before/afterのレイテンシ。probe-output.txt にキャプチャします。
• レンダリング / キャンバス / シェーダー: レンダリングフレームとピクセルアサーション（差分値）を目視で確認し、PNGとして保存します。
• エージェント動作: ツール呼び出しと応答を示す関連トランスクリプトの抜粋。
• バグ修正: 修正を書く前に失敗を再現してキャプチャします。そのキャプチャがbefore/afterペアの「before」部分です。

キャプチャの衛生管理

• プローブしているサーバーが あなたの コードを実行していることを確認します（正しいポート、正しいプロセス）。特に複数のエージェントがマシンを共有している場合: lsof -i :<port> — または lsof がインストールされていない場合: `ss -ltnp "spo