Tomoasleep Pr Style

---
name: tomoasleep-pr-style
description: tomoasleep が書くような Pull Request の書き方を教えます。PR の説明文を書く・直す・レビューする・What/How/Why を整える・flaky 修正やバグ修正の説明を書くときは必ず使ってください。特に How が実装詳細に寄りすぎている場合や、Why に「なぜこの変更で直るのか」を検証可能に書く必要がある場合に使います。
---

# 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)
```

#### flaky 修正やバグ修正では、コードから分からない理由を検証可能に書く

`How` にはコードを読めば分かる実装詳細を並べない。アプローチを一言で書く。

`Why` には、レビュワーがコードや CI ログを辿って検証できる形で「なぜ落ちていたのか」「なぜこの変更で直るのか」を書く。

以下を意識する。

- 失敗条件を具体的に書く
- 該当するソースコード URL を添える
- 「対象外のつもり」「たまたま」「依存している」などの曖昧な表現だけで済ませない
- 具体的な値や作成順が重要なら例を出す
- 最近落ちやすくなった理由が推測できるなら、推測であることが分かる文で書く
- 将来的な改善案と今回の修正方針を分けて書く

例:

```
## How

この spec 内で作った campaign の id だけを Tech Festa 2026 の対象 campaign id として扱うようにする。

## Why

### flaky が起きていた理由

修正前の spec では、Tech Festa 2026 対象の campaign を `tech_festa2026.posting_campaign_ids` の固定 id で作り、対象外 campaign は id を指定せず通常の factory で作っていた。

- 対象 campaign を固定 id で作っている箇所
  https://github.com/example/repo/blob/<sha>/path/to/spec.rb#L10-L11

- 対象外 campaign を id 未指定で作っている箇所
  https://github.com/example/repo/blob/<sha>/path/to/spec.rb#L12

たとえば、対象 campaign として `id: 155` / `id: 156` を作ったあと、次に id 未指定で対象外 campaign を作る。DB sequence がまだ 156 未満だった場合、次の id として `157` が採番されやすい。

`157` が対象 id の一覧に含まれている場合、spec 上は対象外として作った campaign が、実際の集計条件では対象 campaign として扱われる。

- 集計条件
  https://github.com/example/repo/blob/<sha>/path/to/model.rb#L20-L23

そのため、対象外記事に付けた likes が ranking に混ざり、期待している件数より多く返って flaky になる。

### 最近落ちやすかった理由

今回の flaky は「対象外 campaign がたまたま対象 id に被る」だけではなく、修正前の作成順だと `157` が採番されやすい条件になっていた。

```text
id: 155 の target_campaign を作る
id: 156 の other_campaign を作る
次に id 未指定で non_target_campaign を作る
DB sequence が 156 未満なら 157 が採番される
157 は対象 campaign id に含まれる
```

この spec が auto increment がまだ十分に進んでいない DB worker で実行されると、高確率で失敗条件を踏む。最近落ちる確率が高く見えたのは、CI の test split や並列 worker の割り当てによって、この spec がそういう DB sequence 状態で実行されやすくなったためだと考えている。

### なぜこの変更で直るのか

今回の変更では、固定 id を test data として直接使うのではなく、この spec 内で factory により作った record の id を対象 id として扱うようにする。

- 変更後の対象 id の定義
  https://github.com/example/repo/blob/<sha>/path/to/spec.rb#L30-L33

これにより、集計で対象になる id が spec 内で作った record に限定される。対象外 record の id は対象 id に含まれないので、DB sequence の状態に依存しなくなる。

なお、本来は固定 id を spec に直接持ち込まない形にしていく方が望ましい。今回は flaky の原因になっている spec に閉じて、対象 id のリストを spec 内の test data に合わせることで修正する。
```

チェックリスト:

- `How` は実装詳細の羅列ではなく、アプローチを一文で説明しているか
- `Why` はサブ見出しで読みやすく分割しているか
- ソースコード URL があり、レビュワーが該当箇所を開いて確認できるか
- 失敗条件を具体的な値や作成順で説明しているか
- 「なぜこの変更で直るのか」が、変更後の条件と失敗条件の関係で説明されているか
- 今回対応しない将来的な改善案を、今回の修正方針と混ぜずに補足として書いているか

***

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