当サイトの記事は編集部が国土交通省・IPA・デジタル庁などの公的機関の情報、規格や業界団体の公開情報を調べて独自に執筆しています。記事内にIT・Webエンジニアの転職サービスへの案内（広告）を含みます。
設計書がほとんど残っていないシステムを引き継いで、『ソースを読んで設計書を作り直して』と頼まれた。そんな場面で途方に暮れている方も多いはずです。
結論から言うと、設計書のリバースは「コードから読み取れる事実」と「人に聞かないと分からない理由」を分けて書くのがコツです。全部をコードから起こそうとせず、目的に合う範囲だけを先に決めると、ぐっと進めやすくなります。
この記事を読めば、リバースの手順と、どこまで書けば十分かの目安が分かります。
設計書のリバースとは？何を作る作業なのか
設計書のリバースは、今動いているソースコードやデータベースを読んで、設計書を後から書き起こす作業です。ふだんの開発は「設計書からコード」ですが、その逆向きなのでリバースと呼ばれます。
現場では「設計書リバース」「リバースで設計書を起こす」のように言われます。設計書が最初から無い、あってもコードと合っていない、という時に出てくる仕事です。
設計書の種類や役割そのものは、設計書とは？システム開発の設計書の種類と役割でまとめています。ここでは、リバースならではの進め方に絞ってお話ししますね。
リバースが必要になるのはこんな時
『そもそも、なんで今さら設計書を作るの？』と思うかもしれません。実は、リバースの依頼にはだいたい決まった理由があります。
| きっかけ | よくある状況 | 主に欲しい物 |
|---|---|---|
| 保守の引き継ぎ | 担当者が異動して、資料がほぼ無い | 全体の構成と、よく直す所の処理の流れ |
| 改修の前 | 機能を足したいが、影響範囲が読めない | 触る画面・処理・テーブルのつながり |
| 作り直し・移行 | 古いシステムを新しくしたい | 今の機能の一覧と、業務のルール |
| 監査・説明 | 外部に仕組みを説明する必要がある | 構成図とデータの流れ |
同じリバースでも、きっかけによって作る物も細かさも変わります。ここを最初に決めないまま始めると、量だけ増えて使われない設計書になりがちなんです。
リバースで分かること・分からないこと
コードからは「何をしているか」は読み取れますが、「なぜそうしたのか」は読み取れません。この2つを最初から分けて書くと、設計書の信頼度がぐっと上がります。
ソースコードは、システムが今どう動くかを一番正確に表している資料です。ただ、書いた人の考えや、業務上の決まりまではコードに残っていないことが多いんですよね。
そこで編集部では、リバースで分かることと分からないことを表に分けてみました。
| 知りたいこと | コードから読み取れるか | 分からない時の確かめ先 |
|---|---|---|
| 画面やプログラムの一覧 | 読み取れる | なし（コードとフォルダ構成で足りる） |
| 処理の流れ・呼び出し順 | 読み取れる | 動かして確かめると確実 |
| テーブルと項目の一覧 | 読み取れる | データベースの定義と照らし合わせる |
| 入力チェックや計算の中身 | 読み取れる | 条件が多い所はテストで確かめる |
| なぜその計算方法にしたか | 読み取れない | 業務の担当者・前任者に聞く |
| 業務上の決まりや例外の理由 | 読み取れない | 業務マニュアル・社内の規程 |
| 使われていない機能かどうか | 一部だけ | 利用ログや業務の担当者に聞く |
| 今後の変更予定 | 読み取れない | システムの責任者に聞く |
分からないことは「確認待ち」と書いておく
読み取れない所を推測で埋めてしまうのが、一番やってはいけないことです。推測が設計書に載ると、次の人はそれを事実だと思って読んでしまいますよね。
例えばこんな書き方にしておくと、後から見ても誤解されません。
「会員の割引率は、登録年数で3段階に分かれる（コードで確認）。段階の分け方の理由は確認待ち（業務担当に質問中）。」
「コードで確認」「動かして確認」「担当者に聞いた」のように、情報の出どころを一言添えておくと、レビューする人も判断しやすくなります。
設計書をリバースで作る手順
いきなりコードを1行目から読むのではなく、全体の地図を作ってから、目的に関係する所だけを深く読みます。この順番にすると、迷子になりません。
『どこから読めばいいのか分からない』というのは、リバースで一番よくある悩みです。編集部のおすすめは、外側から内側へ読んでいく順番です。
- 目的と範囲を決める（引き継ぎ用か、改修用か、作り直し用か）
- 動く環境を用意して、画面を実際に触ってみる
- フォルダ構成とプログラムの一覧を作る
- 画面・処理・テーブルのつながりを1枚の図にする
- 目的に関係する処理だけ、流れを詳しく書く
- 分からない所を質問表にまとめて、担当者に確かめる
- 書いた設計書を、別の人に読んでもらって直す
先に画面を触るのが近道
コードを読む前に、まず画面を触ってみてください。どのボタンを押すと何が起きるかを知っていると、コードの意味がずっと早く分かります。
「登録ボタンを押すと、確認画面が出てから保存される」と分かっていれば、コードのどこを追えばいいかの見当がつきますよね。
一覧と図を先に作る
次に、プログラムの一覧と、画面・処理・テーブルのつながりの図を作ります。この2つは、どんな目的のリバースでも役に立つ土台です。
| 作る物 | 書く中身 | 使い道 |
|---|---|---|
| プログラム一覧 | ファイル名、役割、呼び出し元 | 影響範囲を調べる時の索引 |
| 画面一覧 | 画面名、開き方、使う人 | 業務の担当者と話す時の共通語 |
| テーブル一覧 | テーブル名、中身、使う画面 | データの流れを追う時の索引 |
| 全体のつながりの図 | 画面と処理とテーブルの関係 | 新しく来た人への説明 |
画面一覧の書き方は画面設計書・画面仕様書の書き方、テーブル一覧の書き方はテーブル定義書・データベース設計書の書き方も参考にしてみてください。
どこまで書く？目的別のまとめ方
リバースで全部の処理を詳しく書く必要はありません。目的が引き継ぎなら「全体の地図＋よく直す所」、改修なら「触る所の詳しい流れ」で十分なことが多いです。
ここが一番迷う所ですよね。『全部書かないと怒られるかも…』と不安になる方もいるはずです。
ただ、コードの中身をそのまま日本語に置き換えただけの設計書は、コードを読むのと手間が変わりません。設計書に書く価値があるのは、コードを読まなくても分かる「まとめ」の部分なんです。
| 目的 | 優先して書く物 | 細かさの目安 |
|---|---|---|
| 保守の引き継ぎ | 全体のつながりの図、画面一覧、よく問い合わせが来る処理 | 処理は概要と注意点まで |
| 改修の前の調査 | 触る画面・処理・テーブルと、その呼び出し元 | 触る所は条件分岐まで詳しく |
| 作り直し・移行 | 機能の一覧、業務のルール、データの持ち方 | 画面の見た目より決まりごと |
| 監査・説明 | 構成図、データの流れ、権限の分け方 | 外部の人が読める言葉で |
詳細設計書の細かさで書くのは一部だけ
処理の中身を一つずつ書く詳細設計書の形は、改修で触る所や、間違えると影響が大きい所に絞るのがおすすめです。詳細設計書の書き方は詳細設計書とは？基本設計書との違いと書き方で紹介しています。
- この設計書を読むのは誰かを決める
- 読んだ人が何をできるようになればいいかを決める
- 期限と、使える時間を確かめる
- 範囲から外す所を書き出しておく
- 依頼した人と、範囲を合意しておく
生成AIやツールに任せる時に確かめる所
コードを読み込ませて設計書の下書きを作る方法は便利です。ただ、出てきた文章は「コードの言い換え」にすぎないので、分からないことまで埋めていないかを人が確かめます。
最近は、生成AIにソースコードを読ませて、処理の説明や一覧を下書きさせる方法もありますよね。プログラム一覧や呼び出し関係を図にしてくれる開発ツールもあります。
一覧づくりのような手間のかかる作業を任せられるのは、大きな助けです。使い方の流れは仕様書をAIで作る｜生成AIに下書きさせる手順と確かめる所で詳しく紹介しています。
生成AIの下書きは、もっともらしい「理由」まで書いてしまうことがあります。コードに書いていない理由や業務の決まりは、担当者に確かめるまで「確認待ち」にしておきましょう。
会社のルールも確かめておく
社内のソースコードを外部のサービスに読み込ませてよいかは、会社ごとに決まりがあります。使う前に、情報システムの担当や上司に確かめておくと安心です。
| 任せやすい作業 | 人が確かめる作業 |
|---|---|
| プログラムやテーブルの一覧づくり | 一覧に漏れがないか |
| 処理の流れの下書き | 実際に動かした結果と合っているか |
| 呼び出し関係の図 | 使われていない部分の判断 |
| 説明文の言い換え | 業務の決まりや理由の記述 |
設計書リバースでよくある相談
よく寄せられるのは「資料のないシステムをどう読み解くか」と「条件分岐まで全部書くべきか」の2つです。どちらも、目的を決めて範囲を絞ることが答えになります。
よく見かける相談を、内容をまとめた形で紹介します。
相談1：資料のないシステムを引き継いだ。どこから手をつける？
ドキュメントがほとんど無いシステムの運用と保守を引き継ぎ、ソースを読んで機能を調べたい、という相談です。閲覧数も多く、同じ状況の方がたくさんいることが分かります。
まずは画面を触り、プログラムと画面とテーブルの一覧を作るところから始めてみてください。そのうえで、問い合わせや障害の連絡が多い処理から詳しく読むと、引き継ぎに一番効く設計書になります。
保守の仕事では、資料を作る時間を取りにくいですよね。直すたびに少しずつ書き足していく形でも、十分に価値があります。
相談2：条件分岐を全部仕様書に書くのは無理では？
プログラマーとして経験のある方からの、条件分岐をすべて仕様書に書くのは現実的ではないのでは、という相談です。
この悩みはもっともです。分岐を全部書き写すと、コードと同じ量の文書ができてしまいますよね。
おすすめは、業務のルールとして意味がある分岐だけを表にまとめる方法です。
| 条件 | 結果 | 出どころ |
|---|---|---|
| 会員で、登録から1年以上 | 割引を適用する | コードで確認 |
| 会員で、登録から1年未満 | 割引なし | コードで確認 |
| 会員でない | 割引なし | コードで確認 |
エラー処理や細かな分岐は、コードのコメントに任せる割り切りも大事です。
リバースの経験はどこで活きる？
人の書いたコードを読み解いて、誰でも分かる文書にまとめる力は、どの開発現場でも頼りにされます。リバースは地味ですが、設計の力を伸ばす近道でもあるんです。
実は、リバースで設計書を起こした経験は、そのまま設計の練習になっています。どこに何を書けば次の人が困らないかを、身をもって学べるからなんです。
今の職場で保守を続けながら、設計の担当を任せてもらえるよう相談するのも立派な道です。そのうえで、要件定義や設計を任される職場に進みたい方は、求人の仕事内容を比べてみると道が見えてきますよ。
IT・Webエンジニアの転職（PR）
仕様書を書く経験を活かせる職場を探すなら、求人も比べてみる
要件定義や設計を任されるか、発注側か開発側か、扱うシステムや働き方は会社によって大きく違います。担当したい工程や条件から、IT・Webエンジニアの求人を比べてみてください。
無料ITエンジニアの求人を探す求人の条件・待遇は各求人票と応募先の案内でご確認ください。
仕様書と設計書の違いや全体の位置づけは、仕様書とは？意味と目的、設計書・要件定義書との違いで確かめられます。
よくある質問
設計書のリバースとは何ですか？
今動いているソースコードやデータベースを読んで、設計書を後から書き起こす作業です。設計書が無い、またはコードと合っていない時に行います。
リバースで作った設計書は、どこまで細かく書けばいいですか？
目的によって変わります。引き継ぎなら全体の地図とよく直す所、改修なら触る所の詳しい流れ、のように範囲を決めて書くのがおすすめです。
コードから分からないことはどう書けばいいですか？
推測で埋めず、「確認待ち」と書いて担当者に質問します。情報の出どころを一言添えておくと、後から読む人が判断しやすくなります。
生成AIで設計書をリバースしてもいいですか？
下書きや一覧づくりには便利です。ただ、ソースコードを外部に出してよいかは会社の決まりを確かめ、出てきた内容は人が動作と照らし合わせて確かめましょう。
まとめ
- 設計書のリバースは、ソースコードから設計書を後から起こす作業
- コードで分かる「何をしているか」と、人に聞く「なぜか」を分けて書く
- 画面を触り、一覧と全体の図を作ってから詳しく読む
- 目的に合わせて範囲を決め、全部を書き写さない
- 生成AIの下書きは、理由や業務の決まりを人が確かめる
コメント