当サイトの記事は編集部が国土交通省・IPA・デジタル庁などの公的機関の情報、規格や業界団体の公開情報を調べて独自に執筆しています。記事内にIT・Webエンジニアの転職サービスへの案内（広告）を含みます。
チームで『仕様書はMarkdownで書こう』と決まったものの、Excelの方眼紙に慣れていると、何から手をつければいいか迷いますよね。
結論から言うと、仕様書をMarkdownで書く時は「見出し」「表」「テキストの図」「変更履歴」の4つの部品を決めておけば十分です。記法は少しだけ覚えれば書けます。
この記事を読めば、設計書や要件定義書をマークダウンで書く手順と、ファイルを散らからせない管理のコツが分かります。
仕様書をMarkdownで書くとはどういうこと？
Markdownは、記号を少し足すだけで見出しや表を表せる、テキストの書き方のルールです。仕様書をこれで書くと、普通のテキストファイルのまま読める文書になります。
Markdown（マークダウン）は、行の頭に「#」を付けると見出し、「-」を付けると箇条書き、という簡単な決まりで書く方法です。特別なソフトが無くても、メモ帳のようなテキストエディタで開けば中身が読めます。
書き方の細かい決まりには流派がありますが、広く参照されている仕様のひとつがCommonMarkです。CommonMark Specの最新版は0.31.2（2024年1月28日）とされています。
CommonMarkは、Markdownという書き方そのものの仕様書なんです。記法の細かいところで迷った時は、CommonMark Specで確かめられます。
Excel・Wordで書く仕様書と何が違う？
『Excelでも書けるのに、わざわざ変える意味ある？』と思う方も多いはずです。違いは、どこに強みがあるかなんです。
| 比べる点 | Markdown | Excel・Word |
|---|---|---|
| ファイルの中身 | ただのテキスト | 専用の形式 |
| 変更の差分 | 行ごとに比べやすい | 比べるのに手間がかかる |
| 表 | 簡単な表なら書ける | 大きな表や計算が得意 |
| 見た目の自由度 | 低め（そのぶん揃う） | 高い |
| 向く場面 | 開発者が読む設計書・要件のメモ | 発注先や社外に渡す正式な書類 |
どちらが上ということはありません。読む人と使い方で選ぶのが近道です。
設計書・要件定義書をマークダウンで書くメリット
いちばんのメリットは、変更の差分が追いやすいことです。ソースコードと同じ場所で管理できるので、設計書と実装のずれにも気づきやすくなります。
設計書をマークダウンで書くと、ソースコードと同じ仕組みで版を管理できます。誰がどの行をいつ変えたかが、行単位で残るんですね。
例えばこんな場面
画面の入力チェックで、文字数の上限を変えたい時を考えてみましょう。Excelだと、どのセルが変わったか探すのに時間がかかりがちです。
Markdownなら、変わった1行だけが差分として出ます。レビューする人は、その行だけ見れば済むんです。
- 開発チームの中で読む設計書
- 何度も書き直す要件のメモ
- APIや画面の項目一覧
- 押印や表紙の体裁が決まった契約まわりの書類
- 計算式の入った大きな表
- 社外の人が専用ソフトで開く前提の書類
要件定義書をマークダウンで書く場合も同じ考え方です。ただし発注者に渡す正式版は、相手が読める形式に書き出して渡すのが親切ですよ。
4つの部品で組むMarkdown仕様書の手順
Markdownの仕様書は「見出し」「表」「テキストの図」「変更履歴」の4部品で組み立てます。この4つの書き方をチームで決めておくと、誰が書いても同じ形になります。
ここが大事なところです。記法を全部覚えるより、仕様書で使う部品を絞ったほうが書きやすくなります。
部品1：見出しで目次を作る
まず「#」の数で見出しの深さを決めます。「#」が1つなら文書のタイトル、2つなら章、3つなら節、という使い方が一般的です。
章立ては、先に見出しだけ並べてから中身を書くと迷いません。例えば次のような並びです。
| 見出しの深さ | 例（架空の会員登録機能） |
|---|---|
| # 1つ | 会員登録機能 設計書 |
| # 2つ | 1. 概要 |
| # 2つ | 2. 画面の項目 |
| # 2つ | 3. 入力チェック |
| # 2つ | 4. エラー時の動き |
| # 2つ | 5. 変更履歴 |
部品2：表で項目を並べる
画面の項目やテーブルの列は、表で書くと読みやすくなります。Markdownの表は、縦棒で列を区切り、2行目にハイフンの行を入れる書き方です。
表の列は、項目名・型・必須・桁数・備考くらいに絞っておきましょう。列が10を超えるような表は、Excelで管理したほうが楽なこともあります。
部品3：図はテキストで描く
画面遷移や処理の流れは、テキストで図を描く記法を使う方法があります。文字で書いた図なので、図の変更も差分で追えるんです。
テキストの図が使えない環境なら、作図ツールで描いた画像を同じフォルダに置き、Markdownから画像として読み込みます。この時、画像の元ファイルも一緒に保存しておくと、あとで直しやすくなりますよ。
部品4：変更履歴を残す
文書の最後に、版・日付・変えた所・変えた人を表で残します。版の管理の仕組みでも履歴は残りますが、読む人がひと目で分かるように文書の中にも書いておくと親切です。
- 見出しだけを並べて章立てを決める
- 画面やデータの項目を表で書く
- 流れや遷移をテキストの図か画像で添える
- 決まっていない所に「未定」と書いて残す
- 変更履歴の表に初版を記入する
- チームの誰かに読んでもらう
Markdownの仕様書テンプレートを作るコツ
Markdownの仕様書テンプレートは、見出しと表の枠だけを入れた空のファイルとして作ります。書き方の説明を枠の中に短く書いておくと、初めての人でも迷いません。
『テンプレートって、どこかの見本を持ってくればいいの？』と思うかもしれません。ただ、仕様書の章立ては会社や案件で変わるので、自分たちの項目で作るほうが使いやすいんです。
架空の記入例で見るテンプレートの枠
編集部で作った架空の枠を紹介します。章ごとに「何を書くか」を1行で添えておくのがコツです。
| 章 | 枠の中に書いておく説明 |
|---|---|
| 概要 | この機能が何のためにあるかを2〜3文で |
| 前提 | 使う人、使う場面、決まっている制約 |
| 項目一覧 | 表で項目名・型・必須・桁数 |
| 処理の流れ | テキストの図か画像で |
| エラー時 | どんな時に何を表示するか |
| 未決事項 | 決まっていない事と、いつ誰が決めるか |
| 変更履歴 | 版・日付・内容・担当 |
ExcelやWordのひな形との使い分けは、仕様書のテンプレートで詳しく紹介しています。設計書の見本の考え方は設計書のテンプレート・サンプルも参考にしてみてください。
- 見出しの深さが章ごとにそろっている
- 表の列の名前と順番が決まっている
- 図をどこに置くかが書いてある
- 未決事項を書く場所がある
- 変更履歴の表が最後にある
マークダウン仕様書のよくある相談
よく見かけるのは「マークダウンって流行っているの？」「記号の意味が分からない」「AIで書く時もマークダウン？」の3つです。どれも、仕様書で使う範囲に絞れば難しくありません。
知恵袋などで見かける相談を、内容をまとめて紹介します。
相談1：マークダウン記法って流行っているの？
マークダウンは覚えやすくて書くのが楽しいけれど、世の中で流行っているのか、という相談です。閲覧数も多く、気になっている人が多いことが分かります。
開発の現場では、説明書きや設計のメモをマークダウンで書く場面がよくあります。ただ、社外への正式な書類はWordやPDFという職場も多いので、両方に慣れておくと安心ですよ。
相談2：「*」の記号はどういう意味？
文章に出てくる「*」の記号は何を意味するのか、という相談もあります。Markdownでは、この記号で文字をはさむと強調、行の頭に置くと箇条書き、という使い方をします。
仕様書の中では、強調と箇条書きの記号をチームでどちらかに決めておきましょう。人によって「*」と「-」が混ざると、読む時に気が散ってしまいます。
相談3：AIを使った開発でも仕様書はマークダウン？
IT企業では、どれくらい生成AIを使って開発しているのか、という相談です。実は、AIに読ませる仕様書をMarkdownで書く場面が増えています。
仕様書駆動開発の公開ツールの中には、要求や設計をMarkdownのファイルで書き出す流れのものもあります。詳しくは仕様書駆動開発とは？や仕様書をAIで作るで紹介しています。
AIが書いたMarkdownをそのまま正式な仕様書にしてしまうことです。項目の抜けや、決めていない事が決まったように書かれていることがあります。人が読んで確かめてから版を付けましょう。
Markdownで書いた仕様書を管理するコツ
管理のコツは「1機能1ファイル」「画像は同じ場所」「決まった所で版を付ける」の3つです。ファイルが増えても迷子になりません。
Markdownは書くのが手軽なぶん、ファイルがどんどん増えますよね。最初に置き場所とファイル名の決まりを作っておくと、あとで探す手間が減ります。
| 決めておくこと | 決め方の例 |
|---|---|
| ファイルの単位 | 1機能につき1ファイル |
| ファイル名 | 機能名を英数字で、日付は入れない |
| 画像の置き場所 | 同じフォルダの中に画像用のフォルダを作る |
| 版の付け方 | レビューで確定した時に版を上げる |
| 正式版の渡し方 | 社外にはPDFなどに書き出して渡す |
ファイル名に日付を入れないのは、同じ機能のファイルが何個もできるのを防ぐためです。履歴は版の管理の仕組みと、文書の中の変更履歴に任せましょう。
例えばこんな会話
「この設計書、最新はどれ？」
「同じファイルが1つだけだから、それが最新だよ。前の版は履歴で見られるよ」
こんなふうに言える状態が、Markdownで管理するいちばんの良さなんです。
Markdownで仕様書を書く経験を仕事に活かすには
Markdownで設計書を書き、差分でレビューする経験は、今の開発の現場でよく求められる力です。上流工程に進みたい人の足がかりにもなります。
『書き方を変えただけで、仕事に関係あるの？』と思うかもしれません。実は、仕様をテキストで残し、変更を差分で説明できる人は、チームの中で頼られやすいんです。
今の職場で設計書を任せてもらえるよう経験を積むのも、もちろん正当な道です。要件定義や設計を担当する仕事に一歩進みたい人は、求人の仕事内容で「どの工程を任されるか」を比べてみると、進む道が見えてきますよ。
IT・Webエンジニアの転職（PR）
仕様書を書く経験を活かせる職場を探すなら、求人も比べてみる
要件定義や設計を任されるか、発注側か開発側か、扱うシステムや働き方は会社によって大きく違います。担当したい工程や条件から、IT・Webエンジニアの求人を比べてみてください。
無料ITエンジニアの求人を探す求人の条件・待遇は各求人票と応募先の案内でご確認ください。
よくある質問
仕様書をMarkdownで書くのは一般的ですか？
開発チームの中で読む設計書や要件のメモでは、よく使われる書き方です。社外に渡す正式な書類はWordやPDFという職場も多いので、読む人に合わせて使い分けましょう。
設計書をマークダウンで書く時、表はどう書きますか？
縦棒で列を区切り、2行目にハイフンの行を入れて表にします。列が多い表や計算が必要な表は、Excelで管理したほうが楽なこともあります。
Markdownの仕様書テンプレートはどう作ればいいですか？
見出しと表の枠だけを入れた空のファイルを作り、各章に「何を書くか」を1行で添えます。未決事項と変更履歴の欄を最初から入れておくのがおすすめです。
要件定義書もマークダウンで書けますか？
書けます。ただし発注者が読む正式版は、相手が開ける形式に書き出して渡すと親切です。決まっていない要件は「未定」と書いて残しておきましょう。
まとめ
- Markdownは記号を少し足して見出しや表を表すテキストの書き方
- 仕様書は見出し・表・テキストの図・変更履歴の4部品で組む
- 変更の差分が行単位で追えるのがいちばんの良さ
- テンプレートは見出しと表の枠だけの空のファイルで作る
- 社外に渡す正式版は相手が読める形式に書き出す
コメント