pr-diagram: プルリクエストを図にする
目標: レビュアーが何が変わり、どのような流れかを10秒で把握できる1つの図を作成すること。 コードベース全体の地図ではありません。
ガードレール(絶対遵守)
- 決してコードを変更しないこと。 リポジトリ内のファイルを編集、作成、削除したり、コミット、プッシュ、ブランチの切り替えを行わないでください。
.mmdファイルは一時ディレクトリまたはスクラッチパッドに置き、リポジトリには置かないでください。 - 決して承認、変更要求、マージを行わないこと。
gh pr review、gh pr merge、gh pr closeを実行したり、PRコメントを投稿しないでください。このスキルが行う唯一の書き込みは、gh pr edit --body-fileによる説明文の更新です。 - 承認ステップは1回:完全な新しい説明文を表示し、同じメッセージ内で投稿を確認すること。 「投稿しますか?」と聞いてから説明文を表示するのは、承認ラウンドが2回になるため避けてください。追加したセクションだけでなく、全体を表示し、メッセージの最後に質問を記述してください。「Looks good」「post it」「yes」が承認とみなされます。沈黙、質問、修正依頼は承認とみなしません。修正後は、再度全体と質問を一緒に表示してください。
- 追加するすべての内容に、次の行を最終行として署名すること:
- 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と同じメッセージで)
応答する前にこれを行い、図、新しい完全な説明文、および質問がすべて一緒に送信されるようにします:
-
現在の本文を一時ファイルに取得:
gh pr view <N> --json body -q .body > <tmp>/body-old.md -
<tmp>/body-new.mdに新しい本文を構築します。ブロックをマーカーの間に配置し、再実行時に積み重なるのではなく置き換わるようにします:<!-- pr-diagram:start --> ## 変更図 <要約文> ```mermaid ...凡例: 緑 = 新規 · 黄 = 変更 · グレー(または色なし)= 未変更 (言葉を使用し、色の絵文字は使用しないでください。絵文字はOSごとに異なる色でレンダリングされます。例: ⬜はWindowsではラベンダー色で表示されます。)
- Generated by Claude Code
マーカーが既に存在する場合は、マーカー間のテキストのみを置き換えます。それ以外の場合は、空行の後にブロックを追加します。元の本文の他のすべてのバイトは変更しないでください。 -
新しい本文が元の本文全体で始まっていることを確認します。元の本文はバイト単位で保存されなければなりません。
-
メッセージの最後に、新しい完全な説明文をフェンスで囲んだブロック、PRのURL、および質問を記述します: 「これをに投稿しますか?」 その後、停止して待機します(ガードレール3)。
ステップ8: 投稿(ステップ7のメッセージに対して「はい」の応答があった場合のみ)
gh pr edit <N> --body-file <tmp>/body-new.md。インラインテキストで--bodyを決して使用しないでください。シェルの引用がバッククォートと$を破壊するためです。gh pr view <N> --json body -q .bodyでbody-new.mdと一致することを確認し、PRのURLを提供します。比較する際は末尾の空白を無視します(-qは改行を追加するため)。例えば、Pythonで両方を.rstrip()して比較します。
PRがまだない場合(ローカルブランチのみ)? ユーザーがPRを開いたときに貼り付けるブロックを提供します。PRは作成しないでください。
禁止事項
- すべてのファイルを図にしないでください。すべてを示す図は何も示しません。
- シークレット、内部ホスト名、トークンやクエリ文字列を含む完全なURL、顧客データをラベルに含めないでください。