Markdownで「お客さんに出せる仕様書」を作る ― VS Code + MPE + MkDocs + AI活用の工夫

はじめに

システム開発の受託案件では、機能設計書・画面設計書・帳票設計書を お客さんに提出し、承認印をもらう 場面があります。
多くの現場ではExcelやWordが使われますが、次のような悩みがありました。

• 差分が追えず、レビューが辛い
• 画面・帳票ごとに書き方がバラバラになる
• 修正のたびにレイアウトが崩れる
• 過去案件の設計書を流用しづらい

そこで、Markdownで書いて、そのまま顧客提出用の体裁(承認欄・目次・印刷レイアウト付き)で出力する 運用にしました。
この記事では、その工夫点を紹介します。

全体像

図の見方は次のとおりです。

1. 子設計書を書く: 画面・帳票ごとにMarkdownで設計書を作成します。画面レイアウトの項目説明は、Draw.ioのAnnotation機能から生成したMarkdownを子設計書に貼り付けます。
2. 親設計書に集約する: 親設計書で子設計書を @import で取り込み、1冊の機能仕様書にまとめます。
3. 顧客提出用に出力する: 親設計書をMPE(Markdown Preview Enhanced)でHTML/PDFに出力し、お客さんへ提出します。
4. 社内向けサイトを公開する: 同じMarkdownをMkDocsでビルドし、社内で閲覧できるサイトとして公開します。

つまり、元になるMarkdownは1つで、提出用(MPE)と社内閲覧用(MkDocs)の2種類の出力を作る 構成です。

使用ツールは次のとおりです。

用途	ツール
執筆	Visual Studio Code
提出用出力	Markdown Preview Enhanced(MPE)
社内公開	MkDocs(Material for MkDocs)+ GitHub Pages
図	PlantUML / Mermaid / Draw.io

工夫1: 子設計書 → 親設計書の2階層構造

設計書は 画面・帳票単位の「子設計書」 に分割して書き、「親設計書」で @import して1冊に集約 します。

templates/
├─ 親設計書_テンプレート.md
└─ 子設計書_テンプレート.md

親設計書はこれだけです。

@import "画面A.md"
@import "帳票B.md"

メリットは次のとおりです。

• 担当者ごとに子設計書を並行して書ける
• Gitの差分が画面・帳票単位で小さくなる
• 過去案件の子設計書をコピーして流用しやすい
• 提出時は親設計書1つを出力すれば済む

工夫2: 親設計書テンプレートで「提出物の体裁」を固定する

親設計書のフロントマターで、目次の深さとHTML自動出力を設定しています。

---
toc:
  depth_from: 2
  depth_to: 4
  ordered: false
export_on_save:
  html: true
title: 機能仕様書
---

• export_on_save により、保存するだけでHTMLが更新される
• 目次は [TOC] で自動生成する

さらに、表紙にお客さん向けの 承認欄(ご承認日・ご承認印) をHTMLテーブルで埋め込んでいます。

<table style="border-collapse:collapse; font-size:12px; text-align:center;">
  <tr>
    <th style="border:1px solid #555; padding:6px 20px;">ご承認日</th>
    <th style="border:1px solid #555; padding:6px 40px;">ご承認印</th>
  </tr>
  <tr>
    <td style="border:1px solid #555; padding:6px 20px;">　　　年　　月　　日</td>
    <td style="border:1px solid #555; padding:32px 40px;"></td>
  </tr>
</table>

テンプレートに入れておくことで、案件ごとに表紙を作り直す必要がなくなりました。

工夫3: 印刷スタイルを style.less に集約

MPEのPDF出力・ブラウザ印刷を前提に、共通スタイルを .crossnote/style.less にまとめています。

• 改ページ制御
• ヘッダー・フッター
• フォントサイズ・表レイアウト・余白

案件固有のスタイルは最小限にし、共通化できるものはすべて style.less に寄せるルールにしました。
これにより どの案件でも同じ見た目で出力できる ようになります。

また .crossnote/head.html で、出力HTMLに 目次サイドバー を表示しています。お客さんがブラウザで閲覧するときに便利です。

工夫4: @import 後の余計な改行を防ぐ

MPEの @import は、取り込み後に <br /> が自動挿入されることがあります。
.vscode/settings.json で無効化しておくと、レイアウトが安定します。
設定はリポジトリに含めておき、全員が同じ状態で書けるようにしています。

工夫5: MkDocsで社内向けサイトも自動公開

main ブランチへのプッシュをトリガーに、MkDocsでビルドしてGitHub Pagesへデプロイしています。

site_name: 設計書サイト
theme:
  name: material
  language: ja
  features:
    - navigation.sections
    - navigation.expand
    - toc.follow
  palette:
    - scheme: default
      toggle:
        icon: material/weather-night
        name: ダークモードに切替
    - scheme: slate
      toggle:
        icon: material/weather-sunny
        name: ライトモードに切替

docs_dir: docs

plugins:
  - search
  - plantuml:
      puml_url: https://www.plantuml.com/plantuml/

• 日本語検索ができる
• ダークモードに切り替えられる
• PlantUMLの図をそのままMarkdown内に書ける

「提出用はMPEのHTML/PDF」「日常の参照は MkDocsサイト」と 用途で出力を使い分け ています。

工夫6: Draw.ioにアノテーション機能を自作し、Markdownを生成

画面レイアウトに「①②③…」の番号を振って項目説明を書く設計書は、図と説明表の番号ズレ が起きがちです。

そこで、VS Codeの Draw.io Integration 用に カスタムプラグイン を作りました。

操作	内容
Add Annotation	キャンバスをクリックして番号マーカーを配置
自動採番	最大番号 + 1(欠番は再利用しない)
Renumber	番号の昇順で1から振り直し
Generate Markdown	番号順のMarkdownを生成してクリップボードへコピー

• Annotationは専用レイヤーに分離し、表示・非表示を切り替えられる
• 情報は .drawio ファイル自身に保存されるので、Git管理でき、外部サーバーも不要

図に番号を打つだけで説明表のたたき台ができるため、図と表の不整合を防げます。

工夫7: ルールをREADMEに明文化する

次のルールをREADMEに書いています。

• 子設計書は画面・帳票単位で分割する
• 親設計書で集約する
• 過去の設計書を参考にし、記載粒度を統一する
• style.less の修正時は既存設計書への影響を確認する

属人化を防ぎ、新しく参加した人でも同じ品質で書けるようにするためです。

導入して良かったこと

• Gitで差分レビューできるようになった
• 保存するだけで提出用HTMLが更新される
• 案件をまたいでテンプレート・スタイルを再利用できる
• AIが読みやすいので、次のプロジェクトでも活かしやすい

課題と今後

• お客さんによっては、Excel・Word形式での提出を求められる
• MPEのPDF出力は、改ページの微調整が必要な場面がある
• 承認印はHTML表で再現しているが、電子承認との連携は未対応

まとめ

Markdownでも、次の工夫で お客さんに出せる品質の仕様書 を作れます。

1. 子設計書と親設計書に分割し、@import で集約する
2. 表紙・承認欄・目次をテンプレート化する
3. 印刷スタイルを style.less に集約する
4. MkDocsで社内向けサイトも自動公開する
5. Draw.ioのアノテーションから説明表を生成する
6. AIの指示ファイルで書式を揃える

同じ悩みを持つ方の参考になれば幸いです。