この記事は、Finatext Advent Calendar 2025 の10日目の記事です。
はじめに
こんにちは。Finatextでバックエンド・インフラエンジニアをしている @takuma5884rbb です。
ここ1年くらいは新卒採用の場にも結構出ています（採用サイトもリリースしました！）
さて、社会人3年目が終わろうとしている今日この頃ですが、Pull Request（以下、PR）の作り方について私なりに意識していることをまとめてみました。
ジュニア寄りの内容にはなりますが、そろそろジュニアとは言ってられない私が無事ジュニアを卒業する禊としてまとめているところもございますので、ご辛抱の上お付き合いください。
前提
この記事で話すこと
- 私がPR作成に記載することを個人的に心がけていること
- 私の周囲でのGitHub運用方法
この記事で話さないこと
- Git/GitHubの仕様
コーディング前：設計を整理してから書き始める
いきなりコードを書き始めるのは避けましょう。コーディング前に以下のような点を確認しておくと、スムーズに実装を進められます。
まず、実装に必要なデータや情報が揃っているか確認します。データが足りない場合、途中で実装方針を変更せざるを得なくなり、PRが大きくなる原因になります。
次に、必要なインターフェースが揃っているかチェックします。例えば、repositoryやadapterのinterfaceが不足していると、後から追加することになり、PRのスコープが広がってしまいます。
また、外側のレイヤーから実装を始めると、依存する内側の実装も同じPRに含めることになり、結果として大きなPRになりがちです。1つのPRには1つのスコープという原則を守ることを意識しましょう。
最後に、最初から綺麗な分割を考えるのは大変なので、まずは愚直に逐次的に書いた後、テストを書き、それを壊さないようにリファクタリングしていくアプローチがおすすめです。いわゆるテスト駆動開発の考え方ですね。
コーディング中：コンテキストを残す
コードを書く際は、単にコードだけでなく、コードに表れない意図やコンテキストをコメントとして残すことが大切です。
PRはコード差分とDescriptionで主に構成されていますが、この内コード差分はプログラムの振る舞い、つまり"how"の変化を表します。したがってDescriptionは"how"以外の要素ー"what"や"why"ーを盛り込むことで情報量を増やす必要があります。逆に言えば、"how"の情報を表すのみの文章、コメントは情報量が増えない（増えるようなら、ロジックの整理や関数の責務の見直しなど、コードの複雑さを減らすべき）ので不要ということになります。生成AIはこの辺りのコメントを吐きがちですが、残しておいても目が滑るだけなのでこまめに消しておきましょう。
単純なロジックであるほど、AIはhowを上手に説明する（Claude Codeの例）
例えば、実装を試行錯誤した末に今の形に落ち着いた箇所があれば、コメントで補足しておきます。自分が迷った箇所は、レビュワーも「これではダメなのか」と疑問に思う可能性が高いからです。先回りして説明を残しておくことで、レビュワーの理解を助けられます。以下は、環境変数を読み出す初期化処理を記述する際、本番運用を見据えたフェイルセーフの機構を考えたときのコメントです。
who not を端的に表したコメント例
また、自分の周囲ではsquash mergeの運用を進めています。正直コーディング中はかなり試行錯誤するので、綺麗な機能単位でコミットを作ることに固執するのは個人的にはあまりいいことだとは思っていません（OSS開発などではまた話は違うことは認識しています）。mainブランチの履歴さえ綺麗であれば未来の開発者はそうそう困らないと思うので、最後にsquashして綺麗にすればいいよね、という感じです。リリースフローもGitHub Flowを用いているため、そこまで困ることはないです。
コーディング後：俯瞰してセルフレビューする
コーディングが終わったら、すぐにレビュー依頼を出すのではなく、一旦draftの状態でPRを作成し、差分全体を見渡しましょう。
俯瞰するだけでも見えてくるものは多く、タイポや不要なコード、命名の不整合などに気づけます。また、最近ではGitHub CopilotなどのAIレビュー機能を活用すると、凡ミスやちょっとした命名の不整合を自動で拾ってくれるので便利です。自分はコーディングの途中で命名の方針を変えたまま直し切るのを忘れたりするので、かなり助かっています☺️
RulesetによってCopilotのレビューを義務化できる他、copilot-instruction.mdの設定によって日本語レビューもしてくれます。
GitHub Copilot設定画面の例
また、そこまで一般的ではないとは思いつつ続けている習慣として、レビューをもらって修正する際は、1つのレビューに関連する修正内容を1つのコミットにまとめ、そのリンクをレビューコメントに返信する形を取る、というものをやっています。複数のレビューが付いた場合、修正後に改めてコード差分を確認すると、どこが変わったのか、デグレはしていないか、を一目で確認することが難しく、初回と同等の時間を使ってしまうこともあります。レビューとコミットを対応させることで、レビュワーが修正内容を確認しやすくなり、指摘が想定通りに反映されているか一目で分かるようになります。
レビュー対応したcommitをコメントに返信で紐づけている例
終わりに
以上、3年弱のチーム開発を通して身につけた術をまとめてみました。PRを作成する側だけでなく、レビュワーとして他の人のPRを見る機会も増えたことで、読みやすいPRとは何か、どんな説明があると理解しやすいかといった気づきが得られた気がします。
また、PRの書き方はAIへのプロンプトの書き方に通じるところもあるかもしれません。ClineやClaude CodeといったAIエージェントは、プロンプトを解釈したりリポジトリのコードを読んだりして、実装の道筋を立てています。ここでプロンプトが適当だと、方針を迷ったり変な実装を吐いたりしてしまいますし、逆にアーキテクチャの説明を与えてやると、ちゃんとそれに沿って実装してくれたりします。PRに必要な実装を一括で載せることは、レビュワーのコンテキストに必要な情報を与えることに繋がり、スムーズなレビューを行うことができるようになるのです！
この記事が、皆さんのPR作成の参考になれば幸いです。
Discussion