pr-body-generator

PR Body Generator

Analyze changes implemented by AI usinga hierarchy of abstraction levels, and generate a PR body that lets humans immediately perceive the nuances.

Principles

From the big picture to the concrete. Use abstract → concrete as the basic order. However, when the change is small-scale or the reverse order is more natural for the reader, flexibly choose the structure.
Speak with diagrams and tables. Prioritize Mermaid diagrams and tables over long prose explanations.
Internally, doubt and verify; in output, convey the facts. The analysis process should be rigorous, and the PR body should be calm.
The AI determines the sections. Do not output sections unrelated to the change (but require is always included).
Use the Golden Circle as a thinking guide. Think in the order of Why (why it is needed) → How (how it was solved) → What (what was changed). However, do not fix this as the output format or template. Choose the optimal structure according to the situation.
Make it readable with zero prior knowledge. Add supplementary explanations for technical terms, and write so that the context is self-contained.

Title Guide

Assume the PR title may also be checked by CS (Customer Support), and make ita concise and easy-to-understand title.to.

Do not line up technical terms. fix: null check in getUserById rather than ユーザー詳細取得時のエラーを修正
Capture the essence of the change in one phrase. In words CS can understand, say what changed and who is affected.
The prefix is optional. fix:, feat: Follow existing conventions for prefixes such as these. Do not force them.
English is also acceptable. If the repository convention is English, English is fine. However, conciseness is the same.

Execution Flow

Step 0: Grasp the overall picture of the change

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

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

Understand which layers (infrastructure/backend/frontend/DB) the changes are concentrated in, and the sense of scale.

Step 1: Hierarchical Perspective analysis (internal thought process)

From the following5 layers, select those relevant to the change content and analyze them in order from the highest abstraction level. This analysis does not appear directly in the PR body. It is material for composing the body.

Layer catalog (abstract → concrete)

Level	Layer name	Target	Output format	When to choose
L0	System architecture	Connections between functional components, infrastructure configuration	Mermaid diagram	When there are changes across multiple layers or multiple services
L1	Data Structure	ERD overview, data model, relationships between entities	Mermaid ERD + Table	When there are changes to the DB schema or data model
L2	Communication / Interface	API endpoint list, request/response specifications, event definitions	Table	When there are changes to APIs, events, or messaging
L3	Processing Flow	Processing flow for each endpoint, external integrations, state transitions	Mermaid sequence diagrams/flowcharts	When there are changes to important business logic or external integrations
L4	Implementation Details	DB column details, frontend changes, infrastructure configuration details	Table	When specific implementation details need to be recorded

Analysis content for each layer (internal use)

Organize the following for each layer.

L0: System Configuration

Overall picture of functional components and connection relationships
Infrastructure configuration (servers, network, middleware)
Identification of components that changed
Addition, deletion, or change of boundaries

L1: Data Structure

Added, changed, or deleted entities
Relationships between entities (1:N, N:N)
Main columns and their meanings
Overview of data flow (where it is born, where it is stored)

L2: Communication / Interface

Added, changed, or deleted API endpoints
Main fields of request/response
Changes to authentication/authorization
Versioning/backward compatibility

L3: Processing Flow

Call chain of main processing
Timing and content of external service integrations
Error handling flow
Presence of asynchronous processing/queues

L4: Implementation Details

Types, constraints, and default values of main columns
Frontend component structure
Changes to environment variables and configuration files
Performance-related changes

Determination of Analysis Depth

Change Scale	Depth	Content
Lines changed < 50	Shallow	Only the description of the relevant layer
Lines changed 50-200	Standard	All fields of the relevant layer
Lines changed > 200 or 3 or more layers	Deep	All fields of all relevant layers + code excerpts

Step 2: Determination of PR Body Sections

Based on the analysis results, determine the sections to be output.

Section Determination Rules

Section	Category	Output Condition
Change Overview	require	Always output
Background, Issues, Causes	require	Always output
Scope of Impact	require	Always output
System Architecture Diagram	optional	When there are L0 analysis results (changes to multiple layers/services)
Data Structure	optional	When there are L1 analysis results (changes to DB/data model)
API Changes	optional	When there are L2 analysis results (changes to API endpoints)
Processing Flow	optional	When there are L3 analysis results (changes to business logic/external integrations)
External Integrations	optional	When there are changes to external services in L3
Frontend Changes	optional	When there are major UI/UX changes in L4
Infrastructure Changes	optional	When there are changes to infrastructure configuration in L0/L4
Design Decisions	optional	When there were important design decisions or trade-offs
Design Verification	optional	When analysis was performed at two or more layers
Concerns and Technical Debt	require	Always output (if none, write "None in particular")
Future Improvements	optional	When there are improvements to be made
Test Plan	require	Always output
Checklist	optional	When there are breaking changes, migrations, environment variable changes, etc.

Step 3: Constructing the PR Body

Construct the PR body using only the sections that were determined.

## 変更概要

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

## 背景・課題・原因

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

## 影響範囲

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

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

## システム構成図

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

```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で示す]

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

### 変更されたエンティティ

| エンティティ | 変更内容   | 主要カラム                                |
| ------------ | ---------- | ----------------------------------------- |
| `users`      | カラム追加 | `email_verified_at`, `last_login_at`      |
| `orders`     | 新規作成   | `id`, `user_id`, `status`, `total_amount` |

## API変更

### エンドポイント一覧

| Method   | Path             | 変更 | 概要                                   |
| -------- | ---------------- | ---- | -------------------------------------- |
| `GET`    | `/api/users/:id` | 変更 | プロフィール情報に検証ステータスを追加 |
| `POST`   | `/api/orders`    | 新規 | 注文作成エンドポイント                 |
| `DELETE` | `/api/sessions`  | 削除 | 旧セッション管理APIを廃止              |

### 主要なRequest/Response

**`POST /api/orders`**

| フィールド       | 型            | 必須 | 説明           |
| ---------------- | ------------- | ---- | -------------- |
| `items`          | `OrderItem[]` | ✓    | 注文商品リスト |
| `payment_method` | `string`      | ✓    | 支払い方法     |

## 処理フロー

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

```mermaid
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
```

## 外部連携

| 外部サービス | 用途           | 変更内容                          |
| ------------ | -------------- | --------------------------------- |
| Stripe API   | 決済処理       | 新規統合。`stripe-node` v14を使用 |
| SendGrid     | 注文確認メール | 新規統合。テンプレートID `d-xxx`  |

## フロントエンド変更

| コンポーネント    | 変更内容                 | 影響           |
| ----------------- | ------------------------ | -------------- |
| `OrderForm.tsx`   | 新規作成                 | 注文入力画面   |
| `UserProfile.tsx` | 検証ステータス表示を追加 | 既存画面の拡張 |

## インフラ変更

| 対象                 | 変更内容            | 影響                   |
| -------------------- | ------------------- | ---------------------- |
| `docker-compose.yml` | Redisサービス追加   | ローカル開発環境に変更 |
| GitHub Actions       | E2Eテストジョブ追加 | CI実行時間が+3分増加   |

## 設計判断

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

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

## 設計上の検証

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

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

## 懸念点・技術的負債

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

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

## 今後の改善事項

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

- [ ] [todo 1]
- [ ] [todo 2]

## Test Plan

### テスト項目

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

### 動作確認ポイント

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

### 自動テスト

```bash
# 実行コマンド例
```

## チェックリスト

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

Mermaid Syntax Rules

Node labels must always be enclosed in double quotes. This is a rule, not a recommendation.

Required Format

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

Prohibited Format

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

Rule Details

graph / flowchart all node labels: id["Label"] format is mandatory
Labels containing line breaks: Always use the "Line1\nLine2" format
Labels containing special characters（/, :, -, () etc.): Always use double quotes
Edge Label: -->|"ラベル"| format. Quotation marks are mandatory
ER Diagram: Entity names do not require quotation marks (USERS ||--o{ ORDERS）
Sequence Diagram: participant declaration aliases do not require quotation marks (participant A as API）

Output Rules

Output in HEREDOC format. gh pr create --body "$(cat <<'EOF' ... EOF)" format so it can be used as-is
Write in Japanese
Prioritize diagrams and tables. Mermaid diagrams and tables take priority over long-form explanations
Follow the basic principle of abstract to concrete. The guideline is the order L0→L1→L2→L3→L4, but the order may be adjusted flexibly if it makes for a more natural structure for the reader
Do not output irrelevant sections. optional sections only when applicable
require sections are always output. "Change Overview", "Background/Problem/Cause", "Scope of Impact", "Concerns/Technical Debt", and "Test Plan" are mandatory
Always write the concerns. Even if it's "Nothing in particular," state it explicitly. Not writing it will be taken as concealment
Titles should be from a CS perspective. Choose concise and easy-to-understand wording

Notes

Use in combination with pr.md. After executing Steps 1-6 of pr.md (branch creation through push), replace Step 7 (creating the PR body) with this skill
Use together with module-boundary-design. If you are unsure about how to divide responsibilities, refer to module-boundary-design and reflect the rationale for that decision in the "Design Decisions" section
Keep the analysis internal. Do not paste the per-layer analysis results directly into the PR body. Integrate them into a single story
Do not take the AI's self-assessment at face value. Before outputting, check for yourself whether "this description contradicts the code diff"
For changes exceeding 10,000 lines, start with L0 (system architecture). Grasp the overall picture before jumping into the details