3万文字・68ページの仕様書をAIで横断レビューする

背景

長期間保守されてきたソフトウェア製品のWord仕様書群をMarkdownへ移行した。移行後の仕様書は68ファイル、元仕様書の規模は約30,000文字・68ページだった。分割されたMarkdownをPythonで統合し、GitHub Copilotによる横断レビューと、人間による確認・判断・修正を組み合わせた。

当初は、仕様書とコードのどちらが正しいか分からない状態だった。今回は現在動作している実装へ仕様書を合わせるため、現在のコードを正本として照合した。コードだけでは決まらない内容は人間が判断し、最終修正も人間自身が行った。

最初の目的はMarkdown移行レビューだった

当初は、WordからMarkdownへの変換によって情報欠落、表崩れ、参照切れ、記述差異が発生していないかを確認することが目的だった。

しかし、変換が正確でも、元の説明が現在の実装と一致しているとは限らない。変換結果の確認に加え、仕様書の内容を現在の実装と照合する必要があった。

ドキュメントの負債が見つかった

レビューでは、次の問題が確認された。

多数の誤字・表記ミス： 単発の誤字ではなく、仕様書全体に複数の誤字や表記ミスが存在した。
古い説明： 現在の対象外環境であるWindows 2000に関する記述が残っており、不要な古い説明として削除した。この記述の削除可否について、互換性や過去仕様の追加確認は不要だった。
コマンド説明・例の誤り： 単なる表記ミスではなく、読者が誤った操作や理解をする可能性がある説明や例があった。
仕様書間の不整合・矛盾： 複数の仕様書や章で、同じ対象について説明や条件が一致しない箇所があった。

これらは変換時に生じた問題だけではない。長期保守の中で文書の更新や整合確認が追いつかずに蓄積した、ドキュメントの負債だった。

そこで、問題を「変換品質の確認」から「大量の仕様書が現在の実装と整合しているかの調査」へ捉え直した。

68ファイル・約3万文字・68ページを照合する難しさ

仕様書が複数ファイルへ分かれていると、全体像、重複、不整合、参照関係、表記揺れを追いにくい。別の章にある条件や同じ設定項目の説明を探し、現在のコードと突き合わせる必要がある。

AIへ横断レビューを依頼する場合も、必要な情報が分散していると、比較すべき記述を参照しにくい。今回のレビューでは、探索・検索・比較・根拠収集をAIへ任せ、人間が確認できる形に問題候補を揃えた。

なぜ現在のコードを正本にしたか

仕様書同士を比較すれば差異は見つかるが、どの説明が現在の動作に合っているかは文書だけでは決められない。今回の主要な問題は、仕様書の記述が現在の実装と一致しているか分からないことだった。

そのため、今回のレビューでは現在のコードを正本として扱った。仕様書の記述が実装と異なる場合は、コード側の挙動を確認し、仕様書を修正した。仕様書とコードを対等な候補として正しさを比較する運用ではなく、現在動作する実装を基準に仕様書を最新状態へ合わせる運用だった。

ただし、コードから読み取れる挙動と、仕様としてどう表現するかは別の判断である。意図や設計上の意味、業務上の判断、将来方針など、コードだけでは決まらない部分は人間が判断した。

分割された仕様書を横断レビューできる形へ整える

Markdown化には、検索性、差分管理、分割管理に加え、AIが参照・比較しやすい形へ知識を構造化する意味があった。形式を変えるだけでモデルの能力が上がるわけではない。

そこで、分割されたMarkdownを1ファイルへ統合するPythonスクリプトを作成した。仕様書全体をAIへまとめて渡し、ファイルをまたいだ重複、不整合、参照関係、表記揺れ、条件差、古い説明を確認しやすくするためである。道具そのものより、横断調査に必要な情報を一つのコンテキストへ再構成したことが重要だった。

仕様書と現在のコードを同じコンテキストで調査する

Markdown化した仕様書をGit管理し、現在のソースコードと同じ開発プロジェクト内の関連情報を、AIが参照できる状態にした。GitHub Copilotを使い、統合した仕様書全体を横断レビューした上で、関連コードを探して説明と実装を照合した。

AIを選ぶことはモデルを選ぶことだけでなく、調査に必要な情報へアクセスさせることでもある。この考え方はAIを使い分ける基準は、モデル性能よりコンテキストではないかにもつながる。

AIは候補を提示し、人間が変更を判断する

＋の付いた項目を選ぶと、詳しい説明が下に表示されます。

今回は現在のコードを正本として仕様書を照合しました。コードだけでは決まらない部分は人間が判断し、最終修正も人間が行います。

詳しい説明

気になる項目を選ぶと、その役割や判断理由を確認できます。

仕様書群

分割されたMarkdown仕様書をPythonで1ファイルへ統合し、横断比較できるコンテキストを整えました。誤字・古い説明・コマンド例の誤り・矛盾を調査しました。

現在のコード

今回の照合では現在のコードを正本としました。コードで確認できる挙動を基準に仕様書を修正し、意図や方針などコードだけでは決まらない部分は人間が判断しました。

AIによる横断調査

GitHub Copilotで仕様書全体を横断レビューし、現在のコードと照合しました。問題候補・根拠・修正候補を提示し、最終仕様は決定しません。

問題候補

誤字・古い説明・コマンド例の誤り・矛盾などの問題候補です。人間が検出結果とコードを確認します。

修正候補

AIが提示する修正案です。そのまま反映せず、人間がコードとの整合と記述の妥当性を確認します。

人間による確認

AIの検出結果と現在のコードを確認し、実装で決まる部分と人間の判断が必要な部分を分けます。

変更前・変更後の比較

修正前後を比較し、現在のコードの挙動を正しく説明しているか、他仕様との矛盾が残らないかを確認します。

変更する

根拠と変更前後を確認し、人間が修正を採用する判断です。

現状維持

人間の確認で変更が不要と判断した場合に、AIの提案を採用しない経路です。対象外環境の古い説明を残すという意味ではありません。

追加調査

根拠が足りない場合は決定を保留して調査へ戻す経路です。この図は判断の構造を示し、実施件数を示すものではありません。

人間の仕様判断

コードで決まる部分はその挙動を基準にし、意図・業務上の判断・将来方針などコードだけでは決まらない部分は人間が最終判断します。

人間が仕様書へ反映

人間自身が、採用した内容を仕様書へ修正・反映しました。現状維持では記述を変更せず、追加調査では決定を保留します。自動反映は採用しませんでした。

統合した仕様書を現在のコードと照合し、AIが問題候補と根拠を整理する。コードで決まる部分はその挙動に合わせ、コードだけでは決まらない部分は人間が判断する。最終修正は人間が行う。図の追加調査経路は判断材料が足りない場合の扱いを示し、実施件数を示すものではない。

AIへ任せたこと、人間へ残したこと

AIへ任せたのは、誤字・古い記述・コマンド説明や例の誤り・仕様書間矛盾の候補検出、仕様書とコードの差分調査、関連箇所の探索、横断比較、修正候補の提示だった。

人間はAIの検出結果とコードを確認した。コードで決まる部分は、現在の実装を基準に仕様書を修正した。コードから意図が読み取れない、複数の説明候補が成立する、業務上の判断が必要といった部分は、人間が最終判断した。AIが仕様を決定したわけではない。

作業の流れは次のとおりである。

Word仕様書
  ↓ Markdown化
分割されたMarkdownをPythonで統合
  ↓ Copilotで仕様書全体を横断レビュー
仕様書と現在のコードを照合
  ↓ 誤字・古い説明・コマンド例ミス・矛盾の候補を検出
人間が検出結果とコードを確認
  ├ コードで決まる部分：コードを正本として修正内容を決める
  └ コードだけでは決まらない部分：人間が判断する
  ↓ 人間自身が最終修正
仕様書へ反映

変更前・変更後を人間が確認する

AIの確認結果や修正候補を、そのまま仕様書へ反映することはしなかった。人間が現在の記述と修正候補を比較し、コードの挙動を正しく説明しているか、他の仕様書との矛盾が残らないか、意味を変えていないかを確認した。

コードだけでは決まらない箇所では、設計上の意味や業務上の判断を含め、仕様としてどう記述するかを決めた。実装の挙動が明確な箇所と、意図や方針の判断が必要な箇所を分けることが重要だった。

ファイル更新まで自動化することは技術的には可能だった。しかし今回は、仕様責任、削除可否、他仕様との整合、コード外の事情、誤修正の影響を確認する必要があり、自動反映を採用しなかった。採用した変更は人間自身が修正し、仕様書へ反映した。AI出力の責任境界とHITLを、仕様書の変更工程へ適用した形である。

実際に見つかったもの

レビューで確認した問題は約40件だった。すべてが修正対象だったわけではない。AIの問題候補を人間が確認し、対応を判断した。

具体例として、あるコマンドの説明や例に誤りが見つかった。AIが関連仕様と現在のコードを照合し、記述と挙動の差異を問題候補として提示した。人間が該当記述、関連仕様、コードの挙動、修正候補を確認し、実装に合わせて説明と例を修正した。実コマンド名や構文、内部実装は示さない。

コードだけでは決まらない部分を判断する

コードで確認できるのは現在の挙動であり、その意図や業務上の意味が必ずしも明らかになるわけではない。設計意図が不明な箇所、将来方針に関わる箇所、複数の説明候補が成立する箇所では、人間の判断が必要だった。

これらをAIの推測だけで確定せず、人間が仕様としての表現や対応を決めた。今回の「コードを正本とする」という方針は、人間の判断をなくすものではない。コードで決まる部分の照合基準と、コードだけでは決まらない部分の判断責任を明確にするものだった。

確認できた結果と限界

68ファイル、元仕様書約30,000文字・68ページを対象としたレビューで約40件の問題を確認した。多数の誤字・表記ミス、対象外環境の説明、コマンド説明・例の誤り、仕様書間の矛盾を調査し、人間が最終修正した。

今回の対象では、AIによる横断調査、人間による確認・判断・修正を組み合わせ、一連のレビューと修正を約3時間で完了した。これは今回の実績値であり、AI単体の処理時間や従来方式との比較結果ではない。WordからMarkdownへの移行やPythonスクリプトの作成を含む全工程の所要時間を示すものではない。

仕様書は長期保守で参照され続ける知識であり、誤った修正が後の判断へ影響する。修正反映を自動化すれば操作を速められるとしても、今回は品質と仕様責任を優先した。自動化できることと、自動化すべき範囲は同じではない。

ただし、従来方式との工数比較は行っていないため、削減率・短縮率・ROIは未評価である。

約40件は修正件数ではなく、レビューで確認した問題数である。
AI検出の網羅性や精度は厳密に測定していない。見落としがないとは言えない。
コードだけでは判断できない内容が存在し、人間の判断が必要だった。
AIの指摘には人による確認が必要であり、もっともらしさだけでは採用できない。

この事例から得た設計原則

形式移行を知識の点検機会にする。 コピーで終えず、古い説明や記述の不整合を見直す。
照合の正本を目的に合わせて決める。 今回は現在の実装へ仕様書を合わせるため、コードを正本にした。コードだけでは決まらない内容の判断は人間へ残す。
AIへ調査を任せ、最終判断は人間が持つ。 候補の検出、関連箇所の探索、比較、根拠収集を支援させる。
必要な情報へアクセスできる状態を作る。 Markdownの構造化とPythonによる統合で、横断調査できるコンテキストを整える。
人による確認を責任工程にする。 変更前後とコードの挙動を確認し、誤変更の影響と仕様責任から反映方法を選ぶ。今回の最終修正は人間が行った。
問題候補の検出と変更判断を分ける。 AIの指摘をそのまま採用せず、コード確認と必要な人間判断を経て修正する。
長期保守では文書も保守する。 コードだけでなく、仕様書の整合と有効性も保守対象に含める。

Markdownによる構造化、Pythonによる知識の統合、Copilotによる横断レビュー、コードを基準とした照合、人間による判断・修正を組み合わせた。AI単体で完結させず、必要な情報構造と道具、作業フロー、人間の判断を設計した事例である。