pr-writer

PR Writer

PR の本文は、変更履歴、テンプレート、検証ログ、ファイルごとの要約ではなく、レビュアー向けのカバーノートとして記述します。

変更内容の確認

認証済みの gh が必要です。現在のブランチ、作業ツリー、PR、ベースブランチ、コミット、差分全体を確認します。

git branch --show-current
git status --porcelain
gh pr view --json number,title,body,url,baseRefName,headRefName
gh repo view --json defaultBranchRef

gh pr view で PR が存在しないと報告された場合は、初回の PR 作成に進みます。既存の PR がある場合はその baseRefName を使い、ない場合はリポジトリのデフォルトブランチを使います。BASE を設定してから、次を確認します。

git log "$BASE"..HEAD --oneline
git diff "$BASE"...HEAD

main または master にいる場合は、先にフィーチャーブランチを作成します。意図した変更がコミットされていることを確認し、最新のコミットや既存の PR の本文だけでなく、ブランチ全体の差分を確認してください。

基本ルール

• 実装の詳細より先に、具体的に変更された動作、影響を受ける箇所、レビュアーへの影響を説明します。
• 動機、リスク、トレードオフ、移行、レビューの着眼点は、有用な場合にのみ説明します。
• 変更のレビューを容易にするために必要な最小限の構成を使います。
• 内部向けのプロンプトやプロセスに関する用語は、具体的な動作に置き換えます。
• PR を更新する際は、レビュー履歴を語るのではなく、現在の差分全体に沿って書き直します。

タイトル

<type>(<scope>): <subject> または <type>: <subject> を使います。

使用できるタイプ：feat、fix、ref、perf、docs、test、build、ci、chore、style、meta、license、revert。

• ブランチ全体で主要な変更を、正確さを保てる最も限定的なタイプとスコープで表します。
• 外部との契約に後方互換性のない変更がある場合にのみ ! を使い、影響を受ける箇所を本文で説明します。
• update、cleanup、misc、fix stuff、address feedback のような曖昧な件名は避けます。末尾にピリオドを付けないでください。
• 既存のタイトルは、差分全体を引き続き表している場合にのみ維持します。

本文の構成

役立つ最小限の構成を選びます。

変更	含める内容
小規模または明白な変更	見出しを付けず、簡潔な段落を 1 つ。
機能追加、バグ修正、リファクタリング	変更された動作とその影響。関連する場合は、根本原因、変更されていない動作、または一見して分かりにくいアプローチを追加します。
契約の変更または破壊的変更	影響を受ける API、スキーマ、ペイロード、設定、権限、ストレージ、CLI の箇所。互換性と移行の手引きも含めます。
運用、表示、ワークフローの変更	有用な場合は、ユーザーや運用担当者への影響、測定された効果、障害モード、フローを説明します。
広範囲、生成された変更、または横断的な変更	変更を整理する原則、広範囲な変更が必要な理由、レビューを始める箇所を説明します。

デフォルト：

<What changed and what effect it has.>

<Why the approach, risk, migration, or review focus matters, if not obvious.>

レビューのフィードバックを受けて更新する場合は、修正の経緯ではなく、結果としての PR 全体を説明します。

レビュアー向けの補助情報

レビュアーが内容を再構成する手間を減らせる場合にのみ、次の補助情報を使います。

• 変更された契約を示す簡潔な変更前／変更後の例やインターフェース例。
• 非同期フローや状態遷移を示す小さな Mermaid 図。
• 視覚的な証拠がある場合のスクリーンショットや録画に関する注記。
• レビュアーや導入担当者に必要な場合の、展開、互換性、リスク、レビュー順序に関する注記。

レビュアーが注目すべき点を説明する文を 1 文添えて成果物を紹介します。文章のほうが明確な場合は省略します。

境界

• デフォルトで Summary、Changes、Test Plan のセクションを追加しないでください。
• リスク評価に影響する場合や、重要な回帰テストの範囲を説明する場合を除き、通常の検証は省略します。ドキュメント、スキル、文言、設定の変更では、デフォルトで省略してください。
• コマンド、CI ログ、検証結果のダンプ、コミットログ、プレースホルダー、網羅的なファイル一覧を貼り付けないでください。
• 顧客名や組織名、ユーザーのメールアドレス、サポートチケットの内容、シークレット、個人を特定できる情報を含めないでください。
• 課題への参照は、ユーザーの入力、ブランチ名、コミット、PR の議論、トラッカーの出力から確認できた場合にのみ使います。Fixes <issue> は課題をクローズし、Refs <issue> はリンクするだけです。

作成または更新

新しい PR はドラフトとして作成します。本文を一時的な Markdown ファイルに書き込み、その後、次を実行します。

gh pr create --draft --title '<title>' --body-file /tmp/pr-body.md

既存の PR は gh api で更新します。

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
  -f title='<title>' \
  -F body=@/tmp/pr-body.md

後続のコミットによってスコープ、アプローチ、破壊的な動作、リスク、移行、またはレビュー時の期待が実質的に変わった場合は、タイトルと本文を更新します。誤字、書式、名前の変更だけの後続作業は対象外です。

例

小規模な変更：

The AI Customizations section now starts collapsed so it does not consume
sidebar space before users need it. Expanding it preserves the existing saved
preference behavior.

互換性を破る変更：

Run logs now emit chunk-level records instead of one skill-level record.
Consumers that read top-level `findings` must iterate over
`chunk.findings` for each record.

Before:

```json
{"skill": "security-review", "findings": [...]}
```

After:

```json
{"schemaVersion": 1, "chunk": {"index": 1, "findings": [...]}}
```