miro-code-review

ビジュアルコードレビュー

プルリクエスト／マージリクエスト、ローカルの変更、またはブランチ比較をもとに、Miro ボード上に包括的なビジュアルコードレビューを生成します。アーキテクチャ分析とセキュリティレビューを含み、必要に応じてエンタープライズ向けドキュメントで内容を補強します。成果物の作成後、レビュー担当者が利用中のコードホスティングサービスを離れずに確認できるよう、PR/MR の説明から成果物にリンクします。

ユーザーは、Miro ボードの URL と、次のいずれかのソースを指定します。PR/MR 番号、owner/repo#number（または group/project!number）、PR/MR の完全な URL、「local changes」というキーワード、またはデフォルトブランチと比較するブランチ名です。このスキルはプラットフォームに依存せず、URL または設定済みの git リモートからコードホスティングサービスを判別し、ローカルで利用可能な CLI を使用します。

ワークフロー

1. ユーザーのリクエストからソースを特定する

ソースの種類を判別し、URL または設定済みの git リモートからプラットフォームを推定します。

• 数字のみ → 現在のリポジトリの PR/MR（設定済みの git リモートからプラットフォームを推定します。git remote get-url origin）
• owner/repo#number（GitLab 形式の場合は group/project!number）→ ホストが指定されていない限り、現在のリモートと同じプラットフォーム上の外部リポジトリの PR/MR
• 完全な URL → URL からホスト、所有者／グループ、リポジトリ／プロジェクト、PR/MR 番号を抽出します。ホストからプラットフォームを判別します。
• 「local changes」／未コミットの作業 → PR なしのローカル差分のみ
• ブランチ名 → デフォルトブランチ（main またはリモートが示すデフォルトブランチ）とのローカル差分

ツールの選択

インストール済みの CLI とソースに応じて CLI を選びます。gh があると決めつけないでください。実行前に command -v <cli> を実行して、利用可能か確認します。

• GitHub の URL／github.com のリモート → 利用可能であれば gh CLI
• GitLab の URL／gitlab.com またはセルフホスト型 GitLab → 利用可能であれば glab CLI
• 検出したプラットフォームの公式 CLI が利用できない場合は、ユーザーがすでに設定している認証情報（例：~/.netrc、$GITHUB_TOKEN や $GITLAB_TOKEN などの環境変数トークン）を使い、認証済み REST を curl で呼び出します。
• ローカルまたはブランチ比較のソースでは、通常の git で十分です。プラットフォーム用 CLI は不要です。

続行する前に、検出したプラットフォームとツールをチャット出力で伝えます。

2. 変更を抽出する

プラットフォームにかかわらず、次の 2 つを取得します。

1. メタデータ：タイトル、説明／本文、作成者、ファイルごとの追加・削除数を含む変更ファイル一覧
2. 統合差分：変更の統合差分

§1 で検出したプラットフォームに対応する CLI を使用します。JSON／テキストの形式はコードホスティングサービスによって異なります。フィールドは後続の処理で正規化します。

GitHub の例（gh）：

# Current repo
gh pr view $PR_NUMBER --json title,body,author,files,additions,deletions
gh pr diff $PR_NUMBER

# External repo
gh pr view $PR_NUMBER --repo $OWNER/$REPO --json title,body,author,files,additions,deletions
gh pr diff $PR_NUMBER --repo $OWNER/$REPO

GitLab の例（glab）：

# Current project
glab mr view $MR_NUMBER -F json
glab mr diff $MR_NUMBER

# External project
glab mr view $MR_NUMBER -R $GROUP/$PROJECT -F json
glab mr diff $MR_NUMBER -R $GROUP/$PROJECT

REST による代替方法（すべてのプラットフォーム）： PR/MR とその差分の REST エンドポイントに、認証済みの curl リクエストを送信します。ユーザーが設定したトークン（$GITHUB_TOKEN、$GITLAB_TOKEN など）を使用し、差分には Accept: application/vnd.github.v3.diff（またはプラットフォームに相当する値）を指定します。

ローカルの変更の場合：

git status --porcelain
git diff HEAD

ブランチ比較の場合：

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git log $DEFAULT_BRANCH..HEAD --oneline
git diff $DEFAULT_BRANCH...HEAD

ソースリンクのベース URL を決定する

一度取得し、§5 のすべてのファイル参照（表のセル、ドキュメントの箇条書き、図のラベル）で再利用します。強制プッシュ後もリンクが有効であるように、ヘッド SHA を指定します。以下を記録します。

• LINK_HOST、LINK_OWNER/LINK_REPO（または LINK_GROUP/LINK_PROJECT）— §1 から取得
• LINK_SHA — PR/MR のヘッドコミット SHA（ローカルソースまたはブランチソースの場合は git rev-parse HEAD にフォールバック）
• LINK_BASE_SHA — ベースコミット SHA（PR/MR のターゲットブランチの先端、またはブランチ比較の場合は git merge-base）。§5 の「変更の表示」で必須です。到達できない場合は「変更前」の図を省略し、チャットで一度だけその旨を伝えます。
• LINK_TEMPLATE — {path} プレースホルダーと、任意の #L<start>-L<end> アンカーを含む、ホスト形式の blob URL。リモートのないソース（local changes またはリモート/PR のないブランチ）の場合は "" を設定し、パスをそのまま表示します。URL を作り出してはいけません。

成果物を作成する前に、選択したテンプレートをチャットで伝えてください。プラットフォームごとの SHA 取得コマンド、ホスティングサービス別の URL テンプレート、リモートなし／ベースに到達できない場合の処理については、references/source-links.md を参照してください。

3. 変更の分析

変更されたファイルごとに、次の項目を特定します。

基本分析：

• ステータス：追加、変更、または削除
• 変更の要約：変更内容とレビュー時の確認事項を組み合わせた簡潔な説明
• リスクレベル：以下のリスク評価を参照

アーキテクチャ分析：

• 新たに導入されたコンポーネントまたはモジュール
• 依存関係の変更（新しいインポート、パッケージの更新）
• インターフェース／API の変更
• パターンの変更（導入または違反されたデザインパターン）
• 利用側の更新が必要となる後方互換性のない変更

セキュリティ分析：

• 入力の検証とサニタイズ
• 認証／認可の変更
• 機密データの取り扱い（ログ記録、保存）
• インジェクションの脆弱性（SQL、XSS、コマンド）
• 暗号技術の使用
• 設定のセキュリティ

4. リスク評価

リスクレベル	基準
高	セキュリティ上重要な変更、認証／認可、データベースのマイグレーション、中核となるビジネスロジック、後方互換性のない API 変更、暗号技術
中	API の変更、設定、共有ユーティリティ、新しい依存関係、データモデルの変更
低	テスト、ドキュメント、スタイル、ローカライズ、内部リファクタリング

4.5 トリアージ：作成するもの（または作成しないもの）を決める

すべての成果物には、作成するだけの価値が必要です。作成作業を始める前に、その PR を視覚化する価値があるかどうか、またレビュー担当者に実際に役立つ成果物の種類を決めてください。

中止ルール。 以下の条件がすべて当てはまる場合、Miro の成果物は作成せず、チャットでのみ報告してください。

• 変更ファイル数が 2 以下、かつ
• 変更行数（追加と削除の合計）が 20 行未満、かつ
• §4 でリスクが High とマークされたファイルがない、かつ
• セキュリティ上重要なパス（認証、暗号、設定、マイグレーション）に変更がない。

この場合、スキルの出力全体は、次の形式のチャットメッセージ 1 件のみです。

PR は軽微です（N ファイル、±M 行、高リスク領域なし）。Miro による視覚化を省略します。ボードを作成してもレビューの価値は高まりません。PR/MR の説明は変更していません。

§5 と §6 は完全に省略してください。

価値基準（成果物ごと）。 中止ルールに該当しない場合も、差分を見るだけでは明らかでない情報をレビュー担当者に伝える成果物のみを作成してください。

• 表 — 変更ファイル数が 3 以上の場合、または複数のリスクレベルがある場合に作成します。中止ルールに該当しない 1～2 ファイルの PR では、表を省略してください。
• サマリードキュメント — PR のタイトルや本文にまだ記載されていない重要な意図がある場合、または注記が必要な高リスク項目が 2 件以上ある場合に作成します。PR の説明を言い換えるだけになる場合は省略してください。
• アーキテクチャドキュメント — 構造上の変更（新しいモジュール、公開インターフェースの変更、依存関係の変更、破壊的変更）が検出された場合にのみ作成します。それ以外は省略してください。
• セキュリティドキュメント — セキュリティ上重要なパスに変更がある場合（§3「セキュリティ分析」を参照）にのみ作成します。チェックリストだけの成果物は決して作成しないでください。
• 図 — 複数コンポーネント間のフロー、制御フローやデータパスの変更、または差分から把握しにくい構造的な関係が変更に含まれる場合にのみ作成します。既定では変更前と変更後を並べたペアとして描画してください（§5「変更の表示」を参照）。変更が純粋な追加のみで、変更対象が 3 要素以下の場合に限り、注釈付きの**「変更後」図を 1 つ**使用してください。ノードが 1 つだけの図、1 本の矢印で 2 つのノードを結ぶ図、差分をそのまま言い換えた図は、明示的に省略してください。

何かを作成する前に、チャットで計画を伝えてください。例：

計画：表 1 つ、サマリードキュメント 1 つ、図なし（変更が単一の関数に局所化されているため）。

これによりトリアージの内容が明確になり、ボードのコンテンツを作成する前にユーザーが計画を変更できるようになります。

5. Miro ボードのコンテンツを作成する

原則： すべての成果物には、作成するだけの価値が必要です。差分だけを見るよりも PR をすばやく理解するのに役立たない成果物は作成しないでください。トリアージのルールについては §4.5 を参照してください。

PR の規模に応じて、§4.5 の価値基準を適用しながら、コンテンツを以下の上限まで拡充してください。成果物は少なくてもかまいません。

リンクの規則

§5 で出力するすべてのファイル参照は、ベース URL が利用可能な場合、ソースプラットフォームへのクリック可能なハイパーリンクにしてください。§2 で取得した LINK_TEMPLATE と LINK_SHA を使用してください。

• LINK_TEMPLATE が設定されている場合（PR/MR、またはリモートが判明しているブランチ）：ファイルの {path} を置き換えて URL を作成します。特定のハンク（高リスクファイル、セキュリティ上の指摘、アーキテクチャに関する指摘）を示す場合は、行アンカー #L<start>-L<end> を追加します。開始行と終了行は、§2 で取得した差分のハンク（@@ -a,b +c,d @@。新しいファイル側の範囲を使用）から特定します。参照先が複数の連続していないハンクにまたがる場合、アンカーは省略します。
• LINK_TEMPLATE が空の場合（local changes またはリモートなし）：すべてのファイル参照を通常のパスとして記載します。URL を作らないでください。

成果物ごとの規則：

• 表 → File 列：セルの内容として完全な URL を記載します。Miro はテキストセル内の URL をクリック可能なリンクとして表示します。リモートがない場合は通常のパスを記載します。
• ドキュメント：Markdown リンクを使用します。ファイル全体への参照は [path/to/file.ts](url)、ハンクへの参照は [path/to/file.ts:42-58](url#L42-L58) の形式にします。すべてのファイルへの言及（Overview、Key Changes、High-Risk Areas、Architecture > New Components / Modified Interfaces、Security > Security-Sensitive Changes など）に適用してください。
• 図：ノードラベルは通常のパスのままにします。Miro の図ツールでは、クリック可能なノードは文書化されていません。ノードが単一のソースファイルに対応する場合は、コピーできるよう URL をノードラベルの2行目に追加します。

配置：

レビュー担当者が左から右へ確認できるよう、成果物は1行に並べることを優先してください。Miro MCP ツールには、各ツールのスキーマに従って配置を指定します。

スケーリングのガイドライン

PR の規模	ファイル数	LOC（±）	ドキュメント	図
軽微	1–2	< 20	なし（§4.5 に従って中止）	なし
小規模	1–5	< 100	0–1（概要）	0–1（フロー）
中規模	6–15	< 500	1–2（概要＋必要に応じて詳細）	1–3
大規模	16–30	< 1500	2–3（概要＋アーキテクチャ＋該当する場合はセキュリティ）	2–4
非常に大規模	30+	≥ 1500	3+（サブシステムごと）	3+

左右に並べた変更前／変更後のペアは、上記の上限では図1つとして数えます。上限の対象は概念上の成果物であり、ボード上のウィジェット数ではありません。

---

ファイル変更テーブル

最初に作成します（ボードの中央に配置されます）。Miro MCP のテーブルツールを使用して、次の順序で4列のテーブルを作成します。

1. Status — 固定値の列で、値は Added、Modified、Deleted とし、それぞれ緑／オレンジ／赤で色分けします。
2. File — §5「リンクの規則」に従って作成した完全なソース URL を含むテキスト列です（Miro はテキストセル内の URL をクリック可能なリンクとして表示します）。リモート URL を利用できない場合は通常のパスを使用します。
3. Change — 変更内容と主なレビュー項目を簡潔にまとめたテキスト列です。
4. Risk — 固定値の列で、値は Low、Medium、High とし、それぞれ緑／オレンジ／赤で色分けします。

列の種類とオプションの形式は、テーブルツールのライブスキーマを参照してください。

非常に大規模な PR（ファイル数が30以上）では、テーブルを分けて作成します。

• 高リスク変更テーブル
• 標準変更テーブル

ドキュメント

ドキュメント 1：概要 — §4.5 の概要ドキュメントの価値判定を通過した場合に作成します。PR の説明にすでに同じ内容が含まれている場合は省略します。

ドキュメント 2：アーキテクチャ分析 — §4.5 のアーキテクチャドキュメントの価値判定を通過した場合にのみ作成します（差分で新しいモジュールが導入される、公開インターフェースが変更される、依存関係が変わる、または破壊的変更が追加される場合）。それ以外の場合は、中規模または大規模の PR であっても省略します。

ドキュメント 3：セキュリティ分析 — セキュリティ上重要なパス（認証、暗号化、設定、マイグレーション、入力処理）に変更がある場合にのみ作成します。セキュリティに関係する差分がない PR で、チェックリストだけの成果物を作成してはいけません。

追加ドキュメント — 非常に大規模な PR では、サブシステムごとに同じ行にドキュメントを作成します（「API 変更分析」、「データベースマイグレーションレビュー」、「UI／フロントエンド変更」など）。

各ドキュメントの完全な Markdown テンプレートについては、references/document-templates.md を参照してください。

---

図

変更の種類に応じて図を作成します。最後のドキュメントの後に配置します（x の値は 800 ずつ増やしていきます）。

変更の表示：変更前／変更後と注釈付きの比較

すべての図で、変更後の状態だけでなく、差分がひと目でわかるようにしてください。

• デフォルト：変更前／変更後を並べて表示します。 同じ種類の図を、同じ DSL の規約で 2 つ作成し、同じ y 行に隣り合わせで配置します。「変更前」は LINK_BASE_SHA のリビジョンから作成します（統合差分だけでは周辺構造が十分にわからない場合は、git show $LINK_BASE_SHA:path を使用します）。「変更後」は LINK_SHA から作成します。
• 次の条件をすべて満たす場合は、注釈付きの「変更後」図を 1 つだけ作成します。
  • 変更が純粋な追加である（関連するサブシステムに削除されたファイル、クラス、コンポーネント、エッジがない）、かつ
  • 追加によって既存の関係が再編されない（呼び出し元の接続変更や責任の移動がない）、かつ
  • 印を付ける新しいノード／エッジが 3 つ以下である。
• LINK_BASE_SHA に到達できない場合（シャロークローン、履歴の削除など）、すべてのペアを注釈付きの「変更後」図 1 つに切り替え、§2 のチャット告知を再利用します。

マーキング規則

主な目印はラベルのプレフィックスです（要素ごとのスタイル設定は、Miro Mermaid レンダラーでは保証されません）。[ADDED]（変更後の図のみ）、[REMOVED]（変更前の図のみ）、[UPDATED]（両方の図。ただしプレフィックスは変更後の図のみ）を付けます。印のない要素は変更されていないコンテキストです。プレフィックスだけで変更内容が分かるようにしてください。さらに、可能な範囲で色分けするために Mermaid の classDef ディレクティブも出力してください。

プレフィックスの意味の全容と、出力する classDef ブロックについては、references/diagram-conventions.md を参照してください。

図の選択ガイド：

変更の種類	図の種類	パターン	目的
機能追加（純粋な追加）	フローチャート	注釈付き単独図（変更後）	新しいコンポーネントと、その組み込み方を示す
リファクタリング	クラス図	変更前／変更後を並べて表示	構造の再編成が主な目的
API／統合の変更	シーケンス図	変更前／変更後を並べて表示	フローの形状の変化を示す
DB 移行／スキーマ変更	ER 図	変更前／変更後を並べて表示	スキーマの差分に焦点を当てる
バグ修正	フローチャート	注釈付き単独図（変更後）	フロー内の修正箇所を示す
データパイプラインの再構成	フローチャート	変更前／変更後を並べて表示	データフローの形状の変化を示す
複合的／大規模なリファクタリング	サブシステムごと	サブシステムごとに変更前／変更後を並べて表示	影響を受ける境界ごとに1組ずつ作成する

図の配置：

変更前／変更後の図は、差分がひと目で分かるように隣り合わせに配置してください。それ以外は、§5「配置」に記載の行レイアウトに従ってください。配置は、スキーマに従って Miro MCP 図ツールに渡します。

図（または図の組）	作成するタイミング
メインフロー／アーキテクチャの図の組	常に
コンポーネント関係の図の組	構造変更を伴う中規模以上の PR
シーケンス／インタラクション図の組	API／統合の変更
ER 図の組	データパイプライン／スキーマの変更
注釈付き単独図（追加のみ）	純粋な追加で、新規要素が3つ以下の場合

各図には、以下を示してください：

• 影響を受けるコンポーネント／モジュール（強調表示）
• 変更されたコード内のデータ／制御フロー
• 変更されたファイル間の依存関係
• 信頼境界（セキュリティに関係する変更の場合）
• ノードが単一のソースファイルに対応する場合は、読者がコピーできるよう、ラベルの2行目にその URL を追加してください（パスのみ。図のノードはクリックできません）。リモートが利用できない場合は URL を省略してください。変更前の図の URL には LINK_BASE_SHA を使用し、変更後の図には LINK_SHA を使用してください。
• §5「マーキング規則」の変更マーカーを、変更／追加／削除されたすべての要素に適用してください。図または図の組で、差分がひと目で分かるようにしてください。

6. PR/MR にリンクを追加する

成果物を作成したら、PR/MR 自体にリンクを表示し、レビュー担当者がリポジトリのホスティングサービスを離れずに確認できるようにします。

以下の場合は、この手順を完全に省略してください：

• ソースが「ローカルの変更」の場合
• ソースが、関連するオープン中の PR/MR を持たないブランチの場合

その場合、リンクはチャット出力（下記の「出力」を参照）にのみ記載します。

既存の説明文に区切りブロック（実行のたびに同じ … マーカーを再利用）を追記してください。すでにブロックがある場合は、その箇所で置き換え、ユーザーが記述した部分は上書きしないでください。§1 の CLI 選択を使用して本文を読み取り、挿入し、書き戻してください。権限不足で編集に失敗した場合は、代わりにそのブロックを PR/MR のコメントとして投稿し、チャットでその旨を伝えてください。

ブロックの正確な形式、リンクの規則、冪等性の規則、各プラットフォーム（gh／glab／REST）のコマンドについては、references/pr-linking.md を参照してください。

出力

§4.5 の中止条件が適用された場合、出力全体は簡潔な PR に関するチャットメッセージのみです。ボードへのリンクも、説明の更新も、その他の内容もありません。

それ以外の場合、完了後に以下を提示します。

1. Miro ボードへのリンク（moveToWidget が指定されている場合はフレームへのリンク）
2. PR/MR の説明を更新したこと、フォールバックとしてコメントを残したこと、またはソースがローカル／ブランチなしのため投稿ステップをスキップしたことの確認
3. 作成した要素の概要（X 件のドキュメント、N 組のペアと M 件の単独注釈付き図で構成される Y 件の図、Z 行のテーブル）。このチャットの概要に限り、ベースリビジョン <short LINK_BASE_SHA> とヘッドリビジョン <short LINK_SHA> に言及してください。これらの SHA は Miro ボードには記載しないでください。また、§4.5 に従って意図的にスキップした成果物の種類と、その理由を一行で記載してください。
4. 慎重なレビューが必要な高リスクファイル
5. セキュリティ上の指摘（重大または高リスクのものがある場合）
6. アーキテクチャ上の懸念（破壊的変更がある場合）

参考資料

• references/risk-assessment.md — 詳細なスコアリング基準
• references/review-patterns.md — レビューパターン
• references/source-links.md — §2 のプラットフォーム別 SHA 取得コマンドと blob URL テンプレート
• references/diagram-conventions.md — 図の変更マーク用プレフィックスと Mermaid の classDef ブロック（§5）
• references/document-templates.md — 概要、アーキテクチャ、セキュリティ文書の完全な Markdown テンプレート（§5）
• references/pr-linking.md — PR/MR へのリンクを投稿するためのブロック形式、リンク／冪等性ルール、プラットフォーム別コマンド（§6）
• references/background.md — レビューの理念、ビジュアルレビューの利点、成果物の選択表、ボードレイアウトの参考資料