jam-proof

jam-proof

成果物は Jam リンクです。検証を実施しながら記録し、完了したらリンクを渡します。ウィンドウよりヘッドレスブラウザーを、画面全体よりウィンドウを優先してください。

ユーザーが Jam で共有する録画を求めた場合は、Jam を作成します。ローカル動画だけを希望している場合は、ローカルに保存します。PR、チケット、既存の Jam への投稿には、そこへの公開を求める依頼が必要です。画面に表示するものがない場合は録画を省略し、その旨を伝えてください。

CLI をセットアップする

command -v jam >/dev/null || echo "jam is not installed"
export PATH="$HOME/.local/bin:$PATH"
jam auth status --json || jam auth login

jam が PATH にない場合は作業を中止し、https://jam.dev/docs/cli からインストールするようユーザーに依頼してから続行します。自分でインストールしてはいけません。

終了コード 3 は、サインインしていないことを意味します。ブラウザーがない環境（CI、クラウドエージェント）では、https://jam.dev/s/settings/mcp から取得した個人用アクセストークンをシークレットとして JAM_TOKEN に設定するようユーザーに依頼します。トークンをファイルに書き込んではいけません。 タイトルとコメントは、自分が書いた短い説明にします。ユーザーやページのテキストをシェル引数に貼り付けてはいけません。 jam doctor は録画の準備状況を確認します。jam agent-context はすべてのコマンドとフラグを表示します。

次の順に対象を選ぶ

説明内容を示せる最初の段階を選びます。下の段階ほど、他人のマシンが映り込む範囲が広くなります。

1. ヘッドレス Chrome。 デフォルトです。画面ではなくページを録画するため、ユーザーは自分のものが映らない状態で作業を続けられます。また、ノートパソコン、コンテナー、CI のいずれでも同じように実行できます。ウィンドウやディスプレイを指定せずに jam record start --cdp <endpoint> を実行すると、Chrome 自体から動画を取得するため、ウィンドウを他の画面で覆われないようにしたり、ディスプレイを起動したままにしたりする必要はありません。コンソールとネットワークのパネルも同じ接続から取得されます。エージェントが操作するブラウザーを録画するを参照してください。
2. 単一のウィンドウ。 ページだけのキャプチャーでは表示できないものが証明に必要な場合に選びます。アドレスバー、Chrome のダイアログ、ファイル選択ダイアログ、またはブラウザーではないデスクトップアプリなどです。自分でアプリのインスタンスを起動し、アプリにプロファイルやデータディレクトリがある場合は新しいものを使って、他人の情報が映らないようにします。起動したプロセスの --pid <pid> で指定します。ウィンドウが開くまで最大 5 秒待つため、ウィンドウ一覧を取得したり、アプリの起動と競合したりする必要はありません。自分で起動していないウィンドウの場合は、jam record windows --json で ID を取得して --window-id に渡します。macOS では open -g で起動し、フォーカスを奪わないようにします。また、OS のマウスではなくアプリ独自の自動化インターフェイスを使って操作し、ユーザーからカーソルを奪わないようにします。macOS ではウィンドウをほかのウィンドウの背後に置いても構いません。Linux ではウィンドウのキャプチャーが画面領域の録画になるため、分離されたデスクトップセッションを使うか、下記の画面全体の録画と同じ同意を得ます。その領域がほかの画面で覆われたり、最小化されたりしないようにし、ディスプレイを起動したままにしてください。
3. 画面全体。 最後の手段です。jam record displays --json でディスプレイの一覧を取得できます。誰も使っていないマシン（CI ランナー、コンテナー、自分が所有するリモート Linux デスクトップ）であれば、確認なしで問題ありません。誰かが使っているマシンでは、その人のメッセージ、タブ、通知が映るため、まず確認し、ディスプレイ名とおおよその録画時間を伝えて、承諾を待ちます。返答がなければ録画しません。録画中はディスプレイがスリープしないようにする必要があります。セレクターも --cdp も指定せずに start または run を実行すると画面全体が録画されるため、意図せずこの段階に進まないよう、対象を指定してください。

ブラウザーの証明をどの段階で録画する場合も、Chrome のデバッグポートを --cdp <port> として jam record に渡してください。Jam にはすべてのタブのコンソールとネットワークの情報が含まれ、これが動画では見えない証拠の半分を補います。start は独自の cdpProxy を表示します。Chrome ではなくそちらにドライバーを接続すると、クリックや入力も、操作対象の要素とともにアクションとして記録されます。

録画の範囲を限定する

jam record run は、ラップしたコマンドが終了するまで録画します。検証をラップします。

jam record run --cdp <cdp-url> --url <page url> --title "<the claim>" --json -- <verify command>

これが第1段階です。第2段階では、--cdp <cdp-url> を、起動したアプリの --pid <pid> に置き換え、ブラウザーの場合は --cdp <port> も指定します。--url はウィンドウに表示されているページです。Sharepage はその名前を表示します。

自分でアプリを操作し、コマンドでラップできない場合は、バックグラウンドで実行し、完了したら SIGINT を送信します。アプリが停止してアップロードされ、標準出力にレシートを出力して終了コード 0 で終了します。

jam record run --cdp <cdp-url> --url <page url> --title "<the claim>" --json > proof.json 2> proof.log &
REC=$!
# drive the steps that show the behavior
kill -INT $REC; wait $REC

エージェントが操作するブラウザーを録画する

これは第1段階であり、通常のケースです。Chrome はヘッドレスのままです。動画にはページの Chrome 独自のフレームが記録され、コンソール、ネットワーク、ユーザー操作の各パネルも同じ Chrome から取得されます。そのため、テスト対象のページ上で Jam の処理が実行されることはなく、ユーザーの画面が映り込むこともありません。

CDP に対応している場合は、プロジェクト独自のブラウザードライバーを使います。Playwright では、chromium.connectOverCDP(cdpProxy) を使ってスクリプトからページを操作します。jam record の行はそのままです。対応するドライバーがない場合は、以下のコマンドで agent-browser（npm i -g agent-browser、0.38 以降）を使用します。agent-browser には独自の Chromium が付属します。環境に Chrome がまったくない場合は第1段階を実行できないことを明記してください。

agent-browser --session proof --input-mode human open <url>
agent-browser --session proof set viewport 1920 1080   # then reload: it does not apply to the open page
agent-browser --session proof open <url>
agent-browser --session proof get cdp-url          # ws://127.0.0.1:<port>/devtools/browser/…
jam record start --cdp <cdp-url> --title "<the claim>" --json   # → { session, cdpProxy }
agent-browser --session proof record start /tmp/discard.webm --cursor --fps 5   # only turns the pointer overlay on; the file is unused
agent-browser --session drive --input-mode human --cdp <cdpProxy> mouse move <x> <y>   # drive THROUGH the proxy
agent-browser --session drive --cdp <cdpProxy> mouse down
agent-browser --session drive --cdp <cdpProxy> mouse up
agent-browser --session drive --cdp <cdpProxy> wait "<what the click produced>"
agent-browser --session proof record stop
jam record stop <session> --json

--cdp を指定し、ウィンドウやディスプレイのセレクターを指定しない場合、動画には表示中のタブのページが 30 fps のスクリーンキャストとして記録されます。アドレスバー、カーソル、Chrome のダイアログは映らず、画面収録の許可も不要で、覆わないようにしておくウィンドウもありません。

ページを読み込む前に 1920x1080 に設定し、クリックごとにカーソルのオーバーレイが表示されるよう、mouse move、続けて mouse down と mouse up を使ってクリックします。references/browser.md には、カーソルオーバーレイのルール（agent-browser 0.38 以降）、その他のサイズ、第2段階で Chrome を表示する方法が記載されています。

Chrome ではなく cdpProxy 経由で操作してください。そうしないと、クリックや入力がアクションとして記録されません。DevTools の URL を受け取るものには、次の URL を渡します。 chrome-devtools-mcp --browserUrl <cdpProxy>、Playwright の chromium.connectOverCDP。

start が出力した session を使って、jam record stop <session> --json で停止します。これにより、別のエージェントが開始した録画を誤って停止することがありません。レシートが Jam です。タップが機能していれば、標準エラーには何も出ません。Chrome からコンソール、ネットワーク、ユーザー操作のイベントがひとつも送られなかった場合は、その旨が表示されます。これはタップまたはプロキシが実際には経路上になかったことを意味します。そのメッセージが出たら、証明に失敗したものとして扱い、リンクを共有する前に接続を修正してください。

jam record start または run が失敗した場合は、jam doctor を実行し、Recording と Screencast の行を報告してください。取得できていないリンクを共有してはいけません。

読みやすくする

自分のためではなく、見る人に合わせたペースにしてください。 あなたはアクセシビリティツリーからページを読み取りますが、そのツリーはページの描画、アニメーション、状態の安定よりずっと早く利用できます。あなたの速度では正しく見える実行も、見る人には一瞬のちらつきにしか見えず、ちらつきでは何も証明できません。したがって、待機時間は証明の一部であり、余分な時間ではありません。

• 既知の状態から始めます。ページを再読み込みし、アプリを再起動し、ターミナルをクリアします。
• 時間ではなく対象を待ちます。アクションによって表示されるものには wait "<selector>" を使います。固定の待機時間は、遅い実行では短すぎ、速い実行では無駄な空白になります。同じ間隔が続く動画は機械的に見えます。
• その後、見る人が追いつけるようにします。画面内の小さな変化には少し間を置き、新しい画面にはより長く、主張を裏付ける状態には最も長く時間を取ります。変化の大きさに合わせて表示時間を調整し、動いているものから途中で切り替えてはいけません。ツリーに要素があることと、人がその要素を目にしたことは別です。
• 短くまとめます。動作を示す 30 秒の動画は、5 分の動画に勝ります。
• タイトルには主張を記します。「proof」ではなく「Deep link scrolls to comment 6」のようにします。
• 手順と期待される結果は --description に記載します。

修正前と修正後

バグ修正では、報告された Jam にバグが示されている場合、それを「修正前」として再利用します。修正前と修正後の録画が新たに必要な場合は、テストデータを使い、分離したチェックアウトで旧バージョンと修正版を実行します。ユーザーの作業ツリーは保持してください。意味のある修正前の状態がない場合は最初の録画を省略し、その理由を伝えてください。

完了後

1. レシートを確認します。常に id と url を確認し、jam record で録画した場合は durationMs、width、height、記録された target も確認します。録画またはアップロードに失敗した場合は、その旨を伝えます。確認できていない証拠を提示したと主張してはいけません。
2. リンクできるものがあれば、リンクを追加します。プルリクエスト、チケット、CI 実行がある場合は、jam update jam <jamId> --resource <url> で添付します。URLから内容がわからない場合は、--label "<name>" を付けます。不具合の Jam があり、録画で修正の動作を確認できる場合は、jam update jam <jamId> --mark-related <bug jam> --type fixes で関連付けると、不具合の Jam に「fixed by」のバックリンクが表示されます。主張のデモには proves を使い、1つのワークフローに属する複数の Jam をまとめる場合や、録画では解決を確認できない修正には relates_to を使います。MCP では、これらは addResource と markRelated です。共有ページは公開される場合があります。トークンを含む URL は決して添付しないでください。
3. 動画だけでは伝わらない情報がある場合は、コメントを提案します。新しい Jam には、結果が表示された時点に jam create comment <jamId> "<what to look at>" --at <ms> でコメントを追加します。不具合の Jam には、修正の動作が確認できた時点、またはチェックに失敗した時点で、新しい Jam へのリンクとともにコメントを追加します。ユーザーが了承した場合、またはすでに依頼されている場合は、すぐに投稿します。
4. リンクを返します。「不具合 | 修正」の形式にするか、主張を裏付ける1つのリンクを返します。ユーザーから投稿先の指定があった場合に限り、PR またはチケットに投稿します。

Jam にフィードバックを送信する

このスキル、Jam MCP ツール、jam コマンド、または Jam のドキュメントに誤りや古い情報、わかりにくい点があった場合、または特にうまく機能した場合は、Jam に知らせます。自分で送信してください。Jam のエージェントがフィードバックを読むため、承認は不要です。

body、category、subject を指定して submitFeedback MCP ツールを呼び出します。

MCP を利用できない場合は、CLI を使います。

jam feedback "<what you were doing, what you expected, what happened, the mistake>" --category <skills|mcp|cli|docs> --subject <skill name, tool name or command>

• Jam の機能に関する内容に限り、ユーザーのコードや他のツールに関する内容は含めません。
• 1セッションにつき最大1回とし、自分で修正した些細なミスについては送信しません。
• シークレット、顧客データ、ソースコード、スタックトレース、録画の内容は含めません。