今回は詳細設計書の意義について、私の考えを述べてみようと思います。
あくまで私の考えであり、独断と偏見が多分に含まれています。1意見として参考程度にとらえていただければと思います。
詳細設計・パラメータシートの説明
まず、ここでの詳細設計の定義を明確にしておきます。
私はもともとSIerでインフラエンジニアをやっていました。その時に作るドキュメント類は例えば以下のようになります。
- 要件定義書
- 基本設計書
- 詳細設計書
- 手順書
- 単体テスト仕様書
- 結合テストシナリオ
案件によっては基本設計書を外部設計書や概要設計書と呼んでいたり、詳細設計書を内部設計書やパラメータシートと呼んでいたりしました。
プログラミングを伴う開発の場合は詳細設計フェーズが終われば実際にコードを書く行為が製造にあたりますが、インフラの場合は、詳細設計フェーズ(にあたるフェーズ)でパラメータシート+構築手順書を作成していることが多かったです。
パラメータシートとは例えばOracleのインストールに伴って、テーブルはどういう名前で作るのか？キャラクタセットや照合順序はどうするのか？などの構築時に必要なパラメータを事細かに記しておくものです。
構築手順書ではこのパラメータシート通りに構築するための手順を記載しておきます。
この二つを渡せば、設計者以外でもOracleの構築が行えるはず！ということです。
基本設計と詳細設計の目的
プロジェクトによってフェーズ自体の呼び名が違ったり、ドキュメントの呼び方や位置づけは様々でした。(これ自体も問題だと思いますが、この件は一旦置いておきます。)
特にIaCなどのツールが浸透する前、クラウドが今より一般的でなかった時は、物理的なサーバーを購入して、そこにBIOSの設定やOSのインストールを行って、ようやくOracleなどのミドルウェアをインストールして設定していくわけですが、これを何十台とか何百台とかやるわけです。
なので、構築作業は出来るだけスケーラブルに行うわけですが、今ほどツールが浸透していないプロジェクトとかだと、構築やテストのタイミングで人を大量に入れて、人海戦術で期間を短くするということが良くありました。
この場合は、構築は手作業になりますし、設計までのフェーズに関わっていなかった人が、何のコンテキストも与えられないままいきなりサーバー構築とかをやらされるわけですので、パラメータシートや手順書を一生懸命作って、何度もレビューするというのはある種必要な作業だったように思います。今考えると非常にめんどくさい作業ですが、大規模なプロジェクトで関わる人数も増えると、むしろこういう「正解」がどこにあるかというのをチームで共通認識として持てるのは、円滑に物事を進めるために必要なことでした。
オンプレミスでもIaCが使われ始める
私が新卒としてエンジニアになった2017年は、すでにIaCツールは登場していて、それなりに使われ始めており、枯れた技術を好むSIer業界でも徐々に使われて行っていました。
私がよく使っていたツールと言えばAnsibleでしたが、この使い方が独特でした。
- まず専用のエクセルパラメータシートに設定したいパラメータを記載します。
- そのパラメータシートをAnsibleのホストサーバーに配置して、yamlファイルに変換します。
- 生成されたyamlファイルをもとにAnsibleを実行します。
このようにして利用されていました。yamlファイルをgit管理するわけでもなく、あくまで構築の自動化のために利用するわけです。エンジニアはどのplaybookが利用されているか、serviceモジュールが使われているのかsystemcltモジュールが使われているのかは一切関知しません。
これをやっていると、例えば以下のような問題が浮かび上がってきます。
- エラーになってしまったが、Ansibleのコードはいじれないので、構築を無効化し、結局手で設定する。
- エクセルのパラメータシートの古いバージョンを適用してしまい、間違った設定が入ってしまう。
- エクセル->yamlの変換部分にバグがあり、意図しない設定が入ってしまう。
これを読んでいる皆さんも想像がつきやすいと思いますが、ちょっと考えればわかるような不具合が当然のように起きるわけです。これは本来Ansibleが目指しているような使い方をすれば発生しないような話かなと思います。
gitでバージョン管理して、エンジニアはAnsibleのプレイブックの内容を理解し、レビューしておけばいい話です。
詳細設計書を書くことによる問題点
サーバー構築に関していうと、パラメータシートを作成した場合、少なくとも構築時点ではサーバーのパラメータとパラメータシートが一致していることが求められます。
ですが、前述した通り、人の手で構築してしまうとどうしてもヒューマンエラーが発生して、設定もれが発生します。それを防ぐために構築した人とは別の人がチェックを行ったりしますが、数百台もあるとやっぱりもれます。動作に影響せず、スルーされることもあるかもしれませんし、単体テストレベルでは気付かない場合もあります。
加えて、そもそも設計書を作っている段階で正しいパラメータと手順とは限りません。というかほとんどの場合一発ではうまくいきません。
そのたびに設計書を修正して手順書を修正して、どれが最新版なのか、何台目のサーバーまで間違ったパラメータになってしまっているのか、その確認作業は途方もないです。
詳細設計の意義
現代のエンジニアリングでは、DevOpsの考え方も当たりまえに浸透して、CI/CDやIaCの導入はもはやWEB系のプロジェクトなら当然のように組み込まれています。(SIerの現在は分かりませんが、私がいた頃よりは増えていることを願います。)
Ansibleでのサーバー構築を例にとっても、適切にgit管理して、適切にレビューを行い、CI/CDでちゃんとテストして、自動でデプロイさせれば、上記の問題は発生しなくなるのかなと思います。
こんなに便利なものがあるのに使わない、もしくは正しく使えないのはなぜなんでしょうか？それにはいろんな要因があると思いますが、その大部分を占めているのは、エンジニアの技術力不足かなと思います。
新しい技術をみんなすぐに習得できない
Ansible自体は2012年に登場しているので、そんなにモダンな技術というわけでもなく、クラウドを使ってコンテナ環境やFaaS環境でコンピューティングリソースを確保している今、むしろ古い技術といってもいいですが、それでもエンジニアのレベルによっては、「新しくて詳しくは分からない技術」となってしまっています。
確かにOSやミドルウェアの知識とは全く別の知識が必要となります。git管理したければそれも覚えないといけません。
パラメータシートを書いてしまうと、それを適切に管理・運用する必要が出てきます。変更履歴を正しくつけて、それをすぐにサーバーに正しく反映させる必要があります。
アプリケーション開発においても、同様です。私が以前SIerに居た頃は実際にメソッドの中身の処理のループやSQLの内容を日本語で設計書に起こしたりしていましたが、それを書くくらいならコードを書いて動かした方が早いです。
何故このようになってしまっているかというと、レビューする側のスキル不足が原因として考えられるかなと思います。
AnsibleのプレイブックやSQL、Javaのメソッドの中身を見てもこれが意図した動作になっているのか確認できないわけです。動作の確認は、意図した動作になっているかどうかはテストをちゃんと書いて、テストをレビューしてもいいわけですし、いちいちコードを読んでられないにしてももう少しやり方があるように思います。
それに詳細設計書にしてレビューしたからちゃんとレビューできるかというとそういうわけでもありませんし、書いてある通りに正しく実装されているとも限りません。また、前述のとおり、こちらも設計書とコードがちゃんと変更に伴って同期されている保証もありません。
結論
色々と書き連ねましたが、結論としては詳細設計書は私は不要だと思います。
基本設計書は依頼主(顧客など)と仕様の認識合わせのために必要だとして、それをどう実現して、具体的にどういう仕様にするかは、IaCの中のプレイブックや、READMEなどのドキュメント、アプリケーション開発であれば、クラス図やエンティティ図などの実装に必要ないくつかの図と、設計の概要を記した少しのドキュメント、そしてユニットテストとコードの中のコメントで必ずコードの変更と同期されるように整えていくべきだと思います。
これは完全に私個人の意見ですし、現時点での考えです。今後もっとより良い技術が出てきたりすれば考えが変わるかもしれません。
コメント