Community画像github.com

pr-diagram

プルリクエストの変更点をMermaid図で可視化し、レビュアーが差分を読む前に処理の流れを把握できるようにします。

pr-diagram とは?

pr-diagramは、PRの変更点をMermaid図として自動生成するAIエージェントスキルです。レビュアーが差分の詳細に入る前に、変更の全体的な流れを直感的に理解できるように設計されています。このスキルは、PR番号やURLを指定するか、現在のブランチを基に動作します。スキルはまずPRの差分を取得し、変更されたファイルの現在のコードを読み取って、処理の流れ(トリガー、実行順序、終了点)と各ステップのステータス(新規/変更/未変更)を特定します。次に、変更内容に最適な図のタイプ(フローチャート、シーケンス図、状態遷移図、ER図など)を自動選択し、色分けされたMermaid図を生成します。最後に、図を含む完全な新しいPR説明文をユーザーに確認・承認を求めてから、PR説明欄に投稿します。このスキルはClaude Code上で動作し、コードの読み取りのみを行い、一切の変更やコミットは行いません。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/amihali1/claude-skills/tree/HEAD/plugins/pr-diagram/skills/pr-diagram

Installed? Explore more 画像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

pr-diagram: プルリクエストを図にする

目標: レビュアーが何が変わり、どのような流れかを10秒で把握できる1つの図を作成すること。 コードベース全体の地図ではありません。

ガードレール(絶対遵守)

  1. 決してコードを変更しないこと。 リポジトリ内のファイルを編集、作成、削除したり、コミット、プッシュ、ブランチの切り替えを行わないでください。.mmdファイルは一時ディレクトリまたはスクラッチパッドに置き、リポジトリには置かないでください。
  2. 決して承認、変更要求、マージを行わないこと。 gh pr review、gh pr merge、gh pr closeを実行したり、PRコメントを投稿しないでください。このスキルが行う唯一の書き込みは、gh pr edit --body-fileによる説明文の更新です。
  3. 承認ステップは1回:完全な新しい説明文を表示し、同じメッセージ内で投稿を確認すること。 「投稿しますか?」と聞いてから説明文を表示するのは、承認ラウンドが2回になるため避けてください。追加したセクションだけでなく、全体を表示し、メッセージの最後に質問を記述してください。「Looks good」「post it」「yes」が承認とみなされます。沈黙、質問、修正依頼は承認とみなしません。修正後は、再度全体と質問を一緒に表示してください。
  4. 追加するすべての内容に、次の行を最終行として署名すること: - Generated by Claude Code

引数

  • /pr-diagram: 現在のブランチのPRを使用します。PRが存在しない場合はローカルブランチの差分を使用します。
  • /pr-diagram 123 またはPRのURL: そのPRを対象とします(URLを使用して他のリポジトリのPRも対象にできます)。
  • type=td|lr|sequence|state|er: 図のタイプを強制指定します。

ステップ1: 差分を収集する

PRがある場合(すべて読み取り専用):

gh pr view <N> --json number,title,body,url,baseRefName,headRefName,files,additions,deletions
gh pr diff <N> --name-only
gh pr diff <N>

PRがない場合: ベースブランチを見つけ(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)、次に git diff --stat $(git merge-base origin/<base> HEAD) および git diff $(git merge-base origin/<base> HEAD) を実行します。

大きな差分(変更行数1500行超、またはファイル数30超)の場合: 最初に --stat とPR本文を読み、次にロジックを含むファイルのみを読みます。ロックファイル、生成コード、スナップショット、純粋なリネームはスキップします。

ステップ2: フローを特定する

差分は行を示しますが、関係性は示しません。タッチされた各ファイルの現在のバージョンを読み(読み取り専用)、以下を明らかにします:

  • フロー: 何がトリガーか(リクエスト、ジョブ、イベント、ユーザーアクション)、どの順序で何が実行されるか、どこで終わるか(レスポンス、DB書き込み、メッセージ、外部呼び出し)。
  • 各ステップのステータス: 新規(このPRで追加)、変更(既存、修正)、未変更(レビュアーが変更を配置するために必要なコンテキスト)。
  • レビュアーに必要な1文の要約(「支払い呼び出しの前にリトライステップを追加」)。

PRのタイトルと本文を意図として使用しますが、コードと矛盾する場合はコードを優先します。すべてのノードとエッジは、読んだコードにトレース可能でなければなりません。図をきれいにするためにステップをでっち上げないでください。 不明な点がある場合は、そのままにして、その旨を明記してください。

削除されたコード: 削除されたステップがレビュアーにとって重要な場合は、灰色のノードに「(removed)」というラベルを付け、点線のエッジで表示します。それ以外の場合は省略します。

ステップ3: 図のタイプを選択する

出力は常にMermaid形式の.mmdファイルです。フローに合うタイプを選択してください:

変更の主な内容図のタイプ
段階的なプロセスまたは分岐ロジックflowchart TD(上から下)
コンポーネントやサービスの結合、パイプラインflowchart LR(左から右)
3つ以上の参加者間でのリクエストやメッセージの経時的な受け渡しsequenceDiagram
ステータスやライフサイクルの変更(保留中 → 承認 → ...)stateDiagram-v2
テーブル、カラム、リレーション(マイグレーション)erDiagram

1つの図を使用してください。PRが構造と実行時フローの両方を明確に変更している場合にのみ、2つ使用してください。PRが小さすぎて図が必要ない場合(1〜2ファイルで新しいフローがない場合)は、その旨を伝えて停止します。

ステップ4: 図を構築する

ラベル: 平易な英語で、短く。

  • ステップが何をするかを書き、コードの識別子は使わないでください: CardValidator.validateExpiry()ではなくCheck card is not expired。名前が役立つ場合は短縮形を使用します: PaymentReconciliationServiceはPayment reconcilerに。
  • URLはパスに短縮します: api.example.com/v2/orders/{id}/refundsはPOST /orders/:id/refundsに。
  • 矩形ノード A["..."]: 1行あたり最大35文字。
  • スタジアム A(["..."]) および角丸 A("...") ノード: 1行あたり最大25文字。
  • ノードにより詳細な説明が必要な場合は、<br/>で行を分割します(各行は制限内)。最大3行までです。
  • 形状の意味: 矩形 = ステップまたはコンポーネント、スタジアム = 開始または終了(トリガー、レスポンス)、角丸 = 外部システム、菱形 A{"..."} = 判定(最大25文字)、円筒 A[("...")] = データストア。
  • 最大15ノード。約8ノードを超える場合は、subgraphを使用してサービスまたはエリアごとにグループ化します。
  • エッジのラベルは簡潔な平易な英語で(sends、on failure、saves)、最大20文字。
  • シーケンス図: participantおよびactor名は最大25文字。メッセージ、loop、alt、optのラベル、およびNoteテキストは1行あたり最大35文字(<br/>で分割、最大3行)。メッセージテキストに;や#を使用しないでください。解析が壊れます。

色(GitHubのライトモードとダークモードの両方で読みやすい)。 明るい塗りつぶしと暗いテキスト、太い境界線を使用してください:

classDef new fill:#d3f9d8,stroke:#2b8a3e,stroke-width:2px,color:#0b3d17
classDef changed fill:#fff3bf,stroke:#e67700,stroke-width:2px,color:#4a2b00
classDef unchanged fill:#e9ecef,stroke:#868e96,stroke-width:1px,color:#343a40
class StepA,StepB new
class StepC changed
class StepD unchanged

すべてのノードは正確に1つのクラスを取得します。stateDiagram-v2では、classDefとclass StateName newを使用します。

シーケンス図: クラスは適用されません。rectは背景のみを設定し、テキストの色はGitHubのテーマ(ダークモードではライトグレー)から来ます。不透明な明るい塗りつぶしはダークモードでテキストを読めなくするため、常に半透明のティントを使用してください:

  • new: rect rgba(46,160,67,0.18)
  • changed: rect rgba(210,153,34,0.22)
  • unchanged: rectなし

不透明なrect rgb(...)は決して使用しないでください。主要な変更についてはNote overを追加してください。

全く新しいPR(変更も未変更もない場合): 緑色のティントを維持し、要約に「この図のすべてのコードは新規です」と記載してください。対比するものがないためです。

構文の落とし穴(GitHubのレンダリングを壊します)。すべて確認してください:

  • ノードIDは英数字のみ(ChkCard)。ラベルは常に引用符で囲む: ChkCard["Check card"]。
  • リテラルの"をラベル内で使用するには#quot;を使用します。<br/>はラベル内で許可される唯一のHTMLです。
  • end(小文字)をIDとして使用しないでください。矢印の周りには必ずスペースを入れてください(A --> B。A---oBは円形エッジとして解析されます)。
  • subgraph Id["Label"] ... end。各subgraphには独自のendが必要です。
  • シーケンスのparticipant: participant API as Orders API(IDにスペースは含めません)。
  • erDiagram属性タイプは単一の単語でなければなりません(varchar(255)ではなくvarchar)。
  • %%{init}%%テーマブロックは使用しないでください。classDefの色が両方のモードを処理します。

保存 ダイアグラムを pr-<N>-diagram.mmd(または branch-<name>-diagram.mmd)として一時ディレクトリまたはスクラッチパッドに保存します。完全なパスを指定します。

ステップ5: 提示前の自己チェック

  • ラベル行のすべての文字数を、各行の制限(矩形: 35、スタジアム、角丸、菱形: 25、エッジラベル: 20、シーケンス図ではparticipant: 25、メッセージ・ブロック・ノート: 35)に対してカウントし、超過しているものを修正します。
  • 平易な英語で表現できるのに、生のコード識別子(camelCase、Foo.bar()、snake_case)がラベルに含まれていないことを確認します。
  • 各ノードの色を確認します。そのノードは差分において本当に新規、変更、または未変更ですか?
  • オプションのレンダリングチェック: npx -y @mermaid-js/mermaid-cli -i <file>.mmd -o <file>.svg。初回実行はChromium(約150 MB)をダウンロードするため、実行前に確認してください。

ステップ6: 提示

チャットで次の形式を使用します:

**<PRが行うことの1文要約>**

<2〜3文: 言葉でのフロー、変更がどこに位置するか、省略したことや不明なこと>

```mermaid
...
```
**凡例:** 緑 = 新規コード · 黄 = 変更コード · グレー(または色なし)= 未変更のコンテキスト

保存先: <.mmdへの完全パス>

ステップ7: 完全な説明文を表示し、投稿を確認する(ステップ6と同じメッセージで)

応答する前にこれを行い、図、新しい完全な説明文、および質問がすべて一緒に送信されるようにします:

  1. 現在の本文を一時ファイルに取得: gh pr view <N> --json body -q .body > <tmp>/body-old.md

  2. <tmp>/body-new.mdに新しい本文を構築します。ブロックをマーカーの間に配置し、再実行時に積み重なるのではなく置き換わるようにします:

    <!-- pr-diagram:start -->
    ## 変更図
    <要約文>
    
    ```mermaid
    ...
    

    凡例: 緑 = 新規 · 黄 = 変更 · グレー(または色なし)= 未変更 (言葉を使用し、色の絵文字は使用しないでください。絵文字はOSごとに異なる色でレンダリングされます。例: ⬜はWindowsではラベンダー色で表示されます。)

    • Generated by Claude Code
    マーカーが既に存在する場合は、マーカー間のテキストのみを置き換えます。それ以外の場合は、空行の後にブロックを追加します。元の本文の他のすべてのバイトは変更しないでください。
    
  3. 新しい本文が元の本文全体で始まっていることを確認します。元の本文はバイト単位で保存されなければなりません。

  4. メッセージの最後に、新しい完全な説明文をフェンスで囲んだブロック、PRのURL、および質問を記述します: 「これをに投稿しますか?」 その後、停止して待機します(ガードレール3)。

ステップ8: 投稿(ステップ7のメッセージに対して「はい」の応答があった場合のみ)

  1. gh pr edit <N> --body-file <tmp>/body-new.md。インラインテキストで--bodyを決して使用しないでください。シェルの引用がバッククォートと$を破壊するためです。
  2. gh pr view <N> --json body -q .bodyでbody-new.mdと一致することを確認し、PRのURLを提供します。比較する際は末尾の空白を無視します(-qは改行を追加するため)。例えば、Pythonで両方を.rstrip()して比較します。

PRがまだない場合(ローカルブランチのみ)? ユーザーがPRを開いたときに貼り付けるブロックを提供します。PRは作成しないでください。

禁止事項

  • すべてのファイルを図にしないでください。すべてを示す図は何も示しません。
  • シークレット、内部ホスト名、トークンやクエリ文字列を含む完全なURL、顧客データをラベルに含めないでください。

関連スキル