PR Body（pr-body）

AIに実装させた変更を抽象度の階層構造で分析し、人間が機微を即座に知覚できるGitHub PR本文を生成する。本スキルは本文の生成のみを担い、ブランチ・コミット・push などの Git 操作は行わない（それらは pr / pr-stage の責務）。

原則

• 大きい地図から具体へ。 抽象→具体を基本順序とする。ただし変更が小規模な場合や、読者にとって逆順が自然な場合は柔軟に構成を選べ
• 図と表で語れ。 長文の説明より、Mermaid図とテーブルが優先
• 内部では疑って検証し、出力では事実を伝える。 分析プロセスは厳しく、PR本文は冷静に
• セクションはAIが判断する。 変更に関係ないセクションは出力しない（ただしrequireは常に）
• ゴールデンサークルを思考の指針に。 Why（なぜ必要か）→ How（どう解決したか）→ What（何を変更したか）の順で考えよ。ただし出力の形式やテンプレートとして固定するな。状況に応じた最適な構成を選ぶこと
• 前提知識ゼロで読めるように。 専門用語は補足を添え、文脈が独立して完結するように書け

タイトルガイド

PRタイトルはCS（カスタマーサポート）が確認することも想定し、簡潔で分かりやすいタイトルにする。

• 技術用語を並べるな。 fix: null check in getUserById ではなく ユーザー詳細取得時のエラーを修正
• 変更の本質を一言で。 何が変わったか、誰に影響するかをCSでも理解できる言葉で
• prefixは任意。 fix:, feat: 等のプレフィクスは既存の慣習に従う。強制しない
• 英語でも可。 リポジトリの慣習が英語の場合は英語で良い。ただし簡潔さは同様

実行フロー

Step 0: 変更の全体像を掴む

# 変更ファイル一覧と行数
git diff --stat <base-branch>...HEAD

# 変更のあったディレクトリ構造
git diff --name-only <base-branch>...HEAD | sort

どのレイヤー（インフラ/バックエンド/フロントエンド/DB）に変更が集中しているか、規模感を把握する。

Step 1: 階層型Perspective分析（内部思考プロセス）

以下の5階層から、変更内容に関連するものを選び、抽象度の高い順に分析する。この分析はPR本文にはそのまま出ない。本文を構成するための材料である。

階層カタログ（抽象 → 具体）

各階層の分析内容（内部用）

各階層ごとに以下を整理する。

L0: システム構成

• 機能コンポーネントの全体像と接続関係
• インフラ構成（サーバー、ネットワーク、ミドルウェア）
• 変更があったコンポーネントの特定
• 境界の追加・削除・変更

L1: データ構造

• 追加・変更・削除されたエンティティ
• エンティティ間の関係（1:N、N:N）
• 主要なカラムとその意味
• データフローの概要（どこで生まれ、どこに格納されるか）

L2: 通信・インターフェース

• 追加・変更・削除されたAPIエンドポイント
• request/responseの主要フィールド
• 認証・認可の変更
• バージョニング・後方互換性

L3: 処理フロー

• 主要な処理の呼び出しチェーン
• 外部サービス連携のタイミングと内容
• エラーハンドリングの流れ
• 非同期処理・キューの存在

L4: 実装詳細

• 主要なカラムの型・制約・デフォルト値
• フロントエンドのコンポーネント構成
• 環境変数・設定ファイルの変更
• パフォーマンス関連の変更

分析深度の判定

Step 2: PR本文セクションの判定

分析結果に基づき、出力すべきセクションを判定する。

セクション判定ルール

Step 3: PR本文の構築

判定されたセクションのみでPR本文を構築する。

``````markdown

変更概要

[1-2行で変更の本質を説明。何が変わり、なぜ変わったか]

背景・課題・原因

[なぜこの変更が必要だったか。背景事情と解決すべき課題] [問題の根本原因が判明している場合は、その原因と導出過程を簡潔に記述]

影響範囲

[この変更が影響する範囲を明示。CSも読者を想定し、技術的詳細だけでなくユーザー視点の影響も含める]

• 影響モジュール: [影響を受けるコンポーネント名]
• ユーザーへの影響: [UI/UXの変化、既存機能への影響有無]
• データへの影響: [既存データへの影響、マイグレーションの要否]
• 他サービスへの影響: [連携サービスへの波及効果]

システム構成図

[変更後のシステム全体像をMermaidで示す。変更箇所を視覚的に区別]

graph TB
    subgraph "Frontend"
        Web["Web App"]
    end
    subgraph "Backend"
        API["API Server"]
        Worker["Worker"]
    end
    subgraph "Data"
        DB["PostgreSQL"]
        Cache["Redis"]
    end
    Web -->|"HTTP/REST"| API
    API -->|"query"| DB
    API -->|"cache"| Cache
    API -->|"enqueue"| Worker
    classDef changed fill:#fef3c7,stroke:#f59e0b
    class API,Worker changed

データ構造

ERD概要

[変更後のエンティティ関係をMermaidで示す]

erDiagram
    USERS ||--o{ ORDERS : places
    ORDERS ||--|{ ORDER_ITEMS : contains
    PRODUCTS ||--o{ ORDER_ITEMS : included_in

変更されたエンティティ

API変更

エンドポイント一覧

主要なRequest/Response

POST /api/orders

処理フロー

[主要な処理の流れをシーケンス図またはフローチャートで示す]

sequenceDiagram
    participant C as Client
    participant A as API
    participant DB as Database
    participant Q as Queue
    C->>A: POST /api/orders
    A->>DB: トランザクション開始
    A->>DB: 注文・明細INSERT
    A->>Q: 注文イベント送信
    A-->>C: 201 Created

外部連携

フロントエンド変更

画像エビデンス

ケース	確認内容	画像
URL誤入力	LIFF URLではなく、LIFF IDを入力してください。 が表示
正常保存	保存成功後に期待した表示へ遷移する

インフラ変更

設計判断

[今回の実装で意識した設計ルール・判断基準]

• [判断1]: [内容] — [なぜそう判断したか、代替案との比較]
• [判断2]: [内容] — [なぜそう判断したか]

設計上の検証

[階層型分析の結果を要約]

• システム構成: [変更は既存の境界内で完結している / 新規コンポーネントを追加した]
• データ構造: [エンティティ関係に循環なし / 正規化は第3形準拠]
• API: [後方互換性を維持している / 破壊的変更あり（別途チェックリスト参照）]

懸念点・技術的負債

[正直に書く。なければ「特になし」で良い]

• [懸念1]: [内容] — [なぜ許容するか、または次回どう対応するか]

今後の改善事項

[今すぐ必須ではないが、将来対応すべきこと]

• [todo 1]
• [todo 2]

Test Plan

テスト項目

• [テスト項目1]: [期待結果]
• [テスト項目2]: [期待結果]

動作確認ポイント

• [確認ポイント1]
• [確認ポイント2]

自動テスト

# 実行コマンド例

チェックリスト

• 既存APIの破壊的変更: [あり/なし]
• DBマイグレーション: [必要/不要]
• 環境変数の追加: [あり/なし]
• 他サービスへの影響: [あり/なし]

``````

画像・スクリーンショット運用

UI変更、バグ再現、before/after比較、入力バリデーションの証跡がある場合は、## 画像エビデンス 節を表（ケース / 確認内容 / 画像）で本文に用意する。アップロード手順と禁止事項（画像の commit 禁止・local path 直書き禁止・user-attachments URL の使用・gh image extension の導入確認・--body-file での後付け更新等）は references/image-attachments.md に従う。

Mermaid記法ルール

ノードラベルは必ずダブルクオーテーションで囲む。 これはルールであり、推奨ではない。

必須形式

graph TB
    API["API Server"]
    DB["(PostgreSQL)"]
    Web["Web App\nsrc/frontend/"]

禁止形式

graph TB
    API[API Server]        ← NG: クオーテーションなし
    Web[Web App\nsrc/]     ← NG: 改行を含むラベルでクオーテーションなし

ルール詳細

• graph / flowchart の全ノードラベル: id["Label"] 形式を強制
• 改行を含むラベル: 必ず "Line1\nLine2" 形式
• 特殊文字を含むラベル（/, :, -, () 等）: 必ずダブルクオーテーション
• エッジラベル: -->|"ラベル"| 形式。クオーテーション必須
• ER図: エンティティ名はクオーテーション不要（USERS ||--o{ ORDERS）
• シーケンス図: participant 宣言の別名はクオーテーション不要（participant A as API）

出力ルール

• HEREDOC形式または --body-file 前提で出力する。 gh pr create --body "$(cat <<'EOF' ... EOF)" または gh pr edit --body-file - <<'EOF' ... EOF でそのまま使えるようにする
• 日本語で記述する
• 図と表を優先する。 長文の説明よりMermaid図とテーブルが優先
• 抽象→具体を基本とする。 L0→L1→L2→L3→L4の順を指針とするが、読者にとって自然な構成であれば柔軟に順序を調整して良い
• 関係ないセクションは出力しない。 optionalセクションは該当する場合のみ
• requireセクションは常に出力する。 「変更概要」「背景・課題・原因」「影響範囲」「懸念点・技術的負債」「Test Plan」は必須
• 懸念点は必ず書く。 「特になし」でも明示する。書かないのは隠蔽と受け取られる
• タイトルはCS視点で。 簡潔で分かりやすい言葉を選ぶ
• 画像つき本文は --body 直書きより --body-file を優先する。 改行崩れや shell escaping を避ける

注意事項

• 構造化PR本文の生成が中心責務である。 画像運用はその補助であり、本文の整理なく画像だけを貼るな（画像の手順詳細は references/image-attachments.md）
• pr スキルと組み合わせて使う。 pr の実行フロー 1〜6（ブランチ作成〜push）を実行した後、7「Pull Request 作成」の本文生成を本スキルで代替する
• module-boundary-designと併用せよ。 責務分割の判断に迷った場合は module-boundary-design を参照し、その判断根拠を「設計判断」セクションに反映する
• 分析は内部に留める。 階層ごとの分析結果をそのままPR本文に貼るな。統合して1つのストーリーにしろ
• AIの自己評価を鵜呑みにするな。 出力前に「この記述はコード差分と矛盾しないか」を自分で確認する
• 1万行を超える変更では、まずL0（システム構成）から始めよ。 詳細に飛びつく前に、全体像を掴む