miro-spec-guide

Miro 仕様抽出ガイド

miro-spec とは？

miro-spec プラグインは、Miro ボードから仕様の内容を抽出し、ローカルファイルに保存します。これにより、API を繰り返し呼び出すことなく、計画や実装の際に AI が仕様を参照できます。

miro-spec を使うタイミング

次のような場合に miro-spec を使用します。

• Miro ボードから製品要件を抽出する
• 実装用の設計仕様を保存する
• 参照用にプロトタイプや図をダウンロードする
• Miro のドキュメントのローカルコピーを作成する
• オフラインまたはバージョン管理下で仕様を扱う

コマンド：/miro-spec:get

Miro ボードまたはアイテムから仕様を抽出します。

/miro-spec:get [url]

URL の種類

ボード URL — 仕様に関連するすべてのアイテムを抽出します。

https://miro.com/app/board/uXjVK123abc=/

アイテム URL — 単一のアイテムを抽出します。

https://miro.com/app/board/uXjVK123abc=/?moveToWidget=3458764612345

.miro/specs/ ディレクトリについて

ディレクトリ構造

.miro/specs/
├── documents/      # Miro documents (Markdown format)
├── diagrams/       # Diagram descriptions (Markdown)
├── prototypes/     # Prototype containers (Markdown) and screens (HTML)
├── tables/         # Table data (JSON)
├── frames/         # Frame summaries (Markdown)
├── other/          # Unknown types like slides (Markdown)
├── images/         # Downloaded images (PNG)
└── index.json      # Metadata index

コンテンツの種類

ドキュメント（.md）

• 書式付きの Markdown コンテンツ
• 見出しと構造を保持
• 整形されたテキスト形式

図（.md）

• AI が生成した図の説明
• フロー分析とコンポーネント間の関係
• 主要な要素と接続

プロトタイプ（.md / .html）

• コンテナー：ナビゲーションマップを含む Markdown（.md、サフィックス -container）
• 画面：UI レイアウトを含む HTML マークアップ（.html、サフィックス -screen）
• UI コンポーネントの構造

テーブル（.json）

• 列の定義を含む構造化データ
• すべての行とセルの値
• 列の型とメタデータ

フレーム（.md）

• AI が生成したフレームの内容の要約
• 含まれるアイテムの概要
• 構成

画像（.png）

• プロトタイプから自動的に抽出
• プロトタイプ画面内で相対パスを使って参照
• Miro アイテム ID に基づいて命名

抽出ワークフロー

1. 抽出コマンドを実行する

/miro-spec:get https://miro.com/app/board/uXjVK-spec=/

2. 既存のコンテンツを処理する

.miro/specs/ にすでにファイルがある場合は、次から選択します。

• クリーンアップして新たに抽出 — 最初からやり直します
• 既存の内容に追加 — 現在のファイルを保持します
• キャンセル — 中止します

3. 抽出の概要を確認する

出力には次の内容が表示されます。

Extracted 5 documents, 3 diagrams, 2 prototypes, 1 table
Downloaded 12 images
Saved to .miro/specs/

4. メタデータインデックスを確認する

.miro/specs/index.json を開くと、次の内容を確認できます。

• 抽出したすべてのアイテムとその種類
• 各アイテムのファイルパス
• 元の Miro URL
• 抽出日時

ボード URL とアイテム URL

ボード URL

使用するタイミング：

• 仕様全体を抽出する
• 関連するすべてのドキュメントや図を取得する
• 仕様を包括的に抽出する

実行内容：

• ボード上のすべてのアイテムを一覧表示する
• 仕様に関連する種類に絞り込む
• 各アイテムを個別に抽出する

例：

/miro-spec:get https://miro.com/app/board/uXjVK123abc=/

アイテム URL

使用するタイミング：

• 単一のドキュメントや図を抽出する
• 特定のプロトタイプ画面を取得する
• 対象を絞って抽出する

実行内容：

• 指定したアイテムのみを抽出する
• 単一アイテムの場合により高速
• moveToWidget パラメーターを使用する

例：

/miro-spec:get https://miro.com/app/board/uXjVK123abc=/?moveToWidget=3458764612345

画像の抽出方法

画像の自動検出

1. プラグインがプロトタイプ画面の HTML コンテンツをスキャンします
2. src 属性内の Miro 画像 URL を見つけます
3. URL から board_id と item_id を抽出します
4. Miro MCP を使って各画像をダウンロードします

URL の置き換え

元の HTML：

<img src="https://miro.com/api/v2/boards/uXjVK123abc=/images/3458764612345"/>

抽出後：

<img src="../images/3458764612345.png"/>

メリット

• 画像をオフラインで表示できます
• ドキュメントの表示に API 呼び出しが不要です
• ローカルファイルから素早く読み込めます
• バージョン管理にコミットできます

実装計画で仕様を使用する

ワークフローの例

1. 仕様を抽出する：

   /miro-spec:get https://miro.com/app/board/uXjVK-product-spec=/
   

2. 抽出内容を確認する： .miro/specs/index.json を確認し、利用可能な仕様を確認します

3. AI に実装計画を依頼する： 「.miro/specs/ 内の仕様に基づいて、ユーザー認証機能の実装計画を作成してください」

4. AI が関連ファイルを読み込む： AI は計画の際、ドキュメント、図、テーブルを自動的に読み込みます

5. コンテキストを活用して実装する： AI は仕様の内容を使ってコード生成を導きます

AI プロンプトの例

仕様に基づいた計画：

"Review the product requirements in .miro/specs/documents/ and create a technical implementation plan"

特定の図を使用する：

"Reference the architecture diagram in .miro/specs/diagrams/3458764612345.md and implement the database schema"

実装を検証する：

"Compare the authentication flow I implemented against the spec in .miro/specs/prototypes/3458764612346.html"

ベストプラクティス

抽出戦略

• 初回に包括的な抽出を行うにはボード URL を使用します
• 特定のドキュメントを更新するにはアイテム URL を使用します
• 実装を開始する前に抽出します
• 仕様が変更されたら再抽出します

ディレクトリ管理

• 仕様が一時的なものであれば、.miro/specs/ を .gitignore に保持します
• 仕様を共有する場合は、バージョン管理にコミットします
• ボードの構造が大幅に変更された場合は、クリーンな状態で抽出します
• 個々のアイテムを更新する場合は、既存のものに追加します

仕様の操作

• 何が利用可能かを把握するため、まず index.json を必ず確認します
• ドキュメントの内容全体を確認するには、HTML ファイルを直接読み取ります
• 図の概要を素早く確認するには、Markdown ファイルを使用します
• 構造化されたテーブルデータを解析するには、JSON ファイルを使用します

パフォーマンスのヒント

• ボードが大きい場合は、アイテム URL を使用して特定のフレームから抽出します
• 混乱を避けるため、古い抽出結果を削除します
• ボード URL の使用は控えめにします（大きなボードでは時間がかかる場合があります）
• 実装セッションの間は抽出結果をキャッシュします

よくあるワークフロー

製品要件を抽出する

# Extract all PRD documents
/miro-spec:get https://miro.com/app/board/uXjVK-prd=/

# Review extracted docs
cat .miro/specs/index.json | grep documents

# Plan implementation
"Plan implementation based on requirements in .miro/specs/"

単一の仕様を更新する

# Extract updated design doc
/miro-spec:get https://miro.com/app/board/uXjVK=/.../?moveToWidget=3458764612345

# Choose "Add to existing" when prompted
# Review changes in .miro/specs/documents/3458764612345.html

アーキテクチャ図を抽出する

# Extract board with diagrams
/miro-spec:get https://miro.com/app/board/uXjVK-architecture=/

# Check diagram summaries
ls .miro/specs/diagrams/
cat .miro/specs/diagrams/*.md

トラブルシューティング

ボードからアイテムが抽出されない場合：

• ボードにドキュメント、フレーム、テーブルのアイテムが含まれていない可能性があります
• 特定のコンテンツにはアイテム URL を使用してみてください
• ボード URL が正しいか確認してください

画像がダウンロードされない場合：

• MCP 経由ではアクセスできない画像もあります
• ダウンロードに失敗した場合、元の URL は保持されます
• 外部画像 URL を使用しても、ドキュメントは引き続き読み取れます

抽出後にファイルが見つからない場合：

• 実際のパスは .miro/specs/index.json で確認してください
• 抽出が正常に完了したことを確認してください
• 抽出結果にエラーメッセージがないか確認してください

大きなボードの処理に時間がかかりすぎる場合：

• アイテム URL を使用して特定のコンテンツを抽出します
• ボード全体ではなく、個々のフレームを抽出します
• コンテンツタイプによるフィルタリングを検討してください

関連項目

• 仕様の保存形式 - ファイル形式の詳細なドキュメント
• Miro MCP ツール - Miro MCP の機能について
• プラグインの README - インストールとセットアップの手順