開発の流れ

ここまでは道具の話でした。この章からはチームでソフトウェアを作る流れの話をします。

新人が最初に戸惑うのは、技術そのものより「何をどの順番でやるのか分からない」ことです。 コードは書けるのに、チケットを渡された瞬間に手が止まる。これは能力の問題ではなく、 単に流れを知らないだけです。

ソフトウェアが作られる1周

Web サービスの開発は、だいたいこの輪を回し続けています。

   ┌─────────────────────────────────────────────┐
   │                                             │
   ▼                                             │
[要求]→[設計]→[実装]→[レビュー]→[テスト]→[デプロイ]→[運用・計測]
                                                 │
                                          ここで得た学びが
                                          次の要求になる

大事なのは、これが一方通行ではなく輪だということです。 「作って終わり」ではなく、出したあとに数字を見て、次を決めます。

あなたが最初に任されるのは、この輪の中の [実装]→[レビュー] の部分です。 ただし前後を知らないと、良い実装はできません。

チケットから始まる

仕事はたいてい「チケット」という単位で渡されます（Jira / GitHub Issues / Linear など）。

着手前に確認すること

チケットを読んで、すぐコードを書き始めてはいけません。 まず次を確認します。

1. 何を作るのか — 期待される振る舞いが書いてあるか
2. なぜ作るのか — 背景。これが分かると設計判断ができる
3. どこまでやるのか — 対象外の範囲が明示されているか
4. 完了の条件は何か — 何をもって「できた」とするか

書いていないことは聞く

新人が遠慮しがちなポイントですが、仕様が曖昧なのはチケットを書いた人の責任です。 聞かれた側も「そこ決めてなかった」と気づけるので、聞くこと自体がチームへの貢献になります。

聞き方の例です。

このチケットについて確認させてください。 検索対象は商品名だけでしょうか、説明文も含めますか？ 実装の手戻りを避けたいので、先に決めておきたいです。 （自分の考えとしては、まずは商品名だけで出すのが早いかと思っています）

最後の1行がポイントです。自分の案を添えると、相手は「はい」か「いいえ」で答えられます。 丸投げの質問より、はるかに早く返事が来ます。

既存コードの読み方

新人が入社してから最初の1ヶ月、業務時間の7〜8割は「読む」時間です。 書くのはその後です。ところが「コードの読み方」を教わる機会はほとんどありません。

全部読もうとしない

10万行のリポジトリを頭から読むのは不可能ですし、意味もありません。 必要な経路だけを辿ります。

入口から辿る

Web アプリなら、必ずどこかに入口があります。

HTTP リクエスト
  → ルーティング定義（どの URL がどの関数に繋がるか）
    → ハンドラ / コントローラ
      → ビジネスロジック
        → データベースアクセス

「商品検索の処理を直して」と言われたら、まずルーティング定義を探します。 /search のような URL がどの関数に繋がっているかが分かれば、そこから下に辿れます。

具体的な探し方

git log は優秀な資料

「なんでこんな変な実装になってるんだろう」と思ったコードがあったら、履歴を見ます。

git log -p path/to/file.go     # そのファイルの変更履歴と差分
git blame path/to/file.go      # 各行を最後に変えた人とコミット

たいてい何か理由があります。障害対応の名残、特定の顧客要件、外部 API の癖。 それを知らずに「きれいに」書き直すと、直っていたバグが復活します。

実装中に何をしているか

実装は「エディタでコードを書く」だけの作業ではありません。実際はこのループです。

書く → 動かす → 期待と違う → 原因を調べる → 直す → 動かす → ...

この「原因を調べる」が実装時間の大半です。だからコマンドラインで生きるのログ調査や、 デバッガの使い方が効いてきます。

動かす環境を先に作る

実装より先に、変更を確認できる状態を作ってください。

• ローカルでサービスが起動するか
• テストが走るか
• 変更が画面（またはレスポンス）に反映されるか

ここが整っていないまま書き進めると、最後にまとめて動かして総崩れになります。

PR の出し方

実装ができたら Pull Request（PR）を出してレビューを受けます。

小さく出す

これが新人が最初に覚えるべき最重要の習慣です。

800行の PR は、レビュアーにとって1時間の仕事です。 150行なら10分です。人は10分の仕事はすぐやりますが、1時間の仕事は後回しにします。

しかも大きい PR ほどレビューは雑になります。 「全体的に良さそう」で通ってしまい、バグが本番に流れます。

機能を分割できないか、常に考えてください。 「DB のテーブル追加」「API の追加」「画面の追加」は別々の PR にできることが多いです。

説明に書くこと

PR の説明は、レビュアーがコードを読む前に読むものです。ここが良いとレビューが速くなります。

## 何を
商品検索に、説明文も検索対象に含める機能を追加します。
 
## なぜ
商品名にキーワードが入っていない商品が検索から漏れており、
問い合わせが月10件ほど来ているため（チケット: PROJ-123）。
 
## どうやって
Spanner の全文検索インデックスに description カラムを追加し、
検索クエリの対象に含めました。
 
## 確認したこと
- ローカルで「送料無料」を検索し、説明文だけに含む商品が出ることを確認
- 既存の商品名検索の結果が変わらないことを確認
- 検索レイテンシが 120ms → 145ms（許容範囲内と判断）
 
## レビューで特に見てほしいところ
検索クエリの組み立て（src/search/query.go）。
インデックスの使われ方に自信がありません。

レビューの受け方

指摘は人格への評価ではない

これは頭では分かっていても、最初は落ち込みます。 指摘が20個ついた PR を見ると「自分はダメだ」と思います。

でも実際は、コードの品質をチームで担保する仕組みが動いているだけです。 シニアエンジニアの PR にも普通に20個つきます。

指摘への対応

言われた通りに全部直すのが正解ではありません。 理由を理解せずに直すと、次も同じ指摘を受けます。 「なぜそうすべきか」を聞くのは、レビュアーにとっても歓迎される質問です。

用語

「動いた」と「終わった」の違い

新人が最も誤解しやすいところです。

手元で動いた = 終わった、ではありません。

チームには「完了の定義（Definition of Done, DoD）」があります。だいたいこんな内容です。

• 実装が終わっている
• テストが書かれていて、通っている
• レビューで承認されている
• ステージング環境で動作確認した
• ドキュメント（README / API 仕様）を更新した
• ログ・メトリクスを仕込んだ

「動いたので終わりました」と報告してからこれらを求められると、 見積もりが崩れます。最初から DoD を見て計画してください。

デプロイと運用

コードをマージしたら終わり、ではありません。本番に出てからが本番です。

環境の種類

ステージングで確認せずに本番に出さない、が基本です。

段階的に出す

Web サービスでは、いきなり全ユーザーに出さない仕組みがあります。

炭鉱のカナリアが語源です。「出す」より「戻せる」ことの方が重要、という思想です。

出したあとに見るもの

デプロイしたら、最低30分は張り付いて次を見ます。

• エラー率が上がっていないか
• レイテンシ（応答時間）が悪化していないか
• ログに知らないエラーが出ていないか

ケーススタディ: 800行の PR

新人の A さんが、検索機能の改善を任されました。

Day 1-4   実装に集中。DB のスキーマ変更、API 追加、画面の修正を一気に進める
Day 5     完成。800行の PR を出す
Day 6-8   レビューが返ってこない（レビュアーが時間を確保できない）
Day 9     レビューが来る。「設計から相談したかった」と指摘。DB 設計をやり直し
Day 12    ようやくマージ

もし PR を分割していたら、こうなりました。

Day 1     DB スキーマ変更だけの PR（80行）→ 翌朝マージ。設計の誤りをここで発見できた
Day 2-3   API 追加の PR（150行）→ その日にレビュー、翌日マージ
Day 4-5   画面修正の PR（120行）→ 翌日マージ

同じ作業量でも、5日と12日の差が出ます。 そして分割した方が、設計の誤りを Day 1 で発見できています。

ケーススタディ: ログがなかった

B さんの実装した決済処理が、本番で「たまに失敗する」と報告されました。

再現できません。ログには error: payment failed としか出ていませんでした。

• どのユーザーで失敗したのか分からない
• 外部の決済 API のどのレスポンスで失敗したのか分からない
• 何回目のリトライで失敗したのか分からない

結局、ログを足す PR を出し、本番に反映し、再発を待って、3日後にようやく原因が分かりました。

ログは「動かすため」ではなく「後から調べるため」に書きます。 実装している時は全部分かっているので不要に思えますが、 3ヶ月後の自分と、深夜に障害対応する誰かのために書いてください。

実務の落とし穴まとめ

1. 仕様が曖昧なまま着手する — 確認は5分、手戻りは3日
2. PR を大きく出す — レビューが返らず、しかも雑になる
3. 「動いた」で完了報告する — DoD を先に見る
4. ログを仕込まない — 障害時に原因が特定できない
5. 既存コードを全部読もうとする — 必要な経路だけ辿る
6. git blame を見ずに書き直す — 直っていたバグを復活させる

まとめ

• 開発は輪。作って終わりではなく、出したあとの数字が次の要求になる
• チケットは着手前に「何を・なぜ・どこまで・完了条件」を確認する
• 新人の仕事の7割は読むこと。入口から辿り、grep し、ログを入れて確かめる
• PR は小さく出す。800行は3日放置され、150行は当日見てもらえる
• レビューの指摘は人格への評価ではない。納得できなければ議論していい
• 「動いた」と「終わった」は違う。DoD を先に確認する
• 本番に出してからが本番。戻せることが出せることより重要

公式ドキュメント

迷ったら一次情報に戻ってください。

次の章では、この流れの中で最も時間を使う作業—— 初めて見るコードベースをどう読むかを扱います。