Tomoasleep Pr Style

---
name: tomoasleep-pr-style
description: tomoasleep が書くような Pull Request の書き方を教えます。
---

# Pull Request 説明文の特徴レポート

## 総合的な特徴まとめ
### 強み

1. 一貫したテンプレート使用 — What/Why/How の構造が統一されている
2. Issue へのトラッカビリティ — For https://github.com/... パターンで関連Issueを明示
3. 設計意図の説明 — 「なぜこの方法を選んだか」「ボツにした案」を記載
4. 実用的な補足 — 動作確認方法、依存関係、未対応事項を明記
5. 適切な詳細度 — リポジトリ/変更規模に応じて詳細度を調整

### スタイル

- 日本語メイン、英語タイトル
- 箇条書きと一文説明の使い分け
- カジュアルなトーン（「〜したい」「〜なので」）
- 括弧による補足を多用
- スクリーンショットで視覚的に説明（特にUI変更時）



## 構造的特徴：テンプレートの徹底活用

ほぼ全てのPRで、以下の構造化されたテンプレートが一貫して使用されています。これにより、レビュワーが必要な情報に即座にアクセスできる状態が保たれています。

*   **`## What` (何をしたか)**:
    *   実装の概要。
    *   Issueへのリンク。
*   **`## How` (どうやったか)**:
    *   設計の概要、技術選定の理由。 意思決定プロセスが開示されている。
*   **`## Why` (なぜやったか)**:
    *   背景、解決したい課題。Issueがない場合の補足。

## 記述スタイルの特徴

### 1. 徹底したコンテキストの紐付け ("For" パターン)
PRの冒頭、特に `What` や `Why` セクションにおいて、**`For <Issue URL>`** という形式で、対応するIssueへのリンクを貼る習慣が徹底されています（有意なPRの約半数で確認）。

また、設計の根拠として社内ドキュメントや Slack のスレッドへの参照 (`Ref: ...`) が頻繁に登場し、**「なぜその実装になったか」の文脈**をコード外の情報源と強く結びつけています。

### 2. 「意志」と「感情」の記述
単なる作業報告にとどまらず、開発者としての**意志やモチベーション**が率直に語られる傾向があります。

*   *「〜が面倒なので、まとめて実行できるようにして、**考えるコストを減らしたい**」*
*   *「**こればっかりは動かしてみないとわからんので**試行錯誤でやる」*
*   *「**今後〜したい。そのために**〜できるようにしたい」*

このように、「現在の変更」だけでなく「未来の展望」や「個人的な動機」を含めることで、レビュワーに対して変更の妥当性を訴求しています。

### 3. AI / 自動化への投資
PRの内容自体にも特徴があり、自身の開発効率を向上させるための「環境整備」に関するPRが多く見られます。

*   **AI Agent Skills の追加**: AIアシスタントに特定のタスク（例: 特定言語の型定義、テストコードの記述）を行わせるための「スキル定義ファイル」を追加するPRが複数ある。
*   **タスクランナーの整備**: `make` や `rake` 等のタスクを整備し、開発手順を簡略化するPR。

## セクション毎の書き方

### What セクションの書き方

#### パターンA: 箇条書きで変更内容を列挙

```
## What
XXX に対して以下の変更を行う。リファクタリングで挙動の変更はほぼ無い。
- feature_dirs/xxx 用の AGENTS.md を追加する (この package 固有の事項を書く)
- XXX で行っていた AAA のチェックを、 XXX 側から YYY 側に移動する。
```

#### パターンB: 一文で簡潔に

```
## What

xxx するタスクを全部まとめた yyy task を追加する。 (zzz から実行できる)
```

### パターンC: 補足セクションを追加

```
## What

GitHub Actions で yaml anchor が使えるようになったので、設定を yaml anchor で統一する。

### 細かい差異も減らす

微妙に設定が違うことがあったので、これらは極力統一した。
```

### パターンD: 関連 Issue を明示

```
## What

For https://github.com/example-org/some-repository/issues/104

xxx を出来るようにする。
```


### Why セクションの書き方


#### 特徴的なパターン:

「〜したい」で動機を表現

```
## Why

今後、XXX Feature を追加したい。
そのために、Feature 毎に必要な権限をカスタマイズできるようにしたい。
```

#### 問題点を明示

```
## Why
CI で xxx を忘れて怒られることまあまああり、毎回どのタスクを実行すればいいか調べるのが面倒。
なので、 `task-runner xxx` でまとめたら全部実行できるようにして、考えるコストを減らしたい。
```

#### Ref: でドキュメントへリンク

```
 Why
Ref: [Agent Skills をどんどん書いていきませんか - Internal Docs](https://internal-docs.example.com/items/12345)
```

***

以上が、あなたのPull Request説明文の分析レポートです。**「構造化された記述」**と**「人間味のある文脈共有」**のバランスが特徴的であると言えます。