【実務テンプレート付】システム設計書・仕様書をMarkdownで書く完全ガイド｜構成案・Mermaid図解・Word/Excel脱却手順

システム開発の現場で、誰もが一度は経験したことのある 「WordやExcelで書かれた仕様書・設計書が放置され、ソースコードと完全に乖離したゾンビドキュメントになる悲劇」 。仕様変更のたびに重いExcelファイルを開き、セルの結合を崩さないようにテキストを微調整し、「どれが最新版かわからない」とチーム全員が頭を抱える運用は、今や開発効率と品質を著しく低下させる最大のボトルネックとなっています。

この課題を根本から打破し、アジャイル開発やDevOpsの現場でデファクトスタンダードとなっているのが 「Markdown（マークダウン）によるシステム設計書・仕様書の運用（Docs as Code）」 です。設計書をプレーンテキストのMarkdownで記述することで、Gitを用いた行単位の変更差分（diff）管理、Pull Request（PR）でのインラインレビュー、ソースコードとドキュメントのリポジトリ一元管理、CI/CDパイプラインでの自動ビルド＆静的ホスティングまで、現代のエンジニアリングの強力なエコシステムをそのまま設計書に適用できます。

本記事は、 「WordやExcelの設計書から脱却したい」「GitとMarkdownで生きた仕様書を運用したい」 と考えるエンジニア・開発チームのために、 コピペしてリポジトリにそのままコミットできる4大実務テンプレート（基本設計書・REST API仕様書・DBテーブル定義書・画面設計書） をはじめ、Mermaidによるダイアグラム直接描画、PDF納品時の改ページCSS設定、客先折衷案までを徹底解説した完全ガイドです。

なぜ今、Word/ExcelからMarkdown設計書への移行が進むのか？（脱Excelの決定打）

従来、日本のSIerや受託開発、社内情報システム部では「設計書＝Excel」「仕様書＝Word」という固定概念が長年定着していました。しかし近年、先進的なWeb系企業やアジャイル開発チームのみならず、エンタープライズ領域でも 「Docs as Code（ドキュメントをコードと同様に扱う）」 という思想のもと、Markdownへの移行が急速に加速しています。その決定打となっている3大メリットを解説します。

Gitによる変更差分（diff）の可視化とPRレビューによる品質向上

WordやExcelの最大の弱点は、ファイルがバイナリ形式（または圧縮XML）であるため、 「具体的に誰が、どの行を、どう変更したのか」がGitの標準diffで判別できないこと です。変更履歴機能やWinMergeなどの外部ツールを使っても、セルの位置ズレや微小な書式変更がノイズとなり、本質的な仕様変更を見逃す重大なリスクを常に抱えていました。

一方、プレーンテキストであるMarkdown設計書なら、GitHubやGitLab、Bitbucket上で 「1行単位の差分（diff）」 が緑と赤で明確にハイライトされます。変更箇所に対してインラインでコメントを投稿し、Pull Request（PR）上で同僚やアーキテクトと建設的なコードレビューを行うことが可能です。

コミットメッセージに「Fix #104: 認証トークンの有効期限を24時間から2時間に短縮」のようにチケット番号や変更理由を紐付けることで、 「なぜこの仕様決定が行われたのか」という歴史的コンテキスト（経緯） がリポジトリ内に永久に記録され、属人化を完全に排除できます。

ソースコードと設計書のリポジトリ一元管理（ゾンビドキュメント化の防止）

仕様書が腐敗する（ゾンビ化する）最大の原因は、 「ソースコードのリポジトリ」と「設計書の保存場所（ファイルサーバー、SharePoint、Google Drive等）」が物理的に分離していること にあります。開発者はコードの修正をコミットしても、離れた場所にあるWordやExcelファイルをわざわざ開いて更新するのを忘れがちになります。

Markdown設計書を導入すれば、プロジェクトのリポジトリ配下に docs/ ディレクトリを設置し、ソースコードと設計書を 同一リポジトリ（Monorepo） で管理できます。これにより、チーム内で以下の鉄壁の運用ルールを徹底することが可能になります。

CI/CDパイプラインでのドキュメント自動ビルド＆静的ホスティング

テキスト形式であるMarkdownは、自動化プログラムとの親和性が抜群です。GitHub ActionsやGitLab CIなどのCI/CDパイプラインにドキュメント処理を組み込むことで、人間が手作業で行っていたルーチン作業をすべて全自動化できます。

1. 静的解析・構文検査（Linting）： PR作成時に markdownlint を自動実行し、見出し構造の破綻や記法の揺らぎを自動検知
2. リンク切れ自動検出： ドキュメント内の内部リンクや外部リンクをクローラーで検証し、デッドリンクを事前に防止
3. 静的サイト自動生成（SSG）： mainブランチへのマージをトリガーに、Material for MkDocs などを用いて美しいHTMLドキュメントサイトを自動ビルド
4. セキュアな社内配信： 社内専用のS3バケット、Cloudflare Pages、GitHub Pages（プライベート）へ自動デプロイし、常に最新の仕様書をブラウザから全文検索可能にする

これにより、開発者だけでなく、プロダクトマネージャー（PdM）、QAテスター、カスタマーサポートなどの関係者全員が、 「常に本番コードと100%同期した最新の仕様ポータル」 をブラウザから瞬時に確認できるようになります。

【即時コピペ枠】システム設計書・仕様書Markdownテンプレート4選

実務の現場で直ちに使える、完成度の高い Markdown設計書・仕様書テンプレート4選 です。リポジトリの docs/ フォルダにそのままコピー＆ペーストし、プロジェクトの要件に合わせて内容を書き換えるだけで、即座にプロフェッショナルな設計書運用を開始できます。

① 基本設計書テンプレート（システム概要・システム構成・非機能要件）

新規プロジェクトの立ち上げ時や、マイクロサービスのアーキテクチャ定義で必須となる 基本設計書（システム概要・構成・非機能要件） の標準テンプレートです。ファイルパス例: docs/design/basic-design.md

# 基本設計書：ECプラットフォーム基盤システム

## 1. 文書メタ情報
| 項目 | 内容 |
| :--- | :--- |
| ドキュメントID | BD-EC-001 |
| 作成日 | 2026-09-15 |
| 最終更新日 | 2026-09-20 |
| バージョン | v1.0.0 |
| 作成者 | アーキテクチャ設計チーム |
| 承認者 | プロジェクトリード |
| ステータス | 承認済（Approved） |

---

## 2. システム概要・目的
### 2.1 開発の背景と目的
既存のレガシーなモノリス型ECシステムにおいて、ピーク時のアクセス集中によるレスポンス低下および機能追加のリリースサイクル長期化が課題となっていた。本プロジェクトでは、クラウドネイティブなマイクロサービス基盤への移行を行い、可用性の向上と継続的デプロイの実現を目的とする。

### 2.2 システム全体像
```
[クライアント端末] 
       │ (HTTPS)
       ▼
[CloudFront (CDN)] ── S3 (静的アセット)
       │
       ▼
[ALB (Application Load Balancer)]
       │
   ┌───┴────────────────┬────────────────┐
   ▼                    ▼                ▼
[Auth Service]   [Order Service]  [Product Service]
   │                    │                │
   └──────┬─────────────┴────────────────┘
          ▼
   [Amazon Aurora (PostgreSQL)] ── [Amazon ElastiCache (Redis)]
```

---

## 3. システムアーキテクチャ構成
### 3.1 採用技術スタック
- **フロントエンド:** Next.js (TypeScript) / Tailwind CSS
- **バックエンドAPI:** Go 1.23 / Gin Web Framework
- **データベース:** Amazon Aurora PostgreSQL v16.2
- **キャッシュ / セッション:** Amazon ElastiCache for Redis v7.1
- **コンテナ基盤:** AWS ECS on Fargate
- **CI/CD:** GitHub Actions (ビルド・テスト・自動デプロイ)
- **監視・ロギング:** Datadog / AWS CloudWatch Logs

---

## 4. 機能要件一覧
| 機能ID | 大項目 | 中項目 | 機能概要 | 実装フェーズ |
| :--- | :--- | :--- | :--- | :--- |
| F-001 | 認証・認可 | ユーザー登録 | メールアドレス・パスワードによる新規登録、メール認証 | Phase 1 |
| F-002 | 認証・認可 | JWTログイン | アクセストークン(15分)およびリフレッシュトークン発行 | Phase 1 |
| F-003 | 商品管理 | 商品一覧検索 | カテゴリ・価格帯・キーワード検索（複合インデックス対応） | Phase 1 |
| F-004 | 注文管理 | カート投入 | Redisを用いた一時セッションカートの管理 | Phase 1 |
| F-005 | 決済連携 | クレジット決済 | Stripe API連携による非同期Webhook決済処理 | Phase 2 |

---

## 5. 非機能要件
### 5.1 可用性・信頼性
- **目標稼働率:** 99.95% 以上（年間ダウンタイム 4.38時間以内）
- **マルチAZ冗長化:** ALB、ECSタスク、Auroraを最低2つ以上のAvailability Zoneに分散配置
- **自動復旧:** ECSサービスオートスケーリングにより、異常終了タスクの自動検知およびヘルスチェックによる自動再起動

### 5.2 性能・拡張性
- **目標応答時間:** 通常時 95% のAPIリクエストを 200ms 以内に返却（ピーク時 500ms 以内）
- **想定スループット:** 通常時 500 req/sec、セール時ピーク 3,000 req/sec
- **スケーリング:** CPU使用率 70% 超過時にECSタスクを自動スケールアウト（最大30タスク）

### 5.3 セキュリティ要件
- **通信暗号化:** すべての外部通信は TLS 1.3 必須、内部マイクロサービス間通信は VPC内プライベートネットワークで完結
- **データ保護:** データベースの保管時暗号化（AWS KMS）、パスワードは Argon2id によるソルト付きハッシュ化
- **脆弱性診断:** コンテナイメージの Trivy スキャン、GitHub Dependabot による依存関係定期監視

### 5.4 バックアップ・運用監視
- **DBバックアップ:** Aurora継続的自動バックアップ（保持期間30日、特定時点リカバリPITR対応）
- **アラート通知:** エラーレート 1% 超過または死活監視失敗時にSlack `#alert-dev` へ即時通知

② REST API仕様書テンプレート（エンドポイント・ヘッダー・Request/Response JSON）

バックエンド開発者とフロントエンド開発者、モバイルアプリチーム間の契約（インターフェース）となる REST API仕様書 の標準テンプレートです。ファイルパス例: docs/api/v1/auth-login.md

# API仕様書：POST /api/v1/auth/login

## 1. 基本情報
- **概要:** 登録済みユーザーのメールアドレスとパスワードを検証し、JWT認証トークンを発行する。
- **エンドポイント:** `POST /api/v1/auth/login`
- **ベースURL:** `https://api.example.com`
- **認証要否:** 不要（Public Endpoint）
- **Rate Limit:** 10リクエスト / 分（ブルートフォース攻撃対策）

---

## 2. リクエスト仕様
### 2.1 リクエストヘッダー
| ヘッダー名 | 必須 | 設定値 / 例 | 説明 |
| :--- | :---: | :--- | :--- |
| `Content-Type` | ○ | `application/json` | JSONフォーマット指定 |
| `X-Request-Id` | - | `uuid-v4-xxxx-xxxx` | 分散トレーシング用リクエストID（未設定時は自動生成） |

### 2.2 リクエストボディ（パラメータ定義）
| パラメータ名 | 型 | 必須 | バリデーション制約 | 説明 |
| :--- | :--- | :---: | :--- | :--- |
| `email` | string | ○ | 有効なメールアドレス形式, 最大255文字 | 登録済みメールアドレス |
| `password` | string | ○ | 半角英数記号8〜64文字 | ログインパスワード |
| `remember_me` | boolean | - | true / false（デフォルト: false） | ログイン状態維持フラグ |

### 2.3 リクエストボディ（JSONサンプル）
```json
{
  "email": "dev.user@example.com",
  "password": "SecurePassword123!#",
  "remember_me": true
}
```

---

## 3. レスポンス仕様
### 3.1 成功時レスポンス（200 OK）
認証に成功した場合、アクセストークンとリフレッシュトークンを返却する。

```json
{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 900,
    "refresh_token": "def502004a6b22c83f9821a7...",
    "user": {
      "id": "usr_9b1deb4d3b7d4bb6",
      "email": "dev.user@example.com",
      "name": "開発太郎",
      "role": "editor"
    }
  }
}
```

### 3.2 エラーレスポンス一覧
共通エラー構造に従い、エラーコードと詳細メッセージを返却する。

| HTTPステータス | エラーコード | 発生契機 / 説明 |
| :--- | :--- | :--- |
| `400 Bad Request` | `VALIDATION_FAILED` | 必須項目の欠落、メールアドレス形式の不正 |
| `401 Unauthorized` | `INVALID_CREDENTIALS` | メールアドレスまたはパスワードが不一致 |
| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | 同一IPからの短時間連続リクエスト超過 |
| `500 Internal Server Error` | `INTERNAL_SYSTEM_ERROR` | 認証サーバーまたはDBの内部障害 |

#### 401 Unauthorized エラーJSONサンプル
```json
{
  "status": "error",
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "メールアドレスまたはパスワードが正しくありません。",
    "details": []
  }
}
```

③ DBテーブル定義書テンプレート（物理名・論理名・データ型・制約・インデックス）

データベース設計を正確に共有し、マイグレーションファイル（Flyway, Prisma, GORM等）の正本となる DBテーブル定義書 の標準テンプレートです。ファイルパス例: docs/db/tables/orders.md

# DBテーブル定義書：orders（注文基本テーブル）

## 1. テーブル基本情報
| 項目 | 内容 |
| :--- | :--- |
| 物理テーブル名 | `orders` |
| 論理テーブル名 | 注文情報 |
| 用途概要 | 顧客の購入トランザクション（注文ヘッダー情報）を管理する |
| ストレージエンジン | InnoDB (PostgreSQL: Heap) |
| 文字コード / 照合順序 | `utf8mb4` / `utf8mb4_bin` (PostgreSQL: UTF8) |
| テーブル種別 | トランザクション |

---

## 2. カラム定義一覧
| No | 物理カラム名 | 論理カラム名 | データ型 | NULL | 初期値 | キー | 説明 |
| :-: | :--- | :--- | :--- | :-: | :--- | :-: | :--- |
| 1 | `id` | 注文ID | BIGINT UNSIGNED | × | AUTO_INCREMENT | PK | 内部主キー（自動採番） |
| 2 | `order_number` | 注文番号 | VARCHAR(32) | × | なし | UK | 顧客向け公開注文コード（例: ORD-2026-001） |
| 3 | `user_id` | 顧客ID | BIGINT UNSIGNED | × | なし | FK | 購入顧客ID（`users.id` を参照） |
| 4 | `total_amount` | 注文総額 | DECIMAL(12,2) | × | 0.00 | - | 税・送料込みの請求合計金額 |
| 5 | `status` | 注文ステータス | VARCHAR(20) | × | 'pending' | IDX | `pending`, `paid`, `shipping`, `completed`, `cancelled` |
| 6 | `payment_method`| 決済手段 | VARCHAR(30) | × | なし | - | `credit_card`, `convenience`, `bank_transfer` |
| 7 | `shipping_zip` | 配送先郵便番号 | VARCHAR(8) | × | なし | - | ハイフンなし7桁 |
| 8 | `shipping_address`| 配送先住所 | VARCHAR(255) | × | なし | - | 都道府県・市区町村・番地・建物名 |
| 9 | `created_at` | 作成日時 | TIMESTAMP | × | CURRENT_TIMESTAMP | - | レコード作成日時 |
| 10| `updated_at` | 更新日時 | TIMESTAMP | × | CURRENT_TIMESTAMP | - | レコード最終更新日時 |
| 11| `deleted_at` | 削除日時 | TIMESTAMP | ○ | NULL | - | 論理削除日時（NULL時は有効レコード） |

---

## 3. インデックス定義一覧
| インデックス名 | 種別 | 対象カラム | 用途・選定理由 |
| :--- | :--- | :--- | :--- |
| `pk_orders` | PRIMARY KEY | `id` | 主キー検索およびクラスタ化 |
| `uk_orders_order_number` | UNIQUE KEY | `order_number` | 注文コードの重複防止および注文詳細取得の高速化 |
| `idx_orders_user_created` | COMPOSITE INDEX | `user_id, created_at DESC` | マイページにおける特定顧客の注文履歴一覧ソート用 |
| `idx_orders_status` | NORMAL INDEX | `status` | 管理画面での「未発送」「入金待ち」絞り込み用 |

---

## 4. 外部キー制約（Foreign Key）
| 制約名 | 対象カラム | 参照先テーブル / カラム | ON UPDATE | ON DELETE |
| :--- | :--- | :--- | :--- | :--- |
| `fk_orders_user_id` | `user_id` | `users(id)` | RESTRICT | RESTRICT（注文存在時は顧客削除不可） |

④ 画面設計書テンプレート（画面レイアウト枠・入出力項目・イベント定義）

UI/UXデザイナーとフロントエンド開発者が画面の責務・レイアウト・操作イベントを共有するための 画面設計書 の標準テンプレートです。ファイルパス例: docs/screens/SC-001-login.md

# 画面設計書：SC-001 ログイン画面

## 1. 画面基本情報
| 項目 | 内容 |
| :--- | :--- |
| 画面ID | SC-001 |
| 画面名 | ユーザーログイン画面 |
| URL / パス | `/login` |
| アクセス権限 | ゲストユーザー（未認証者のみ。認証済みは `/dashboard` へリダイレクト） |
| レスポンシブ対応 | PC (1024px〜) / Tablet (768px〜) / SP (〜767px) |

---

## 2. 画面レイアウト（ASCIIワイヤーフレーム）
```
+-------------------------------------------------------------+
|                          ヘッダーロゴ                       |
+-------------------------------------------------------------+
|                                                             |
|                 +-------------------------+                 |
|                 |       会員ログイン      |                 |
|                 +-------------------------+                 |
|                 | メールアドレス          |                 |
|                 | [ txt_email           ] |                 |
|                 |                         |                 |
|                 | パスワード              |                 |
|                 | [ txt_password        ] |                 |
|                 |                         |                 |
|                 | [x] ログイン状態を保持  |                 |
|                 |                         |                 |
|                 | +---------------------+ |                 |
|                 | |     [btn_login]     | |                 |
|                 | +---------------------+ |                 |
|                 |                         |                 |
|                 | パスワードをお忘れの方  |                 |
|                 | 新規会員登録はこちら    |                 |
|                 +-------------------------+                 |
|                                                             |
+-------------------------------------------------------------+
|                          フッター                           |
+-------------------------------------------------------------+
```

---

## 3. 入出力項目一覧
| No | 項目論理名 | 項目物理名 | 種別 | 必須 | 入力形式 / 制約 | 初期表示 |
| :-: | :--- | :--- | :--- | :-: | :--- | :--- |
| 1 | メールアドレス入力欄 | `txt_email` | テキスト | ○ | 半角英数記号、RFC適合メール形式 | 空文字（プレースホルダ表示） |
| 2 | パスワード入力欄 | `txt_password` | パスワード | ○ | マスク表示（伏字）、表示切替アイコン有 | 空文字 |
| 3 | ログイン保持チェック | `chk_remember` | チェックボックス | - | boolean（true / false） | チェックOFF（false） |
| 4 | ログインボタン | `btn_login` | ボタン | - | プライマリボタンスタイル | 活性（初期状態） |
| 5 | パスワード再設定リンク | `lnk_reset_pw` | リンク | - | テキストリンク | 活性 |
| 6 | 新規登録リンク | `lnk_register` | リンク | - | テキストリンク | 活性 |

---

## 4. ユーザーアクションおよび画面イベント定義
| No | イベント契機 | 処理内容 | 遷移先 / 画面挙動 |
| :-: | :--- | :--- | :--- |
| 1 | ログインボタン押下 | クライアント側バリデーション実施後、`POST /api/v1/auth/login` を送信 | - 処理中はボタンをスピナー表示（非活性化）
- 成功時: `/dashboard` へ遷移
- 失敗時: 画面上部にエラートーストを表示 |
| 2 | パスワード表示切替 | アイコンクリックで `type="password"` と `type="text"` をトグル | パスワード文字の平文/マスク表示を切り替え |
| 3 | パスワード忘れ押下 | リセット画面へのリンクルーティング | `/password/reset` へ画面遷移 |
| 4 | 新規登録リンク押下 | 会員登録画面へのリンクルーティング | `/register` へ画面遷移 |

Mermaidで設計書に直接ダイアグラムを埋め込む実務テクニック

Markdown設計書がWordやExcelに対して圧倒的な優位性を持つもう1つの理由が、テキストベースで作図できるオープンソースライブラリ 「Mermaid（マーメイド）」の標準サポート です。GitHub、GitLab、VS Code、Notion、ObsidianなどはすべてMermaidのレンダリングにネイティブ対応しており、コードブロック内にテキストを記述するだけで美しいダイアグラムが自動描画されます。

認証・認可フローを描くシーケンス図（JWTトークン検証の実践コード）

API連携や認証基盤の設計で頻出する 「JWTアクセストークン検証および保護リソース取得のシーケンス図」 の実務Mermaidコードです。正常系と異常系（トークン失効・リフレッシュ）の条件分岐を alt / else ブロックで表現しています。

sequenceDiagram
    autonumber
    actor User as ユーザー（ブラウザ）
    participant Client as SPA (Next.js)
    participant Gateway as API Gateway
    participant Auth as 認証サーバー (Auth Service)
    participant Resource as 注文API (Order Service)

    User->>Client: 1. 商品購入ボタンをクリック
    Client->>Gateway: 2. POST /api/v1/orders (Bearer JWT)
    Gateway->>Gateway: 3. トークンの形式・有効期限(exp)を検証

    alt トークン有効の場合
        Gateway->>Resource: 4. リクエスト転送 (X-User-Idヘッダー付与)
        Resource->>Resource: 5. 注文データ作成処理
        Resource-->>Gateway: 6. 201 Created (注文確定JSON)
        Gateway-->>Client: 7. 201 Created
        Client-->>User: 8. 注文完了画面を表示
    else トークン期限切れ (401 Unauthorized)
        Gateway-->>Client: 4. 401 Token Expired
        Client->>Auth: 5. POST /auth/refresh (RefreshToken)
        alt リフレッシュ成功
            Auth-->>Client: 6. 新規AccessToken発行
            Client->>Gateway: 7. 直前の注文リクエストを自動再送
            Gateway->>Resource: 8. リクエスト転送
            Resource-->>Client: 9. 201 Created
        else リフレッシュ失敗（完全失効）
            Auth-->>Client: 6. 403 Session Expired
            Client-->>User: 7. ログイン画面へ強制リダイレクト
        end
    end

テーブルリレーションを可視化するER図（主キー・外部キー指定コード）

データベース設計書に不可欠な 「エンティティ・リレーションシップ図（ER図）」 です。ECサイトの主要テーブル（users, orders, order_items, products, categories）における「1対多」「多対1」のリレーションシップと、PK・FK属性を正確に定義しています。

erDiagram
    users ||--o{ orders : "1人の顧客は0件以上の注文を持つ"
    orders ||--|{ order_items : "1つの注文は1件以上の明細を持つ"
    products ||--o{ order_items : "1つの商品は0件以上の明細に含まれる"
    categories ||--o{ products : "1つのカテゴリは0件以上の商品を持つ"

    users {
        bigint id PK "顧客ID (自動採番)"
        string email UK "メールアドレス"
        string password_hash "暗号化パスワード"
        string status "ステータス (active/suspended)"
        timestamp created_at "作成日時"
    }

    orders {
        bigint id PK "注文ID"
        string order_number UK "公開注文番号"
        bigint user_id FK "顧客ID"
        decimal total_amount "注文総額"
        string status "注文状態"
        timestamp created_at "注文日時"
    }

    order_items {
        bigint id PK "注文明細ID"
        bigint order_id FK "注文ID"
        bigint product_id FK "商品ID"
        int quantity "購入数量"
        decimal unit_price "購入時単価"
    }

    products {
        bigint id PK "商品ID"
        bigint category_id FK "カテゴリID"
        string name "商品名"
        decimal price "現在販売価格"
        int stock_quantity "在庫数量"
    }

    categories {
        bigint id PK "カテゴリID"
        string name "カテゴリ名"
        string slug UK "URLスラッグ"
    }

注文・決済ステータスを管理する状態遷移図（ステートマシン図コード）

ECや業務システムの注文処理において、仕様の抜け漏れが最も発生しやすい 「ステータス遷移（状態マシン図）」 です。初期状態から完了・キャンセル・返金までの全ライフサイクルと遷移トリガーを可視化します。

stateDiagram-v2
    [*] --> Pending : 注文作成 (カート確定)
    
    Pending --> PaymentProcessing : 決済処理開始
    PaymentProcessing --> Paid : 決済成功 (Webhook受信)
    PaymentProcessing --> PaymentFailed : 決済失敗 (カード与信NG)
    
    PaymentFailed --> Pending : 別カードで再試行
    PaymentFailed --> Cancelled : 24時間未決済で自動取消

    Paid --> ShippingPreparation : 在庫引当・出荷手配
    Paid --> Cancelled : 発送前キャンセル申請

    ShippingPreparation --> Shipped : 配送業者引き渡し (追跡番号発行)
    Shipped --> Delivered : 配達完了 (受取確認)
    
    Delivered --> ReturnRequested : 返品申請 (到着後7日以内)
    ReturnRequested --> Refunded : 返品受取・返金実行
    ReturnRequested --> Delivered : 返品却下

    Cancelled --> [*]
    Refunded --> [*]
    Delivered --> [*]

業務フロー・例外分岐を明示するフローチャートコード

ユーザー登録時のメール認証および例外ハンドリングを網羅した 「業務フローチャート」 です。 subgraph を活用してフロントエンド処理とバックエンド処理の責務境界を視覚的に分離しています。

flowchart TD
    subgraph Frontend["フロントエンド (Client)"]
        A([開始: 会員登録フォーム]) --> B[入力情報の入力]
        B --> C{クライアント側検証}
        C -- 入力不備あり --> D[エラーメッセージ表示]
        D --> B
        C -- 検証OK --> E[POST /api/v1/register 送信]
    end

    subgraph Backend["バックエンド (Server & DB)"]
        E --> F{メール重複チェック}
        F -- 既に登録済み --> G[409 Conflict: 登録済エラー返却]
        F -- 未登録 --> H[仮登録レコード作成]
        H --> I[ワンタイム認証トークン生成]
        I --> J[確認メール送信キュー投入]
        J --> K[200 OK: 仮登録完了レスポンス]
    end

    G --> D
    K --> L[仮登録完了画面を表示]
    L --> M([終了: メール確認待ち])

設計書作成を爆速化する内部ツール連携ハブ（サイト内記事との連動）

Markdown設計書をチームや企業全体へ定着させるためには、 「書く手間を極限まで減らすエコシステム」 の整備が不可欠です。当サイトで解説している各要素技術・ツールと連携させることで、ドキュメンテーション作業を劇的に高速化できます。

複雑なテーブル定義は「Excel→Markdown変換ツール」で一発生成

既存プロジェクトからMarkdown設計書へ移行する際、最大の苦痛となるのが 「何十シートもあるExcelのテーブル定義書を手作業でMarkdownテーブル記法（パイプ記号）に書き直す作業」 です。この作業を手作業で行うのは時間の完全な浪費です。

クリップボード経由でExcelのセル範囲をコピーし、即座にMarkdownの罫線表に変換できるWeb変換ツールや、VS Codeの拡張機能（ Excel to Markdown table 等）を導入すれば、1シートわずか 1秒 でMarkdown化できます。

長文の仕様書には「Markdown目次（TOC）自動生成」を組み込む

数十ページに及ぶ基本設計書や詳細設計書では、目的の章へ瞬時にジャンプできる 「目次（Table of Contents）」 が欠かせません。しかし、見出しの追加・削除のたびに手動で目次リンクを更新するのは非現実的です。

VS Codeの定番拡張機能「Markdown All in One」の自動目次生成機能（コマンドパレットから Create Table of Contents ）を利用すれば、H2〜H4の見出し階層を解析し、正しいGitHub/GitLab仕様のアンカーリンク付き目次が自動挿入されます。ファイルを保存するたびに目次が自動更新される設定も可能です。

チーム内の記法統一には「markdownlint」で静的解析チェック

複数人の開発者がMarkdown設計書を執筆すると、 「見出しレベルがH2からいきなりH4に飛ぶ」「リストのインデント幅がバラバラ」「全角スペースが混入する」 といったフォーマットの乱れが必ず生じます。これを防ぐのが静的解析ツール 「markdownlint」 です。

リポジトリのルートに .markdownlint.json を配置し、プロジェクトの規約に合わせたルールを設定します。実務の設計書運用では、行長制限（MD013）やインラインHTML（MD033）を適切に調整するのがポイントです。

{
  "default": true,
  "MD013": false,
  "MD033": {
    "allowed_elements": ["div", "span", "table", "tr", "td", "th", "tbody", "thead", "br", "img"]
  },
  "MD024": {
    "siblings_only": true
  },
  "MD041": false
}

VS Codeの保存時自動整形（editor.codeActionsOnSave）とCI（GitHub Actions）を連動させることで、常に全ドキュメントの品質と統一性が担保されます。

ドキュメントを社内ポータル化するなら「MkDocs」と連携

リポジトリ内に蓄積されたMarkdownファイルを、Google検索のようにサクサク検索でき、見栄えの良い社内開発ポータルサイトへ昇華させるのが 「Material for MkDocs」 です。

mkdocs.yml に設定を記述するだけで、ディレクトリ構造をそのまま階層ナビゲーションバーに変換し、Mermaid図の描画、コードブロックのコピー機能、ライト/ダークモード切り替え、多言語対応などを備えた極めて高機能なWebポータルが完成します。

site_name: 開発基盤システム設計書ポータル
theme:
  name: material
  language: ja
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.sections
    - search.suggest
    - search.highlight
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:
      anchor_linenums: true

「客先にPDFやExcelで納品しろ」と言われたときの解決策（変換手順）

受託開発やSIer、公的機関向けのプロジェクトでは、開発チーム内でどれほどMarkdownが効率的であっても、契約上の検収条件として 「A4用紙に印刷可能なPDFでの納品」 や 「指定フォーマットのWord / Excel納品」 を義務付けられるケースが依然として多く存在します。

ここで「客先が古いからMarkdown化は諦めよう」と後退する必要は一切ありません。 「原本（Single Source of Truth）はGit上のMarkdownで高速に運用し、納品成果物としてPDFやWordを自動変換で生成する」 というパイプラインを組むことで、日々の開発速度を落とさずに顧客の納品要件を100%満たすことができます。

VS Code拡張機能「Markdown PDF」でA4用紙に美しく出力するCSSスニペット

VS Codeの拡張機能 「Markdown PDF」 は、Chromiumのヘッドレスブラウザを利用してMarkdownファイルをPDFに高精度エクスポートできます。ただし、デフォルトのスタイルのまま出力すると、文字が小さすぎたり余白が不自然になったりするため、 実務納品に耐えるカスタムCSS を適用します。

VS Codeの settings.json に markdown-pdf.styles を指定し、以下のCSSファイルを読み込ませます。

/* ===================================================
   実務納品用 A4印刷スタイルシート (markdown-pdf.css)
   =================================================== */
@page {
  size: A4 portrait;
  margin: 20mm 15mm 20mm 15mm;
  @top-right {
    content: "機密情報 (Confidential)";
    font-size: 8pt;
    color: #666;
  }
  @bottom-center {
    content: counter(page) " / " counter(pages);
    font-size: 9pt;
    color: #333;
  }
}

body {
  font-family: "Noto Sans JP", "Hiragino Kaku Gothic ProN", Meiryo, sans-serif;
  font-size: 10pt;
  line-height: 1.65;
  color: #24292e;
}

/* 見出しスタイル */
h1 {
  font-size: 18pt;
  border-bottom: 2px solid #0969da;
  padding-bottom: 6px;
  margin-top: 0;
  page-break-before: always;
}
h1:first-of-type {
  page-break-before: avoid; /* 表紙・最初のH1は改ページしない */
}
h2 {
  font-size: 14pt;
  border-bottom: 1px solid #d0d7de;
  padding-bottom: 4px;
  margin-top: 24pt;
}
h3 {
  font-size: 11pt;
  margin-top: 16pt;
}

/* テーブルスタイル */
table {
  width: 100%;
  border-collapse: collapse;
  margin: 12pt 0;
  font-size: 8.5pt;
}
th, td {
  border: 1px solid #d0d7de;
  padding: 6px 8px;
  text-align: left;
}
th {
  background-color: #f6f8fa;
  font-weight: bold;
}
tr:nth-child(even) {
  background-color: #fafbfc;
}

/* コードブロック */
pre {
  background-color: #f6f8fa;
  border: 1px solid #e1e4e8;
  border-radius: 4px;
  padding: 10px;
  font-family: "Consolas", "Courier New", monospace;
  font-size: 8.5pt;
  line-height: 1.45;
  overflow: hidden;
}

表やMermaid図の途切れを防ぐ改ページ制御技（page-break-inside: avoid）

PDF出力でエンジニアが最も頭を抱えるのが、 「長いテーブル定義書やMermaid図の真ん中でページがぶった切られ、ヘッダーもなしに次ページへ中途半端にはみ出る事故」 です。これをCSSの印刷メディアクエリで完全に制御します。

/* ===================================================
   要素の途中分割を防ぐ改ページ制御ルール
   =================================================== */
table, pre, blockquote, .mermaid, .page-break-avoid {
  page-break-inside: avoid !important;
  break-inside: avoid !important;
}

/* 章の切り替わりで必ず改ページさせたい場合のクラス */
.page-break-before {
  page-break-before: always !important;
  break-before: page !important;
}

/* 印刷時に改行位置を固定するためのユーティリティ */
@media print {
  h2, h3 {
    page-break-after: avoid !important;
    break-after: avoid !important;
  }
}

特定のH2セクションの直前で意図的にページを改めたい場合は、Markdown内に <div class="page-break-before"></div> または <div style="page-break-before: always;"></div> を直接記述することで、ピンポイントでの美しいレイアウト調整が可能です。

Pandocを使ったWord（.docx）一括変換コマンド

客先から「納品物はWordファイル形式でなければ受け取れない」と厳格に指定された場合は、汎用ドキュメント変換ツール 「Pandoc（パンドック）」 を使用して、MarkdownからWord（.docx）へ無劣化一括変換します。

# 基本のWord変換コマンド
pandoc basic-design.md   -o basic-design.docx   --from markdown   --to docx   --highlight-style tango

# 企業の指定Wordスタイル（テンプレート）を適用して変換する場合
pandoc basic-design.md   -o basic-design.docx   --reference-doc=company-template.docx   --toc   --toc-depth=3

--reference-doc オプションに社内既定のWordテンプレートを指定することで、見出しフォント、ヘッダー/フッター、表の罫線色などを自動で企業のフォーマットに整えた美しいWordファイルを出力できます。

よくある挫折ポイントとトラブルシューティング（FAQ・構造化データ）

Markdown設計書を現場へ導入する際に、多くの開発者が直面する 現場ならではのつまずきポイントと実務解決策 をQ&A形式で解説します。

まとめ：Markdown設計書で「生きた仕様書」を運用しよう

ソフトウェア開発における設計書の価値は、 「作られた瞬間」ではなく、「変化し続けるコードと同期し、いつでも誰でも信頼できる情報源として機能し続けること」 にあります。WordやExcelの分厚いドキュメントが更新されずに陳腐化していく旧来の開発プロセスから、GitとMarkdownによる 「Docs as Code」 への移行は、開発チームの生産性とアジリティを飛躍的に高める決定打となります。

ぜひ本記事のテンプレートとテクニックを活用し、あなたのチームでも「メンテナンスされ続ける生きた仕様書」の運用をスタートしてみてください！

{
“@context”: “https://schema.org”,
“@type”: “FAQPage”,
“mainEntity”: [
{
“@type”: “Question”,
“name”: “テーブル定義書の列数が多くて横スクロールが発生する時の対策は？”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “MarkdownテーブルをHTMLタグ（div style=”overflow-x: auto;”）で囲むことで横スクロールに対応できます。また、主テーブルには基本項目のみを残してインデックスや外部キー制約を別テーブルに分離するか、1カラムを縦型リスト形式で詳細記述するスタイルへの切り替えが効果的です。”
}
},
{
“@type”: “Question”,
“name”: “客先がExcel納品を絶対条件としている場合の現実的な折衷案は？”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “原本はGit上のMarkdownで高速に運用・保守し、納品成果物としてのみPythonスクリプト（pandas/openpyxl）やPandocを用いてMarkdownテーブルをExcelファイル（.xlsx）へ自動エクスポートする運用が推奨されます。”
}
},
{
“@type”: “Question”,
“name”: “設計書内の画像ファイルはリポジトリでどう管理すべき？”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “画像はdocs/images/等に配置し、Markdownからは相対パスで参照します。リポジトリ肥大化を防ぐため画像圧縮を行い、大規模プロジェクトではGit LFSやS3外部ホスティングの併用を検討します。”
}
}
] }