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//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説明文の分析レポートです。**「構造化された記述」**と**「人間味のある文脈共有」**のバランスが特徴的であると言えます。