記事の要約
株式会社カミナシでVPoEを務めるpospome氏が、長年多くのエンジニアのDesign Docをレビューしてきた経験から「優秀なエンジニアが書くDesign Docの違い」を言語化した記事。結論から言うと、優秀なエンジニアは「代替案」「懸念点」「未決定事項」の3点を書くのが上手いという。設計自体の適切さは大前提で、その上でこの3つの書き方にエンジニアとしてのスキル差が表れるという。
Design Docはなぜ重要なのか？
- Design Docの本質は開発前に不確実性を可視化し、可能な限り排除すること
- 実装開始後に「ここどうするんだっけ？」とならず、事前に詰めておくことで手戻りが減る
- 完璧なソリューションを描く必要はなく、どこまで不確実性を潰すかは開発対象次第
レビューで特に見るべき3つのポイント
1. 代替案（今回採用しなかった選択肢）
- エンジニアリングに絶対的な正解はなく、意思決定はトレードオフの選択結果
- 「A案・B案・C案があり、Cは○○の理由で却下」のように選択肢と判断基準がクリアに書けているか
- 優秀なエンジニアほど代替案の数とトレードオフの言語化が適切。代替案ゼロのDocは「他の選択肢を考えたの？」と思われる
- → エンジニアとしての引き出しの多さが分かる
2. 懸念点
- 大きく2種類ある：「不安が残るもの」と「分からないから助けてほしいもの」
- 代替案は「選ばなかった選択肢」だが、懸念点は「A案を選んだ前提で書いているけど、この点は不安」という内容
- 無視できない不安は明示的に書くべき。分からないこともそのまま書けばレビュアーが助けてくれる
- → エンジニアとしての思考の深さが分かる
3. 未決定事項
- 実装時に考えればいいもの・そもそも考慮不要なものは「なぜ今決めないのか」「いつ誰が決めるのか」を明確に
- あえて決めないことで実装開始までのリードタイムを短縮でき、タスク漏れも防げる（承認後にチケット化）
- → 不確実性を左右するポイントを見極める嗅覚が分かる
具体例：ToB SaaSでのスケール考慮
例としてToB SaaSでは「今回作る機能は何年持つのか？」を考える。1年後・3年後の顧客数やレコード数を逆算し、「1年持たせるには不要」「3年持たせるには必要」という判断を代替案セクションで言語化できるか。さらに「こうなったら1年持たない」という想定外ケースは懸念点に記載する。
このように中長期的な視点での設計力は、上位レベル・等級のエンジニアに求められる要件そのものであり、まさにこの3セクションの書き方に表れる。
ドキュメンテーション能力の重要性
- ドキュメントは考えを他人に共有する最強のツール。情報量・共有相手が多いほど威力を発揮
- スタッフ/プリンシパルエンジニア級では高品質なドキュメントを書くスキル（と書くことを嫌がらないマインド）が必須
- ドキュメントが書けないと組織に考えを共有できず、組織を動かす大きな仕事ができない
まとめ
| セクション | 何が分かるか |
|---|---|
| 代替案 | 選択肢の広げ方＝引き出しの多さ |
| 懸念点 | リスクの深掘り＝思考の深さ |
| 未決定事項 | 今決めるべきことの見極め＝嗅覚 |
記載量の多寡ではなく、開発対象に応じて何をどう言語化するかが重要。Design Docだけで能力が決まるわけではないが、設計時の思考プロセスは如実に表れる、という著者の経験に基づく記事だった。