西村威彦

デジタルの理想と現実

【生成AIで仕様書の更新漏れ対策】システムとドキュメントを自動同期する方法

2025/12/30

前回、生成AIを活用したソフトウェア開発について紹介しましたが、まだまだ生成AIによるソフトウェア開発について、ハルシネーションなどによるリスクへの懸念などから検討すらできない企業も多いと思います。

今回は、そんな懸念に対して、よりリスクの低い生成AI活用事例として、システムからのドキュメント生成というアプローチをご紹介します。

システムの仕様はどう確認？ドキュメントとシステムが乖離する現状

自社のシステムの仕様は、どのように確認しますか？情シス部門であれば、仕様書で確認する企業がほとんでしょう。では、その仕様書がシステムと完璧に同期されていますか？自信を持ってYesと言える企業がどれだけいるでしょうか？ソフトウェア開発において、システムとドキュメントの同期を保つことは、多くのプロジェクトで課題として頻繁に発生しています。

ドキュメントとシステムが乖離する事による課題

ドキュメントとシステムが乖離していると、以下のような問題が起こります。

ドキュメントを参考にして連携機能を開発したものの、実際のシステムの動作とドキュメントの記載内容が異なっていたため、何度も改修作業が発生してしまった。

既存システムの運用保守を別の会社に委託したが、引き継いだドキュメントが実際のシステムの状態と一致しておらず、様々なトラブルが続出してしまった。

既存システムの運用保守にかかる費用が高額であるが、ドキュメントが適切に更新されていないため、他の会社に業務を移管することができない状況にある。

勇気を持って追加開発や運用保守について相見積もりを取ったが、価格差よりもリスクが気になり、結局既存ベンダーに発注してしまう。

既存システムに対する軽微な機能追加を行う場合でも、複雑なシステム構造を理解するための調査作業などに多くの費用がかかってしまい、結果として膨大な費用を請求されることになる。

ドキュメントとシステムが乖離する背景

では、このようにドキュメントとシステムが乖離してしまうのは何故なのでしょうか？

ドキュメントがシステムの実態と乖離してしまう背景としては、以下のようなものがあります。

システム開発時にドキュメントをベンダーに作成してもらい、納品してもらったものの、その後の変更に対応してドキュメントを更新していない。

開発時に作成されたドキュメントは、ごく一部のメンバーしか内容を正しく解釈できないため、実際の業務では利用されていない。

エンジニアが実際の開発や保守業務において必要とする情報がドキュメントに記載されていないため、結果として利用されていない。

エンジニアはドキュメントを作成することに対して積極的ではなく、できれば作りたくないと考えている。

こういった背景から、ドキュメントとシステムが乖離している状況は認識しているものの、なかなか手を打てていないのがほとんどの企業だと思います。

新たなアプローチ：AIによるコードからのドキュメント生成

元々、こういった課題背景が存在していたことから、実際のコードからドキュメントを作成するというアプローチが数多く採用されてきており、このような手法は「リバースエンジニアリング」と呼ばれてきました。しかしながら、コードからドキュメントを作成するという作業には、そのシステムで利用されている開発言語を深く理解できる高度な開発スキルと、可読性の高いドキュメントを作成できるドキュメンテーションスキルの両方が必要とされるため、高いコストと長い期間が必要とされてきました。

ドキュメント作成に長い時間がかかるということは、その作成期間中にシステム側で更新された変更内容についても対応する必要があるということを意味しており、ある時点でシステムと完全に同期されたドキュメントを作成することができたとしても、その状態を継続的に維持していくためには、また多くの労力とコストが必要となってしまうという課題があります。

しかしながら、このドキュメント作成の作業をAIによって自動的にかつ短期間で生成することができるようになれば、こういった様々な課題を解決することが可能になります。

▼具体的なアウトプットの例▼

▼フロー図▼

生成AIによるソフトウェア開発ドキュメントにおける図の作成

生成AIがイメージも作成するということを聞くと、その品質や正確性に対して不安を感じる人も多いのではないかと思います。ですが、実際は、ソフトウェア開発ドキュメントにおいて生成AIが作成するのは図そのものではなく、図を描画するためのコードであるため、品質が非常に高いアウトプットを得ることができます。

具体的には、以下のようなコードを生成し、このコードをMermaidというツールを介して処理することで、その下のような図を作成してくれるという仕組みになっています。

ポイント：設計開発時と運用保守時のドキュメントの違いを意識する

システムは、開発する時には要求機能や要求仕様をドキュメントとしてエンジニアに伝え、技術検証や開発を経て、システムを構築し、稼働後も運用保守をしながら徐々に機能追加を行なっていきます。このような流れにおいて、ドキュメントとシステムの乖離はなかなか回避できないのが実態です。

そこで、設計開発時に求めるドキュメントの役割と、運用保守時に求めるドキュメントの役割は別であることを意識することも重要です。

設計開発時のドキュメントは、ビジネス側のニーズや要求を文書化したものであると言えます。要望や仕様をドキュメント化していく過程において、開発側の様々な制約（開発環境、人材リソース、コスト、スケジュールなど）によっては、ビジネス側が求める仕様とは異なる実装をせざるを得ないケースが発生することがあります。当初の計画と異なる実装を行う場合には、ドキュメントも併せて変更するというルールが定められているものの、開発時にテストやエラー対応を何度も繰り返していくうちに、納期を優先するあまりドキュメント更新のための工数が十分に確保されておらず、結果としてドキュメントの更新漏れが発生してしまうという状況が往々に起こりうります。

一方で、運用保守時のドキュメントは、システムと同期されている事が重要となります。システム不具合の改修であったり、機能追加をする場合、エンジニアは、システムのソースコードより先に、ドキュメントを見て、必要な対応や必要なエンジニアについて工数などを算出します。しかし、ドキュメントとシステムが乖離していると、「聞いていた話と違う」となり、基本的には追加対応が必要となり、そのコストについて発注元と委託先で揉める原因となってしまいます。また、運用保守のドキュメントに求められる事が同期されている事であると、より専門家向けの詳細な内容となります。そのため、エンジニアがよく使うことを考えると、ドキュメントはコードに近い場所にある方が適しているため、GitHubなどのコード管理ツールに格納しておくことをお勧めします。

このようにドキュメントは設計開発時と運用保守時の目的に応じて、別々に管理することをお勧めします。