設計レビューってどうやるの？

はじめに

「設計レビューって、結局どうやるのが“正解”なんだろう？」

設計って、会社のフェーズによっても全然異なるものだと思います。今まで所属していた会社は人数の少ないところが多かったので、かっちり設計せずに即実装とか、それぞれ我流でアーキテクチャ図やDesign Docが作られて特にレビューなどせずに実装していくような感じでした。

ここ最近で設計レビューに参加するようになって、自分がDesign Docを作成するのはもちろん、他のメンバーのDesign Docを見て考えをインプットすることでもめちゃめちゃ設計スキルをつけられるな、と思うようになりました。

そんな中、自分のチームではDesign Docを書いて1回だけレビュー会を開く、という運用が続いていました。でもそれでは、設計を担当していないメンバーに膨大な内容が頭に入らず、レビューの時間も足りなかったりして、上手くいかない状況が続いていました。

この記事では、そんな状況の中で私が個人的に試してきた設計レビューの進め方と、その中で見えてきた課題や工夫についてまとめてみます。

チームの設計レビュー運用：Before

• 各開発案件ごとにDesign Docを書く（1人 or 項目ごとに分担）
• ドキュメントが完成したら1回だけレビュー会
• その後すぐに実装フェーズへ

課題感：

• ドキュメントの粒度や書き手の視点がバラバラで、整合性がとれない
• レビューが1回きりなので、指摘が入っても修正の余地が少ない
• 結果として、レビューが形骸化し、実装に問題が持ち越されることがあった

試してみた改善策

• 少しずつ書いて、複数回レビューする
  • Design Docをドラフト段階から共有し、早めにWIPレビューを依頼
  • 1回で全て終わらせるのではなく、複数回レビュー
• アーキテクチャ検討Docを先に作る
  • 特にステークホルダーが多い案件では、いきなり詳細設計に入るのではなく、技術方針や構造の選択肢・トレードオフをまとめたDocを先に用意
  • ADR（Architecture Decision Record）ほど細かくはせず、1つのDocに集約して議論の土台とした
• アーキテクチャ検討Docは事前コメントを前提に回す
  • 会議の尺を圧縮するため、アーキテクチャDocは事前に共有＋コメントをもらう前提で運用…が、事前にコメントのなかった会話で尺を取ったりもした
    → まだまだ運用改善の余地あり

実践してみて分かったこと

• 「設計レビュー＝1回で終わらせる」は本当に無理がある
• 少しずつ設計を出して議論することで、チーム全体の視座が上がった感覚がある
• 一方で、ステークホルダーが多いレビューでは「どう巻き込むか」「どう事前に読んでもらうか」が本当に難しい

今後やってみたいこと

• 設計レビュー観点のリスト化
  • 観点が共有されているとレビューしやすい
• レビュー会のファシリテーターを明確にする
  • 会議の収束性が上がりそう
• 設計の粒度を揃えるテンプレート運用
  • 誰が書いても大きくブレないように
• （若干設計とはズレるが）JIRAチケットを切る前に実装計画 Doc のようなものを作成してみる
  • これまではDesign Docの項目ベースでJIRAチケットを切っていた
    • しかし設計として合意を取りたいポイントと、メンバーに共有したい実装の内容や見積もりの根拠となるポイントは大きく異なる
    • わかりやすいトラブルとして見積もりがガバガバになる・・・
  • なので設計が固まった後、具体的なタスク分解や担当割をレビューしてからチケット化したい
    • 実装フェーズに入る前に、全体像と段取りが見える状態へ

おわりに

自分の試みもまだまだ発展途上ですが、設計品質を高めるには「レビューを回す仕組みづくり」こそが肝心だと感じています。 似たような状況の方の参考になれば嬉しいですし、「うちはこうしてるよ！」という話があれば、ぜひ教えてください。