当サイトの記事は編集部が国土交通省・IPA・デジタル庁などの公的機関の情報、規格や業界団体の公開情報を調べて独自に執筆しています。記事内にIT・Webエンジニアの転職サービスへの案内（広告）を含みます。
Excel VBAで作った業務ツールを『仕様書にまとめておいて』と頼まれた。でも、システム開発のような分厚い仕様書を書くほどの規模でもない。そんなふうに迷っている方も多いはずです。
結論から言うと、VBAの仕様書は「入力ファイル」「処理の手順」「出力」「困った時の連絡先」の4つを1枚にまとめれば、まずは十分です。作った本人がいなくても、別の人が使えて、直せる状態を目指します。
この記事を読めば、VBAやマクロの仕様書の書き方と、そのまま使える1枚のテンプレートが分かります。
VBAの仕様書はなぜ必要？どこまで書く？
VBAの仕様書は、作った人がいなくなっても使い続けられるようにするための物です。小さなツールなら、分厚い設計書はいりません。1枚にまとめた仕様書と、コードの中の説明で足ります。
『VBAくらいで仕様書なんて大げさじゃない？』と思いますよね。実は、小さなツールほど仕様書が無くて困る場面が多いんです。
例えば、毎月の集計マクロを作った人が異動した後、元のExcelの列が1つ増えただけで動かなくなった。こんな時、何を読み込んで何を出すツールだったかが分からないと、直す人は一からコードを読むしかありません。
規模に合わせて、どこまで書くかの目安を表にしてみました。
| ツールの規模 | 使う人 | 書いておく物 |
|---|---|---|
| 自分だけが使う小さなマクロ | 自分 | コードの先頭のメモと、使い方の数行 |
| 部署で使う業務ツール | 部署のメンバー | この記事の1枚の仕様書 |
| 複数の部署や外部の人も使うツール | 社内の広い範囲 | 1枚の仕様書に加えて、要件定義書や設計書 |
部署で使うツールなら、まずは1枚の仕様書から始めてみてください。
VBAの仕様書は4つで1枚にまとめる
VBAの仕様書は「入力ファイル」「処理の手順」「出力」「困った時の連絡先」の4つで書きます。特に「困った時の連絡先」は、ツールを長く使ううえで欠かせない項目です。
ここでは、編集部が考えた1枚の仕様書の形を紹介します。VBAの仕様書のテンプレートとして、そのままExcelのシートに写して使えますよ。
| 書くこと | 書く中身 | 書き方のコツ |
|---|---|---|
| 入力ファイル | 読み込むファイルの名前、置き場所、シート名、列の並び | 列の並びが変わると動かないことも書く |
| 処理の手順 | ボタンを押してから終わるまでに何をするか | 1行に1つの処理で、順番に書く |
| 出力 | 作られるファイルや表、保存する場所、名前の付け方 | 上書きするのか、新しく作るのかを書く |
| 困った時の連絡先 | 作った人、今の担当、エラーの時に見る所 | 個人名でなく担当の部署で書く |
入力ファイルは「前提」を書く
VBAのツールが止まる原因で多いのは、読み込むファイルの形が変わることです。シートの名前や列の並び、1行目が見出しかどうかなど、ツールが前提にしていることを書き出しておきましょう。
『そんなの見れば分かるでしょ』と思う所ほど、書いておくと後で助かりますよ。
処理の手順は、作業の言葉で書く
処理の手順は、コードの言葉ではなく、ふだんの作業の言葉で書きます。手作業でやっていた時の手順を思い出すと書きやすいです。
例えば、手作業の手順をそのまま並べると、こんな書き方になります。
| 順番 | 処理の手順の書き方 |
|---|---|
| 1 | 売上のシートから、今月の行だけを抜き出す |
| 2 | 担当者ごとに金額を合計する |
| 3 | 合計を集計表のシートに貼る |
| 4 | 集計表を新しいファイルとして保存する |
1行に1つの処理になっていれば、どこで止まったかを探す時にも役に立ちますよ。
エラーの時にどうなるかも書いておく
『正しく動く時のことだけ書けばいいよね』と思いがちです。ただ、困るのは決まって動かなかった時なんです。
ファイルが見つからない時、空の行があった時、同じ名前のファイルがすでにある時に、ツールがどう動くかを書いておきましょう。止まるのか、メッセージを出して続けるのかが分かるだけで、使う人の不安がぐっと減ります。
| よくある場面 | 書いておくこと |
|---|---|
| 読み込むファイルが見つからない | メッセージを出して止まるか |
| 途中に空の行がある | 空の行を飛ばすか、そこで終わるか |
| 同じ名前のファイルがある | 上書きするか、名前を変えて保存するか |
VBA仕様書のサンプル（記入例）
記入例を見ると、どれくらいの細かさで書けばいいかがつかめます。ここでは、編集部が作った架空のツールで書いてみました。
『実際に書くと、どんな感じになるの？』という方のために、VBAの仕様書のサンプルを作ってみました。毎月の売上の集計をするツールという想定です。
| 書くこと | 記入例 |
|---|---|
| ツールの名前 | 月次売上集計ツール |
| 目的 | 毎月の売上の集計にかかる手作業を減らす |
| 入力ファイル | 共有フォルダの「売上」フォルダにある、その月の売上のExcel。シート名は「売上」。1行目は見出し、列は日付・担当者・金額の順 |
| 処理の手順 | 1. 集計したい月を入力する／2. その月の行だけを抜き出す／3. 担当者ごとに金額を合計する／4. 集計表のシートに貼る |
| 出力 | 同じフォルダに「集計_年月」という名前で新しいファイルを作る。上書きはしない |
| エラーの時 | 売上のファイルが見つからない時は、メッセージを出して止まる |
| 困った時の連絡先 | 作った部署は営業管理。今の担当は営業管理の集計担当 |
| 更新の記録 | 作った日、直した日と直した内容を書く |
このサンプルは架空の物です。項目の名前は、自分の職場の言葉に合わせて変えてみてください。
項目ごとの書き方の見本は、仕様書のサンプル・記入例でも紹介しています。
- 作った本人以外が読んで、ツールの使い方が分かる
- 入力ファイルの置き場所と形が書いてある
- 出力が上書きか、新しいファイルかが書いてある
- エラーの時にどうなるかが書いてある
- 困った時に誰に聞けばいいかが書いてある
VBAの設計書・要件定義書はいる？
部署の中で使う小さなツールなら、VBAの設計書や要件定義書を別に作らなくても困らないことが多いです。ただ、使う人が広がる時や、外部に作ってもらう時は、要件定義書から作っておくと安心です。
『VBAでも、ちゃんとした設計書を書くべき？』と迷う方もいますよね。目安は、作る人と使う人が別かどうかです。
| 場面 | 作っておきたい物 | 理由 |
|---|---|---|
| 自分で作って自分の部署で使う | 1枚の仕様書 | 引き継ぎに困らなければ十分 |
| 他の部署に頼まれて作る | 1枚の仕様書と、頼まれた内容のメモ | 何を頼まれたかの食い違いを防ぐ |
| 外部や情報システム部門に作ってもらう | VBAの要件定義書 | 作る人に、何がほしいかを正しく伝える |
| 処理が多く、何人かで直していく | VBAの設計書 | どの処理がどこにあるかを共有する |
VBAの設計書に書くこと
設計書を作る場合は、1枚の仕様書に「どのモジュールで何をするか」を足すイメージです。プロシージャ（処理のまとまり）ごとに、名前、役目、受け取る物と返す物を一覧にしておくと、直す人が迷いません。
機能ごとの仕様の書き方は、機能仕様書とは？も参考になります。
コードの先頭に書いておくこと
仕様書とは別に、コードの先頭にも短いメモを残しておくと、直す人がとても助かります。仕様書を開かなくても、何のためのコードかが分かるからです。
- このツールの目的を1行で書く
- 読み込むファイルと出力するファイルを書く
- 仕様書の置き場所を書く
- 直した日と直した内容を書く
コードを直したのに仕様書を直さず、仕様書と中身が食い違ってしまうことがあります。直した時は、仕様書の「更新の記録」に日付と内容を1行足すのを習慣にしておきましょう。
RPAの仕様書テンプレートにも使える
画面操作を自動にするRPAでも、仕様書の考え方は同じです。4つの項目に「操作する画面」と「止まった時の手作業の手順」を足すと、RPAの仕様書テンプレートになります。
RPAのツールは、人がパソコンでしていた操作を順番に自動で行います。そのため、処理の手順を「どの画面で、どこを押すか」まで書いておくのがポイントです。
| 足す項目 | 書く中身 |
|---|---|
| 操作する画面 | どのシステムの、どの画面を使うか |
| 画面が変わった時 | 画面の見た目が変わったら止まる可能性があること |
| 止まった時の手作業 | 自動で動かない時に、人がどう代わりにやるか |
『自動化したら手順は忘れてもいいよね』と思いがちです。ただ、止まった時に手でやれる人がいないと業務が回らなくなるので、手作業の手順は残しておきましょう。
例えば、毎朝システムから一覧を出してExcelに貼るRPAなら、こんな一文を足しておくと安心です。
「システムの画面が変わってRPAが止まった時は、一覧の画面から手で出力し、集計のシートに貼る。手順は別紙のとおり。」
RPAの仕様書は、システムの画面が変わるたびに見直しが必要になります。画面が変わる予定を聞いたら、仕様書も一緒に確かめる習慣を付けておきましょう。
VBA・マクロの仕様書でよくある相談
よく見かけるのは「VBAで仕様書を書く人はいるのか」「ボタンで仕様書の範囲を出力したい」「VBAの経験を仕事にしたい」の3つです。
よく見かける相談を、内容をまとめた形で紹介します。
相談1：VBAで仕様書を書く人はいる？
VBAで設計の仕様書を書く人はいるのか、それともVBAくらいでは書かないのか、という相談です。
職場によって違いますが、部署で使い続けるツールなら書いておく方が安心です。マクロの仕様書の書き方は、この記事の1枚で十分です。まずは書いてみて、困った所を足していけば大丈夫ですよ。
相談2：ボタンを押したらシートの一部を仕様書として出したい
Excel VBAで作った見積書のシートから、ボタンを押したら特定の範囲を仕様書として出力したい、という相談もあります。
こうした時も、作る前に「どの範囲を」「どんな形で」「どこへ出すか」を1枚に書き出してみてください。入力と出力がはっきりすると、作り方も調べやすくなります。
相談3：VBAの経験を仕事にしたい
VBAでツールを作れるようになったので、もっと本格的なソフトを作る仕事がしたい、という相談も見かけます。
業務の困りごとを聞いて、ツールの仕様にまとめた経験は、社内SEの仕事とも重なります。社内SEと仕様書の関わりは、社内SEと仕様書で紹介しています。
今の職場でツール作りを任されながら経験を積むのも、立派な道です。そのうえで、ITの仕事に興味が出てきた方は、求人の仕事内容を比べてみると道が見えてきますよ。
IT・Webエンジニアの転職（PR）
仕様書を書く経験を活かせる職場を探すなら、求人も比べてみる
要件定義や設計を任されるか、発注側か開発側か、扱うシステムや働き方は会社によって大きく違います。担当したい工程や条件から、IT・Webエンジニアの求人を比べてみてください。
無料ITエンジニアの求人を探す求人の条件・待遇は各求人票と応募先の案内でご確認ください。
仕様書そのものの意味や、設計書・要件定義書との違いは、仕様書とは？意味と目的、設計書・要件定義書との違いで紹介しています。
よくある質問
VBAの仕様書の書き方で一番大事なことは？
作った本人がいなくても、別の人が使えて直せることです。入力ファイル・処理の手順・出力・困った時の連絡先の4つを1枚に書いておきましょう。
VBAの仕様書のテンプレートはありますか？
この記事の4つの項目と記入例の表を、Excelのシートに写して使えます。項目の名前は職場の言葉に合わせて変えてください。
マクロの仕様書はコードの中に書いてもいいですか？
コードの先頭に目的や更新の記録を書いておくのは良い方法です。ただ、使う人はコードを開かないことも多いので、使い方は別の1枚にもまとめておくと安心です。
仕様書をどこに置いておけばいいですか？
ツールのファイルと同じフォルダに置くのがおすすめです。ツールの中に説明のシートを1枚作っておく方法もあります。
VBAの要件定義書は誰が書きますか？
ツールがほしい部署が「何に困っていて、何ができれば助かるか」を書くのが基本です。作る人はそれを読んで、入力や出力の形を一緒に詰めていきます。
まとめ
- VBAの仕様書は、作った人がいなくても使い続けるための物
- 入力ファイル・処理の手順・出力・困った時の連絡先の4つを1枚にまとめる
- 部署の中のツールなら、設計書や要件定義書は無くても困らないことが多い
- RPAの仕様書は、操作する画面と止まった時の手作業を足す
- 直したら仕様書の更新の記録も直す
コメント