「仕様書が古い」「実装と合っていない」「担当者しか分からない」。既存システムにこうした問題があっても、すべての資料を一から作り直す計画は進みにくいものです。
対象範囲が広いほど、必要な工数と予算を見積もりにくくなります。現行保守を止めて文書化だけに集中することも現実的ではありません。その結果、問題を認識しながら、改修や障害が発生するたびにソースコードを調査する状態が続きます。
仕様整理の目的は、棚に並べる文書を増やすことではありません。保守・改修・引き継ぎ・刷新判断に必要な情報を、必要な順番で使える状態にすることです。
したがって、最初から全範囲を同じ精度で整備する必要はありません。本記事では、保守リスクを起点に仕様整理の優先順位を決める方法と、整備した情報を陳腐化させない進め方を解説します。
仕様書の不足範囲が整理できていない場合でも、コード・画面・DB・担当者ヒアリングから現状を確認できます。
仕様整理について相談する
「全部作り直す計画」が止まりやすい理由
対象が広すぎて完了条件を決められない
長年運用されてきたシステムには、画面、バッチ、帳票、外部連携、データベース、運用作業など、多数の要素があります。すべてについて要件定義書、設計書、テスト仕様書、運用手順書を整備しようとすると、どこまで作れば完成なのか判断しづらくなります。
保守と文書化が別プロジェクトになる
文書化を日常保守から切り離すと、現場は「障害対応や改修を優先したい」と考えます。文書作成は後回しになり、作ってもレビューされないまま終わることがあります。
精度を上げるほど確認負荷が増える
コードから処理を読み取れても、業務上の意味や例外条件は担当者に確認しなければ分かりません。全領域を同時に確認しようとすると、少数の有識者に質問が集中します。
作成中にもシステムが変わる
保守・改修が続いていれば、文書化している間にも仕様が変わります。完成を待って一括公開する方式では、最初に作った資料が完成時点ですでに古くなる可能性があります。
こうした問題を避けるには、「全体を一度に完成させる」のではなく、「リスクが高い領域から、使う成果物を整える」という考え方が必要です。
優先順位を決める5つの評価軸
優先順位は、単に「古い機能から」「担当者が気になる箇所から」と決めるのではなく、複数の観点で評価します。以下は、仕様整理の対象を比較する際の代表的な軸です。
1. 変更頻度
改修や設定変更が頻繁に発生する領域では、仕様が分からないことによる調査工数が繰り返し発生します。毎月の制度改定、料金変更、商品追加、顧客要望などで触る機能は、優先度を高くしやすい対象です。
一方、長期間変更されず安定している機能は、重要であっても直ちに詳細文書を作る必要がない場合があります。まずは機能概要と依存関係だけを押さえ、詳細化は改修時に行う方法もあります。
2. 業務影響
停止や誤処理が発生した場合に、売上、顧客対応、決済、出荷、会計、法令対応などへ大きな影響が出る機能は優先します。
業務影響の高い領域では、正常時の仕様だけでなく、異常時の判断、復旧手順、連絡先、代替運用も重要です。設計書だけを作るのではなく、障害対応に使えるナレッジを整える必要があります。
3. 調査・復旧の難しさ
障害や問い合わせが起きた際、原因特定までに時間がかかる領域も優先対象です。
- ログの場所や読み方が分からない
- バッチの実行順序が不明
- 複数システムをまたぐ処理がある
- 再現条件が複雑
- データ修正を特定担当者しかできない
こうした領域では、機能仕様だけでなく、ログ確認、データ追跡、切り分け手順、復旧判断を整理すると、日常保守で効果を出しやすくなります。
4. 知識の集中度
特定の担当者やベンダーにしか分からない領域は、退職・異動・契約終了によって知識を失うリスクがあります。担当者が現在対応できるうちに、コードだけでは分からない業務ルールや例外処理を聞き取ることが重要です。
知識の集中度を見る際は、「担当できる人が何人いるか」だけでなく、問い合わせ対応、障害判断、データ修正、リリース承認など、役割ごとに代替者がいるかを確認します。
5. 今後の計画との関係
近いうちに機能追加、外部連携変更、クラウド移行、ベンダー変更、モダナイゼーションを予定している領域は、事前に仕様を整理する価値が高くなります。
刷新対象だから現行仕様は不要、とは限りません。刷新要件を決めるには、現在の機能、データ、業務上必要な例外、廃止できる処理を把握する必要があります。将来の判断に必要な粒度を定めて整備します。
評価軸を使って対象を3段階に分ける
厳密な点数をつけることが目的ではありません。複数部門で「なぜここから着手するのか」を説明できる状態をつくることが重要です。
優先度A：直ちに整理する領域
業務影響が大きい、変更や障害が多い、担当者が限定されている、近い将来に改修・移管を予定している領域です。現状と一致する機能・処理、データ、例外、運用手順を重点的に整えます。
優先度B：改修や問い合わせに合わせて整える領域
一定の重要性はあるものの、直近の変更が少ない領域です。全資料を先に作るのではなく、改修や障害調査を行うタイミングで、調査結果をナレッジとして残します。
優先度C：概要と所在だけ押さえる領域
利用頻度が低く、変更予定もなく、代替手段がある領域です。詳細設計を復元する前に、機能の目的、担当部署、関連システム、データ保管場所など、全体を見失わないための情報を整理します。
優先度Aで最初に作りたい成果物
仕様整理では、対象ごとに必要な成果物を変えます。すべての領域で同じ文書セットを作る必要はありません。
機能一覧と処理フロー
どの業務にどの機能が関係し、処理がどのシステムへ流れるかを整理します。最初から詳細設計へ入るより、全体像を把握して調査範囲を決めやすくなります。
データ項目定義
テーブル名や型だけでなく、業務上の意味、更新条件、値の制約、他項目との関係を整理します。影響範囲調査やデータ移行の基礎になります。
例外・判断ルール
通常フローよりも、手作業による補正、特定顧客への例外、締め処理、再実行条件などが事故につながりやすい場合があります。担当者の暗黙知を優先して記録します。
運用・障害対応手順
日次・月次作業、バッチ監視、ログ確認、エスカレーション、復旧手順を整理します。新しい担当者が同じ手順で対応できる粒度を目指します。
FAQ・用語集
問い合わせが繰り返される内容や、社内固有の用語をまとめます。仕様書を読む前提知識を共有でき、新任担当者の立ち上がりにも役立ちます。
AIで効率化できる範囲と、人が判断する範囲
既存コード、画面、DB定義、ログ、過去資料から情報を抽出・整理する作業には、AIを活用できる場面があります。例えば、コードの構造把握、関連ファイルの探索、文書のたたき台作成、用語候補の抽出などです。
ただし、AIが生成した内容をそのまま正式仕様にするのは適切ではありません。コードに実装されている処理が、現在も正しい業務ルールとは限らないからです。
- その処理は意図された仕様か
- 過去の暫定対応が残っていないか
- 例外条件は現在も必要か
- 文書化してよい情報か
- 今後も維持すべき機能か
これらは、業務担当者やシステム責任者が確認する必要があります。AIは調査・整理を補助し、人が意味と品質を判断する役割分担が現実的です。
スマラボでは、既存コード・画面・DB・担当者の暗黙知を整理し、機能一覧、処理フロー、データ項目定義、FAQ、運用手順などのナレッジ整備を支援しています。
仕様整理・AIリバースエンジニアリング支援を見る
文書を陳腐化させないための運用
仕様整理は、一度のプロジェクトで終わらせると再び古くなります。保守・改修の業務に更新作業を組み込むことが重要です。
変更時の更新対象を決める
機能追加や不具合修正の完了条件に、関連する仕様書、テスト情報、FAQ、運用手順の更新を含めます。どの変更でどの文書を更新するか、簡単なルールを決めます。
文書の責任者と確認者を分ける
作成者だけに更新を任せると、内容の正しさを確認できません。技術情報の作成担当と、業務上の意味を確認する担当を明確にします。
完璧さより利用実績を確認する
ページ数や文書数ではなく、改修調査の短縮、問い合わせの自己解決、引き継ぎ時の利用など、実務で使われているかを確認します。使われない文書は、粒度や置き場所を見直します。
まとめ：リスクが高い領域から「使える情報」を整える
仕様書不足を解消するために、システム全体の文書を一度に作り直す必要はありません。優先順位を決める主な評価軸は次の5つです。
- 変更頻度
- 業務影響
- 調査・復旧の難しさ
- 知識の集中度
- 今後の計画との関係
高リスク領域から、機能一覧、処理フロー、データ項目定義、例外ルール、運用手順などを整備します。保守や改修と並行して更新を続ければ、文書化を止まりにくい業務へ変えられます。
仕様整理の対象や優先順位が定まらない場合は、現状調査から始める方法があります。すべての資料がそろっていなくても、コード・画面・DB・既存資料・担当者ヒアリングを組み合わせて、必要な範囲を整理できます。