長く運用しているシステムでは、要件定義書、操作手順書、画面一覧、SQL、スクリプト、問い合わせ履歴が別々の場所に散らばっていて、今の仕様を一つの資料で確認できないことがあります。担当したシステムもそうで、現行仕様の一部は担当者の記憶に残っているだけでした。一から設計書を整理するとなると、工数が読めません。
そこで、既存資料の分類や設計書のドラフト作成に生成AIを使いました。作ったのは、業務・機能一覧、業務フロー、機能関連図、機能条件定義の4種類です。ただし、生成AIの出力をそのまま正式仕様にはしていません。確認済みの事実、AIの推測、情報不足による未確認事項を分けて、人が元資料と照合する形で進めました。
設計書整理に生成AIを使った背景
対象システムでは、開発当初の設計書、改修時の資料、利用者向けマニュアルが別々に保存されていました。処理条件の一部はプログラムやSQLにしか書かれておらず、資料だけでは判断できません。
人がすべての資料を読み、機能名や項目名を統一しながら表とフローを作る。この作業は、単純な転記や分類でもかなり時間を食います。そこで、情報の分類、表形式への変換、重複候補の抽出、不明点の洗い出しを生成AIに補助させることにしました。
目的は、AIに仕様を決めてもらうことではありません。人がレビューしやすい状態へ資料を整理して、確認すべき項目を見つけることです。この前提を持たずに始めると、AIが自然な文章で補完した内容を、実在する仕様だと思い込んでしまいます。
今回作成した4種類の設計資料
最初から詳細な設計書を完成させようとせず、全体像から個別条件へ段階的に進めました。まず業務・機能一覧を作り、その一覧を基準に業務フロー、機能関連図、機能条件定義を作っています。
| 成果物 | 目的 | 整理した内容 |
|---|---|---|
| 業務・機能一覧 | 対象範囲を把握する | 業務、機能、利用者、入力、出力 |
| 業務フロー | 処理順序を可視化する | 担当者、判断、承認、例外 |
| 機能関連図 | 機能間の関係を確認する | 画面、データ、外部連携、バッチ |
| 機能条件定義 | 個別仕様を確認する | 実行条件、権限、更新、エラー |
4種類の資料で機能名を統一すると、業務フローには存在するのに機能一覧にはない処理や、機能条件定義が作られていない機能が浮かび上がってきます。
生成AIへ渡す前に資料を収集した
AIへ依頼する前に、対象資料を集めて、どれが現行仕様を表しているのかを整理しました。古い資料と新しい資料を区別せず入力すると、過去仕様と現在仕様が混ざった出力になります。
- 要件定義書、基本設計書、改修設計書
- 操作手順書、利用者向けマニュアル
- 画面一覧、項目一覧、帳票一覧
- ワークフローと権限の設定内容
- プログラム、スクリプト、SQL
- バッチ、ジョブ、外部連携の定義
- 問い合わせ履歴、障害記録、改修履歴
- 担当者へのヒアリング結果
各資料には、作成日、更新日、対象バージョン、現在も有効かどうかを付けました。資料間で内容が食い違う場合は、AIに正しい方を選ばせず、矛盾として抽出させます。
機密情報を除き、必要な範囲だけを入力した
システム資料には、個人情報、社員番号、顧客名、メールアドレス、社内URL、IPアドレス、接続情報が混ざっています。利用するAIサービスの規約、契約内容、社内ルールを確認して、入力できる範囲を整理しました。
入力が許可されている場合でも、設計書整理に不要な情報は削除または置換しています。実在する顧客名は「顧客A」、社員番号は「USER001」、社内URLは「社内システムURL」といった具合です。
パスワード、秘密鍵、APIキー、接続文字列、実在する個人情報など、設計書整理に不要な秘密情報は入力しません。
すべての資料を一度に渡すこともしませんでした。業務単位や機能単位に分割して入力範囲を限定すると、別の業務条件が混ざるのを防げますし、出力結果も確認しやすくなります。
最初の依頼で目的と出力条件を明確にした
「このシステムの設計書を作ってください」とだけ依頼すると、AIは不足情報を一般的なシステム仕様で埋めてきます。そこで、作成する成果物、対象範囲、入力資料、出力形式、不明点の扱いを具体的に指定しました。
次は、実際の依頼内容を記事掲載用に整理したプロンプト例です。対象システム名、資料名、担当者名などは一般化しています。
以下の資料から、業務・機能一覧を作成してください。
条件：
・資料に明記された内容だけを「確認済み」とする
・資料から推定した内容は「推測」とする
・情報がなく判断できない内容は「未確認」とする
・業務名、機能名、利用者、入力、出力、根拠資料を表形式で整理する
・資料に記載されていない機能を補完しない
・資料間で内容が異なる場合は、矛盾事項として出力する
・用語を変更した場合は、元の表記も併記する「推測を禁止する」と書くだけでは、AIが判断した内容を完全には防げません。だから確認済み、推測、未確認の欄を分けて、どの資料を根拠にしたかまで出力させました。
最初に業務・機能一覧を作成した
最初の成果物は業務・機能一覧です。業務名、機能名、目的、利用者、実行タイミング、入力、出力、関連資料を一つの表にまとめました。この一覧を、後続の業務フローや機能条件定義の基準にしています。
たとえば「申請登録」という機能なら、利用者が申請内容を入力することだけでなく、入力チェック、保存されるデータ、通知先、次に実行される承認処理まで整理します。機能名だけ並べても、処理範囲は判断できません。
AIの出力後は、同じ処理が別名称で重複していないか、一覧にない画面やバッチがないかを確認しました。問い合わせ履歴にだけ書かれている例外処理が見つかったときは、その資料を追加して再整理しています。
AIから出力された内容を分類した
次は、記事掲載用に項目名や資料名を置き換えた出力例です。実際の出力そのままではなく、社内情報を削除して構造が分かる形にしています。
機能名：申請登録
分類：確認済み
利用者：一般利用者
入力：申請内容、添付ファイル
出力：申請データ
根拠：操作手順書 3章
通知方法：未確認
確認事項：メール通知か画面通知かを担当者へ確認するこの形式にしたことで、資料に書かれている内容と、追加確認が要る内容を分けられました。根拠資料を付けておくと、レビュー時に元資料へ戻るのも早くなります。
業務フローは表を作ってから図へ変換した
業務フローでは、開始条件、担当者、操作、判断条件、システム処理、承認、差し戻し、完了条件、例外処理を整理しました。正常系だけでなく、入力エラー、承認却下、外部連携失敗も含めます。
最初から図だけを生成させることはしていません。処理番号、担当者、操作、次の処理、条件を表形式で作り、内容を確認してから、必要に応じてMermaidなどのテキスト形式へ変換しました。
図を先に作ると、矢印の意味や条件が曖昧になりがちです。文章と図を別々に生成すると、判断条件が食い違うこともあります。確認済みの表を基準に図を作るほうが安全でした。
画面・データ・外部連携の関係を整理した
機能関連図では、画面同士の関係だけでなく、利用するデータ、マスタ、外部システム、バッチ、通知処理を整理しました。申請画面で登録されたデータが承認処理へ渡され、承認後に外部システムへ連携される、という流れを見える形にします。
関連図があると、項目変更時の影響範囲を確認しやすくなります。一つの項目を変えたときに、帳票、CSV、API、バッチのどこへ波及するかが分かるからです。
入力資料に連携先やタイミングが書かれていない場合は、AIに一般的な構成を補わせません。「連携先未確認」「実行タイミング未確認」として、確認事項に残しました。
機能条件定義で例外処理まで整理した
機能条件定義では、実行条件、入力チェック、権限、ステータス、更新項目、通知、エラー処理、再実行、ログを整理しました。ここで効いてくるのは、正常に処理された場合よりも、失敗時にどの状態が残るかです。
外部連携が失敗したとき、画面上のステータスが「処理中」のまま残るのか、「エラー」へ変わるのか、担当者へ通知されるのか。再実行したときに同じデータが二重登録されない仕組みになっているかも確認します。
資料に具体的な記載がないと、AIは一般的なエラー処理を補ってきます。根拠のない条件は未確認へ移して、担当者への質問として残しました。
確認済み・推測・未確認を分けた
生成AIが作った文章は自然に読めるので、入力資料にない内容でも正しいように見えてしまいます。このリスクを減らすため、出力内容を確認済み、推測、未確認の3つに分類しました。
| 分類 | 判断基準 | 扱い |
|---|---|---|
| 確認済み | 資料に明記されている | 根拠資料と照合する |
| 推測 | 資料から推定している | 正式仕様へ入れず確認する |
| 未確認 | 情報がなく判断できない | 質問事項として管理する |
確認済みの内容には、資料名、ページ、項目名を付けました。推測した内容は正式仕様へ混ぜず、確認事項一覧へ移します。
AIが誤って補完した内容を修正した
実際に使ってみると、AIは資料に書かれていない内容を自然に補完してきました。資料に「担当者へ通知する」とだけ書かれている箇所で、AIが「メールで通知する」と具体化してきたのがその例です。
実際には画面通知、チャット通知、手動連絡かもしれません。ここは「通知方法は未確認」に直して、担当者への質問へ追加しました。
似た名称の機能を同じ機能として統合したり、過去に廃止された機能を現行機能として整理したりすることもありました。資料の作成日と対象バージョンを見て、現行、廃止、将来候補を分けておきます。
設計書と同時に不明点一覧を作った
生成AIを使ってみて一番役に立ったのは、完成した設計書よりも不明点一覧のほうでした。資料間の矛盾、処理条件の不足、例外時の動作、権限範囲、更新タイミングを一覧にしています。
- 設計書と操作手順書で条件が異なる箇所
- エラー時のステータスと通知方法
- 権限を持つ部署、役職、管理者の範囲
- 外部連携の成功・失敗判定
- 手動処理と自動処理の実行タイミング
- 現在も利用中か判断できない機能
不明点には、確認先、優先度、回答期限、回答内容、設計書への反映状況を足しました。これで担当者へのヒアリングを計画的に進められます。
生成された資料を人がレビューした
AIが作った設計書は、必ず元資料と照合しました。存在しない機能が追加されていないか、条件や例外が省略されていないか、用語が混在していないか。
特に気をつけたのは、現行仕様と将来要件の混在です。過去の検討資料に書かれた未実装機能が、現在利用中の機能として整理されることがあります。資料の日付と状態を見て、現行、廃止、将来候補を区別しました。
レビューはシステム担当者だけでなく、実際の業務担当者にも依頼しました。資料には書かれていない手作業、月末だけの処理、例外対応が残っていることがあるからです。
AIに任せる作業と人が判断する作業を分けた
生成AIが向いていたのは、情報の分類、表形式への変換、表記揺れの抽出、重複候補の検出、不明点の洗い出し、ドラフト作成です。大量の文章から共通項目を抜き出して一定の形式へ整える作業では、はっきり効果がありました。
一方、仕様の確定、業務ルール、セキュリティ要件、例外処理、本番影響、関係者との合意は人が判断します。AIが妥当そうな案を出してきても、自社の業務や内部統制に合うとは限りません。
AIは設計者の代替ではなく、レビュー前の下書きを作る補助として使いました。この役割分担なら、作業時間を抑えつつ、根拠のない仕様が紛れ込むリスクも減らせます。
設計書整理を段階的に進めた手順
- 対象資料を収集し、日付と有効性を確認する
- 機密情報を削除または置換する
- 用語一覧と表記ルールを作成する
- 業務・機能一覧を作成する
- 業務フローを作成する
- 機能関連図を作成する
- 機能条件定義を作成する
- 不明点一覧と資料間の矛盾を整理する
- 元資料と照合し、関係者へ確認する
- 確認結果を正式版へ反映する
段階ごとに人の確認を入れると、前段階の誤りが後続資料へ広がりません。業務・機能一覧が不正確なまま関連図や条件定義を作ってしまうと、複数の資料をまとめて直すことになります。
まとめ
生成AIは、分散した既存資料を整理して設計書のドラフトを作る作業に使えます。最初に業務・機能一覧を作り、その情報を基に業務フロー、機能関連図、機能条件定義へ展開していくと、資料間の整合性を確認しやすくなりました。
入力前には機密情報を除き、利用するサービスの規約と社内ルールを確認します。出力は、確認済み、推測、未確認を分けて、資料にない内容を正式仕様へ混ぜないこと。ここを外すと、設計書としては使えません。
今回の進め方で一番効いたのは、設計書と不明点一覧をセットで作ったことでした。生成された資料は必ず人が元資料と照合し、業務担当者やシステム担当者へ確認してから正式版にしています。
コメント