仕様書がないシステムの仕様を、実際の画面の動きを一つずつ確かめながら手元のノートに書き起こしている一人運用の保守担当者
レガシー・技術的負債約14分

仕様書がないシステムの仕様を、現状から起こす進め方

「このシステム、仕様書ってないんですか？」。 上司や新しく入ったメンバーにそう聞かれて、言葉に詰まったことはないでしょうか。 探しても見つからない。あっても数年前のもので、今の動きと合っていない。作った人はとっくにいない。

結局、いま正しいと言えるのは、本番で動いているシステムそのものだけ。 その状態で「仕様を起こしてほしい」と言われると、どこから手をつければいいのか、途方に暮れますよね。 機能はいくつあるのか分からない。全部読み解くのに何か月かかるのか見当もつかない。しかも、日々の障害対応や問い合わせは待ってくれない。

でも大丈夫です。仕様を起こす作業は、「全部を一度に、完璧に書く」ものではありません。 むしろそれを目指すと、たいてい途中で力尽きます。 この記事では、仕様書がないシステムの仕様を、動いている現状から少しずつ起こしていく順番を、一人運用の現場目線で一緒に整理していきます。

結論：仕様を起こすときは、いきなりコードから読まず、次の順で進めます。①何のために起こすのか、目的を1つに絞る → ②外から見える動き（画面・入出力・帳票）を先に書き写す → ③いつ・何が勝手に動くか（バッチ・連携）を控える → ④分かった範囲を1枚に整理し、空白＝「未確認」を可視化する → ⑤コードやDBで裏を取るのは、目的に関わる部分だけ → ⑥「今日分かったこと」を、その都度ドキュメントに追記していく。目的を1つに絞ることが、終わらない作業を終わる作業に変える最初の一手です。

システムの種類（Webか業務システムか、言語、DBやバッチの構成）や、社内で使えるツール・AI利用の可否によって、やりやすい手順は変わります。この記事の順番は出発点として、自分の現場に置き換えて使ってください。 そして前提をひとつ。仕様書が無いのは、あなたの責任ではありません。今ある状態から少しずつ写していけば、それで十分価値のある仕事です。

なぜ「全部を一度に」書こうとすると失敗するのか

仕様を起こすと聞くと、つい「機能一覧を作って、画面ごとに全項目を書いて、DBの全テーブルを説明して……」と、フルセットを思い描いてしまいます。でも、その進め方は一人運用ではまず続きません。理由を先に言葉にしておくと、これから挙げる手順が「なぜこの順なのか」で腑に落ちます。

つまり、仕様起こしの主役は「網羅」ではありません。「いま困っていることを解ける分だけ、今の動きを写す」という割り切りです。だから最初にやるのは、コードを開くことではなく、目的を1つに決めることになります。

① 何のために起こすのか、目的を1つに絞る

具体的な作業に入る前に、いちばん大事な一手です。「この仕様書は、何のために作るのか」を1つに絞る。ここが決まると、どこまで書けばいいか、逆にどこは書かなくていいかがはっきりします。

目的の例を挙げてみます。自分の現場に近いものを1つ選んでみてください。

目的が1つ決まれば、「今回はここまで」という線が引けます。全機能を等しく詳しく書く必要はありません。目的に近い部分は厚く、遠い部分は「未確認」と書いておくだけで十分。線を引くことは、手抜きではなく、終わらせるための設計です。

② 外から見える動きを、先に書き写す

画面・入出力・帳票など外から見える動きを外側の起点にし、そこからバッチ連携、最後にコードやDBの内部へと内側に向かって仕様を写していく同心円の図
外から中へ。見える動きを先に写し、コードで裏を取るのは最後

目的が決まったら、いきなりコードを読み始めないでください。まず写すのは、外から見える動きです。画面、入力フォーム、出力される帳票やCSV、メール——利用者やお客さんが実際に触れている部分から始めます。

理由はシンプルで、外から見える動きは「そのシステムが何をするものか」を、いちばん正直に語っているからです。コードは「どう作られているか」を語りますが、まず知りたいのは「何をしているか」です。

ここでの目的は、完璧な理解ではなく、「この画面は、たぶんこういう機能」という当たりをつけること。分からない画面は「用途不明」と書いておけば、それが後で調べる印になります。

専門用語のメモ：ここで言う「仕様を起こす」は、動いているシステムの現状の挙動を観察して、後から仕様書の形に書き起こすことを指します。ソフトウェア開発では、こうした「完成物から中身や仕様を読み解く」作業をリバースエンジニアリングと呼ぶこともあります。難しく考えず、「今の動きを、見たまま文章と図に写す」と捉えて大丈夫です。

③ いつ・何が勝手に動くかを控える

画面の裏で、システムは自分から動いていることがあります。定期実行（バッチ・cron）や外部連携は、画面を見ているだけでは気づけません。でも、止まったときにいちばん困るのがここです。目的が「バッチ・連携」でなくても、存在の把握だけはしておきます。

「何が、いつ、勝手に動くか」の一覧は、仕様書の中でも特に価値が高い部分です。ここが1枚あるだけで、「原因不明の処理が夜中に走っていた」という事故を、ぐっと減らせます。

④ 分かった範囲を1枚に整理し、空白を可視化する

外から見える動きと、裏で動くものが少し見えてきたら、分かった範囲を1枚にまとめます。きれいな設計書でなくて大丈夫。手書きでも、表でも、箇条書きでもかまいません。

大切なのは、「分かったこと」と同じくらい「まだ分からないこと」をはっきり書くことです。空白を隠さず、「未確認」と明記しておく。この空白リストが、次に何を調べればいいかを教えてくれます。

たとえば、こんな表の形で機能を一覧にしていくと、進み具合が見えます。

機能・画面何をしているっぽいか裏で動く処理確認度
受注登録画面注文を受け付けDBに保存、確認メール送信なし確認済
日次集計前日の売上を集計しCSV出力毎晩2時のバッチ推測（要確認）
顧客インポートCSVを取り込み顧客を一括登録不明未確認

「確認度」の欄があるだけで、どこまで信じていい仕様書かが一目で分かります。全部を「確認済」にしなくて大丈夫。「未確認」がいくつ残っていても、それが見えているだけで、この1枚は立派な資産です。

⑤ コードやDBで裏を取るのは、目的に関わる部分だけ

たくさんの機能の中から、今回の目的に関わる一部だけに光を当てて深く調べ、残りは未確認のまま置いておくことを示した図
全部を深掘りしない。目的に関わる所だけコードで裏を取る

ここまで来て、ようやくコードやデータベースの出番です。ただし、全部を読み解こうとしない。①で決めた目的に関わる部分だけ、裏を取ります。

社内で外部AIの利用が許可されているなら、コードの一部を読ませて「この関数がどんな処理をしていそうか」を要約させ、読み解きの下書きにするのも手です。ただし、これはあくまであたりをつけるための要約。AIは本番だけの事情や運用の経緯までは知りません。鍵やパスワード、個人情報は渡す前に必ず伏せ、要約が指す挙動は実際の画面の動き・設定・データで裏を取ってから仕様書に書き込みます。AI利用のルールが無い・許可待ちの現場では、無理に使わず、grep でキーワード（送信、connect、テーブル名など）を拾う手元だけの方法で十分あたりはつけられます。

確認できたことは「確認済」、できないものは「推測」のまま残す。無理に断定しないことが、後で自分を助ける正直な仕様書を作ります。

⑥ 「今日分かったこと」を、その都度追記していく

仕様起こしは、まとまった時間を取って一気に終わらせる作業ではありません。日々の障害対応や問い合わせのなかで分かったことを、その都度1か所に足していく——このやり方が、一人運用ではいちばん続きます。

こうして「調べる専用の時間」ではなく「実務の副産物」として仕様を貯めていくと、半年後には、探しても見つからなかった仕様書が、いつの間にか手元にできています。

やってしまいがちな落とし穴

仕様起こしは、まじめな人ほど「完璧にやろう」として、かえって進まなくなります。よくあるつまずきを先に共有します。

落とし穴はどれも、「目的を絞り、外から写し、未確認を隠さない」という方針で、ほとんど受け止められます。

明日、いちばん小さく試せること

全部を一度にやろうとしなくて大丈夫です。まずひとつだけ試してみてください。

  1. 担当システムで、この仕様書は何のために作るかを、一行で書いてみる（①）。
  2. いちばんよく使われている画面を1つだけ開き、「どんな入力を受けて、押すと何が起きるか」をメモする（②）。
  3. crontab -l などで、いつ・何が動くかを1つでも控える（③）。
  4. その3つを、1か所のメモに書いておく（⑥の芽）。

この4つができれば、たとえシステム全体が分からなくても、「仕様書ゼロ」の状態からは確実に一歩抜け出せています。あとは、実務のなかで少しずつ足していけば大丈夫です。

「仕様を現状から起こす」チェックリスト

どこまで進んだかを見る項目です。コピーして、自分のメモに当ててみてください。全部に○が付かなくても、空欄が「次にやること」を教えてくれます。

全部そろわなくて大丈夫です。①の目的決めと②の画面1つ分だけでも、何もない状態より、ずっと落ち着いてシステムと向き合えます。

よければ、こちらも

現状から仕様を起こす作業は、引き継ぎ・改修・障害対応とそのままつながります。「見える化する型」「触る前に影響を見る型」をセットで持っておくと、日々の運用がぐっと楽になります。

現状から少しずつ書き起こした仕様のメモを手に、これで全体像が見えてきたと前向きな表情を見せる一人運用の保守担当者

仕様書がないシステムの仕様を起こすのが途方もなく感じるのは、「全部を、完璧に」書かなければと思うからでした。でも、目的を1つに絞って、外から見える動きを先に写し、未確認は未確認のまま残していけば、「終わらない作業」は「今日ここまで進んだ作業」に変わります。全部は分からなくても、今の動きは写せる。 今日はまず、「この仕様書は何のために作るか」を一行書いてみるだけで十分です。その一行が、途方もなかった作業に、ちゃんと終わりの見える形を与えてくれます。誰も知らないシステムの姿を、少しずつ言葉にしていく——それは、あなたが思うよりずっと、価値のある仕事です。

ほかの実務ヒントは記事一覧からどうぞ。保守運用の小さな備えを、メールでも少しずつお届けしています。

関連用語