ドキュメントがない既存システムを引き継ぐ方法
「仕様書はありますか」と聞くと「コードが仕様書です」という答えが返ってくる——既存システムの引き継ぎでは珍しくない光景です。設計資料も、なぜその仕様になったかの経緯も残っておらず、手元にあるのはソースコードと動いている本番環境だけ。この状態から外部チームや新任の担当者が安全に引き継ぐには、何から手をつければよいのでしょうか。
ドキュメントがないこと自体は、実は致命的な問題ではありません。コードと動いているシステムそのものが一次情報であり、正しい手順で調査すれば仕様はかなりの精度で復元できます。危険なのは、ドキュメントがないまま「分かったつもり」で変更に着手し、書かれていない前提条件を踏み抜くことです。この記事では、非エンジニアの経営者・事業責任者にも分かる形で、ドキュメントゼロの状態からの引き継ぎの現実的な進め方を整理します。
最初にやること: 読む前に「動かして観察する」
コードをいきなり読み込む前に、まずシステムを実際に動かして挙動を観察することが最優先です。理由は単純で、コードの見た目と実際の挙動が一致しているとは限らないからです。長期間運用されたシステムには、コードには残っているが実際には使われていない機能、逆にコードからは読み取りにくい形で本番だけに効いている設定(環境変数・DB上のフラグ・外部の管理画面の設定値)が積み重なっています。
初動でやることは以下の通りです。
- 開発環境やステージング環境を実際に立ち上げてみる。手順書がなければ、まずこの「起動できるかどうか」自体が最初の健全性チェックになる
- 主要な画面・機能を一通り触り、ログを見ながらどのコードが動いているかを確認する。管理画面・会員向け画面・バッチ処理・外部連携それぞれで、実際に使われている経路を洗い出す
- 本番のアクセスログ・エラーログを一定期間分見て、実際にどの機能がどれくらい使われているかを把握する。コード上は存在していても、ログ上に痕跡がない機能は「動いているが誰も使っていない」可能性がある
- DBのテーブル定義とデータの中身を見比べる。カラム名だけでは意味が分からない項目も、実データのパターンを見ると用途が推測できることが多い
この段階では機能追加や修正には手を出さず、あくまで「今何が起きているか」を観察することに徹します。動かして観察する調査は、既存プロダクトの改善で外部チームが最初に見る観点でも詳しく解説しているので、合わせて参照してください。
コードから仕様を逆算する
動かして得られた観察結果を手がかりに、次はコードを読んで仕様を逆算していきます。ゼロからすべてのコードを読むのは非効率なので、優先順位をつけて読む範囲を絞ります。
- お金・個人情報・認証に関わる処理を最優先で読む。決済処理、会員登録・退会、権限チェックのロジックは、仕様の誤読が事故に直結するため精度が要る
- エントリーポイント(ルーティング・コントローラ)から辿る。どのURLがどの処理を呼び、どのテーブルを触るかの地図を作る。この地図があるだけで以降の調査速度が大きく上がる
- バリデーション・条件分岐に注目する。「なぜこの条件が必要なのか」が分からない分岐は、過去に起きた不具合や特殊な業務要件への対応であることが多く、実は最も重要な仕様が隠れている場所
- 外部サービス連携(決済・メール送信・API連携)の呼び出し箇所を洗い出す。認証情報の在り処、失敗時の挙動(リトライするのか、エラーを握りつぶしているのか)を確認する
- バッチ処理・cronの定義を確認する。夜間バッチのような画面から見えない処理ほどドキュメント化されず、かつ止めると業務に影響が出るため優先度が高い
この作業は、コミット履歴やPull Requestのコメントが残っていれば強力な補助線になります。Gitの履歴自体が「なぜこう書かれたか」を示す準ドキュメントとして機能することも多く、コードだけでなく変更履歴も含めて読むと精度が上がります。
危険な変更を避けるための線引き
仕様の全体像がまだ見えていない段階での変更は、意図しない副作用を生みやすいものです。引き継ぎ初期は、次のような変更を避ける、あるいは特に慎重に進めることをお勧めします。
- テストがない箇所への変更。挙動が変わったことを機械的に検知できないため、手動での動作確認範囲を広く取る必要がある
- 複数の機能から共有されているコード(共通処理・共通コンポーネント)の変更。影響範囲が見えていない状態で触ると、一見関係ない画面が壊れることがある
- DBスキーマの変更。カラムの削除・型変更は、見えていない参照箇所(バッチ処理・外部連携・レポート出力など)を壊すリスクが高い
- ライブラリやフレームワークのバージョンアップ。仕様の理解が浅い状態で行うと、挙動の差異が既存の仕様なのかバグなのか切り分けられなくなる
引き継ぎ直後は「小さく、影響範囲が特定しやすい変更」から着手し、変更のたびに実際に動かして確認する、というサイクルを繰り返すのが安全です。焦って大きな改修に着手すると、後から「これは元々の仕様だったのか、今回壊したのか」が分からなくなり、かえって調査コストが膨らみます。
ドキュメントを後追いで作る、現実的な範囲
引き継ぎが一段落したら、次の担当者のためにドキュメントを整備したくなりますが、すべてを網羅しようとすると終わりません。優先順位をつけて、現実的な範囲に絞ることが重要です。
- まず作るべきは「地図」: 画面一覧、主要な機能とそれが触るテーブルの対応、外部連携の一覧。詳細な仕様より、まず全体像が見える一枚の資料が最も価値が高い
- 次に「危険地帯」の記録: 触ると事故りやすい箇所、書かれていない前提条件、過去に起きた障害とその原因。これは調査の過程で見つかった知見をそのまま書き留めるだけでよい
- デプロイ手順とインフラ構成: 属人化しやすく、かつ止まると即業務影響が出るため優先度が高い
- 全機能の詳細仕様書は後回しでよい: 使われていない機能まで丁寧にドキュメント化するのは投資対効果が低い。実際に触る予定の箇所から順に厚みを増していく方が現実的
ドキュメントは一度に完璧を目指さず、「次に誰かがこのコードを触るときに詰まった場所」を都度追記していく運用にすると、実際に使われる資料として育ちます。
外部チームに引き継ぎを依頼する場合
社内にドキュメント化する余力がない、あるいは調査自体を外部に任せたい場合、専門チームに依頼することで初動のスピードが上がります。外部チームが引き継ぎでまず行うのも、ここまで説明した「動かして観察する」「コードから仕様を逆算する」というプロセスそのものです。差が出るのは、こうした調査に慣れているかどうかと、危険な変更を見分ける経験値です。
前任者が退職して連絡が取れない、あるいは開発会社を乗り換えるといった事情がある場合は、進め方がやや異なります。前任者退職後のシステム引き継ぎで最初にやることも参考にしてください。
まとめ
- ドキュメントがなくても、コードと動いているシステムは一次情報。まず動かして観察し、次にコードから仕様を逆算する順序を守る
- お金・個人情報・認証まわりを優先的に読み、テストがない箇所・共有コード・DBスキーマ変更は特に慎重に扱う
- ドキュメントは全網羅を狙わず、まず地図(画面・機能・外部連携の一覧)と危険地帯の記録から着手する
torcheees では、ドキュメントが一切ない既存システムの引き継ぎにも数多く対応してきました。まずは「既存プロダクト改善」の入口として、診断でコードの現状・危険地帯・優先的に整備すべき範囲を洗い出し、必要であれば継続的な改善支援へつなげます。モダナイゼーション・保守・運用のサービスページもご覧いただき、まずはお問い合わせフォームからご相談ください。