| name | figma-spec-extractor |
| description | Figma のワイヤーフレーム URL から仕様書一式を docs/ 配下に Markdown で抽出するスキル。ページ構成・ユースケース・アクター・データモデル・コンポーネントを 15 ステップで段階的に生成し、整合性／データモデル／コンポーネントの 3 レビューを作成する。**既存リポジトリの機能拡張モード** では既存モデル・ルーティング・ビューを再利用優先。**レビュー反復反映ステップ** では質問ループで方針を確定しドキュメントに反映する。Figma URL が提供されたとき、Figma デザインから実装用仕様書を作りたいとき、または既存仕様書の精度向上を求められたときに使用する。 |
Figma Spec Extractor
Figma ワイヤーフレームから仕様書一式を段階的に抽出し、docs/ 配下に Markdown で出力する。Figma に明示的に無い属性は推測補完しない が、構成要素から客観的に導ける範囲（ページ役割、状態遷移、設計示唆、典型ペインポイント等）は本体に含める。
出力構造
docs/
├── existing-codebase.md # extension モードのみ
├── pages/
│ ├── README.md # ページインデックス + 横断サマリー
│ └── <page-slug>.md # 6 セクション固定: 構成要素 / テキスト要素一覧 / アクションボタン / 参照モデル / 利用コンポーネント / 関連する未解決事項
├── use-cases.md
├── actors.md
├── data-model.md
├── components.md
└── reviews/
├── coverage-review.md
├── data-model-review.md
└── components-review.md
ID 命名規則（スコープ付き）
| 対象 | ID 形式 | 例 |
|---|
| ユースケース | UC-XX | UC-01 |
| アクター | A-XX | A-01 |
| Entity | E-XX | E-01 |
| Entity のカラム | E-XX.C-YY | E-01.C-03 |
| Entity のインデックス | E-XX.I-YY | E-01.I-01 |
| Relation | R-XX | R-01 |
| コンポーネント | CMP-XX | CMP-01 |
| コンポーネントのパラメータ | CMP-XX.P-YY | CMP-01.P-02 |
| コンポーネントのイベントハンドラ | CMP-XX.H-YY | CMP-01.H-01 |
数字は 発見順にゼロパディング 2 桁 で採番。後続ステップで参照する際は必ずこの ID を使い、必ず名前を併記 する（例: `E-02.C-06`（Award.application_close_at））。
補完しない原則 と 客観抽出の許容範囲
禁止（推測補完）
- Figma に存在しない属性（業務要件、KPI、戦略目標）を勝手に書き起こす
- 「ありそう」な追加機能（例: ユーザー登録、認証、決済）を勝手に追加する
- ペルソナの架空属性（具体的な年齢、職業、家族構成）をでっち上げる
許容（客観抽出。本体ドキュメントに記述してよい）
- ページ名称＋構成要素から導ける 役割記述
- 属性の状態遷移／ライフサイクル（ENUM 値自体は Figma にある）
- CMS／運用／SEO の設計示唆（構成から自然に導出される）
- アクターの分類（プライマリ／セカンダリ／オフステージ）と典型ペインポイント
- アクションの挙動概要（構成要素名＋親要素＋アイコンから一意に決まるもの）
Figma 未記載のままにする項目
レビューステップ（Step 6 / 9 / 12）で初めて不足を列挙し、ユーザーに提示する。本体側で「未記載」と書くのは、上記「許容」にも当てはまらない場合のみ。
前提条件
figma-dev MCP サーバー（Figma:get_design_context 等）が認証済み（未認証なら /mcp で認証を促す）- 出力先のディレクトリで作業中
- ユーザーから以下を取得済み：
- Figma URL（
https://www.figma.com/design/:fileKey/...）
- プロジェクトのゴール（レビュー時の評価軸として必須）
- 転記先（ローカル Markdown / Notion / GitHub Wiki 等）
- 実装モード（次項参照）
実装モード × 実行モード
実装モード（Step 0 で確認）
| モード | 用途 | Step 0.5 の実行 |
|---|
new | 新規アプリ | スキップ |
extension | 既存アプリの機能拡張 | 実行（既存資産再利用が前提） |
extension モードでは既存モデル → カラム追加 → 新規 Entity の優先順位で設計する。詳細は references/extension-mode-guide.md 参照。
実行モード（Step 0 で確認）
| モード | 確認頻度 | Step 14 |
|---|
| ハイブリッド（推奨） | Step 0 / 1 / 4 / 6 / 7 / 9 / 12 後 | ユーザー意向に応じて |
| 全自動 | レビュー提示のみ | 質問ループあり |
反復反映（extension 推奨） | ハイブリッドと同じ | 必ず実行 |
推奨パス
| ケース | 推奨モード組み合わせ |
|---|
| 新規アプリ + 軽量利用 | new + ハイブリッド |
| 既存リポジトリの機能拡張 | extension + 反復反映 |
ステップ概要
| Step | 内容 | モデル | 並列化 | 対象 |
|---|
| 0 | 準備（URL + ゴール + 転記先 + 実装モード取得） | 親（Opus） | — | 全モード |
| 0.5 | 既存コードベース調査 | サブ（Sonnet） | — | extension のみ |
| 1 | ページ一覧抽出 + キャンバスサイズ自動検出 | 親 + Figma MCP | — | 全モード |
| 2 | 各ページ構造抽出 | サブ（Sonnet） | ページ単位で並列 | 全モード |
| 3 | 各ページのアクション抽出（ソース列付） | サブ（Sonnet） | ページ単位で並列 | 全モード |
| 4 | ユースケース抽出 | 親（Opus） | — | 全モード |
| 5 | アクター抽出 + UC×Actor マトリクス | 親（Opus） | — | 全モード |
| 6 | 整合性レビュー + 横断サマリー追記 | 親（Opus） | — | 全モード |
| 7 | データモデル抽出（状態遷移 + 設計メモ） | 親（Opus） | — | 全モード |
| 8 | 各ページにモデル参照を追記 | サブ（Sonnet） | ページ単位で並列 | 全モード |
| 9 | データモデルレビュー | 親（Opus） | — | 全モード |
| 10 | コンポーネント抽出（共通化方針 + マッピング検証） | 親（Opus） | — | 全モード |
| 11 | 各ページにコンポーネント参照を追記 | サブ（Sonnet） | ページ単位で並列 | 全モード |
| 12 | コンポーネントレビュー | 親（Opus） | — | 全モード |
| 13 | 各ページに「関連する未解決事項」を追記 | サブ（Sonnet） | ページ単位で並列 | 全モード |
| 14 | レビュー反復反映（質問ループ → 全関連ドキュメント反映） | 親 + サブ | レビュー単位は直列／反映は並列 | 反復反映モード推奨 |
モデル割当の方針
| 用途 | モデル |
|---|
| Figma JSON → Markdown 整形（Step 2 / 3 / 8 / 11 / 0.5 / 14c） | Sonnet |
| 合成・抽象化（Step 4 / 5） | Opus |
| 設計判断（Step 7 / 10） | Opus |
| レビュー判定（Step 6 / 9 / 12） | Opus |
| 質問ループ設計（Step 14a / 14b） | Opus |
ステップ詳細
Step 0: 準備
- ユーザーから確認：
- Figma URL（無ければ依頼）
- プロジェクトのゴール（レビューで利用するため必須）
- 出力ディレクトリ（デフォルト
docs/）
- 転記先（Notion 等の場合、相対パスリンクは「{{ファイル名}}（別ページ）」表記に切替）
- 実装モード: 作業ディレクトリに既存リポジトリ（
Gemfile / package.json / app/ / src/）が存在するなら extension を提案。それ以外は new
- URL から
fileKey を抽出
docs/pages/ と docs/reviews/ を作成- 既存
docs/ の有無を確認し、上書きの可否を確認
- プロジェクトゴールを
docs/reviews/coverage-review.md の先頭に保存
extension モードなら Step 0.5 を実行
Step 0.5: 既存コードベース調査（extension モードのみ）
詳細は references/extension-mode-guide.md 参照。
Sonnet サブエージェント 1 つで既存リポジトリの主要資産を調査し、docs/existing-codebase.md に出力：
- 既存モデル一覧（Figma 関連度の 4 段階評価付き）
- 既存ルーティング（Figma 関連のみ）
- 既存ビュー資産
- 既存設定（Settings 等）
- 再利用候補のサマリー（Step 7 / 14 で参照される最重要セクション）
サブエージェント用プロンプトは references/sub-agent-prompts.md の Step 0.5 セクション参照。
Step 1: ページ一覧抽出
figma-use スキルをロードFigma:get_metadata または use_figma で全ページ／トップレベルフレームを列挙- 実装対象を判定（Slice や注釈帯は除外）
- キャンバスサイズ自動検出:
- 全実装対象ページの width を集計し、一意な値が 1 つしか無い場合 → 「単一幅設計（モバイル想定）」と判定し README の「未確認・要追加情報」に自動追記
- 一意な値が 2 つ以上ある場合 → レスポンシブ対応済みと判定
- プロトタイプ Reactions の有無検出:
- Reactions が 1 件も無い場合 → ワイヤーフレームレベルと判定
- 一部のみ設定 → 混在モード
- 各ページのスラッグを決定
docs/pages/README.md の骨組みを作成（横断サマリーは Step 6 で追記）
Step 2-3: 各ページ構造・アクション抽出（並列）
Sonnet サブエージェントをページ単位で並列起動。プロンプト詳細は references/sub-agent-prompts.md 参照。
- Step 2: 構成要素一覧表、テキスト要素、ページ役割概要（客観抽出可）
- Step 3: アクションボタン一覧（ソース列付、語彙制限あり）
Step 4: ユースケース抽出
docs/pages/ 全件を Read し、明示的に読み取れる UC を docs/use-cases.md に列挙。ハイブリッドモードではサマリ確認を挟む。
各 UC の必須フィールド: UC-XX / ユースケース名 / ユースケースカテゴリ / 目的 / シナリオ / 前提・後続 UC / データ更新の有無。
Step 5: アクター抽出 + UC×Actor マトリクス
docs/use-cases.md から登場アクターを集約し、docs/actors.md を生成。
- 各アクターの必須フィールド: A-XX / 名前 / 分類（プライマリ・セカンダリ・オフステージ）/ 役割 / ゴール / 典型ペインポイント / 主なオペレーション / UC 一覧
- UC×Actor マトリクス必須（行=UC、列=全アクター、関与は「●」）
- マトリクス直後に「読み取れる事実」を散文で追記
Step 6: 整合性レビュー + 横断サマリー追記
6a: 整合性レビュー（出力のみ）
docs/reviews/coverage-review.md に以下を列挙：
- ゴールから見て足りない UC / Actor
- UC から見て足りない Page / Action Button
6b: 横断サマリー追記（pages/README.md）
- 共通要素（Header / Footer / Menu Overlay）
- サイト全体のインタラクション分布
- エンティティ／データ設計上の示唆（Step 7 の入力）
- 未確認・要追加情報
Step 7: データモデル抽出
docs/pages/README.md の「エンティティ／データ設計上の示唆」セクションを Read（Step 7 の起点）docs/pages/ 全件を Read- extension モードの場合:
docs/existing-codebase.md の「既存モデル一覧」「再利用候補のサマリー」を Read
- 明示的に読み取れる Entity / Relation を分類
docs/data-model.md を生成（状態遷移セクションと設計メモ必須）- ハイブリッドモードでは Entity 一覧サマリ確認
過剰定義の回避
「Figma に対応ページ／表示要素が存在しない汎用 Entity」（StaticPage、User、Session 等）は本体に定義せず、レビュー側で提案するに留める。
extension モードでの設計優先順位
- 既存モデルそのまま再利用
- 既存モデルにカラム追加
- 既存カラムの用途流用（衝突有無を実コード grep で確認必須）
- 新規 Entity 作成
詳細は references/extension-mode-guide.md の「Step 7 拡張」セクション参照。
Step 8: 各ページにモデル参照を追記（並列）
Sonnet サブエージェントをページ単位で並列起動。詳細は references/sub-agent-prompts.md 参照。
親エージェントの責務
- 事前準備:
data-model.md から使用可能 Entity / カラム ID リストを抽出してサブのプロンプトに含める（リスト外の捏造を防ぐ）
- 事後検証:
grep "^## 参照モデル" docs/pages/*.md で全ページに 1 行ずつヒットすることを確認
集約ルール（冗長性削減）
- 同一カラムを参照する複数の表示要素は集約
- 静的文言は 1 行にまとめる
- セクションあたりの行数の目安は 8 行以内（可読性を担保するため）
Step 9: データモデルレビュー（出力のみ）
docs/reviews/data-model-review.md に以下を列挙（優先度ラベル「必須／推奨／オプション」必須）：
- ページに表示要素があるのに対応する Entity / カラムが無い
- Entity / カラムの過剰定義
- FK の整合性
- インデックスの過不足
Step 10: コンポーネント抽出
docs/pages/ 全件を Readextension モードの場合、既存 UI 資産（docs/existing-codebase.md の「既存ビュー資産」）を考慮- 表示要素を Atomic Design（Atoms / Molecules / Organisms / Templates）に分類
- 冒頭に「共通化方針サマリー」セクションを配置
- ページ→Organism マッピング検証表を必須化（未対応セルが 1 つでも残れば追加）
docs/components.md を生成
詳細は references/extension-mode-guide.md の「Step 10 拡張」セクション参照。
各コンポーネントの必須フィールド: CMP-XX / 名前 / 概要 / Atomic Design 種別 / パラメータ一覧 / イベントハンドラ一覧。
Step 11: 各ページにコンポーネント参照を追記（並列）
Step 8 と同じパターン。詳細は references/sub-agent-prompts.md 参照。
集約ルール
- 出力対象は Organism / Template / 主要 Molecule のみ（Atom は内包される設計のため省略）
- 同一コンポーネントの複数利用箇所は「利用箇所数」に集計
親エージェントの事後検証
grep "^## 利用コンポーネント" docs/pages/*.md
ページで使われている CMP-XX が components.md に実在するかも検証する。
Step 12: コンポーネントレビュー（出力のみ）
docs/reviews/components-review.md に以下を列挙（優先度ラベル必須）：
- ページに表示要素があるのに対応するコンポーネントが無い → 通常「必須」
- コンポーネントが定義されているが使われていない → 通常「オプション」
- 類似コンポーネントの共通化候補 → 通常「推奨」
- パラメータ・イベントハンドラの過不足 → 内容により分類
Step 13: 各ページに「関連する未解決事項」を追記（並列）
3 つのレビューを Read し、自ページに関連する不足項目を逆引きで抽出。
抽出ルール:
- coverage-review の「足りない Page / Action」で自ページ言及あり
- data-model-review の「ページにあるがモデルに無い」で自ページ slug
- components-review の「ページにあるがコンポーネント未定義」で自ページ slug
該当なしの場合は「該当なし」と記載。
Step 14: レビュー反復反映
詳細は references/step-14-review-iteration.md 参照。
進行チェックリスト（コピーして使用）
Step 14 進行:
- [ ] データモデルレビュー: 質問ループ完了
- [ ] データモデルレビュー: data-model.md 反映完了
- [ ] データモデルレビュー: pages/ 並列反映完了
- [ ] データモデルレビュー: サマリー再集計完了
- [ ] 整合性レビュー: 質問ループ完了
- [ ] 整合性レビュー: coverage-review.md 反映完了
- [ ] 整合性レビュー: pages/actors/use-cases 並列反映完了
- [ ] 整合性レビュー: サマリー再集計完了
- [ ] コンポーネントレビュー: 質問ループ完了
- [ ] コンポーネントレビュー: components.md 反映完了
- [ ] コンポーネントレビュー: pages/ 並列反映完了
- [ ] コンポーネントレビュー: サマリー再集計完了
- [ ] 最終サマリーをユーザーに提示
質問ループの要点
- データモデル → 整合性 → コンポーネント の順で処理
- 1 ラウンドで 4 件以内（
AskUserQuestion ツールの質問数上限のため）
- 関連項目は 1 質問に集約（例: ON DELETE 挙動 6 件を 1 質問に）
- Figma 未定義／デザイン待ち項目は質問せず「デザイン待ち」ラベル付与
並列起動の実装パターン
ステップ単位の並列起動は 1 メッセージ内で複数の Agent ツール呼び出しを並べる ことで実現：
const pages = ["top", "award-detail-open", ...];
const agents = pages.map(p => Agent({
description: `${p} 構造抽出`,
subagent_type: "general-purpose",
model: "sonnet",
prompt: extractStep2Prompt(p),
}));
Step 2 / 3 / 8 / 11 / 13 / 14c がページ単位またはレビュー単位で並列化されるステップ。Step 0.5 は extension モード時に Sonnet サブエージェント 1 つを単発で起動する（並列化対象ではない）。
ハイブリッド対話のチェックポイント
| タイミング | 確認内容 | スキップ条件 |
|---|
| Step 0 | URL / ゴール / 転記先 / 出力先 / 実装モード | すべて提示済み |
| Step 0.5 後 | 既存コードベース調査結果 | new モード時 |
| Step 1 後 | 抽出ページ一覧 + キャンバスサイズ検出結果 | 全自動モード時 |
| Step 4 後 | UC 一覧サマリ（任意） | 全自動モード時 |
| Step 7 後 | データモデル Entity 一覧サマリ（任意） | 全自動モード時 |
| Step 6 / 9 / 12 後 | 各レビュー結果（優先度ラベル付） | スキップ不可 |
| Step 13 後 | 各ページの「関連する未解決事項」追記確認 | 全自動モード時 |
| Step 14 中 | レビュー反復反映の質問ループ | ユーザーが Step 14 を希望しない場合 |
| Step 14 後 | 反映後の最終サマリー | スキップ不可（Step 14 実行時） |
エラー時の挙動
- Figma MCP 未認証 →
/mcp での認証を促す
- ノードID エラー → URL の fileKey 部分を確認、ユーザーに再提示を依頼
- サブエージェント失敗 → 親が直接リトライ（Sonnet → Opus フォールバック）
- 出力ファイルが既存 → 上書き／追記／中止をユーザーに確認
- 「Figma 未記載」項目が多い → そのまま「未記載」表記で進める（レビューステップで列挙）
仕上げ
全 15 ステップ（Step 0 〜 14。extension モードでは Step 0.5 を含み、Step 14 は希望時のみ）完了後、最終検証を必須化：
最終検証チェックリスト
for f in docs/pages/*.md; do
if [ "$(basename $f)" != "README.md" ]; then
echo "=== $f ==="
grep "^## " "$f"
fi
done
期待される 6 セクション（順序固定）:
## 構成要素## テキスト要素一覧## アクションボタン## 参照モデル## 利用コンポーネント## 関連する未解決事項
Entity / CMP の整合性検証
grep -ho "E-[0-9]\+" docs/pages/*.md | sort -u > /tmp/used_entities.txt
grep -ho "E-[0-9]\+" docs/data-model.md | sort -u > /tmp/defined_entities.txt
diff /tmp/used_entities.txt /tmp/defined_entities.txt
ページで使われている ID がマスタに無ければサブエージェントが番号を捏造した可能性が高い。該当ページを再実行。
Step 14 実行時の追加検証
for f in docs/reviews/*.md; do
echo "=== $f ==="
grep -c "解消済み" "$f"
done
grep -rn "{{取り下げた ID パターン}}" docs/pages/ docs/actors.md docs/use-cases.md | \
grep -v "取り下げ\|統合\|解消済み\|旧\|~~"
完了報告
- 生成ファイル一覧と各ファイルの行数（extension モード時は
docs/existing-codebase.md も含む）
- 3 つのレビューレポートのサマリ（不足検出数 + 優先度別件数）
- Step 14 実行時: 仕様確認反復プロセスの解消件数と、残存項目の性質（Figma デザイン待ち／将来要件）
- ユーザーが手動で対応すべき必須項目
- 最終検証結果（セクション完備、ID 整合性 OK）
関連スキル・参照ファイル
スキル
figma-use — use_figma MCP ツールを呼ぶ前にロード必須（公式 Figma プラグインに含まれる）
references/ ディレクトリ
