jam-proof-table

jam-proof-table

主張を入力すると、各項目の動作状況と、それを示す Jam をまとめた表が出力されます。ユーザーは「この件の Jam はどこ？」と尋ねることなく、ワンクリックですべての主張を確認できます。

新しい Jam を記録するには、jam-proof を使います。このスキルは 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 agent-context は、すべてのコマンドとフラグを出力します。

1. 1 つの主張につき 1 つの Jam

1 行につき 1 つの主張を記載します。例：「価格が途中で切れなくなった」「サインアウト後にサインインできる」。各行には、その主張を示す Jam を 1 つ付けます。1 つの Jam が複数の主張を裏付ける場合は、該当する箇所の時刻を各行に記載します（at 0:48）。

Jam がない主張も「未記録」として表に残します。ローカルの動画ファイルやスクリーンショットのパスを Jam として記載してはいけません。

2. すべての Jam に名前を付けて保存する

タイトルは、後から Jam を見つけるために使います。<チケットまたはソース> <示す内容> の形式にします。以前の Jam の修正を確認する Jam には、検索結果で両方が表示されるように、元の Jam と同じタイトルの先頭に fix check: を付けます。

jam list folders --query "Release 4.2 checks" --json      # reuse it if it exists
jam create folder "Release 4.2 checks" --json             # otherwise; returns its id
jam update jam "$ID" --folder "$FOLDER_ID" --title "ENG-412 fix check: Pro price wraps"

jam create folder は、同じ名前のフォルダーがあっても呼び出すたびに新しいフォルダーを作成するため、まず既存のフォルダーを確認し、後からその ID を指定します。1 回の実行につきフォルダーは 1 つです。フォルダーを作成すると Viewer が Creator にアップグレードされ、シートの請求額が変わる場合があります。Viewer アカウントでは、先に確認を求めます。

ユーザーから依頼されない限り、この実行で記録した Jam だけを名前変更または移動します。

3. 既存の Jam を探す

もう一度記録する前に、該当する Jam がないか探します。1 回の実行で作成した Jam をすべて見つけるには、その実行のフォルダーを使うのが最も確実です。

jam list folders --query "checks" --json
jam list jams --folder "$FOLDER_ID" --json
jam list jams --created-at -P1D --json                    # created in the last day
jam list jams --query "price" --order-by createdAt --limit 20 --json
jam list jams --url "https://example.com/pricing" --json

--query はあいまい検索であり、タイトルの絞り込みではありません。検索結果を使う前に、各タイトルを確認します。--order-by createdAt は新しい順に並べるため、--limit を指定すると最も古い項目が除外されます。

「私が渡した Jam はどれ？」と聞かれたら、まず会話を検索します。ワークスペースを検索する前に、会話内で jam.dev/c/ を探します。

4. 一覧に載せる前に各 Jam を確認する

jam get jam "$ID" --json                                  # reads back, type, duration

次に、Jam の type に応じて確認します。それ以外のタイプには動画フレームがありません。

jam get frames "$ID" --at 48000 --size medium --out "$(mktemp -d)"   # video; outside the repo
jam get screenshots "$ID" --out "$(mktemp -d)"                       # screenshot

リプレイにはフレームもスクリーンショットもありません。イベント、コンソール、ネットワークを確認し、それらでは主張を確定できない場合は、その行を未確認とします。

動画の場合は、主張が表示される時点のフレームを開きます。--at は Jam の duration より小さい値にする必要があります。空白のページ、1 枚の静止したフレーム、または別のタブは証拠になりません。スクリーンショットは仕様上、静止画像 1 枚です。主張が画像内に見えていれば証拠になります。Jam に主張が示されていない場合は、jam-proof で改めて記録し、その旨を伝えます。

画面外で発生する主張もあります。たとえば、API のステータス、件数、送信されたメッセージなどです。これらは jam get network、jam get console、または jam get user-events で確認し、動画とイベントのそれぞれがどの部分を示しているかを表に記載します。

5. 表を書く

作業した順序を保ちます。ステータスは主張の状態で、次のいずれかです：動作、故障、未確認（Jam では確定できない）、未記録。

| # | Claim | Status | Jam | Source |
|---|-------|--------|-----|--------|
| 1 | Pro price wraps on narrow cards | works | [ENG-412 fix check](https://jam.dev/c/...) | [ENG-412](...) · [original Jam](https://jam.dev/c/...) |
| 2 | Sign-in after sign-out | broken | [ENG-415 repro](https://jam.dev/c/...) | [ENG-415](...) |

表の下に、「動作」以外の各行について、その理由を 1 行ずつ記載します。

その後

行の内容が確定している（動作または故障）元の Jam それぞれに、ステータスと修正確認用 Jam へのリンクを記載したコメントを 1 件投稿します。未確認および未記録の行は対象外です。

jam create comment "$ORIGINAL_ID" "Fix check: works. https://jam.dev/c/<id>"

ユーザーが承認したら投稿します。ユーザーがすでに依頼している場合は、すぐに投稿します。

修正確認用 Jam の行が「動作」の場合に限り、その Jam を元の Jam の修正としてマークします（MCP 経由で markRelated）。すると、元の Jam に「修正した項目」へのバックリンクが表示されます。

jam update jam <fix check id> --mark-related "$ORIGINAL_ID" --type fixes

主張を示す Jam には --type proves を使います。故障または未確認の行には、--type relates_to まで使用できますが、fixes は決して使いません。

表はチャットに投稿します。ユーザーから依頼された場合に限り、プルリクエストまたはチケットにも投稿します。

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 回までとし、自分で修正したミスについては送信しないでください。
• シークレット、顧客データ、ソースコード、スタックトレース、録画の内容を含めないでください。