Communityライティング&編集github.com

PR説明ボット

プルリクエストやバグ修正、ローカルの変更をジュニアエンジニア向けに説明する自己完結型のHTMLページ(デフォルト)またはMarkdownハンドオーバー文書(--md)を生成します。

PR説明ボット とは?

このスキルは「PR説明ボット」と呼ばれ、プルリクエストやバグ修正、ローカルの変更をチームメイトに説明する文書を生成するためのものです。主な対象読者はジュニアエンジニアで、技術的に簡潔な言葉で書かれますが、内容は本格的です。出力形式は自己完結型HTML(デフォルト)またはMarkdown(--mdオプション)で、PR番号やURL、またはローカルの変更を入力として受け取ります。機能追加の場合は「なぜ」「どこにあるか」「どう動くか」「コード解説」「確認方法」などを、バグ修正の場合は「何が問題か」「根本原因」「修正コード」「確認方法」などを構造化して提示します。また、--conciseオプションで短いバージョン、--localオプションで未コミットの変更にも対応し、ダイアグラムやコードスニペットを用いて理解を助けます。GitHub CLI(gh)と連携してPRの詳細を取得したり、gitコマンドでローカルの差分を分析します。生成された文書は.pr-review/ディレクトリに保存され、バージョン管理外に保たれます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sahildaswani/agent-skills/tree/HEAD/skills/pr-explainer

Installed? Explore more ライティング&編集 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

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

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

ドキュメント

PR説明ボット は何をしますか?

チームメイトに変更内容を教えるための文書を1つ作成します。何が間違っていたか、何が足りなかったか、システムがどのように動作するか、変更が何をするか、そしてそれが正しく動作することをどのように確認したか、を説明します。

引数

  • ターゲット: PR番号、URL、または何も指定しない。
    • PRがあり、gh CLIが利用可能な場合、gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files で詳細を取得し、gh pr diff <url> で差分を取得します。周辺コードはPRのheadコミット(git show <headRefOid>:<path>)で読み、ローカルのHEADは使用しません。
    • PRがない場合、またはghがない場合:ローカルの変更を説明します。コミット済みの変更には git diff <base>...HEAD を使用し、未コミットの変更には git diff と git status を使用します。ここで <base> はデフォルトブランチまたは最初のコミットです。
  • --local: PRが存在する場合でもローカルチェックアウトを使用します(未プッシュの作業)。ページ上でローカルの変更を反映していることを明記します。
  • --concise: 約2分で読める短いバージョン。ビジュアルは最大1つ、スニペットは最大3つ、目次なし、セクションごとに1~3文。
  • --md: HTMLではなくMarkdownを書き出します(デフォルトのファイルはリポジトリルートの HANDOVER.md、ただしユーザーが名前を指定した場合はその名前)。ハンドオーバーやブラウザが使えない場合に使用します。

読者と文体

  • 読者はチームのジュニアエンジニアです。短い文、平易な動詞、1段落につき1つのアイデアを使用します。
  • 基礎的な概念(REST、SQL、JWT、Reactフック)は定義せず、非技術的なたとえは使いません。実際のモジュール名、関数名、ルート名、フィールド名、実際の数値を用いて技術的に保ちます。
  • 言葉遣いを簡単にするのであって、内容を簡単にするのではありません。珍しいライブラリ呼び出しやパターンは、最初に登場した場所で説明します。
  • 最終稿として書きます。現在の状態を直接説明します。変更履歴や「以前はこう考えていた」という表現は避けます。
  • 確実性について正直に述べます。未確認の主張には「可能性が高いが、まだ確認されていない」とラベルを付けます。

範囲:差分ではなく変更を説明する

  • ストーリーを伝えるファイルを選び、その中で重要な行のみを取り上げます。
  • ファイルごとに1~3個のスニペットを使用し、各スニペットは約25行以内に収め、... で省略部分を示します。各スニペットにはファイルパスと、それが何をするか、なぜ必要なのかを2~4文で説明します。
  • 修正の場合は、バグの原因となったコードと、修正の差分を表示します。
  • コードは実行時の流れ順に並べ、差分順にはしません。
  • 配管、リネーム、フォーマット変更はスキップします。レビュワーが差分で気にする場合のみ、1行で触れます。

1. 変更を理解する

  • 差分と周辺コードを読みます。モードを決定します:
    • 機能追加:新しい動作または大規模なリファクタリング。
    • バグ修正:症状、根本原因、修正。
  • 最新の検証実行を見つけます:テストコマンドとカウント、そして理想的には、修正がないと失敗し修正があると成功する新しい回帰テストの証拠。そのような証拠がなく、コストが低ければ、自分で生成します:git stash push -- <src files>、テストを実行、git stash pop。また、手動またはエンドツーエンドの確認(CLI出力、リクエスト、スクリーンショット)も探します。それぞれの最新の実行のみを表示します。
  • 会話(根本原因分析、QAレポート、チケット)からの調査結果が存在する場合はそれも使用します。

2. 骨格

すべての文書は、アイブローライン(リポジトリ · PR #n · チケット または リポジトリ · ローカル変更)、平易なタイトル、1~2文のリードから始まります。

バグ修正

  1. 何が問題だったか:症状、どこで見られたか、除外されたもの。
  2. 根本原因:データやフローが壊れる正確な場所(ファイル:行)。役立つ場合はビジュアルも使用。
  3. 問題の原因となったコード:1~2個のスニペット。
  4. 修正:差分スニペットと、なぜそれが機能するか。同時に修正される副作用も記載。
  5. 確認方法:修正前は失敗し修正後は成功する回帰テスト、全スイートのカウント、手動確認。
  6. 教訓:ジュニアエンジニアが他の場所で再利用できる2~4の教訓。

機能追加

  1. なぜ:問題または目標、証拠を添えて。
  2. 位置づけ:アーキテクチャまたはモジュールのコンテキスト(図)。意図的に変更していない部分も記載。
  3. 動作の流れ:コードカードにリンクされた手順またはフローチャート。
  4. コードウォークスルー:重要なファイルごとに1カード、フロー順に。
  5. 知っておくべき動作:エッジケース、状態、障害モード(3つ以上の場合は表)。
  6. 検証:最新の実行のみ。
  7. レビュワーへのポイント:2~3行のメンタルモデルと、差分で最も注意深く見るべき箇所。

ハンドオーバー追加項目(--mdの場合は常に含む。HTMLの場合は任意):

  • 実行/テスト方法:正確なコマンド。
  • 前提としたこと:仕様が沈黙していた箇所で取った判断とその理由。
  • ビジネスへの未解決質問:影響度順に並べる。
  • リスクとロールバック:本番で何が問題になる可能性があるか、元に戻す方法。
  • 次のステップ:もっと時間があれば何をするか。

簡潔版: 「何が問題だったか / 何と理由」「根本原因 / 動作方法」「修正 / 主要コード」「確認方法」のみ。

3. ビジュアル:テキストで説明できない場合のみ使用

内容使用するもの
モジュールやサービスのアーキテクチャ、誰が誰を呼ぶか、リクエストの順序Mermaid flowchart / sequenceDiagram(約12ノード以下)
変更前後で動作が異なる1つのブランチ変更前/変更後の表、または小さい静的SVG
ステージを通過するデータ、フィルタで落とされる値入力→出力の例の表(変更前 vs 変更後)
状態、コマンド、リスク、契約表

Markdownでは、フェンスで囲んだ ```mermaid ブロックを使用します(GitHubがレンダリングします)。アニメーションはユーザーが要求した場合のみ追加します。

4. 構築

  • HTML: references/page-template.html から開始(自己完結型、ライトモード/ダークモード、CDNからのMermaidとhighlight.js)。.pr-review/<名前>.html に保存、名前はチケットまたはPRにちなんで、または local-<短い説明>。Gitの管理外に保つ:git check-ignore -q .pr-review/ が失敗した場合、.pr-review/ を .git/info/exclude に追加します。.gitignore は要求がない限り編集しません。
    • コードスニペット:<pre><code class="language-<言語>">…</code></pre>、HTMLエスケープ。修正差分の場合は language-diff で -/+ 行を使用。
    • Mermaid:<pre class="mermaid">…</pre>。色をハードコードしない。
  • Markdown(--md): プレーンなGitHub Flavored Markdown、同じ骨格、HTMLは使用しません。

5. 一度確認

  • HTML:ブラウザツールが利用可能な場合、ページをデスクトップ幅と約400pxで一度ずつ開きます。Mermaidがレンダリングされ、コードがハイライトされていることを確認します。見つけた問題は1回で修正し、ループしません。それ以外の場合は、プレビューされなかったことを伝え、開くコマンドを提供します(macOSは open、Windowsは start、Linuxは xdg-open)。
  • ページ上のすべての ファイル:行、数値、コマンドをコードと照合して再読します。事実は正確でなければなりません。

6. 報告

以下を含めて返答します:

  • ファイルパス
  • モードとカバーしたセクション
  • 使用したビジュアルとそれぞれが説明する内容
  • 文書が示す検証実行
  • 「未確認」とラベル付けされたもの

許可なくPR本文を編集したり、コメントを投稿したり、何かをプッシュしたりしないでください。

関連スキル