設計意図が曖昧なときレビューアーがすべき補完アプローチ

レビューの現場で最も多くのレビューアーが手を止める場面がある。
それが「この設計、意図が読み取れないけど、どこまで突っ込んでいいか分からない」という状態だ。
仕様の欠落でもなく、明確なバグでもない。それでも「何かがはっきりしない」と感じさせるコードは少なくない。

このマニュアルでは、レビューアーが設計意図の曖昧さに直面したときにどう立ち回るべきかを、視点・姿勢・技術の3層から解説する。
「正解を知っている前提のレビュー」から脱却し、「正解が不明なときのレビュー支援力」を高めるための実践知である。

1. 設計意図が曖昧な状態とは何か

意図が曖昧なコードには共通する特徴がある。

• 書かれている内容は正しいが、なぜその構造にしたかが読み取れない
• 実装は可能だが、ユースケースとの結びつきが見えにくい
• 分岐やデータ構造の選択に判断根拠が示されていない

これは、「コードとして動くか」という観点では問題がないが、「チームとして保守可能か」「設計判断が共有できるか」という観点ではリスクを孕む。
レビューアーがそこに気づいたとき、レビューは品質の検査から、設計意図の補完作業へと変質する。

2. レビューアーが誤る典型パターン

設計意図が曖昧なコードに対して、レビューアーがやってしまいがちな誤対応には次のようなものがある。

• 誤読したまま断定的に否定する
  → 意図を取り違えて指摘してしまい、信頼を損なう
• 「分からないからスルーする」
  → 本質的な問題を見逃し、将来の負債を放置する
• 不明点をそのまま開発者に丸投げする
  → 「なぜこうしたの？」というだけで終わってしまう

これらはいずれも、「レビュー＝チェック」という前提に縛られすぎているために起こる。
設計意図の曖昧さに向き合うには、読み解き・補完・対話を含むレビュー技術が必要となる。

3. レビューアーの補完アプローチ：基本構造

曖昧な設計に対して、レビューアーは以下の3段階で対応する。

@Reviewer: この処理、構造的には正しく見えますが、なぜ3段階の条件分岐に分かれているのか、少し迷いました。  
もしかすると将来的に状態が増えることを想定してこの形式にされたのでしょうか？  
そうであれば、その意図が分かるコメントか、関数名での表現があると理解が助かるかもしれません。

このように、指摘ではなく「仮説・補完・提案」の順に展開することで、相手の意図を引き出すレビューが可能になる。

4. よくある曖昧設計パターンと補完コメント例

無名関数のネストが深い

data.forEach(item => {
  if (item.active) {
    process(item);
  }
});

@Reviewer: この処理はシンプルですが、ネストされたままロジックが展開されていて、少し構造が分かりづらい印象です。  
もし将来的に非activeの扱いが変わる予定があるなら、処理を関数に分離することで意図が際立つかもしれません。

条件分岐がビジネスロジックと直結していない

if (type === 'A') {
  doA();
} else {
  doB();
}

@Reviewer: `type`が何を示すのか、処理の関係性からは読み取りづらいです。  
「A=管理者」などの業務的な意味があるのであれば、定数定義やコメントで明確化しておくと読みやすくなります。

5. 設計が曖昧な背景を読み取る視点

設計意図の曖昧さは、開発者のミスや怠慢だけで起きるものではない。
その背景には、以下のような現場的・構造的な事情がある。

• 時間制約下で最低限の実装を優先した
• 要件がまだ流動的で、将来に備えてあえて曖昧な構造にした
• チーム内で設計ルールが未整備であり、個人判断に委ねられていた
• 実装者がまだ設計に自信がなく、「とりあえず動く形」で仕上げた

レビューアーは、コードの構造やコメント、命名の傾向、過去PRの流れなどから、こうした背景事情を推定する力が必要になる。
その上で、曖昧さが一時的・戦略的なものであるのか、放置された技術的負債の芽なのかを見極める。

@Reviewer: この構造、現時点では少し柔らかく作られている印象ですが、おそらく今後追加される要件に備えての判断かと思いました。  
もし仕様が確定した段階で固め直す予定であれば、その旨をコメントなどに残しておくと、チーム全体で同じ理解を持てそうです。

レビューは過去のコードを見ているが、未来のチームを支援する行為でもある。

6. 曖昧設計が生まれた文脈をレビューアーがどう扱うか

意図が見えない設計に対して「分かりません」と返すだけでは、レビューの責任を果たしていない。
レビューアーには、その設計が今なぜこうなっているのか、という“文脈”を扱う責任がある。

扱い方の基本は以下のとおり。

• 状況を否定するのではなく、観測する
• 曖昧さを責めるのではなく、次の判断に必要な補足を提案する
• 将来に向けた修正点を、無理なく記録化する

@Reviewer: ロジックの分岐が明示的でないため、読み解きに少し時間がかかりました。  
これは今の仕様フローに沿って組まれている印象ですが、他の実装者が見たときに前提を共有しづらくなるかもしれません。  
コメントでユースケースを1行だけでも補足いただけると、読み手としては安心感があります。

レビューで完璧な設計を求めるのではなく、「今の状況下では妥当だが、こうしておくと将来スムーズになる」という視点で補うことが、チーム設計文化の成熟につながる。

7. 曖昧さに向き合うレビュー文化のつくり方

曖昧な設計に対して適切に補完するレビューを定着させるには、個人技ではなくチーム文化としての仕組みが必要である。

共有すべきレビュー方針

• 曖昧さに気づいたら、まずは観察と仮説立てをする
• 「分からない」ではなく、「こう読めるが、合っているか？」という書き方に統一
• レビューコメントは「コード指摘」ではなく「意図整理の支援」として位置づける

ドキュメントや運用面での工夫

• REVIEW_GUIDELINES.md に「設計意図が不明なときの対応方針」を明記する
• SlackやPRコメントでの「設計意図補完テンプレート」を用意しておく
• レビュー後の振り返りで、「意図が明らかになったやりとり」を共有する

@Reviewer: このロジック、仕様的に〇〇だと仮定すると辻褄は合いそうですが、念のため確認させてください。  
処理の意図がそれで正しいようであれば、命名や構造で伝わりやすくする方法も検討できそうです。

このような文化が根付けば、レビューは「指摘される場」ではなく、「意図を磨き上げる場」としてチームに定着する。

8. ケーススタディ：曖昧設計のレビュー履歴と学びの記録化

最後に、実際の開発現場でよくある「曖昧な設計」に対して、レビューアーがどのように補完を試み、記録し、改善につなげていったかのケースを紹介する。

ケース：再帰的なデータ処理の構造が不明瞭

元のコード

function parseNodes(nodes: Node[]): Tree {
  return nodes.map(n => {
    if (n.children) {
      return { ...n, children: parseNodes(n.children) };
    }
    return n;
  });
}

初回レビューコメント

@Reviewer: 再帰処理で意図が見える構造ですが、`parseNodes`が何をしている関数かが読み取りにくいです。  
「データの変換」か「表示用構造化」かなど、関数名やコメントで補足いただけると理解が早まると思います。

実装者からの応答

@Author: 元々は表示用の整形意図でしたが、データ取得直後にも使っていたため、構造がやや曖昧になっていました。関数名と役割を分け直してみます。

その後の改善

• parseNodesをconvertForTreeViewとnormalizeResponseNodesに分離
• 実装者が自ら命名と責務の整理を行い、チーム全体に共有
• 次回から同様の設計で迷わないよう、データ加工関数の命名ルールを作成

このように、レビューは意図の指摘だけで終わらせず、「設計思考の可視化と蓄積」に繋げることができる。
それこそがレビューアーの本質的役割であり、技術支援者としての振る舞いである。