仕様書陳腐化の原因

日本中（いや、世界中）、至る所で「仕様書が陳腐化していて…」という言葉を聞きます。仕様書をアップデートし続けることが難しい理由の一つがわかった気がするので書き留めておきます。

仕様書の役割の問題

そもそも論です。仕様書の役割を理解していない人が多いのではと思うのです。仕様書の役割としては、下記のようなものがあります。

• 関係者が共通認識できる

• 業務とシステムの関係性を明示化する

• 責任部門の明示化

仕様書の元になるのが、要求仕様書　ではないでしょうか。業務の中でどのようなことに困っているか、どのようなことを行いたいか、改善・改革の方針としてどうすべきか　等が書かれている文書です。要求仕様書は、あくまでも「業務」や「経営」「効率」視点のものが多く、粒度としては大きめの話になっています。

これを、もう一段階の小さな粒度で、業務部門の主担当者とIT部門の主担当者が、齟齬なく理解し合えるものとして必要なのが、「仕様書」の位置づけと思います。

そうすると、必然的に業務部門との会話は必要となり、業務とシステムの関係性を図式化できるようになります。言葉だけでは難しい説明も、図式化したうえで説明すると、より理解は深まりますよね。

アプリを開発していく上で、不明点は必ずでてきます。条件分岐から漏れたケースは実装しなくていいんだっけ？ とか、同じ項目が2つあるんだけど、どっちかで良いんだっけ？とか。IT部門内で解決できない問題は、業務部門に聞くしか解決方法はありません。業務部門のコンタクト先は、仕様書に書いておくべき項目の一つです。

仕様書を誰が作っているか問題

仕様書を作成するのは、IT部門側、もしくはIT部門が発注したシステムインテグレータ、もしくはコンサルタントなのではないかと思います。ある程度の知識が無いと書けないものなので、その部門が書くこと自体は問題ありません。

ただし、大前提として、仕様書は業務部門とIT部門の橋渡しをするものです。業務部門の関与無しで書くべきものではありません。書いた仕様が正しいかどうかの合意は業務部門とIT部門の双方が行うべきです。
「業務部門を参画させることに抵抗がある」「業務部門を説得できない」などとおっしゃる方が驚くほど多いのですが、今一度、誰のためのアプリなのかを認識すべきです。使う人の意見がなければ、改善が進むわけがありません。

仕様書は業務全体とシステム全体を見渡し、一つ細かい状態で書くのですから、「システムエンジニア」もしくは「アーキテクト」というような肩書きの方々が書くものになります。これらの方は経験が豊富で、粒度の調整もできる方のはずです。
ところが、ここを「実装担当者」が書いてしまうと、下記のような問題が起こり得ます。

仕様書が詳細設計書化している問題

実装担当者が仕様書を書くと往々にしてこのケースになります。実装を思い浮かべて（もしくは現行システムのソースコードを見ながら）書くものですから、どうしても実装の話を書きがちです。
仕様書のはずなのに、一気にどのテーブルのどのカラムはどういう条件で検索し… などと、詳細設計書レベルのことを書いてしまいます。デキる技術者は、思想や方向性を頭の中で消化してしまうため、こうなってしまうんですよね。私はデキる技術者では無かったですが、この傾向は痛いほどわかります。
アプリモダナイズを行う際も、ソースコードの解析から始めてしまうとこの傾向が非常に強いです。そして、肝心な「仕様」についてが置き去りにされ、後になって「仕様がわからない」問題に発展します。

設計書が詳細設計書化してしまうことで、業務部門が見てもちんぷんかんぷん、わからないところは飛ばし読みしても、物理テーブル名やロジックがそのまま書かれてしまっているので、理解ができなくなります。理解できないとなると、そのドキュメントを作った部門に依存せざるを得なく、業務部門が自力で設計書を更新することはなくなります。

仕様通りに実装してみたものの、気づかなかった技術的問題のために変更せざるを得ないこともよくありますよね。データ項目や量が後付で多くなってしまい、性能とかメモリ使用量とかで問題となり、作りを修正するというような場合のことです。その時、「仕様書」まで変更しますか？しないですよね。つまり、実装者からも見放された「仕様書」になります。

つまり、システムが出来上がったときにはすでに陳腐化している「仕様書」が出来あがってしまうわけです。

ちなみに、仕様書・設計書・詳細設計書　の3点を作るのが一般的と思われているかもしれませんが、殆どの場合、仕様書と設計書はほぼ同じ内容。さらに詳細設計書はプログラムコードとほぼ同じ内容です。詳細設計書は要らないと思います。仕様書さえあれば、「プロフェッショナル」な実装者は実装できるものです。設計書に書くべき内容も「実装のポリシー」のみに限定すべきです。

仕様書の検証が行われていない問題

書いたドキュメントが正しく記載されているかの確認、みなさんやっていますか？発注者側・受注者側が、正しく齟齬なく理解し合えていることを確認していますか？
仕様書が詳細設計書化している現状を見ると、正しい検証はできていないのではと思います。そうするとどうなるか？
言葉の齟齬が発生し、目的とは異なる種類のデータが出力される、実行のタイミングがおかしい、冗長な実装等が起こり、技術的には正しいにもかかわらず業務が成立しない「仕様バグ」と呼ばれる状態に陥ります。

この状態、そのままでは業務が成立しないため、システム全体のリリースを後ろ倒しにしてでも修正しなければならないのですが、技術的には正しい実装をしているために小手先の修正では修正できず（実際にはできますが、複雑化してしまうし性能も落ちる）、仕様からもう一度作り直すことが求められます。

仕様書に書くべき項目・書くべきではない項目

もうここまで来ると皆さんおわかりかと思います。

仕様書に書くべき項目

• 業務全体の流れと、そのアプリの位置関係の図

• そのアプリを使っている業務担当部門名（担当者名は付箋で）

• そのアプリの稼働条件や非機能要件（稼働日時や許容できる応答時間）

• そのアプリが必要とされている理由

• アウトプットとインプットの関係図（ロジックが書けるなら DRD図等で）

• システム全体のアーキテクチャとそのアプリの位置関係図

• 障害が起きた時の連絡先や手段（一旦手作業で後でリカバリー可能かどうかなど）

これらが、「全部先に決まっている」ことは大変お喜ばしいことですが、大概の場合は「まだ決まっていない」ことが多いです。なので、少なくとも「項目だけ」は用意しておき、埋まっていなかったらチケット管理システムにでも投げ込んでおきましょう。また、IT部門だけで書くのではなく、業務部門の協力も仰ぎましょう。

仕様書に書くべきではない項目

• ソースコードレベルの詳細な情報

• あいまいな表現・コンプライアンスに引っかかるような表現

• 現行アプリの構成図

• 業務部門が見てもわからない無機質な記号数字で構成される関数名等

• 一般的ではない略語

新しくモダナイズするアプリの構成で、このアプリだけは全く変えようがない　というような場合を除いて、現行アプリの構成図は書くべきではありません。書いてしまうと開発者はそれを正と認識し、新たなアイデアや発想がなくなってしまい、既存アプリと同じものが出来上がります。

せっかく新しく作るのであれば、もう一度業務から見直すべきです。大変だと思うのであれば、外部コンサルタントの力を借りましょう。良い意味でも悪い意味でもニュートラルな視点で見ますので、皆さんの「当たり前」が世間一般的には「当たり前ではなかった」こともわかり、構造改革が進むきっかけにはなるはずです。UMEZOコンサルティング合同会社は喜んで乙手伝いします。

設計書は全く不要なのか？

全く不要であるということはありません。構築するにあたり、ある程度の決まり事、ポリシーは設計書に書くべきです。例えば下記のような項目です。

• システムとしての全体の基本思想・方針

• アーキテクチャと実現させる製品やツールのマッピング

• （マイクロ）サービスにおける各サービスの役割と禁止事項

• Exception発生時のlogの書き方、取り扱い方法

• サーバー構成とネットワーク図

• コーディング規約

設計書の読み手は、IT部門もしくはその発注先となるので、仕様書で書くべきではないと書いたITの専門用語や誤解を生じない程度の略語などはバンバン使ってください！
あまりに細かすぎると、設計書の更新が苦痛になってきますので、詳細については「技術メモ」といった形で残しておくほうが良いです。詳細設計書はソースコードとほぼ同じことになるので、作らなくてよいです。

まとめ

仕様書の作成、執筆者の立場もあり、意外と難しいものです。
ルール駆動開発では仕様書の作成の前の情報の整理から行います。プロジェクトの根幹に関わる、未来にわたり更新し続けられる仕様書作りを目指しませんか。