Figma Comment Map

/figma-comment-map — Figmaコメントを画面ごとに棚卸しする

Figma の URL を渡すと、全コメントを画面ごとにまとめたレポート（HTML／PDF）を出す。

なぜ必要か

Figma の Slack 通知には 2種類あり、混同すると取りこぼす。

つまり DM だけに頼っている運用に穴がある。CC 外のコメントは DM に来ないので、 Slack を見ているだけでは永久に気づけない。

実例：あるファイルで実装担当者が 45分間に 19件のコメントを連投したが、そこに @自分 が 含まれていなかったため DM は 1件も来ず、翌日の返信（＝自分が参加したスレッド）だけが届いた。 通知が来た数件から全体像を推測できてしまうのが一番危ない。

→ 恒久対策は Slack チャンネルに file を購読させること（下記「取りこぼしを構造的に防ぐ」）。 このスキルの役割は購読の有無に依存しない全件突合と、画面ごとの棚卸し。 購読通知の取りこぼし報告もフォーラムに上がっているので、突合の手段は別に持っておく価値がある。

使いどき

• コメントが溜まったファイルを棚卸ししたい（「どの画面の話か把握できない」状態）
• レビュー会・仕様確定会の資料として、指摘を画面に紐づけて配りたい
• 実装側からのフィージビリティ指摘を、対応漏れなく仕分けたい
• 引き継ぎ時に「この画面で何が議論されたか」を残したい

日々のメンション巡回は /council-figma（Slack DM + REST の二経路収集）を使う。 こちらはファイル単位の全件棚卸しが役割。

実行手順

Step 0: 引数の確認

引数から Figma の URL（または file key）を取る。無ければユーザーに聞く。 --days 相当の指定（「直近2週間だけ」等）があれば控えておく。

Step 1: 機械判定で全件を取る（1パス目）

python3 ~/.claude/skills/figma-comment-map/scripts/figma_comment_map.py \
  "<FigmaのURL>" --me "<自分のFigma handle>" --out "<出力先>" --json-only

--me は要対応判定の基準。省略時は環境変数 FIGMA_ME を見る。 出力される <ファイル名>_threads.json には各スレッドの n（スレッド番号）/ status / screen / text / replies / last_activity が入る。

ステータスの自動判定ルール（機械的に決まる部分）

--stale-days（既定 21）より古い未返信は一段下げる（crit→act→ref）。 古い未返信を今日の対応リストと同列に並べると、返すべきものが埋もれるため。

Step 2: 判断を足す（ここがエージェントの仕事）

threads.json を読み、機械判定では決まらない部分を notes ファイルに書く。

• note — そのスレッドが要するに何なのかを一行で。画面名・依頼者・未処理の箇所を具体的に書く。 「議論あり」のような要約禁止。レポート上ではこの一行がコメント本文の上に出て、目次にも並ぶ
• status — 機械判定の上書き。よくある補正は次の2つ
  • 実装スコープやリリースを止めているものを crit に上げる（メンションが無くても）
  • 既に別スレッドで決着したもの、v1 に反映済みの経緯を ref / done に下げる
• 内容が読み取れないもの（ピンだけで文脈が分からない等）は wait にして、 何が分からないかを note に書く。推測で埋めない

{
  "T68": {"status": "crit", "note": "ある要素の設計難易度。実装側から自分に検討依頼"},
  "T44": {"status": "done", "note": "ボタン文言の変更で決着"},
  "T46": {"status": "wait", "note": "「この要素」が何を指すか判別できず"}
}

キーは T<番号> か comment id。_ で始まるキーは無視されるのでメモを書いてよい。 書かなかったスレッドは自動判定のまま出るので、全件書く必要はない。

Step 3: レポートを生成（2パス目）

python3 ~/.claude/skills/figma-comment-map/scripts/figma_comment_map.py \
  "<FigmaのURL>" --me "<handle>" --out "<出力先>" --notes "<notes.json>" --pdf

出力：

• <ファイル名>_コメント棚卸し_<日付>.html — スクショにピンを重ねた本体（ピン⇄スレッドが相互リンク）
• <ファイル名>_コメント棚卸し_<日付>.pdf — --pdf 指定時。返信を展開した印刷版
• <ファイル名>_threads.json — 構造化データ

notes ファイルは次回も使えるので、出力先に残して育てる。

Step 4: ターミナルに要約を出す

生成したファイルのパスと、次を提示する。

1. 要対応の総数と、そのうち実装・進行を止めているものの内訳
2. 止まっている理由を1件1行で（誰の指摘か、何が決まっていないか）
3. スクショを省略した範囲があればその旨（ページ全体にピンが打たれている場合など）
4. ステータスは推定であること。共有前に目視すべき箇所を名指しする

オプション

レポートの構造

• 画面のグループ分けは Figma のセクション単位（最も近い SECTION の名前）。 検討中の案をセクションで仕切る運用がそのまま検討フェーズの区切りになる。 セクションが無ければページ名でまとまる
• グループ・画面の並び順は「要対応の多い順」。上から読めば手をつける順になる
• コメントピンは client_meta.node_offset を画面の実寸で割った比率で復元しているので、 Figma 上の位置と一致する

トークン

環境変数 FIGMA_TOKEN → macOS キーチェーン（service 名 FIGMA_TOKEN）の順で探す。 未設定なら次を案内する。

security add-generic-password -s FIGMA_TOKEN -a $USER -w figd_xxxxx

必要な権限は file_comments:read と file_content:read。

チームに配るとき

スクリプトは Python 3 標準ライブラリだけで動く（画像圧縮は macOS の sips、 無ければ Pillow、それも無ければ PNG のまま）。配布時に必要なのは次の3点。

1. scripts/figma_comment_map.py と SKILL.md をチームの共有リポジトリに置き、 各自の ~/.claude/skills/ から参照するか、リポジトリ内の .claude/skills/ に置く
2. 各自が自分のトークンをキーチェーンに登録し、FIGMA_ME に自分の handle を入れる
3. スクリプト単体でも動くので、Claude Code を使わないメンバーにも python3 figma_comment_map.py <URL> --me <handle> --pdf で渡せる

取りこぼしを構造的に防ぐ（このスキルの外側）

このスキルは「溜まったものを棚卸しする」道具で、取りこぼし自体は Slack 側の設定で閉じられる。 棚卸しを頼まれたら、あわせて次を提案する。

1. Slack チャンネルに file を購読させる（推奨・数分）

対象チャンネルで /figma subscribe → 種類で file を選び、ファイルを検索 → 配信頻度を real time / hourly / daily から選ぶ。file 購読は Comments, replies, @mentions が対象なので、メンションが無いコメントも流れる。

頻度は real time を推奨。Figma 側で「10分以内のコメントは1つの Slack メッセージにまとめる」 バッチ処理が入るので、バースト（45分で19件など）でもチャンネルは埋まらない。 hourly / daily は実装を止める質問に気づくのが遅れるため、取りこぼし防止の目的に逆行する。

既に購読があるかは、Slack でそのファイル名を含む Figma bot のチャンネル投稿を 検索すれば分かる（DM ではなくチャンネルを見る）。チャンネル内では /figma list で一覧できる。

動作確認: 自分でメンション無しのコメントを1件打てばよい。 自分自身のコメントも購読チャンネルには届く（2026-08-03 実測。公式ドキュメントに記述は無い）。 10分バッチがあるので届くまで最大10分待つ。確認後はテストコメントを消すこと （Figma 側で削除しても、流れた Slack メッセージは残る）。

購読の通知にはノードへの直リンク（?node-id=...）が入るので、Slack から該当フレームへ直接飛べる。 DM 通知は link_redirect 形式でファイルキーが隠蔽されるため、この点でもチャンネル購読の方が扱いやすい。

2. 自前で確実にやる場合

• Webhook: FILE_COMMENT イベントを file context で作る。file context の上限は Professional 150 / Organization 300 / Enterprise 600。受け口（小さな HTTP エンドポイント）が必要
• 定期ポーリング: このスキルのスクリプトを --json-only --days 1 で日次実行し、 前回との差分を Slack に流す。受け口が不要なので webhook より軽い

購読を入れたうえで、月次などにこのスキルで全件突合すると穴が二重に塞がる。

よくある詰まり