はじめに
機能設計書・画面設計書の作成方法について、皆さんはどのような手法を採用していますか？
私が携わってきたプロジェクトでは「Excelで作成し、SharePointで管理」というスタイルが主流でした。特にMicrosoft製品との親和性が高い企業ではこの体制が多いのではないでしょうか。しかし、以下のような課題を感じていませんか？
- SharePointの履歴肥大化による容量圧迫
- Excel（バイナリ）のため差分管理ができない
- 複数人編集時のコンフリクトや属人化
本記事では、これらの課題を解決するために、Git＋Markdown＋draw.io＋MkDocsを組み合わせたドキュメント基盤の構築事例を紹介します。
本記事の前提
本記事で紹介する手法は、主に Windowsフォームを利用したクライアントサーバー型システム（クラサバ）開発 を対象としています。
Webアプリケーション開発では、Figmaによる画面設計やフロントエンド実装物を活用したドキュメント管理など、別の有力な選択肢があります。
一方でWindowsフォーム開発では、
- 画面モックの再利用が難しい
- UI設計情報をコードから取得しづらい
- Excelベースの設計文化が根強い
といった特徴があります。
そのため、本記事では 既存のWindowsフォーム開発環境において、Excel中心の設計書運用から脱却するためのアプローチ として紹介します。
このような課題を持つ方におすすめ
- Excelで設計書を管理していて限界を感じている
- SharePointの容量問題に困っている
- 設計書をGitで管理したい
- レビューや差分管理を効率化したい
従来の課題（Excel＋SharePoint）
まずは従来の問題点を整理します。
主な課題
- 履歴が増え続けて容量オーバー
- Excelのため差分が見えない
- テキスト検索性が低い
- 複数人編集での事故リスク
- ドキュメントが巨大化しやすい
🔴 結論：構成管理と拡張性に限界がある
新しいアプローチ：Git×Markdownベース設計
採用した技術構成
| 要素 | ツール |
|---|---|
| バージョン管理 | Git (GitHub) |
| ドキュメント形式 | Markdown |
| 画面設計 | draw.io（VSCode拡張） |
| 結合・PDF化 | Markdown Preview Enhanced（MPE） |
| 公開・閲覧 | MkDocs + GitHub Pages |
なぜMarkdownなのか？
ExcelからMarkdownに移行した最大の理由は以下です。
メリット
- ✅ 差分管理が可能（Gitと相性抜群）
- ✅ 軽量で高速
- ✅ レビューしやすい（Pull Request）
- ✅ CI/CDと連携可能
- ✅ テキストなので可搬性が高い
画面設計の課題と解決（draw.io）
※ 本記事ではWindowsフォーム開発を前提としています。Webアプリケーション開発であれば、Figmaや実装済み画面を活用した設計手法の方が適しているケースもあります。
課題
- Markdownだけでは画面レイアウトや項目配置を直感的に伝えにくい
- 画面イメージを別ファイルで管理すると設計書との整合性維持が大変
解決策：draw.io
- XMLベースで管理可能
- SVGとしてエクスポート可能
- VSCodeと統合できる
- Markdownに埋め込み可能
- スクラッチパッドで独自部品を再利用可能
さらに強力にしたポイント
- GitHub Copilotで画面構成を自動生成
- 約80%の精度でモック作成
- 残りは手動微調整
✅ 初期コスト（部品作成）はあるが、長期的に効率化
ドキュメント構成戦略
ファイル分割方針
- 機能単位でMarkdownを分割
- 画面
- 帳票
- CSV
メリット
- 可読性向上
- Git管理が楽
- 変更影響が局所化
MPEで「1冊の設計書」にまとめる
使用機能
- Markdownの
import機能
@import "child.md"
実現できること
- 複数Markdownを1つに統合
- そのままPDF出力
- ブラウザプレビュー可能
PDF出力時の課題と解決
発生問題
- 表が見切れる
- ヘッダー/フッターが意図と異なる
- 空白ページが生成される
解決①：CSSカスタマイズ
MPEのカスタムCSSを使用
ポイント
- Workspace単位で管理可能
- Gitによる設定の構成管理
- 新規参画者の環境構築を効率化
- 印刷レイアウト最適化
@media print {
table {
page-break-inside: avoid;
}
}
解決②：謎の空白ページ
原因
<br>タグが自動挿入されていた
対策
設定変更：
"markdown-preview-enhanced.breakOnSingleNewLine": false
ポイント
- Workspace単位で管理可能
- Gitによる設定の構成管理
- 新規参画者の環境構築を効率化
効果
- 不要な改行を防止
- レイアウト崩れ解消
MkDocsで設計書をWeb化
なぜ必要？
- VSCodeを開かずに閲覧したい
- Gitリポジトリをクローンしなくても設計書を参照できる
- 開発メンバー以外にも設計書を共有しやすい
採用構成
- MkDocs（静的サイトジェネレータ）
- GitHub Pages（ホスティング）
メリット
- ✅ ブラウザで即閲覧
- ✅ ナビゲーション付き
- ✅ チーム共有が簡単
注意点（実運用での課題）
- GitHub Enterpriseのライセンス制約
- 非公開（Private）で公開する場合は、GitHub Enterprise の契約が必要
- Privateで公開する場合、公開範囲はOrganizationに所属するメンバーに限定される
- 公開範囲に柔軟性を持たせたい場合は代替ホスティングの検討が必要
導入結果まとめ
| 項目 | 改善結果 |
|---|---|
| 構成管理 | ◎ Gitで完全管理 |
| 差分確認 | ◎ PRレビュー可能 |
| 視認性 | ○ CSSで改善 |
| 共有性 | ○（環境依存あり） |
| 作成効率 | ○（初期コストあり） |
まとめ
✅ この構成の本質
- 設計書を「ファイル」から「コード」に進化させる
- ドキュメントもDevOpsの一部として扱う
最後に
Excel設計から脱却することは、単なるツール変更ではなく、開発プロセスの進化です。
今回の構成はあくまで一例ですが、
「設計書もGitで扱う」という発想は、多くのプロジェクトに応用できます。
ぜひ一度、小さな範囲から試してみてください。
また、CSSの記述内容やMkDocsへの自動デプロイ方法など、技術的な内容については別記事としてまとめる予定です。
参考文献