コードレビューで「また修正か…」を減らす。エンジニア視点の要件整理の秘訣｜現場で使える実践テクニック

こんにちは！

今日は「コードレビューで何度も修正指摘されるのをどうやって減らすか」について、僕の失敗談を踏まえて解説します。

コードレビューで修正が増える本当の理由

僕も昔、後輩のコードレビューをするたびに「あ、こここうなってないな」「え、なぜこの実装？」みたいに指摘がめっちゃ増えちゃってた時期があるんです。
当時は「この子、要件を理解してないのかな」って思ってたんですけど、実は違ったんですよ。

問題は「要件書には書いてあるけど、実装者にとって曖昧だった」っていうところだったんです。
例えば、要件書には「ボタンをホバーで色を変える」って書いてあっても、エンジニアからすると下記のような疑問が出てくるんですよ。

• どの色に変わるのか（RGB値？デザインファイルのどのカラー？）
• アニメーション時間は何秒か
• トランジションのイージングは？
• モバイルではどうなるのか（タップ時？長押し時？）
• デバイスがホバーに対応していない場合は？

これらが明確になっていないから、エンジニアが「こんな感じかな」って実装して、レビューで引っかかるんです。
実は「修正が多い」のって、エンジニアのせいじゃなくて、事前の擦り合わせが不足してるんですよ。ほんま。

エンジニアに「実装の前」に確認してもらうべき3つのこと

僕が現場で気をつけるようになったのは、実装前に「技術的な詳細」をエンジニアと一緒に詰めることです。
具体的には、下記の3つですね。

1. ブラウザやデバイスごとの動作の違い

デザイナーが作ったビジュアルは、めっちゃ綺麗なPC画面で見た状態なんです。
でもエンジニアは「タブレットではどうなるの？」「古いブラウザでは？」って自動的に考えるんです。
実装前に「このデバイスはサポート対象？」「このブラウザのバージョンは対応する？」って確認しておくと、後でやり直しになりません。

例えば、position: stickyを使う要件があったとしましょう。
IE11を対応ブラウザに含める場合、このプロパティは使えないので、JavaScript代替案が必要になります。
実装後に「あ、IE11対応だった」ってなると、めっちゃ手戻りですやん。

2. エッジケース（想定外の状況）の扱い

これは現場あるあるなんですけど、要件書には「成功時の画面」しか書いてないんです。
でも実装するには「テキストが長かったら？」「画像が読み込めなかったら？」「エラーメッセージが複数出たら？」みたいな例外処理も考えておく必要があるんですよ。

実装前にエンジニアと一緒に「こういうケースはどうする？」って話し合っておくと、コードレビューで「あ、これはどうするんですか？」って止まることがなくなります。

3. パフォーマンスや技術的な制約

デザイナーが「このセクションに30個の画像をスライドショーで表示する」って要件を出したとします。
エンジニアからすると「30個全部読み込むと、ページ速度が落ちるな」って気づくんです。
実装前に「遅延読み込みでいい？」「最初は5枚だけ読み込んで、あとはオンデマンド？」って決めておくと、スムーズですよ。

技術的な制約も早めに共有しておくことが大事です。

要件を「実装できる言語」に翻訳するコツ

ここからが僕が一番大事だと思ってることなんですけど、要件をエンジニアが「実装しやすい言葉」に落とし込むことなんです。

デザインの指示を「具体的な数値」に変える

NG例：「ボタンを目立つようにしてください」
OK例：「ボタンのパディングを左右16px、上下12px。フォントサイズは16px、背景色は#FF6B35、テキストカラーは#FFFFFFです。」

要件書に「目立つ」って書いてあっても、エンジニアは実装できません。
デザインファイル（FigmaとかXDとか）から、実装に必要な情報を抽出して、テキストで伝えるといいですよ。

条件分岐を「if-then-else」で書く

NG例：「レスポンシブ対応でお願いします」
OK例：「画面幅768px以上ではグリッドレイアウト3列。767px以下ではスタック表示（1列）です。」

エンジニアは基本的に「条件付きの指示」で思考します。
「いつ、どうなるか」を明確に書いてあると、実装が早いし修正も少ないんです。

代替案も一緒に提案する

例えば、デザイナーが「このテキストはホバーでツールチップを表示」って要件を出したとします。
エンジニアの視点では「タッチデバイスではツールチップが使えないから、タップ時にモーダル開く？」みたいな質問が出てくるんです。

実装前に「モバイルではこうする」って決めておくと、エンジニアは迷わず実装できるんですよ。

まとめ

コードレビューで修正が増える理由は、ほぼ「実装前の擦り合わせ不足」です。
デザイナーやディレクターが「要件書に書いてある」と思ってることでも、エンジニアにとって曖昧な部分がいっぱいあるんですよ。

大事なのは、実装前に「技術的な詳細」を一緒に詰めること。
ブラウザ対応、エッジケース、パフォーマンスの制約を事前に共有しておくと、コードレビューはめっちゃ早く進みます。
そして何より、修正指摘が減るから、エンジニアのモチベーションも上がるんです。

要件を「実装できる言葉」に翻訳するクセをつけると、チーム全体の効率が上がりますよ。
ぜひ試してみてくださいね！