miro-code-spec

Miro の仕様を抽出する

Miro ボードまたはアイテムから仕様の内容を抽出し、.miro/specs/ に保存します。計画や実装の際に、API を繰り返し呼び出すことなく参照できます。

ユーザーが指定する URL は 1 つです。ボード URL の場合はすべての仕様アイテムを抽出し、moveToWidget / focusWidget パラメーターを含むアイテム URL の場合は、そのアイテムのみを抽出します。Miro MCP が利用可能である必要があります。

ワークフロー

1. ユーザーの依頼から URL を特定する

• ユーザーが Miro URL を指定した場合は、それを使用します。
• 指定していない場合は、ユーザーに URL を尋ねます。

2. URL の範囲を判断する

ユーザーが指定した URL がボード URL（ボード上のすべての仕様アイテムを抽出）か、単一アイテムの URL（1 つのアイテムを指定する moveToWidget または focusWidget クエリパラメーターを含むボード URL）かを判断します。URL はそのまま Miro MCP に渡します。URL の処理は MCP が行います。

3. 出力ディレクトリを確認／準備する

• .miro/specs/ が存在し、内容があるかどうかを確認します。
• 内容がある場合は、ユーザーに次のように尋ねます。
  • 「.miro/specs/ ディレクトリにはすでにファイルがあります。どうしますか？」
  • 選択肢：
    • 「既存の内容を削除して新たに抽出」— 既存の内容を削除する
    • 「既存の内容に追加」— 既存のファイルを保持する
    • 「キャンセル」— 操作を中止する
• 必要に応じてディレクトリ構造を作成します。

  .miro/specs/
  ├── documents/      # Markdown documents
  ├── diagrams/       # Diagram descriptions
  ├── prototypes/     # Containers (Markdown) and screens (HTML)
  ├── tables/         # Table JSON data
  ├── frames/         # Frame summaries
  ├── other/          # Unknown types (slides, etc.)
  └── images/         # Extracted images
  

4. 抽出するアイテムを特定する

ボード URL の場合：

• ボード URL を使って、Miro MCP のボード概要ツールを使用します。
• 返される各アイテムには、タイプ、URL（moveToWidget パラメーター付き）、タイトルが含まれます。
• 抽出対象として、すべてのアイテムのタイプ、URL、タイトルを収集します。

アイテム URL の場合：

• 単一アイテムの URL リストを作成します。

5. 抽出タスクを作成する（必須）

🚨 このステップは必須です。省略しないでください

見落としを防ぐため、特定したすべてのアイテムについて、内部チェックリスト項目を作成します。

タスクの構成：

• 件名： 「Extract [type]: [title]」（ボード概要ツールからタイトルを取得できる場合はタイトルを使用し、取得できない場合は ID を使用）
• 説明： アイテムのタイプ、ID、URL、対象ファイルパスを含めます
• activeForm： 「Extracting [type]: [title]」（タイトルを取得できる場合はタイトルを使用し、取得できない場合は ID を使用）

タイトルがある場合の例：

Subject: "Extract document: Product Requirements"
Description: "Extract document item 3458764612345 from board. Save to .miro/specs/documents/3458764612345.md"
activeForm: "Extracting document: Product Requirements"

タイトルがない場合の例：

Subject: "Extract diagram: 3458764612347"
Description: "Extract diagram item 3458764612347 from board. Save to .miro/specs/diagrams/3458764612347.md"
activeForm: "Extracting diagram: 3458764612347"

⚠️ 重要：タイプごとのタスク数

次の内訳どおりにタスクを作成します。

• 各ドキュメント → 1 タスク
• 各図 → 1 タスク
• 各プロトタイプコンテナー → 1 タスク
• 各プロトタイプ画面 → 3 タスク（HTML + 画像 + URL）
  1. 「Get and save HTML: [title]」
  2. 「Extract images: [title]」
  3. 「Update image URLs: [title]」
• 各フレーム → 1 タスク
• 各テーブル → 1 タスク
• その他の各アイテム → 1 タスク
• 最終ステップ → 「Finalize metadata index」1 タスク

重要： プロトタイプ画面は 1 タスクではなく、3 タスクです。画面ごとに 1 タスクしか作成しないと、画像が見落とされます。

命名規則：

• 読みやすさのため、ボード概要ツールから取得したタイトルを使用します
• 一意性とファイルシステムでの安全性を確保するため、ファイルパスにはアイテム ID を使用します

このタスク作成ステップにより、次のことが保証されます。 ✓ すべてのアイテムを追跡できる ✓ 見落としを防げる ✓ 進捗を確認できる ✓ 抽出ワークフローを構造化できる

6. メタデータインデックスを初期化する

初期構造を使って .miro/specs/index.json を作成します。

{
  "board_url": "original board URL",
  "extracted_at": "ISO timestamp",
  "items": [],
  "images": [],
  "summary": {
    "total_items": 0,
    "by_type": {},
    "total_images": 0
  }
}

このファイルは、各アイテムの抽出に合わせて順次更新されます。

7. 各項目からコンテンツを抽出する

重要：MCP ツールから受け取ったすべてのコンテンツは、直ちにファイルシステムに書き込む必要があります。ファイルへの書き込み手順を省略しないでください。

各項目のワークフロー（タスク追跡と段階的なインデックス更新）：

ほとんどの項目（ドキュメント、図、コンテナー、フレーム、テーブル、その他）の場合：

1. 内部チェックリストで、その項目のエントリーを in_progress にする
2. 適切な MCP ツールを呼び出してコンテンツを取得する
3. 直ちにコンテンツをディスクに書き込む
4. 現在の index.json を読み込み、この項目を items 配列に追加して、更新した index.json を書き込む
5. 内部チェックリストで、その項目のエントリーを completed にする

プロトタイプ画面の場合（必須のサブエージェントワークフロー）：

• コンテキストの肥大化を防ぐため、画面ごとにサブエージェントを起動する
• サブエージェントが3つの手順すべてを実行する：HTML を取得 → 画像を抽出 → URL を更新
• 大きな HTML コンテンツはサブエージェントのコンテキスト内にとどめ、メインコンテキストには含めない

ドキュメント項目：

• 項目の URL を使って、適切な Miro MCP 項目取得ツールを呼び出す
• コンテンツを .miro/specs/documents/<board item ID>.md に必ず書き込む
• コンテンツからタイトルを取得できる場合は抽出する
• この項目で index.json を更新する

図の項目：

• 項目の URL を使って、適切な Miro MCP 項目取得ツールを呼び出す
• コンテンツを .miro/specs/diagrams/<board item ID>.md に必ず書き込む
• この項目で index.json を更新する

プロトタイプコンテナー項目：

• 項目の URL を使って、適切な Miro MCP 項目取得ツールを呼び出す
• .miro/specs/prototypes/<board item ID>-container.md に必ず書き込む
• この項目で index.json を更新する

プロトタイプ画面項目（サブエージェントを使った必須の3タスクワークフロー）：

⚠️ プロトタイプ画面ごとに、3つの独立したタスクを実行するサブエージェントが必要です

サブエージェントを使う理由： Miro MCP コンテキストツールは、プロトタイプ画面の大きな HTML を返すため、メインエージェントのコンテキストが肥大化します。サブエージェント内に処理をとどめれば、大きな HTML がメインの会話に入ることはありません。

プロトタイプ画面ごとに、3つの手順を順番にすべて実行する単一のサブエージェント（subagent_type: "general-purpose"）を起動します。必要なコンテキストをすべてサブエージェントに渡してください。

サブエージェントプロンプトのテンプレート：

Extract prototype screen and its images from Miro board.

Context:
- Miro board URL targeting the prototype screen: [url]

Execute these 3 tasks in order:

Task 1: Get and save HTML
- Call the appropriate Miro MCP item-retrieval tool with the item URL
- Save the returned raw HTML to .miro/specs/prototypes/<board item ID>-screen.html
- Read index.json, add this item to items array, Write updated index.json

Task 2: Extract images
- Read the saved HTML file
- Parse HTML for ALL image URLs in `src` attributes
- For EACH image URL found:
  1. Extract resource ID from URL path
  2. Call the appropriate Miro MCP image tool to obtain a download URL for the image
  3. Take the download URL from response
  4. Download: `curl -sL -o .miro/specs/images/<image resource ID>.png "[download_url]"`
  5. Read index.json, add image entry to images array, Write updated index.json:
     {"id": "<image resource ID>", "path": "images/<image resource ID>.png", "referenced_by": ["prototypes/<board item ID>-screen.html"]}
- If any download fails: log warning, continue with others

Task 3: Update image URLs in HTML
- Read the HTML file from .miro/specs/prototypes/<board item ID>-screen.html
- Replace ALL original image URLs with relative paths: src="../images/<image resource ID>.png"
- Save the updated HTML
- Verify all image src attributes now point to ../images/

Report back: number of images found, downloaded, and any failures.

各画面に対するメインエージェントのワークフロー：

1. 内部チェックリストで「HTML を取得して保存：[title]」を in_progress にする
2. 上記のプロンプトでサブエージェントを起動する
3. サブエージェントの完了後、その画面の3つのタスクすべてを completed にする
4. 次の画面に進む

⚠️ プロトタイプ画面に関する重要な要件：

• ✗ メインエージェントから画面用の Miro MCP コンテキストツールを呼び出さないでください（コンテキストの肥大化を防ぐため）
• ✓ プロトタイプ画面ごとに必ずサブエージェントを使用する
• ✓ プロトタイプ画面ごとに3つのタスクを作成する（可視化のため）
• ✓ サブエージェントが3つのタスクすべてを完了する：HTML → 画像 → URL
• ✓ Miro MCP 画像ツールを使ってダウンロード URL を取得し、curl でダウンロードする
• ✓ 次に進む前に、すべての画像 URL をローカルパスに置き換える

フレーム項目：

• 項目の URL を使って、適切な Miro MCP 項目取得ツールを呼び出す
• コンテンツを .miro/specs/frames/<board item ID>.md に必ず書き込む
• この項目で index.json を更新する

テーブル項目：

• テーブル項目に適した Miro MCP テーブル取得ツールを呼び出す
• JSON コンテンツを .miro/specs/tables/<board item ID>.json に必ず書き込む
• JSON に列定義とすべての行データを含める
• この項目で index.json を更新する

不明／その他の項目タイプ（例：スライド、または新しいタイプ）：

• 項目の URL を使って、適切な Miro MCP 項目取得ツールを呼び出す
• コンテンツを .miro/specs/other/<board item ID>.md に必ず書き込む
• 参照用に、メタデータ内で元のタイプ名を保持する
• この項目で index.json を更新する

8. メタデータインデックスを確定する

現在の index.json を読み込み、概要セクションを計算します：

• items 配列から total_items を数える
• by_type を数える（type フィールドごとに項目をグループ化する）
• images 配列から total_images を数える

計算した概要で index.json を更新します：

{
  "summary": {
    "total_items": 8,
    "by_type": {
      "document": 2,
      "diagram": 2,
      "prototype": 2,
      "table": 1,
      "frame": 1
    },
    "total_images": 3
  }
}

更新した index.json を必ず書き込んでください。

9. 検証して概要を表示する

検証チェックリスト（必ず実施）：

• .miro/specs/ ディレクトリに実際に書き込まれたファイル数を数える
• ファイル数が処理した項目数と一致することを確認する
• 一致しない場合、不足している項目を特定して保存する
• プロトタイプ画面：すべての画像 URL がローカルパスに置き換えられていることを確認する
• すべてのタスクが完了としてマークされていることを確認する
• .miro/specs/images/ 内の画像数が index.json の total_images と一致することを確認する

ユーザーに表示する内容：

• 抽出した項目の合計数（種類別）
• ディスクに書き込んだファイルの合計数
• ダウンロードして埋め込んだ画像の合計数
• 出力ディレクトリのパス
• 次のステップ：「これらの仕様を計画と実装に使用してください」

検証に失敗した場合は、成功を報告しないでください：

• プロトタイプ画面の HTML に元の画像 URL が残っている場合 → 画像はローカルで表示されません
• タスク数が項目数と一致しない場合 → スキップされた項目があります
• 完了前に不足している項目を再抽出してください

よくある間違いとその回避方法

🚨 抽出が失敗する、または不完全になる最も一般的な原因は次のとおりです：

1. タスクを作成しない

   • ✗ 誤り：タスクを作成せずにすべての項目を抽出する
   • ✓ 正しい方法：抽出前に、すべての項目について内部チェックリスト項目を作成する
   • 結果：項目がスキップされ、進捗を把握できなくなります

2. プロトタイプ画面を 1 つのタスクとして扱う

   • ✗ 誤り：プロトタイプ画面に 1 つのタスクを作成する
   • ✓ 正しい方法：3 つのタスク（HTML、画像、URL）を作成し、サブエージェントを使用する
   • 結果：画像が抽出されません

3. メインエージェントから画面用の MCP コンテキストツールを呼び出す

   • ✗ 誤り：プロトタイプ画面に対して、メインエージェントから Miro MCP コンテキストツールを直接呼び出す（HTML が大きく、コンテキストを圧迫します）
   • ✓ 正しい方法：画面ごとにサブエージェントを起動する — HTML はサブエージェントのコンテキスト内に保持されます
   • 結果：メインエージェントのコンテキストがあふれ、抽出に失敗します

4. 画像を探すために HTML を解析しない

   • ✗ 誤り：HTML の解析を省略し、画像は存在しないと決めつける
   • ✓ 正しい方法：HTML 内のすべての画像 src 属性を検索する
   • 結果：画像が見つからず、ダウンロードされません

5. HTML 内の画像 URL を更新しない

   • ✗ 誤り：画像をダウンロードしても、元の URL を HTML に残す
   • ✓ 正しい方法：元の URL をすべて ../images/[id].png に置き換える
   • 結果：HTML はローカルファイルではなく、リモート URL を参照したままになります

6. 画像のメタデータを追跡しない

   • ✗ 誤り：画像をダウンロードしても、index.json を更新しない
   • ✓ 正しい方法：画像エントリを index.json の images 配列に追加する
   • 結果：どの画像がどの画面に属するのか追跡できなくなります

7. 完了を検証しない

   • ✗ 誤り：ファイルを確認せずに抽出を終了する
   • ✓ 正しい方法：すべてのタスクが完了し、すべての画像がダウンロードされ、すべての URL が置き換えられていることを確認する
   • 結果：不完全な抽出に気づくのが遅くなります

エラー処理

• Miro MCP が利用できない場合 → インストールが必要であることをユーザーに伝える
• URL が無効な場合 → 有効な Miro URL の提示をユーザーに求める
• ボードまたは項目が見つからない場合 → エラーを表示し、有効な URL の提示をユーザーに求める
• 項目のコンテキスト取得に失敗した場合 → 警告を記録し、ほかの項目の処理を続ける
• 画像のダウンロードに失敗した場合 → 警告を記録し、相対パスで HTML を更新する（失敗したことを確認できるようにする）

実装に関する注意事項

ファイルの書き込み：

• 重要： MCP から取得したすべての項目を必ずディスクに書き込んでください
• 手順：MCP を呼び出す → コンテンツを取得する → ファイルに書き込む → 保存を確認する
• ファイルへの書き込みを省略しないでください。メモリ内だけにあるコンテンツは失われます
• すべてのファイル形式を書き込んでください：.md、.html、.json、.png

ディレクトリ操作：

• ディレクトリ操作には Bash を使用してください（mkdir、クリーンアップ時の rm）
• ファイルを書き込む前にディレクトリを作成してください

出力：

• 進行状況を示しながら、コンソール出力は簡潔にしてください
• 抽出・保存する内容をリアルタイムで表示してください

プロトタイプ画面：

• ⚠️ コンテキストの肥大化を避けるため、プロトタイプ画面には必ずサブエージェントを使用してください
• サブエージェントは3つのタスクをすべて実行します：HTML の取得 → 画像の抽出 → URL の更新
• Miro MCP の画像ツールを使用してダウンロード URL を取得し、curl で画像をディスクに保存してください
• 特定の画像のダウンロードに失敗した場合は、警告を記録し、ほかの画像の処理を続けてください

優先順位：

• ドキュメント、プロトタイプ、テーブルを優先してください（仕様にとって最も価値があります）
• 画像は省略できません。プロトタイプ画面がある場合、画像の抽出は必須です

背景

miro-spec とは？

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

次のような場合に使用してください：

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

コンテンツの種類

種類	保存形式	内容
ドキュメント	.md	書式を含む Markdown コンテンツ。見出しと構造は保持されます
図	.md	AI が生成した説明。フローの分析とコンポーネント間の関係
プロトタイプコンテナ	.md（接尾辞 -container）	ナビゲーションマップを含む Markdown
プロトタイプ画面	.html（接尾辞 -screen）	UI レイアウトを含む HTML マークアップ
テーブル	.json	列定義とすべての行データを含む構造化データ
フレーム	.md	フレームの内容に関する AI 生成の要約
画像	.png	プロトタイプから自動抽出されます。Miro の項目 ID をファイル名として使用します

ボード URL と項目 URL

ボード URL — 仕様全体を抽出します。関連するすべてのドキュメントや図を含む、包括的な仕様抽出に最適です。ボード上のすべての項目を一覧表示し、仕様関連の種類に絞り込んで、それぞれを個別に抽出します。

項目 URL — 単一のドキュメント、図、またはプロトタイプ画面を抽出します。対象を絞った抽出や、1つの項目の更新に最適です。単一項目の場合はより高速で、moveToWidget パラメーターを使用します。

画像の抽出方法

1. プラグインがプロトタイプ画面の HTML コンテンツをスキャンします
2. src 属性内の Miro 画像 URL を見つけます
3. URL を使用して、Miro MCP 経由で各画像を検索します
4. Miro MCP 経由で各画像をダウンロードします
5. 元の URL を相対パスに置き換えます

元の HTML：

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

抽出後：

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

メリット：画像をオフラインで表示でき、ドキュメントを閲覧するための API 呼び出しが不要になり、ローカルでの読み込みが速くなります。また、抽出したフォルダーをバージョン管理にコミットできます。

実装計画における仕様の活用

仕様を抽出したら、ユーザーは AI アシスタントに、それらを踏まえた計画や実装を依頼できます。プロンプトの例：

• 「.miro/specs/documents/ の製品要件を確認し、技術的な実装計画を作成してください」
• 「.miro/specs/diagrams/3458764612345.md のアーキテクチャ図を参照し、データベーススキーマを実装してください」
• 「実装した認証フローを、.miro/specs/prototypes/3458764612346-screen.html の仕様と比較してください」

AI アシスタントは計画時に関連ファイルを自動的に読み込みます。抽出された内容を確認するため、まず .miro/specs/index.json を確認してください。

ベストプラクティス

抽出戦略：

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

ディレクトリの管理：

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

仕様の操作：

• 利用可能な内容を把握するため、必ず最初に index.json を確認します
• プロトタイプの全内容を確認するには、HTML ファイルを直接読みます
• 図の概要を手早く確認するには、Markdown ファイルを使用します
• 構造化された表データを扱うには、JSON ファイルを解析します

パフォーマンスのヒント：

• ボードが大きい場合は、アイテムの URL を使用して特定のフレームから抽出します
• 混乱を避けるため、古い抽出内容をクリーンアップします
• ボードの URL は必要な場合にのみ使用します（大きなボードでは時間がかかることがあります）
• 実装セッションの間は抽出内容をキャッシュします

トラブルシューティング

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

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

画像をダウンロードできない：

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

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

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

大きなボードの処理に時間がかかる：

• アイテムの URL を使用して特定のコンテンツを抽出します
• ボード全体ではなく、個別のフレームを抽出します
• コンテンツの種類で絞り込むことを検討します

関連項目

• 仕様の保存形式 — ファイル形式の詳細なドキュメント
• プラグインの README — インストールとセットアップの手順