EugineKosenko/majordom

analyze-fig

Figma エクスポート（.fig）を Figma API にアクセスせずに解析：ノードツリー、テキスト、ラスターをファイル自体から読み取り、.fig に含まれない作成者のコメントは、MCP 経由でリンクから別途取得します。結果は spcfctn/ui/ 内の md ファイルに保存され、以降は Figma を再読み取りせずにこれらのファイルを利用します。

実行すべきでない場合

既に解析済みのレイアウトに関する質問（「フィルターのコメントには何が…」「画面の列は…」）は、このスキルではなく spcfctn/ui/*.md を読んで解決してください。解析が必要なのは、新しい .fig や更新された .fig、あるいは md に回答がない場合のみです（spcfctn-code.md 参照）。

ディレクトリ（唯一の下書きディレクトリ draft、git 管理外）

• spcfctn/ui/draft/ — 入力 .fig（およびその他の下書き）。ユーザーがファイルを配置します。
• spcfctn/ui/draft/<名前>/ — 展開結果：message.json（全ノード）、meta.json、images/、screens.json、screens.txt、および収集したコメント（comments.json）。.fig から再生成可能で、git には含めません。個別の raw/ や data/ はありません（modeling.md）。
• spcfctn/ui/*.md — 分析結果。これのみ git に残ります。

<名前> は、拡張子を除くファイル名を小文字にし、ハイフンで区切ったものです（例：internal-interfaces）。

ステップ 0 — 準備

• プロジェクトの spcfctn/ を見つけます。存在しない場合は、ユーザーに作成を依頼してください（spcfctn-code.md）。アーティファクト ui/ とそのサブディレクトリ draft/ は自分で作成します。
• spcfctn/ui/.gitignore（アーティファクトリポジトリ）を確認します。draft が含まれている必要があります（modeling.md 参照）；不足があれば、gitignore.org 経由で追加します。
• Fig ファイル：ユーザーが名前を指定します。指定がない場合は、spcfctn/ui/draft/*.fig を表示して確認します。
• プロジェクトの CLAUDE.md（散文の言語、規約）と既存の spcfctn/ui/*.md を読みます：解析はこれら既存の構造と用語を継続し、ゼロから始めないでください。
• python3 と zstd が PATH に必要です。

ステップ 1 — 展開とデコード

python3 ~/.claude/skills/analyze-fig/scripts/fig.py spcfctn/ui/draft/X.fig spcfctn/ui/draft/<名前>

フォーマットバージョン、ノード数、ブロブ数、画像数を出力します。スクリプトはバージョン 106 で検証済みです。他のバージョンやエラーが発生した場合は、フォーマットを推測したり他のデコーダーを読み取ったりせず、ユーザーに伝えてください。meta.json には exported_at（エクスポート日時）が含まれており、ステップ 5 で必要になります。message.json は大きいため、直接出力しないでください。

ステップ 2 — セクションと画面に分割

python3 ~/.claude/skills/analyze-fig/scripts/screens.py spcfctn/ui/draft/<名前>

ページ、セクション（トップレベルのフレーム）、および画面（その子）のリストと、テキスト数とラスター数を出力します。核心は screens.txt にあります：各画面について、テキストレイヤーを上から下、左から右にグループ化した行（フィルター、列ヘッダー、ボタンなどが読み取れます）と、ラスターへのリンクが含まれます。

• 数量を期待値（例：古い md）と比較します；不一致がある場合は停止する理由となります。
• テキストレイヤーは、テキストのない要素（アイコンのみ）やラスターの内容を認識しません。images/ 内の各ラスターについて、ファイルを開いて（Read）テキストレイヤーにない内容を説明し、画像から読み取ったことを明記します。ツリーとテキストが主な証拠であり、画像は補足です。
• コンポーネントインスタンス（INSTANCE）には、スクリプトが認識できないオーバーライドされたテキストがある場合があります；screens.txt はこれについて警告します。

ステップ 3 — spcfctn/ui/*.md に書き込む

• セクションごとに 1 つの md（またはファイルが 1 つの場合は 1 つのファイル）。既存のファイルがある場合は、完全に読み取って更新し、上書きしないでください：md ファイルはエージェントのみが管理しますが、以前の修正を失ってはいけません。
• 散文の言語はプロジェクトの CLAUDE.md に従います。
• 構造（例：job/vale/kylada 内の spcfctn/ui/internal-dashboard.md）：ソースと検証を含む導入（読み取った内容、エクスポート日付、画面数とテキスト数）、レイアウトの読み取りルール、UI ラベルと内部用語の対応、画面ごとの順序（レイアウト順のフィルター、リストボタン、列、行内のアクション）、未解決の質問。
• あなたの解釈であり、レイアウトのテキストやコメントでないものはすべて inferred とマークします。
• レイアウトの読み取りに関するプロジェクトルール（例：列ヘッダー下の Select はソート制御）は、プロジェクトの CLAUDE.md から取得して適用し、独自に作り出さないでください。

ステップ 4 — MCP 経由のリンクからコメントを取得

.fig にはコメントは含まれません（確認済み）：コメントは Figma サーバー上にのみ存在します。

• Figma 上のファイルへのリンクが必要です（node-id の有無は問いません）。ない場合はユーザーに依頼します。
• プロジェクトに接続されている Figma MCP サーバーの comments MCP ツールのみを使用します（サーバー名は接続済みサーバーのリストから取得）；パラメータ file にはリンクを指定します。該当するツールがない場合は、ユーザーに伝えます。公式の figma-cs はコメントを提供しないため、トークンを使った REST API を直接呼び出したり、.env を読み書きしたりしないでください。
• node_id なしで呼び出すと、ファイル内のすべてのコメントがスレッドごとに取得されます（番号、日付、状態、ノード @id、テキスト、返信）。refresh は不必要に実行しないでください。コメントエンドポイントはファイル読み取りとは別にカウントされ、読み取りが 429 を返しても機能します。
• 画面へのバインド：
  • @id が screens.json 内の画面 ID と一致する場合 — 画面が特定されます。
  • セクションまたはページの @id の場合 — 画面をジオメトリで特定します。そのためにはコメントの node_id と node_offset が必要です。キー ノード X Y（例：#144 979:3 500 5471）の形式で行を組み立て、次のコマンドに入力します：python3 ~/.claude/skills/analyze-fig/scripts/place.py spcfctn/ui/draft/<名前> < 行。出力：キー、セクション、画面；または理由と最も近い画面（ポイントが画面上にない場合）。
  • 出力を確認します：comments ツールが node_offset を出力しない場合があります（スキル作成時点でそうでした）。その場合、セクションやページへのコメントは正確に配置できません：テキストから画面を推測せず、セクションに属するものとして扱い、画面不明 とマークし、配置にはコメントのオフセットが必要であることをユーザーに伝えます。
• 返信（↳）は親スレッドに属します。

ステップ 5 — コメントがファイルと一致することを確認

画面が特定された各コメント（およびセクションのコメントグループ）について確認します：

• コメント内で言及されているフィールド、列、ボタン、値が、この画面のテキストレイヤーに存在するか（Amount of integrated services ↔ Services 列；引用符内の引用；値のリスト）。
• コメントがレイアウトと矛盾しないか（列数、順序、要素のタイプ、「フィルターあり」/「なし」）。
• 日付：コメントが meta.json の exported_at よりも新しい場合 — エクスポートが古くなっています。その場合は、spcfctn/ui/draft/ に新しいエクスポートを依頼します。
• コメントのノードがファイル内に存在しない場合（削除または改名） — 孤立したコメントです。
• 画面なし、認識可能な内容なしのコメント。

不一致を小さな表にまとめ（番号 #N、画面、不一致の内容）、ユーザーにどの内容が正しいか尋ねます：黙って修正したり、レイアウトとコメントの間で自分で選択したりしないでください。回答が得られるまで、md 内で conflict とマークします。

ステップ 6 — サマリーを書き込む

• md に作成者のコメントセクションを追加します：ダイジェスト（何を明確にしているか）と、画面ごとの全コメントを番号 #N 付きで。コメントが inferred だった内容を明確にしている場合は、レコードを修正し、コメントを参照します。
• 導入部の「Verification」を更新します：読み取った内容（.fig、バージョン、エクスポート日付、テキスト、ラスター、コメント、取得日）と、カバーされていない内容。
• 未解決の質問は個別のリストに；ユーザーの回答は「Resolved」に移動します。
• 依頼がない限り、何もコミットしません。口頭（日本語）でサマリーを伝えます：セクション数、画面数、コメント数、不一致の数と、具体的に確認すべき内容。

禁止事項

• Figma REST API をトークンで呼び出さない、.env を読み書きしない。
• 外部コード（kiwi デコーダーなど）を読み取らない：フォーマットは既に scripts/ で実装されています。
• .fig と解析結果（draft/ 以下のすべて）を git に含めない。
• テキストレイヤーが存在する場合、コメントの画面を単語から推測したり、画像からレイアウトの内容を推測しない。