| name | tomoasleep-pr-style |
| description | tomoasleep が書くような Pull Request の書き方を教えます。PR の説明文を書く・直す・レビューする・What/How/Why を整える・flaky 修正やバグ修正の説明を書くときは必ず使ってください。特に How が実装詳細に寄りすぎている場合や、Why に「なぜこの変更で直るのか」を検証可能に書く必要がある場合に使います。 |
Pull Request 説明文の特徴レポート
総合的な特徴まとめ
強み
- 一貫したテンプレート使用 — What/Why/How の構造が統一されている
- Issue へのトラッカビリティ — For https://github.com/... パターンで関連Issueを明示
- 設計意図の説明 — 「なぜこの方法を選んだか」「ボツにした案」を記載
- 実用的な補足 — 動作確認方法、依存関係、未対応事項を明記
- 適切な詳細度 — リポジトリ/変更規模に応じて詳細度を調整
スタイル
- 日本語メイン、英語タイトル
- 箇条書きと一文説明の使い分け
- カジュアルなトーン（「〜したい」「〜なので」）
- 括弧による補足を多用
- スクリーンショットで視覚的に説明（特にUI変更時）
構造的特徴：テンプレートの徹底活用
ほぼ全てのPRで、以下の構造化されたテンプレートが一貫して使用されています。これにより、レビュワーが必要な情報に即座にアクセスできる状態が保たれています。
## What (何をしたか):
## 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 が spec 内で作った record に限定される。対象外 record の id は対象 id に含まれないので、DB sequence の状態に依存しなくなる。
なお、本来は固定 id を spec に直接持ち込まない形にしていく方が望ましい。今回は flaky の原因になっている spec に閉じて、対象 id のリストを spec 内の test data に合わせることで修正する。
チェックリスト:
- `How` は実装詳細の羅列ではなく、アプローチを一文で説明しているか
- `Why` はサブ見出しで読みやすく分割しているか
- ソースコード URL があり、レビュワーが該当箇所を開いて確認できるか
- 失敗条件を具体的な値や作成順で説明しているか
- 「なぜこの変更で直るのか」が、変更後の条件と失敗条件の関係で説明されているか
- 今回対応しない将来的な改善案を、今回の修正方針と混ぜずに補足として書いているか
***
以上が、あなたのPull Request説明文の分析レポートです。**「構造化された記述」**と**「人間味のある文脈共有」**のバランスが特徴的であると言えます。
