基本設計書

項目	内容
文書番号	BD-001
版数	1.0
作成日	2026-06-12
作成	Claude Code（実装担当）
承認	けんぞ（PM）

1. アーキテクチャ概要

編集者・増築者人間 / Claude Code更新方法はどちらも同じ「md ファイルを docs/ に置く」だけ

↓md を置く・直す（git で差分管理）

正本docs/ + git唯一の信頼できる原稿。ディレクトリ構造＝サイトマップ

↓vitepress build（リンク切れ検査込み・実測 1.3 秒）

読み口静的サイト（HTML/CSS/JS 一式）サイドバー・検索・スマホ対応はすべて自動生成

↓wrangler pages deploy

公開Cloudflare Pageshttps://asset-portal.pages.dev（無料枠）

動的なサーバーは持たない。すべて静的ファイルなので、運用コストはゼロ、表示は速く、壊れる箇所が少ない。

2. 技術選定

2.1 比較検討

「正本は md のまま、読み口を自動生成する」という要件（FR-01）に対し、5 案を比較した。

案	自動でサイト化	AI が増築可能	アクセス制限	費用	判定
VitePress	◎ ビルド一発	◎ md+git を直接編集	◎ Cloudflare Access 併用	無料	採用
Astro Starlight	◎ ビルド一発	◎ 同上	◎ 同上	無料	次点
GitHub リポジトリ直読み	△ 描画のみ・ナビなし	◎ 同上	◎ リポジトリ権限	無料	Step0 として活用
Google Sites	✗ 手転記が必要	✗ API なし	◎ ドメイン制限	無料	不採用
Notion / Confluence	△ 正本ごと移行が必要	△ 専用 API 経由のみ	◎	有料あり	不採用

2.2 採用理由（VitePress 1.6.4）

セットアップが最小（依存は実質 2 パッケージ）
リンク切れがあるとビルドが失敗する標準仕様 → ビルド自体がテストになる（FR-04）
日本語ローカル検索が組み込み（FR-03）
サイドバー自動生成は vitepress-sidebar 1.36.1 で実現（FR-01/FR-02）

2.3 Google Sites の不採用理由（記録として残す）

社内共有の定番候補として検討したが、生成した HTML を流し込む手段がなく、ページ作成 API も提供されていない。つまり md を書いた後にブラウザで手転記する運用になり、「更新が人間任せだから wiki が廃墟化する」という課題（要件定義書 1 章）の再演になるため不採用とした。Google Workspace のドメイン制限は優秀なので、入口リンク集（ポータル）用途での併用は妨げない。

3. ディレクトリ設計（＝サイトマップ）

docs/
├── index.md                 # ポータルトップ
├── 00-project-plan/         # プロジェクト計画
├── 01-requirements/         # 要件定義
├── 02-design/               # 設計（基本設計・運用設計）
├── 03-test/                 # テスト（計画・結果）
├── 04-release/              # リリース
├── 05-meetings/             # 議事録（時系列）
├── 06-issues/               # 課題管理
└── 07-learnings/            # 学び・改修記録

設計原則は3つ。

番号プレフィックス（NN-）で表示順を制御する。工程順に並ぶ
URL スラグは英語、表示タイトルは日本語。frontmatter title: がサイドバーに反映される
1ファイル1文書。文書が増えたらファイルを足す。ディレクトリが増えたら章が増える

4. サイドバー自動生成の設計

docs/.vitepress/config.mts で vitepress-sidebar の generateSidebar() を呼び、次を指定する。

設定	値	意図
useTitleFromFrontmatter	true	日本語タイトルをサイドバーに表示
useFolderTitleFromIndexFile	true	フォルダ名でなく index.md のタイトルを章名に
sortMenusByName	true	番号プレフィックス順に整列
includeRootIndexFile	false	トップページはサイドバーから除外

5. ホスティング設計

項目	内容
ホスティング	Cloudflare Pages（無料枠）
デプロイ方式	wrangler CLI による直接アップロード（当面）。git 連携自動化は課題 I-03
URL	https://asset-portal.pages.dev
アクセス制限	当面なし（機密ゼロ運用）。必要時に Cloudflare Access（50 ユーザーまで無料）を設定

6. 視覚表現の設計（読み口の装飾規約）

正本（md）の可搬性（NFR-05）を守るため、本文 md はプレーンに保ち、装飾は読み口側（テーマ CSS）に寄せる。md にインライン style やページ固有の装飾を直書きしない。生成ツールを将来乗り換えても、md は素のまま読める形を維持する。

使ってよい表現は次の2系統のみ。

6.1 VitePress 標準機能

表現	用途
カスタムコンテナ（tip / info / warning / danger / details）	注意喚起・補足・折りたたみ
Badge コンポーネント	状態表示（合格・未着手・完了など）

6.2 共通クラス（`.vitepress/theme/custom.css` に定義）

クラス	用途	使用例
`.ap-flow`	上から下へのフロー図	本書 1 章のアーキテクチャ図
`.ap-steps`	段階導入のステッパー（現在地表示）	リリース計画書 1 章
`.ap-metrics`	実測値のメトリクスカード	テスト結果報告書 2 章
`.ap-checklist`	チェックリスト	リリース計画書 3 章

新しい表現が必要になったら、まず共通クラスとして custom.css に追加してから使う（ページ単位の使い捨て装飾を作らない）。

変更履歴

版	日付	変更内容
1.0	2026-06-12	初版作成
1.1	2026-06-12	アーキテクチャ図を HTML 化、6 章「視覚表現の設計」を新設

基本設計書 ​

1. アーキテクチャ概要 ​

2. 技術選定 ​

2.1 比較検討 ​

2.2 採用理由（VitePress 1.6.4） ​

2.3 Google Sites の不採用理由（記録として残す） ​

3. ディレクトリ設計（＝サイトマップ） ​

4. サイドバー自動生成の設計 ​

5. ホスティング設計 ​

6. 視覚表現の設計（読み口の装飾規約） ​

6.1 VitePress 標準機能 ​

6.2 共通クラス（.vitepress/theme/custom.css に定義） ​

変更履歴 ​