ドキュメントサイト駆動開発：ドキュメントを先に書いて「仕様→実装」を回す実践

ドキュメントサイト駆動開発とは

ソフトウェア開発において「ドキュメントは後から書く」という慣習は根強い。しかし、AI エージェントと協働する時代において、この順序を逆転させることには大きなメリットがある。

ドキュメントサイト駆動開発は、以下のサイクルで開発を進めるアプローチである。

実装したいことをドキュメントとして先に書く
AI エージェントがドキュメントを読み、タスクを理解する
ドキュメントに基づいてコードを実装する
実装結果をドキュメントに反映する

README.md や Wiki ではなく、ドキュメントサイトを採用する点がポイントとなる。構造化された情報を、人間にも AI にも読みやすい形で管理できる。

なぜ Fumadocs なのか

Fumadocs は、Next.js ベースのドキュメンテーションフレームワークである。筆者が採用した理由を以下に紹介する。

コンテンツと構造の分離

Fumadocs は MDX ファイルでコンテンツを管理し、サイドバーやナビゲーションは meta.json で定義する。この分離により、ドキュメントの内容に集中でき、構造の変更も容易になる。

monorepo との相性

monorepo 構成で apps/docs にドキュメントサイトを配置する形が自然にフィットする。プロダクトコードとドキュメントが同じリポジトリに存在することで、PR でコードとドキュメントの変更を同時にレビューできる。

repo-root/
├── apps/
│   ├── docs/          # Fumadocs
│   │   ├── content/
│   │   │   ├── en/
│   │   │   └── ja/
│   │   └── ...
│   └── web/
├── packages/
├── AGENTS.md
└── ...

i18n サポート

Fumadocs は i18n を標準でサポートしている。プロジェクト全体のコードやコメントは英語（en）で統一しつつ、ドキュメントサイトのみ日本語（ja）と英語（en）の両方で提供できる。

これにより、人間向けの情報は母国語で読めるという大きな利点が得られる。設計思想やアーキテクチャの背景など、ニュアンスが重要な情報を日本語で記述できるのは、日本語話者にとって非常にありがたい。

AGENTS.md との連携

この開発スタイルで最も効果を発揮するのが、AI エージェントとの連携である。

リポジトリのルートに置く AGENTS.md に、以下のような指示を記述している。

## Understanding Tasks
 
Refer to the documentation in `apps/docs` for features to implement
and their context. Follow the specifications documented there.

こうすることで、AI エージェントはドキュメントを「仕様書」として読み取り、何を実装すべきかを自律的に理解する。人間がタスクの詳細を逐一説明する必要がなくなる。

ドキュメントが仕様書になる

従来のドキュメントは「実装の説明」であった。ドキュメントサイト駆動開発では、ドキュメントが「実装の指示」になる。

従来のアプローチ	ドキュメントサイト駆動開発
コードを書く → ドキュメントを書く	ドキュメントを書く → コードを書く
ドキュメントは実装の後追い	ドキュメントが実装の指針
ドキュメントは人間向け	ドキュメントは人間と AI の両方向け
ドキュメントの陳腐化が起きやすい	ドキュメントが常に最新（先に書くため）

実践から得た知見

実際にこのアプローチを運用して気づいた点をいくつか共有する。

1. 「書けないドキュメント」は設計が固まっていないサイン

ドキュメントを先に書こうとして手が止まるときは、そもそも何を作りたいのかが明確になっていない。ドキュメントを書く行為自体が、思考を整理するプロセスとして機能している。

2. 「AI が読むドキュメント」と「人間が読むドキュメント」は性質が異なる

API リファレンスのような機械的な情報は、AI エージェントが実装時に直接参照するコンテキストとして機能する。一方、アーキテクチャガイドや設計判断の背景は、人間がレビューや意思決定の際に読むものである。この二つは読者と目的が異なるため、ディレクトリやカテゴリを分けて管理するのが望ましい。

3. ドキュメントのレビュー = 設計のレビュー

PR でドキュメントの変更をレビューすることが、そのまま設計レビューになる。コードレビューの前にドキュメントレビューを挟むことで、実装前に方針のズレを検知できる。

4. Day 1 から入れることの重要性

「ある程度コードが書けてからドキュメントサイトを入れよう」と考えると、結局入れないまま終わることが多い。リポジトリを作成した瞬間からドキュメントサイトをセットアップし、最初のコミットに含めることが重要である。

ドキュメントサイト駆動開発のワークフロー

ここまで紹介した考え方を、具体例を交えて一連の流れとして示す。

Step 1: ドキュメントを書く

新機能やリファクタリングの計画を、まずドキュメントとして書く。たとえば apps/docs/content/ja/architecture/notification.mdx に以下のようなページを作成する。

# 通知システム
 
## 概要
特定のイベント発生時に、アプリ内通知やメール通知を送信する。
 
## 要件
- 複数チャネルに対応: アプリ内、メール、Slack
- ユーザーがチャネルごとに通知設定を変更できる
- 配信失敗時は指数バックオフでリトライする
 
## アーキテクチャ
- イベントバス: `packages/events`
- チャネルアダプター: `packages/notifications/channels/`
- 設定ストア: データベースにユーザーごとの設定を保持

Step 2: ドキュメントをコミット

ドキュメントを先にコミットする。この時点ではコードは一切書いていない。

Step 3: AI エージェントにタスクを実行させる

AI エージェントは AGENTS.md の指示に従い、apps/docs のドキュメントを読み、実装に取りかかる。

Step 4: 実装後にドキュメントを更新

実装の過程で判明した詳細や変更点をドキュメントに反映する。

まとめ

ドキュメントサイト駆動開発は、以下の問題を同時に解決するアプローチである。

ドキュメントの陳腐化：先に書くから常に最新
AI エージェントへのコンテキスト共有：構造化されたドキュメントが仕様書になる
設計の曖昧さ：書けないなら、まだ設計が固まっていない
多言語対応：Fumadocs の i18n で、コードは英語、ドキュメントは母国語

Fumadocs はこの目的に非常に適したフレームワークである。monorepo の day 1 から導入し、ドキュメントファーストな開発を始めてみてほしい。

以上、ドキュメントサイト駆動開発の実践を紹介した、現場からお送りしました。