PR説明ボット は何をしますか?
チームメイトに変更内容を教えるための文書を1つ作成します。何が間違っていたか、何が足りなかったか、システムがどのように動作するか、変更が何をするか、そしてそれが正しく動作することをどのように確認したか、を説明します。
引数
- ターゲット: PR番号、URL、または何も指定しない。
- PRがあり、
ghCLIが利用可能な場合、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>はデフォルトブランチまたは最初のコミットです。
- PRがあり、
--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個のスニペット。
- 修正:差分スニペットと、なぜそれが機能するか。同時に修正される副作用も記載。
- 確認方法:修正前は失敗し修正後は成功する回帰テスト、全スイートのカウント、手動確認。
- 教訓:ジュニアエンジニアが他の場所で再利用できる2~4の教訓。
機能追加
- なぜ:問題または目標、証拠を添えて。
- 位置づけ:アーキテクチャまたはモジュールのコンテキスト(図)。意図的に変更していない部分も記載。
- 動作の流れ:コードカードにリンクされた手順またはフローチャート。
- コードウォークスルー:重要なファイルごとに1カード、フロー順に。
- 知っておくべき動作:エッジケース、状態、障害モード(3つ以上の場合は表)。
- 検証:最新の実行のみ。
- レビュワーへのポイント: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本文を編集したり、コメントを投稿したり、何かをプッシュしたりしないでください。