はじめに
初めまして！株式会社リンクアンドモチベーション新卒1年目の小間です！現在は基幹プロダクトであるモチベーションクラウドシリーズの保守・運用に携わっています！
この記事では、設計書作成で学んだ「重要性」と「やらかしポイント」を共有します。
設計書作成ってめちゃくちゃ難しい
新卒でほぼ未経験で入った私は「設計書って、要件定義書からどんな実装をするかを書けばいい」と考えていました。見積もりも 1 日で終わるとしていました。
そんな甘い考えで作成した設計書は、今思えばズタボロのドキュメントでした…
読みづらい、見出しもめちゃくちゃ、どんな実装をしたいのかわからない、そもそも実装できない状態…
結局かかった時間はほぼ2週間。
そんな経験から得た学びをアウトプットし、新卒・未経験エンジニアの方々の少しでも学びになると嬉しいです。
設計書ってなんで重要なの？
設計書が重要な理由は以下の3点だと考えています。
- 実装フェーズに無思考で入るためのドキュメント
- レビュワー（第三者）との共通言語を作るためのドキュメント
- 将来の資産になるドキュメント
実装フェーズに無思考で入るためのドキュメント
「設計書作成できたし、LGTM もらったから早速実装に移ろうかなぁ」と実装フェーズに移行しようとした際、「どこから手をつけよう」とか、実装している時に「この実装でいいんだっけ」と少しでも手が止まったら設計書は未完成です。
あらゆる可能性を潰し、根拠を持ってもう実装できます！と言える、自分に自信が持てるレベルまで書く必要があると思います。
ただし、後述しますが、自己満で終わってはいけない…
レビュワーやチームでの共通言語を作るためのドキュメント
設計書を作成することで、自分以外のメンバーとの共通言語ができます。
設計書は見てもらうだけで終わりではなく、実装や保守運用にも影響すると思います。
例えば「匿名ユーザー登録機能」の設計書で、この機能を unknown_user と呼んでいたら…
- 「unknownって何が不明なの？」
- 「anonymousじゃないの？」
- 「ゲストユーザーとは違うの？」
用語の定義が曖昧だと、チーム内で呼び方がバラバラになり、実装やレビューで認識ズレが発生します。
設計書は 「何を作るか」の齟齬を防ぎ、保守運用や新メンバーのオンボーディングを効率化する役割も担っています。
そんなことを意識してドキュメント作成をすると肝に銘じました。
将来の資産になるドキュメント
過去のコードがどんな動きか知りたい、バグの原因を調べたい…そんな時の手段として、
- コードを読み込む
- 実装者に直接聞く
- 要件定義者や設計書を探して読む
などの方法があると思います。
でも、実装者がいなくなったら？コードだけで意図が読み取れなかったら？
つまり、設計書は現在のフェーズだけではなく、未来を守る資産になることがあるかもしれません。
だからこそ、自分だけが読めればいいドキュメントでは不十分なのだと思います。
※参考
以下は今回自分が設計書を作成する時に最終的なゴールの一つにした指標です。
AI や次の新卒(26 新卒)が見ても、無思考で実装できる粒度の設計書
やらかしポイント
① PRレベルの詳細度で設計書を書こう
Pull Request のことです。
設計書段階で、PRでLGTMがもらえるレベルまで詳細に書こうということです。
実際に先輩からアドバイス頂いた言葉です。
設計書段階で詳細な実装方針まで書いて、LGTM 貰えたらそれは PR でも手戻り少なく LGTM もらえるってことだから、あらゆる可能性で考えてみて
設計書でLGTMをもらえたら、ほぼ実装にもLGTMがもらえているということです。
設計書に工数を割くメリット：
- 実装後に変更するより楽
- 実装してテストとか回した後に変更するのも中々苦ですし…
- 仕様理解を進めながら不確実性を潰せる
- 最終的な工数が減る
仕様理解を進めつつ、不確実性も潰しながらできるタイミングなので時間をたっぷりかけてもいいかもしれません。
② 結論ファーストで書こう
いわゆる Roleplay（他者の立場に立つこと）です。
相手の気持ちを意識して、結論ファーストで書くことです。
やらかしポイントなので「何を当たり前なこと言ってるの」をというツッコミはしまっておいてください。もはや一番最初に習うドキュメントの書き方です。私はできていませんでした。
最初の設計書では、既存の設計の仕様や改修したいファイル、実装方針の検討などをつらつらと書き繋いで、最後に「この通り実装します！」と流れで書きがちでした。
「で、どんな実装したいの？」「結論は？」「レビュワーの負担考えられている？」
なんで相手の気持ちを意識した方がいいのか？
自己満で終わってはいけない理由です。
設計書にはレビュワーである先輩が必ずついてくださいます。しかし先輩は自分より忙しいのです。
だからこそ、以下を満たすドキュメントを作るべきだと思うのです。
- 先輩が手の空いた10分でスッと読める
- 1行で何を言いたいか理解できる
- 指摘しやすい
③ 根拠を持とう
AI が出してくれた回答に常に疑問を持ち、最終的な意思決定は自分で行うということです。
これも当たり前かもしれませんが、AI 時代に入社した自分は AI の方が何倍も理解できる存在であるため、出してくれた回答がそれっぽく見えてしまいます。
AI 駆動開発なるものは時に新卒エンジニアの味方で、時に敵であるかもしれません。
でも実際は、適当なこと言っていることも多かったです。
AI ← 自分 ← レビュワー
この順番でレビューが進むと考えるとわかりやすいです。
AIの回答を1つ1つ調べてコードを読んでみると「おかしいやろ！」と思うことが出てきます。AIを評価する気分で自分もレビュワーになってみてください。適当なこと言っているドキュメントがいかにムカムカするのかわかるかもしれません笑
設計方針の背景やメリデメを書く際は、根拠の正しさを確認しましょう。その方がレビュワーも安心感と納得感を持てます。
④ 実装の価値を理解しよう
価値を理解することで、設計の質が上がる
「渡されたから」「仕事だから」という気持ちで作業に入ると、的外れな設計になりがちです。
なぜ価値を理解すると設計の質が上がるのか？
価値（＝誰の何を解決するか）を理解していると、設計時に以下の判断ができます。
- どこまで作り込むべきか（過剰設計を防ぐ）
- 何を優先すべきか（トレードオフの判断）
- レビュワーへの説明に説得力が出る
「こんな小さな実装/修正したって意味がない」と思うかもしれません。
本当にそうでしょうか。
- カスタマーサポートチームの対応工数の削減
- エンジニアチームのインシデントや顧客対応工数の削減
- コミュニケーションコストの削減
- 顧客体験の向上
一例ですが、これだけでも会社の価値を上げることに繋がっています。
価値を理解してから設計すると、「なぜこの設計にしたか」の根拠が明確になり、結果的に良い設計書が書けると思います。
⑤ 1人で作らない
レビュワーと一緒に作る
「問題発見は早いほど修正コストが低い」というシフトレフトの原則があります。
実装後に設計ミスが見つかると手戻りが大きいですが、設計段階なら根本から軌道修正できます。
じゃあなんでレビュワーと一緒に作成した方がいいのか？
レビュワーを巻き込むメリットとして以下が挙げられると思います。
- 「こういうケース考えた？」という指摘が早期に得られる
- 集合知による洗練
- A・B・C以外にも「Dという選択肢もありそう」みたいなのが出てくる
- 共通言語を早めに共有できる
- ラバーダッキング効果に近い効果を得られやすい
- 曖昧だった思考が明確になったり、新たな視点に気づいたりして、自己解決能力が向上すること
まとめ
| やらかしポイント | 学び | |
|---|---|---|
| ① | PRレベルの詳細度で書こう | 設計書でLGTMもらえたら、実装もほぼLGTM |
| ② | 結論ファーストで書こう | 忙しい先輩が10分で読めるドキュメントに |
| ③ | 根拠を持とう | AIの回答を鵜呑みにせず、自分で確認 |
| ④ | 実装の価値を理解しよう | 価値がわかると設計の質が上がる |
| ⑤ | 1人で作らない | レビュワーと一緒に作ると早期に軌道修正できる |
おわりに
AIの進化で設計書を作成する時間はどんどん減っていくと思います。
だからこそ、一回一回の設計書作成を大切にしていきたいですね。
この記事が少しでも参考になれば嬉しいです！
参考記事
「いい設計って何？」をレビュワー目線からもっと深く知りたい方はこちらの記事がおすすめです！！
https://link-and-motivation.hatenablog.com/entry/2022/10/05/181858