個人開発のドキュメント戦略：設計書・思考ログの使い分け

この記事は、ひとりで作るSaaS - 設計・実装・運用の記録 Advent Calendar 2025 の4日目の記事です。

昨日の記事では「Next.js + Supabaseで始める個人開発」について書きました。今日は、個人開発におけるドキュメント戦略について書きます。

:::message
この記事で紹介する内容は、私が試行錯誤した結果の「現時点での形」です。失敗もたくさんあるので、それも含めて共有します。
:::

📁 現在のドキュメント構造

私はSIerでウォーターフォール型の開発を長く経験してきました。要件定義→基本設計→詳細設計→実装→テストという流れが身についています。私が個人開発しているMemoreruでも、最初はウォーターフォール型のアプローチで進めましたが、徐々にアジャイル的な要素を取り入れたハイブリッドなスタイルに変わっていきました。

試行錯誤の結果、Memoreruのドキュメントは以下のような構造になっています。今後も変わっていく可能性があります。

docs/
├── 00_プロジェクト管理/   # 開発ログ、タスク管理
├── 05_マーケット戦略/     # 競合分析、ポジショニング
├── 10_要件定義/           # 機能要件、非機能要件
├── 20_基本設計/           # アーキテクチャ、DB設計
├── 30_詳細設計/           # 画面定義、API仕様、テーブル定義
├── 40_実装/               # 実装ガイド、コーディング規約
├── 50_テスト/             # テスト仕様、テスト計画
├── 60_リリース/           # リリース手順、チェックリスト
├── 70_マニュアル/         # ユーザー向けガイド
├── 80_運用/               # 監視、障害対応
├── 90_その他/             # 分類しにくいもの
├── 99_アーカイブ/         # 古くなったドキュメント
├── analysis/              # 分析レポート
├── features/              # 機能別の検討資料
├── learning/              # 技術調査メモ
├── refactoring/           # リファクタリング計画
├── thinking/              # 思考ログ
└── deleted/               # 削除した機能

番号付きディレクトリはウォーターフォール型の開発フェーズに対応しています。一方で、thinking/ や features/ などは開発を進める中で必要になって追加したものです。

後者の構成は、以下のポストを参考にしました。

https://x.com/commte/status/1980832165182284233

補足

ウォーターフォール型で体系的にドキュメントを作成するのは、SaaSのような中規模〜大規模な開発を行う場合の話です。小規模な開発であれば、最初からフォルダを細かく分けず、日付付きのドキュメントをフラットに置いていくアジャイル的なアプローチの方が合っているかもしれません。たとえば以下のリポジトリでは、日付付きのドキュメントがフラットに配置されています。

https://github.com/team-mirai-volunteer/marumie/tree/develop/docs

また、docsを更新するたびにVercelの自動デプロイが走るのが気になる場合は、Vercelの「Ignored Build Step」で回避できます。コミットメッセージに[skip ci]を含める方法もあります。

ドキュメントとコードを別リポジトリにする選択肢もあります。リポジトリを分ければ権限を分けられるメリットがありますが、個人開発では同じ場所にある方が検索性やメンテナンス性の面でメリットが大きいと考えています。

🚀 序盤：ウォーターフォール型で要件を固める

開発の序盤は、ウォーターフォール型のアプローチを取りました。Claude Codeと壁打ちしながら、こんな感じで要件定義書を作成していきました。

# 機能要件定義書

## 1. ユーザー管理
- 1.1 ユーザー登録・ログイン
- 1.2 プロフィール編集
- 1.3 アカウント削除

## 2. コンテンツ管理
- 2.1 作成・編集・削除
- 2.2 公開設定

「10_要件定義」→「20_基本設計」→「30_詳細設計」と、ドキュメントを順番に作成していきました。当時は意識していませんでしたが、これは「仕様駆動開発」に近いアプローチだったと思います。

この段階では、ドキュメントを書いてから実装するというサイクルがうまく回っていました。

😿 失敗：ドキュメントのメンテナンスが追いつかなくなった

しかし、実装が進むにつれて問題が発生しました。

コードは日々変わっていくのに、ドキュメントは古いまま。設計書と実装が乖離していきます。「ドキュメントを更新してから実装」というサイクルが回らなくなりました。

詳細設計だけで大量のファイルがありますが、正直なところ、その多くは現在の実装と一致していません。ここは反省すべき点と考えています。

🔄 変化：アジャイルとのハイブリッドへ

ドキュメント駆動の限界を感じ、アプローチを変えました。

大きな設計変更: 事前にドキュメントを書く（ウォーターフォール的）
日々の実装: コードを先に書き、必要に応じてドキュメントを更新（アジャイル的）

完全なウォーターフォールでも完全なアジャイルでもない、ハイブリッドなスタイルに落ち着きました。

🧠 工夫①：思考ログを日付付きで残す

設計書のメンテナンスは追いつかなくなりましたが、thinking/ ディレクトリの思考ログは今でも役に立っています。後から振り返ったときに、なぜその判断をしたのかが分かるからです。たとえば以下のような感じです。

thinking/
├── 20251010_テーブル設計の見直し.md
├── 20251110_ID生成方式の検討.md
├── 20251111_キャッシュ戦略の検討.md
└── 20251113_AI機能の設計.md

日付をプレフィックスにして、その日に検討した内容を記録しています。

思考ログのポイントは、「決定した結果」だけでなく「なぜその決定をしたか」を残すことです。私はこんなフォーマットで書いています。

## 2025-11-10: 削除機能の仕様

### 背景
ユーザーがデータを削除したとき、どう処理するか決める必要がある。

### 検討した選択肢
1. 物理削除（完全に消す）
2. 論理削除（フラグで非表示にする）
3. ゴミ箱機能（30日後に自動削除）

### 決定
ゴミ箱機能を採用。

### 理由
- 誤削除からの復旧ができる
- ストレージ容量は定期削除で管理できる

設計書は古くなっても、思考ログは「その時点での判断」として価値が残ります。

💡 工夫②：コードの近くにドキュメントを置く

ドキュメントと実装の乖離を防ぐため、コードの近くにドキュメントを置くアプローチを試しています。

src/server/README.md   # サーバー層の設計説明

たとえばサーバーディレクトリのREADMEには、レイヤー構成や命名規則を記述しています。

## ディレクトリ構成

server/
├── loaders/          # 参照系エントリーポイント（SSR用）
├── actions/          # 書き込み系エントリーポイント
├── api/              # APIハンドラ
├── usecases/         # ビジネスロジック
└── repositories/     # データアクセス層

## レイヤー構成

リクエスト → api/ → usecases/ → repositories/ → database/

コードの近くにドキュメントがあれば、実装を変更したときに一緒に更新しやすくなります。これはうまくいっている部分です。

📊 工夫③：ドキュメントをAIのコンテキストとして活用

Claude Codeを使った開発では、ドキュメントが重要な役割を果たします。

AIはコードを読めますが、「なぜこの設計にしたのか」という意図は読み取れません。思考ログを読ませることで、背景を理解した上での提案を得られます。ドキュメントは、AIへのコンテキスト提供としても機能します。

CLAUDE.md：AIエージェントへの指示書

Claude Codeでは、プロジェクトルートにCLAUDE.mdを置くことで、AIにプロジェクト固有のルールや文脈を伝えられます。

MemoreruのCLAUDE.mdには以下のような情報を記載しています。

プロジェクト状態: 開発段階、最優先目標
設計思想: コアバリュー、設計原則
ディレクトリ構造: 各ディレクトリの役割
実装ルール: コーディング規約、禁止事項
Git運用: ブランチ戦略、コミットルール
thinkingへの参照: 過去の設計判断へのリンク

特に、禁止事項（本番環境への直接操作など）を明記しておくと、AIが誤った操作を提案するリスクを減らせます。

CLAUDE.mdの工夫については、以下のポストも参考になります。

https://x.com/oikon48/status/1995781484108734682

✅ まとめ：試行錯誤から得た学び

Memoreruでの試行錯誤から得た学びをまとめます。

うまくいったこと:

要件定義の段階でAIと壁打ちする
思考ログを日付付きで残す
コードの近くにREADMEを置く

うまくいかなかったこと:

詳細設計書を完璧に書いてから実装しようとした
ドキュメントの更新を後回しにした

現在は「コード自体を設計書にする」という方向で、より良いドキュメント運用を引き続き模索中です。みなさんの開発されているプロダクトではどのようなドキュメント運用をしていますか？

明日は「Gitブランチ戦略：個人開発で実践するワークフロー」について解説します。

シリーズの他の記事

12/3: Next.js + Supabaseで始める個人開発：プロジェクト構成の全体像
12/5: Gitブランチ戦略：個人開発で実践するワークフロー