jam-annotate

jam-annotate

成果物は、レビュアーが5秒で読めるスクリーンショットのJamです。壊れている箇所に枠を付け、説明文の行番号と一致する番号を付け、秘密情報を隠します。jam create jam はアップロード前に画像へマークを描き込みます。jam agent-context は完全なペイロードスキーマを出力します。

Jam の作成または共有をリクエストすると、アップロードが許可されます。ローカルのみで注釈や墨消しを行う場合は、利用可能な画像ツールを使い、ローカルファイルを返してください。Jam へアップロードしたり、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 に設定するよう依頼してください。トークンをファイルに書き込んではいけません。

マークを選ぶ

種類は5つあります。マークが示す内容に応じて選んでください。

種類	示す内容	番号付き
box	この要素が対象です	はい
arrow	ここからあちらを見てください（方向）	はい
text	指し示す要素がない事実	いいえ
redact	この領域を画面外に出してはいけません	いいえ
blur	この領域は重要ではありません	いいえ

座標を正確に指定する

座標は画像ファイル上のピクセル単位で、原点は左上です。CSS ピクセルではありません。Retina キャプチャーは2倍なので、CSS (120, 340) にあるボタンは、画像上では (240, 680) にあります。

1. 要素の境界と画像の原点を一致させるため、ページ全体ではなくビューポートをキャプチャーします。
2. 画像サイズ（PNG ヘッダー、またはドライバーのスクリーンショットメタデータ）を読み取り、ビューポート幅で割ります。その比率がスケールです。
3. ドライバーから要素の境界を取得し（Playwright の locator.boundingBox()、CDP の DOM.getBoxModel）、すべての数値にスケールを掛けます。
4. 枠線が要素自体の境界線に重ならないよう、要素から外側へ6〜10 CSS ピクセル分の余白を設けます。

ドライバーがなく画像ファイルしかない場合は、画像のピクセルサイズを読み取り、画像上のピクセル単位で目視により余裕のある枠を配置し、返信で位置が推定値であることを伝えてください。

CLI は画像の範囲外にあるマークを拒否し、そのインデックスを示します。拒否される原因のほとんどは、スケールを適用し忘れていることです。

マークが覆う範囲を把握する

枠や矢印は、輪郭線より広い範囲を描画します。以下では、u は画像幅を1440で割った値（1以上）で、すべてのサイズは画像上のピクセル単位です。

• バッジ：枠の左上、または矢印の from を中心とする半径 14u の円です。内側の4分の1が、その角にあるもの（アイコン、アバター、先頭の文字）に重なります。
• 枠ラベル：高さ 29u のチップで、下端は枠の 7u 上にあり、枠の左端から右へ 21u の位置に始まります。枠が画像上端から 36u 未満の位置にある場合、チップは枠の上端内側に入り、内容に重なります。
• 矢印ラベル：高さ 29u のチップで、from の高さに中央揃えされ、そこから右へ 21u の位置に始まります。
• チップの幅は、文字あたり約 8.4u に 14u を加えた幅です。
• 画像の端では、CLI がバッジとチップを内側へ移動して画像内に収めます。そのため、上記の数値で示した範囲よりも枠に大きく重なります。

ラベル付きの枠には、上部に 36u の空きが必要です。リスト、テーブル、アクティビティフィードの行間はそれより狭いため、ある行のラベルはその上の行を覆い、次の行のラベルは先頭行のテキストを覆います。

作成

• 記載する事実ごとにマークを1つ付けます。3〜5個にします。それ以上は動画にします。
• マークが覆う部分には、別のマークの対象も含め、読者に必要なテキストを置かないでください。ラベルを追加する前に、そのチップとバッジが上のセクションに重ならないことを確認してください。
• 隣り合う要素（縦に並んだ行、隣接するボタン）は、それぞれラベルなしで囲み、説明文に内容を記載します。画像上にラベルを置く必要がある場合は、チップを右側に置ける余白を確保し、矢印の始点を空白の余白に置きます。
• アイコンやアバターが要素の先頭にある場合は、バッジで隠れないよう、左側に少なくとも 14u の余白を設けて要素を囲みます。
• 間違っている要素を囲みます。方向そのものが重要な場合に限り、矢印を使います。たとえば、クリックした先に表示されるはずだった場所や、どのコントロールがどの値を変更したかを示す場合です。始点は空白に置き、矢印の先端は対象の中央ではなく端に置きます。
• テキストは、対応する要素がない事実（「クリック後に何も起きなかった」など）に使います。説明する領域の近くの空白に配置します。
• まず、十分な範囲をマスクします。メールアドレス、名前、アバター、トークン、内部 URL、顧客 ID が対象です。単語だけでなく、行全体をマスクしてください。
• ぼかしは、秘密情報ではなく雑多な要素に使います。サイドバー、無関係な行の一覧、デモに映る顔などです。ぼかすと、その領域が目立たなくなり、目が向きにくくなります。大きな文字はぼかしても判読できるため、画面外に出してはいけないものには redact を使ってください。
• 順序がストーリーを伝えます。番号はペイロードの順序に従うため、説明文で伝える順にマークを並べます。
• ラベルは5語以内のラテン文字で、末尾にピリオドを付けません。文は説明文に記載します。
• 色には意味を持たせ、意味ごとに1色を使います。デフォルトの lime は「ここを見て」です。マークが複数ある場合、問題のある箇所には strawberry を使います。その他の色は grape、blueberry、mint、lemon、black です。
• マークはメインのスクリーンショットにのみ描画されます。secondaryScreenshotPath はそのままアップロードされるため、メイン画像でマスクしても隠れません。マスクした内容が一切含まれない場合に限り、セカンダリ画像を添付してください。それ以外の場合は、まず画像ツールでマスクするか、添付を省略してください。

ペイロード

以下のキャプチャは2倍の大きさです。そのため、1440×900 のビューポートは 2880×1800 の画像になり、すべての座標が2倍になります。

ファイル書き込みツール（たとえば payload.json）を使ってペイロードをファイルに書き込み、jam create jam @payload.json を実行します。URL、タイトル、説明はユーザーまたはページから取得するため、シェル引数に含めてはいけません。

{
  "url": "https://app.example.com/checkout",
  "title": "Pay button does nothing on retry",
  "description": "1. The Pay button, clicked twice.\n2. Where the confirmation should have appeared.\nCard number redacted.",
  "screenshotPath": "./checkout.png",
  "screenDimensions": { "width": 1440, "height": 900 },
  "annotations": [
    { "type": "redact", "x": 1200, "y": 640, "width": 560, "height": 48 },
    { "type": "blur", "x": 0, "y": 0, "width": 480, "height": 1800 },
    { "type": "box", "x": 1180, "y": 1120, "width": 320, "height": 88, "label": "Pay, clicked twice", "color": "strawberry" },
    { "type": "arrow", "from": { "x": 600, "y": 1400 }, "to": { "x": 1440, "y": 980 }, "label": "no confirmation here" }
  ]
}

説明文の番号はバッジの番号と一致させます。「1.」はペイロード内の最初のボックスまたは矢印、「2.」は2番目を指します。マスク、ぼかし、テキスト注記には番号を付けません。

作成後

1. レシートの id、url、kind を確認します。コマンドが失敗した場合は、その旨を伝えてペイロードを修正します。取得していないリンクを渡してはいけません。
2. 描画された内容を確認します。jam get screenshots <id> --out <dir> を実行してから、PNG を開きます。チップやバッジが、主張の根拠となるテキストを覆っている場合は、ペイロードを修正して Jam を作成し直し、新しいリンクだけを共有します。最初の Jam は削除すると元に戻せないため、削除する前に必ず人に確認してください。
3. リンクすべきものがある場合は、リンクを付けます。スクリーンショットが属するプルリクエストまたはチケットには、jam update jam <id> --resource <url> を使います。UI の状態ごとに Jam を1つ作る場合は、jam update jam <id> --mark-related <other jam> --type relates_to を使って関連付けます。トークンを含む URL は決して添付しないでください。共有ページが公開される可能性があります。
4. リンクを、それが裏付ける主張とともに返します。ユーザーが投稿先を指定した場合に限り、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 回までとし、自分で修正したミスについては送信しないでください。
• シークレット、顧客データ、ソースコード、スタックトレース、録画の内容は含めないでください。