こんにちは。スタディストのやも（@yamotuki）です。
2025年6月に入社して、この記事を書いている時点ではちょうどチームに配属されて1ヶ月くらいです。入社エントリの代わりにこの記事を公開したいと思います。
チームに早く馴染んで、開発に貢献したいという気持ちで頑張ってきましたが、そこで気がついたノウハウを言語化してみたいと思います。
というわけで、今回の記事のテーマは、「新しい環境でコードベースに慣れてプルリクエストを出すには」です。
プルリクエスト（以下プルリクと呼びます）を出すまでにはいくつかのステップがあるのですが、この記事では、コードを読むステップと、書くステップに大別して考えてみます。
前提の話
対象読者
Webエンジニアで、新しい環境で頑張っている人。
特に、フロントエンドとバックエンドが別れた構成を前提とする環境にいる方が対象です。
今回の話の例に使う題材
この記事の中で、例として使う事例を先に概要だけ紹介します。
タスク: 動画一覧に以下の情報を追加したい。
- 動画追加時間
- 動画追加者
画面イメージとしては以下のようなものになります（開発中かつ、厳密にはページではなくダイアログですが、本記事の本筋から離れるので詳細は省きます）
コードを読む編
概要としてはこの3ステップです。
- UIの動きと通信の流れを実際に触って理解する
- LLMを活用してコードの概略を理解する
- コード詳細を読む
1. UIの動きと通信の流れを実際に触って理解する
コードを直接読み始めても、なかなか頭に入るものではありません。まずは人間らしく、動きの理解から入ります。該当の機能については、先輩にエントリーポイントとなるページと動きについて聞きましょう。もしくは、過去の関連するプルリクのリンクが貰えれば、最低限のとっかかりとなるでしょう。
事例として挙げた動画一覧のケースだと、まずは、動画一覧が表示できるパスを聞きます。実際に動かしてみて、以下のような情報を調べます。
- 動画一覧の表示。今は何が項目として表示されているか。
- 動画の保存はどこでやっているか。入力は何か。
- 動画にひもづくユーザーの追加や削除はどこでやっているか
2. ネットワークタブでAPIの流れを理解
動きを見たら、次は、どのような流れで処理がされているか確認します。
Chrome の DevTools のネットワークタブを見て、実際の動きをAPIの外形から理解します。画像とかJavaScriptのダウンロードが多いとノイズなので、ネットワークタブをXHRで絞り込んで以下の情報を確認します。
- 使っているURLとHTTPメソッド
- 特に大事。この二つが分かると、ルーティング経由でどの実装か特定できることが多い
- ステータスコード
- そのURLのパラメータ、リクエストボディ、レスポンスボディをなんとなく眺めておく
事例として挙げたケースの動画投稿だと、実際には以下のような処理が走っていました。
- 動画一覧への投稿制限の前提確認APIを叩いてチェック
- アップロード先のS3エンドポイント取得API
- アップロードした結果をDBに登録するAPI
要件として「動画追加時間」と「動画追加者」を一覧に表示するというのがあったので、この一連の処理の流れの中で、どこに実装を追加すればいいのか想像します。(例えば、作成者についてはおそらく最後のAPIに認証情報として一緒に乗っているからそこから取ればいいのでは、とか)
この↑の流れは、言い換えると、今のタスクにおいて重要そうな箇所を想像するというプロセスです。今回のケースだと、UIの関わる箇所だったのでUIから入ってその付近の入出力をみました。
仮に、他のタスクだと、例えばバッチ処理だったり、DB保存処理だけが大事なケースもあると思いますが、プログラムの入出力を中心に追っていくというアプローチは同じなのかなと思います。結局のところ、プログラムというのは、何かを受け取って、加工して、そして吐き出す、という処理なので。
3. AIエージェントに相談する
処理の概要が理解できたら、それぞれのエンドポイントを詳細に読んで理解したいのですが、ここら辺でAIエージェントを召喚しましょう。
エントリーポイントと、処理のイメージを伝えた上で、大体のコードを読んでもらって答え合わせをしておきます。また、追加したい処理について、追加する場所について相談して、その方針が正しいか、他に選択肢があるとしたらどんなものがあるか壁打ちします。
このステップの相棒
- Cursor: とにかくコードを読むのが早いので、概略を掴むのと壁打ち相手に最適。
- Devin Search: Devin君に質問するモード。特にDeepモードにするとしっかり読み込んで答えてくれます。
プロンプトはそんなに凝らなくていいと思いますが、以下のように聞くといいかもしれません。
動画保存機能について理解したいです。/hoge/fuga において、「画面をキャプチャして保存」ボタンを押して画面キャプチャをして、動画を保存する流れです。
まずはs3に動画を保存してから、その後にDBに保存する処理の流れになっていると理解したのですが合ってますでしょうか？
また、DBの hoge_video の owner カラムに追加ユーザーを保存したいです。DBに保存するエンドポイントの中でやるのが適切だと思いますが、どう思いますか。
まずは実装ではなくて、全体像の確認をしたいです。
また、できるだけフラットな意見を聞きたいです。
※最後の２行は無くてももちろん動きますが、多くのLLMはこちらが提案するとそれに迎合したり、すぐ変更アクションしようとするので、それを緩和したい意図です。
4. コード詳細を読む
LLMなど使って概略がわかったら、泥臭いコードリーディングで詳細にコードジャンプをして読んでいきます。例えばマジックメソッドなどで飛びづらいところもLLMに相談しながらコードを追っていくと一段理解が深まります。
歴史があるプロダクトだと、全てを読むことはできないので、上で重要そうだと当たりをつけたところを中心に追っていきます。
慣れているIDEがあればそれでもいいのですが、新しい環境で特に慣れない技術を使っている場合には、先輩たちがどんなふうに快適に仕事をしているか聞いてみます。
私の場合のこのステップの相棒
- RubyMine（Jetbrains社のエディタ）: VSCodeやCursorより、デフォルト設定でコードジャンプできるところが多いので特に初学者におすすめ。
5. LLMを活用した理解の深掘り
上のコードリーディングの中で、処理の流れがわかりにくい場合には、全体像を聞いたコンテキストの中で詳細を解説してもらいます。
単に言語の構文がわからないとかを聞くだけなら、同じコンテキストの中ではなく、別のところで聞いてコンテキストを圧迫しない方がいい気がしています。
この時点で完全に理解する必要はないですが、処理の流れの概略が自分で説明できるようになっているくらいがいいと思います。
コードを書く編
さて、やっとコードを書くフェーズです。
概要としてはこの3ステップです。
- 課題背景と仕様を把握する
- 責務を意識した実装
- 共通処理の探索
1. 課題背景と仕様を把握する
コードを書き始める前に、改めて課題背景や仕様を把握しておきましょう。本当はコードリーディング前が望ましいと言えばそうなのですが、中身の話が分かっていない状態で何を作りたいか聞いても適切な擦り合わせができないことが多いため、このフェーズでやります。
このタイミングで、先輩と処理の流れの答え合わせと、実装箇所のイメージについて共有して擦り合わせをしてもいいかもしれません。
2. 責務を意識した実装
コードを書きます。コードの書く場所は、その追加するコードの責務を意識して配置します。責務についての話はここに書くとキリがないので端折りますが、ざっくりイメージをしてもらうために少しだけ書きます。
例えば、動画追加日時についてだと、値を返すという処理と、値を整形するという処理を書くことになります。バックエンドのモデルやプレゼンテーション層で値の整形するというのも、もちろん動くコードにはなります。しかし、APIは値を返すのに徹して、整形はフロントエンドに任せた方が良さそうです。日時の表示形式については単に表示の見た目の調整であるという感覚から、フロント側に責務がありそうです。そのように責務に則った配置にすると、表示箇所（一覧か詳細かとか）によって日付まで出したいとか秒まで出したいとか、そういった要件に柔軟に対応しやすいことが多いです。
このステップでの相棒
- Claude Code: Opus モデルが使えるならコードを書くときにおすすめ、でもコードベースを理解しながら実装していくなら、よく喋るCursorで相談しながら進めた方が学びが深いので、最後の仕上げに登場してもらう方が個人的には好き。Claude Codeは寡黙な印象。
仕上げにをする時にはこんなプロンプトを使うことがあります。エラーで動かない時とかも、同じようにコミット差分だけ見てもらうと効率的です。きっと git diff を使って差分を見て最適な提案をしてくれます。
コミット番号 70e7e6f から dbafe00 の間の差分についてプルリクを作ろうと思っています。無理な設計になっていたり、書いたコードがあるべきレイヤに配置されていない懸念がある場合には教えてください。コード詳細でも懸念点や改善点があったら教えてください。
3. 共通処理の探索
大体コードを書いたら、プルリクを出す前にセルフレビューをします。もちろん変なコードがないか、理解が甘いところがないか、そういうチェックはした方がいいです。ただ、今回の記事の趣旨で言うと、「共通処理の探索」をしてからプルリクを出す方がいいのではという話を伝えたいです。
歴史があるコードベースでも、ちゃんとしたエンジニアが多い環境であれば、DRY原則に則って共通のコードが整理されていることが多いです。
自分が長期保守するとして、共通処理になっているべきであろうというパターン（たとえば動画関係処理や、日時整形処理）に対して、自分の実装がそうなっていない場合には、その仮説をもとにAIエージェントに探させます。自分の実装の意図と合致する処理があったら積極的に流用しましょう。
こういう時に使うプロンプト
日時をフォーマットしている箇所は一般的な処理なので、沢山あるはずです。他の実装コードを読み込んで、最適な共通処理があるか確認してください。
※DRYとは: 「Don't Repeat Yourself」の略で、ソフトウェア開発における設計原則の一つ。同じ機能や情報を複数の場所に重複して記述しないようにすること
その他のノウハウ
コードの読み書きにあたって、他の重要だと思ったその他のノウハウについて羅列しておきます。
触るコードベースを絞る
一気にいろんなところに手を出さないこと。コードを読むのは大変な作業。小さいタスクだから大丈夫、と思って全然違うところのタスクを引き受けると、ずっとコードリーディングすることになり辛い時期が伸びます。一見大変だけども、一つの中規模プロジェクトに組み込まれた方が、読むべきコードを絞れるので知識を使いまわせて効率的なこともあります。
リファクタリングに慌てない
過去の経緯があって現状になっているので、違和感を感じても大きなリファクタリングについては慌てないこと。仮説だけ頭に残しておく。現状で違和感があったら、初期コードでどういう構成だったら今のコードになるのか想いを馳せると、案外妥当なコードだなと思うこともあるでしょう。AIエージェントに違和感を伝えて、あり得た過去の経緯を推測させるなんてのもやってみてもいいと思います。
終わりに: 入社1ヶ月の自分と、似た状況にある方々に向けて
新しい環境でコードベースに慣れるには、気合が必要です。しかし真面目にやっていれば頭の中にコードベースがマッピングされて、どんどん仕事が楽になっていくはずなので頑張っていきましょう。
（相棒として紹介しましたが、色々ツールを使わせてもらって本当にありがたいことです。スタディスト社は生産性を高めるためにツール・AIへの投資に積極的です。慣れてきたら使うツールは絞ろうと思ってます。）
Discussion