Markdownで日本式の設計書を書くテンプレート｜基本設計書の項目例

日本の業務システムで使いやすい基本設計書をMarkdownで書くテンプレートです。文書情報、改訂履歴、要件、構成、運用、未決事項まで掲載します。

Markdownで設計書を管理するメリット

MarkdownはGitで差分を確認でき、レビューと改訂履歴を残しやすい形式です。一方、日本の社内設計書では、本文だけでなく文書番号、版、作成者、承認状況、改訂履歴、対象範囲が求められることがあります。最初から項目をテンプレート化すると、案件ごとの抜けを減らせます。

以下のテンプレートは基本設計書を想定しています。すべて埋めるのではなく、案件規模と読者に合わせて不要な章を削除してください。空の章を残すより、「対象外」と理由を明記する方が誤解を防げます。

コピーして使える基本設計書テンプレート

# システム基本設計書

## 文書情報

| 項目 | 内容 |
|---|---|
| 文書名 | システム基本設計書 |
| 文書番号 | SYS-BD-001 |
| 版 | 1.0 |
| 作成日 | YYYY-MM-DD |
| 作成者 | 部署・氏名 |
| 承認者 | 部署・氏名 |
| ステータス | Draft / Review / Approved |

## 改訂履歴

| 版 | 日付 | 変更内容 | 変更者 |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | 初版作成 | 氏名 |

## 概要

### 背景
[なぜこのシステムが必要か]

### 目的
[達成する業務上・技術上の目的]

### 対象読者
[PM、開発者、運用担当者など]

## 対象範囲

### 対象
- [対象業務・機能]

### 対象外
- [扱わない範囲と理由]

## 用語・略語

| 用語 | 意味 |
|---|---|
| [用語] | [定義] |

## 前提・制約
- [利用環境]
- [予算・期日]
- [既存システムとの制約]

## システム構成

### 全体構成
[構成図と説明]

### コンポーネント
| ID | 名称 | 役割 | 管理主体 |
|---|---|---|---|
| CMP-01 | [名称] | [役割] | [部署] |

## 機能設計

### 機能一覧
| ID | 機能名 | 概要 | 優先度 |
|---|---|---|---|
| F-001 | [名称] | [概要] | Must |

### 主要業務フロー
[正常系、例外系、担当者を説明]

## データ設計

### 主要データ
| ID | データ名 | 概要 | 保持期間 |
|---|---|---|---|
| D-001 | [名称] | [概要] | [期間] |

### データ連携
[入力元、出力先、頻度、形式]

## 外部インターフェース
| ID | 接続先 | 方式 | タイミング |
|---|---|---|---|
| IF-001 | [システム] | REST / Batch | [条件] |

## 非機能要件

### 性能・容量
[応答時間、同時利用、データ量]

### 可用性
[稼働時間、目標復旧時間、バックアップ]

### セキュリティ
[認証、認可、暗号化、監査ログ]

### 運用・監視
[監視項目、通知、定期作業、問い合わせ]

## 移行・リリース
[移行対象、手順、切り戻し、判定条件]

## テスト方針
[対象、環境、完了条件、責任分担]

## リスク
| ID | リスク | 影響 | 対応 |
|---|---|---|---|
| R-001 | [内容] | [影響] | [回避・軽減策] |

## 未決事項
| ID | 論点 | 担当 | 期限 |
|---|---|---|---|
| Q-001 | [確認事項] | [担当] | YYYY-MM-DD |

## 参考資料
- [要件定義書](URL)

文書情報と改訂履歴を書く理由

ファイル名だけで版を管理すると、PDFを別フォルダへ移したときに正式版か分からなくなります。本文と表紙にも版、日付、ステータスを記載し、Gitのタグや承認記録と対応させます。「最新版」という表現だけではなく、1.2のような識別可能な版を使います。

改訂履歴には誤字修正をすべて書くのではなく、読み手の判断へ影響する変更を簡潔に記録します。要件変更なら関連する機能IDやチケットも示します。

表を増やしすぎない

設計書は表が多くなりがちですが、1セルへ段落を詰めるとレビューもPDFも読みにくくなります。表は一覧と比較に使い、背景、判断理由、例外条件はH3の本文へ書きます。A4縦では4列程度を目安にし、長い識別子やURLは表示名付きリンクへ変えます。

1ページを超える表は意味のまとまりで分けます。「途中で改ページしない」は短い表だけに使い、長い一覧へ適用しないでください。

Mermaidで構成図を書く

構成図をテキスト管理したい場合はMermaidを利用できます。

```mermaid
flowchart LR
  User[利用者] --> Web[Webアプリ]
  Web --> API[API]
  API --> DB[(Database)]
  API --> External[外部サービス]
```

図だけで仕様を完結させず、各コンポーネントの責任、データ、障害時の動作を本文でも説明します。横長になりすぎる場合は概要図と詳細図へ分けます。Mermaid図をきれいにPDFへ出力する手順はMermaid図入りMarkdownをPDFにする方法で詳しく解説しています。

設計書PDFへ変換する

このテンプレートから作った.mdを、目次と印刷レイアウトに対応したPDF変換器へ読み込みます。表紙へ文書名、組織、作成日、版を設定し、H2を主要目次、H3を補助項目として扱います。保存後に開始ページと見出し階層が一致するか確認してください。

余白、ページ番号、背景色は印刷用CSSまたは変換器の設定で文書全体へ適用します。章や図表が不自然に切れる場合は、break-beforeやbreak-insideを必要な箇所だけに指定します。出力ファイル名にはタイトル、日付、版を含め、本文の版情報と一致させてください。設計書に限らず、議事録や職務経歴書といった業務文書をPDFで納品する運用は議事録・仕様書・職務経歴書をMarkdownで書いてPDF納品する方法にまとめています。

レビュー前のチェックリスト

対象範囲と対象外が明確である
要件、機能、テストのIDが対応している
未決事項に担当と期限がある
表へ長文を詰めていない
図と本文の説明が矛盾していない
セキュリティと運用が後回しになっていない
文書情報、表紙、ファイル名の版が一致している
保存したPDFで目次とページ番号を確認した

よくある質問

すべての章が必要ですか？

いいえ。小規模案件では統合・削除できます。ただし非機能、運用、未決事項を無意識に消さず、対象外なら理由を残します。

詳細設計にも使えますか？

文書情報や共通章は再利用できます。機能設計を入力・処理・出力・例外・ログの単位へ深くし、基本設計のIDと対応させます。

Wordで提出する場合は？

相手側で編集が必要な場合は、Pandocなどで同じ原稿をdocxへ変換します。固定版の承認・配布にはPDFが適しています。

設計書テンプレートをPDFで試す