AI Readyな設計書を目指して。人もAIも読みやすい設計書管理

はじめに

以前、設計書はMarkdownで管理してPDFに自動変換しよう！ という記事で、設計書を Markdown で管理していく話を書きました。

ここではその発展形として、Markdown で管理した設計書を HTML として公開し、GitHub 上でのレビューや AI 活用まで見据えた構成をもう少し具体的に詰めてみます。

動機

私のチームでは、今は Confluence で設計書を管理しています。

編集や閲覧はしやすく、日常的な運用で大きく困っているわけではありません。ただ、AI で設計書を参照したり、修正案を作ったり、アップロードして更新したりしようとすると、不便な点がいくつかあります。

• MCP 経由での取得や更新のコストが大きい
• 設計書本文や図をまとめて扱いにくい
• 差分をコードレビューの流れで見づらい

そのため、GitHub で扱いやすい Markdown ベースに寄せつつ、人が読むときの閲覧性はなるべく落とさない構成を検討してみました。

やってみたこと

1. 設計書を GitHub で管理する
2. GitHub Actions で HTML ページを自動生成し、GitHub Pages で公開する
3. PR 単位でも HTML ページを生成し、見た目を確認できるようにする

作った構成

検証用に、Markdown の設計書を MkDocs Material でサイト化するサンプルを作りました。

検証に使っているサンプルは、GitHub で公開しています。

• tgrhg/md-to-design-doc

ざっくりした構成は以下です。

mkdocs.yml
requirements.txt
package.json
.github/workflows/pages.yml
docs/
  index.md
  architecture/sample-ec-service.md
  assets/images/sample-system-context.svg
scripts/
  write-version.mjs

役割をまとめるとこんな感じです。

ファイル	役割
mkdocs.yml	テーマ、ナビ、Markdown拡張の設定
docs/**/*.md	設計書本文
docs/assets/images/*	画像アセット
.github/workflows/pages.yml	GitHub Pages への公開

生成の流れは次のイメージです。

MkDocs とは

MkDocs は、Markdown で書いたドキュメントを静的な HTML サイトに変換するツールです。

ここではこちらを使って設計書を HTML 化していきます。GitHub Pages のような静的ホスティングとも相性が良く、構成も比較的シンプルです。

MkDocs 自体は、Markdown からサイトを生成するための土台です。その上に載せるテーマとして Material for MkDocs を使っています。

Material for MkDocs は、見た目だけでなく、検索、ナビゲーション、目次、日本語対応などを強化しやすいのが特徴です。人が読みやすいドキュメントサイトとして整えやすいので、これを選びました。

本文管理

設計書本文は docs/ 配下にそのまま Markdown で置きます。

Markdown にしておくと、本文の変更がそのまま Pull Request の差分になります。

たとえば、非機能要件の表も普通の Markdown で十分です。

| 分類 | 要件 | 補足 |
| --- | --- | --- |
| 可用性 | 月間稼働率 99.9% | CDN と Backend API を冗長化する |
| 性能 | 商品検索 P95 500ms 未満 | キャッシュを活用する |
| セキュリティ | 管理画面は SSO 必須 | 監査ログを保存する |

図や画像の扱い

設計書では図も重要です。これまでは PlantUML をよく使っていましたが、GitHub 上でそのまま表示できないことから、Mermaid を使う方針にしました。

PlantUML を動的に SVG へ変換して表示する方法も検討しましたが、その場合は HTML へ変換したあとでないと確認しづらくなります。GitHub 上でそのまま見えて、差分も追いやすい形に寄せたかったので、Mermaid を優先しました。

種類	向いている用途	管理方法
Mermaid	構成図、フロー図、シーケンス図	Markdown 内に直接書く
画像ファイル	画面キャプチャ、既存資料	docs/assets/images/ に置く

Mermaid や画像であれば GitHub 上でもそのまま表示できるので、設計書をリポジトリで読むときにも扱いやすいです。

ローカル確認

ローカルでは以下でビルドできます。

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
npm test
python3 -m http.server 8000 -d site

GitHub Pages に公開する

main ブランチにマージされたら、GitHub Actions でサイトをビルドして GitHub Pages に公開します。

workflow は push / PR / 手動実行に対応させました。

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, reopened, synchronize, closed]
  workflow_dispatch:

main への push では production を更新し、PR では preview を公開します。

PR 時のプレビュー表示

Markdown の差分だけでもレビューはできますが、次のような崩れは HTML で見ないと気づきにくいです。

• Mermaid や画像の表示崩れ
• 画像リンク切れ
• 表の横幅
• ナビゲーションでの見え方

そこで、PR ごとに preview を公開するようにしました。PR ではビルドしたサイトを gh-pages ブランチの /previews/pr-<PR番号>/ 配下に配置し、差分レビューと見た目確認を分けて見られるようにしています。

仕組みとしては、GitHub Actions でビルドしたサイトを PR 用のパスへ配置し、workflow 側で preview URL を組み立てて PR コメントに自動で埋め込んでいます。あわせて、配置した preview ページへのリンクをサイドバーから辿れるようにしておくと、production と見比べやすくなります。

production:
  https://<owner>.github.io/<repo>/

PR preview:
  https://<owner>.github.io/<repo>/previews/pr-<PR番号>/

PR の流れは次の通りです。

preview の公開には gh-pages ブランチのサブディレクトリを使い、PR コメントにも URL を出すようにしました。必要であれば、preview 一覧やサイドバーも同時に更新しておくと導線を作りやすいです。

このあたりは workflow とスクリプトで少し力技に寄せている部分もあるので、詳しくは実際のファイルを見てもらうのが早いです。

• pages.yml

Preview ページの URL を組み立てる workflow

- name: Compute preview URL
  id: preview_url
  env:
    OWNER: ${{ github.repository_owner }}
    REPO: ${{ github.event.repository.name }}
    PR_NUMBER: ${{ github.event.pull_request.number }}
  run: |
    if [ "$REPO" = "$OWNER.github.io" ]; then
      BASE_URL="https://$OWNER.github.io"
    else
      BASE_URL="https://$OWNER.github.io/$REPO"
    fi
    echo "url=$BASE_URL/previews/pr-$PR_NUMBER/" >> "$GITHUB_OUTPUT"

PR コメントに preview URL を埋め込む workflow

- name: Comment preview URL
  uses: actions/github-script@v7
  env:
    PREVIEW_URL: ${{ steps.preview_url.outputs.url }}
  with:
    script: |
      const body = [
        '### Design Docs Preview',
        `🔎 **Preview:** ${process.env.PREVIEW_URL}`,
      ].join('\n');

実際には、PR に preview URL と version index へのリンクを含むコメントを自動で投稿するようにしています。

コメントから preview ページを開くと、生成された HTML をそのまま確認できます。

注意点

GitHub Pages の設定

PR preview を URL で見せるには、GitHub Pages を branch-based で有効にしておく必要があります。

Settings > Pages > Build and deployment
Source: Deploy from a branch
Branch: gh-pages
Folder: / (root)

fork からの PR

同一リポジトリ内の PR であれば扱いやすいですが、fork からの PR は権限や secret の扱いに注意が必要です。

この場合は、preview を公開せず artifact のみにする構成も現実的だと思います。

終わりに

設計書を AI でも扱いやすくしつつ、人が読むときの見やすさも保ちたい場合、Markdown + MkDocs Material + GitHub Pages は試す価値のある構成だと思います。

興味が湧いたら、まずは小さな設計書ひとつからでも試してみてください。