わしが最近気になっておった記事を見つけたのじゃ。個人開発でClaude Codeを使うときに、なんと24個ものドキュメントを事前に準備するという、まさに 準備が8割 を体現したお話なのじゃよ。

参考神記事：【Claude Code】マネできる！個人開発するときに最初に用意したドキュメント24種と機能要件書を全公開

🧸「しろくまちゃん、24個って多すぎない？そんなに準備が必要なの？」

🐻‍❄️「ほほう、テディよ。確かに多く感じるかもしれんが、これには深い理由があるのじゃ。AIエージェントというのは優秀じゃが、プロジェクト全体の一貫性を保つのが苦手なのじゃよ。人間が事前にルールを決めておかないと、コードがバラバラになってしまうのじゃ」

この記事の著者さんも、過去に3つの個人開発アプリを作る中で、毎回同じところで詰まっていたのじゃ。「このエラーはどう処理すればいいの？」「APIの設計はどうする？」といった悩みを何度も繰り返しておったのじゃよ。それで今回は 実装前の準備で開発中のずれをほぼゼロ にする実験をしたのじゃな。

✨ ドキュメントの全体像を見てみるのじゃ

わしも驚いたのじゃが、このドキュメント群は3つのカテゴリーに分かれておるのじゃ。

🏗️ 技術設計ドキュメント（15個）

システムの骨格となる部分じゃな。アーキテクチャ設計から始まって、データベース設計、API設計、エラーハンドリング、セキュリティまで、技術的な決め事を全て文書化しておるのじゃ。

🧸「しろくまちゃん、これって設計書を作るのに時間がかかりすぎない？」

🐻‍❄️「おお、それが面白いところなのじゃ！実はこれら全部、AIだけで作ったのじゃよ。Claude OpusやDeep Researchを使って調査し、Claude Codeに各種ドキュメントを作らせたのじゃ。つまり 再現性が高い ということなのじゃ」

🎨 デザインシステム（5個）

見た目の統一感を保つためのドキュメント群じゃな。カラーパレット、タイポグラフィ、アニメーション、レイアウトなど、デザインに関するルールを事前に決めておくのじゃ。

これがないと、AIエージェントが作るUIがバラバラになってしまうのじゃよ。「プライマリカラーは#3B82F6」「見出しのフォントサイズは2rem」といった具体的な値を決めておけば、一貫したデザインが保たれるのじゃ。

📚 ライブラリ対策ドキュメント（4個）

これが特に実用的じゃな。過去の開発で最も時間を無駄にしたのが、ライブラリ固有の問題でハマることだったのじゃ。Shadcn UI、Supabase、Next.js App Routerなど、よく使うライブラリの使い方や注意点を事前にまとめておるのじゃよ。

🧸「なるほど！でもこれだけドキュメントがあると、どれを見ればいいか迷いそうだね」

🐻‍❄️「その通りじゃ！だからこそ CLAUDE.md という司令塔ファイルが重要なのじゃ。このファイルがAIエージェントの道標となって、必要な情報をすぐに取得できるようにしておるのじゃよ」

🎯 実践チュートリアル：今すぐできる手順なのじゃ

🧸「具体的にはどうやって始めればいいの？手順を教えて！」

🐻‍❄️「よい質問じゃな、テディよ！わしが実際に試してみた手順を、ステップバイステップで教えてあげるのじゃ」

📋 ステップ1：プロジェクトのコンセプトを固める（30分）

まずは何を作るのかを明確にするのじゃ。以下の質問に答えてみるとよいじゃろう：

基本情報の整理

• どんなアプリを作りたいのか？（例：タスク管理アプリ、SNS、ECサイト）
• 誰が使うのか？（ターゲットユーザー）
• なぜ作るのか？（解決したい課題）
• どんな技術を使うのか？（Next.js、React、Supabaseなど）

🐻‍❄️「Claude OpusやChatGPTに『私は○○なアプリを作りたいです。以下の情報を整理して、機能要件書を作ってください』と頼むのが効率的じゃよ」

実際のプロンプト例

私は個人開発者向けのポートフォリオ管理アプリを作りたいです。
- ターゲット：フリーランスのWebデザイナー
- 課題：作品をきれいに整理して見せたい
- 技術：Next.js + Supabase + Tailwind CSS

この情報を元に、機能要件書とアプリのコンセプトドキュメントを作成してください。

📁 ステップ2：プロジェクト構造を作る（15分）

次に、プロジェクトフォルダに以下の構造を作るのじゃ：

your-project/
├── .claude/
│   ├── 00_project/
│   │   ├── 01_concept_requirements.md
│   │   └── 02_inception_deck.md
│   ├── 01_development_docs/
│   ├── 02_design_system/
│   ├── 03_library_docs/
│   └── CLAUDE.md

🧸「手動で作るの？」

🐻‍❄️「いや、これもClaude Codeに任せられるのじゃ！以下のプロンプトを使うとよいじゃろう」

フォルダ構造作成プロンプト

プロジェクトのドキュメント管理用に、以下の構造でフォルダとファイルを作成してください：

.claude/
├── 00_project/（機能要件とコンセプト）
├── 01_development_docs/（技術設計書）
├── 02_design_system/（デザインシステム）
├── 03_library_docs/（ライブラリ対策）
└── CLAUDE.md（司令塔ファイル）

各フォルダには空の.gitkeepファイルも作成してください。

🏗️ ステップ3：コア設計ドキュメントを作る（60分）

ここからが本格的な作業じゃな。まず最重要な5つのドキュメントから始めるのじゃ：

Phase 1：基本設計（必須）

1. 01_architecture_design.md – システム設計
2. 02_database_design.md – データベース設計
3. 03_api_design.md – API設計
4. 06_error_handling_design.md – エラーハンドリング
5. 00_basic_design.md – デザインの基本方針

🐻‍❄️「これらは順番に作るのが重要じゃ。まずアーキテクチャを決めて、次にデータベース、その次にAPIという流れじゃな」

実際のプロンプト例（アーキテクチャ設計）

私のプロジェクト（ポートフォリオ管理アプリ）について、以下の要件でアーキテクチャ設計書を作成してください：

技術スタック：Next.js 14 App Router + Supabase + Tailwind CSS
要件：ユーザー登録、作品アップロード、公開ページ生成

以下の内容を含めてください：
- フォルダ構造の設計
- レイヤー分けの方針（presentation, business, data）
- 状態管理の方針
- ファイル命名規則

ファイル名：01_architecture_design.md

🎨 ステップ4：デザインシステムを構築（45分）

次にデザインの統一感を保つためのドキュメントを作るのじゃ：

作成するドキュメント

• 00_basic_design.md – デザインの概要
• 01_design_principles.md – カラー、フォント、スペーシング
• 02_component_design.md – UIコンポーネント設計

🧸「デザインって難しそう…」

🐻‍❄️「心配いらんのじゃ！AIに任せれば、現代的でアクセシブルなデザインシステムを作ってくれるのじゃよ」

デザインシステム作成プロンプト

ポートフォリオ管理アプリ用のデザインシステムを作成してください。

要件：
- モダンで洗練された印象
- ダークモード対応
- アクセシビリティを重視
- Tailwind CSSを使用

以下を含むデザインシステムを3つのMarkdownファイルで作成：
1. 基本方針（00_basic_design.md）
2. カラーパレット・タイポグラフィ（01_design_principles.md）  
3. ボタン・カード・フォームのコンポーネント設計（02_component_design.md）

📚 ステップ5：ライブラリ対策ドキュメント（30分）

使用予定のライブラリについて、事前にハマりポイントを調査するのじゃ：

調査すべきライブラリ

• フレームワーク（Next.js App Routerなど）
• データベース（Supabaseなど）
• UIライブラリ（Shadcn/ui、Chakra UIなど）
• 認証システム

🐻‍❄️「これは過去にハマった経験がある人ほど価値を感じるはずじゃ。事前に調査しておけば、実装中に数時間溶かすことを防げるのじゃよ」

ライブラリ調査プロンプト

Next.js 14 App RouterとSupabaseを使った開発でよくあるハマりポイントと解決策をまとめてください。

特に以下について：
- Server ComponentsとClient Componentsの使い分け
- Supabase認証のテスト方法
- ファイルアップロードの実装
- よくあるエラーと対処法

結果を以下のファイルに分けて作成：
- 04_nextjs_app_router_patterns.md
- 02_supabase_auth_patterns.md

🎯 ステップ6：司令塔ファイル（CLAUDE.md）を作成（20分）

最後に、すべてのドキュメントを統括する司令塔ファイルを作るのじゃ：

CLAUDE.md作成プロンプト

これまで作成した設計ドキュメントを統括する司令塔ファイル「CLAUDE.md」を作成してください。

以下を含めてください：
- プロジェクト概要
- 各ドキュメントへのリンク
- タスク別クイックリファレンス（「APIを追加したい時は○○を参照」など）
- よくある落とし穴の警告
- 開発時の注意事項

このファイルを見れば、何をする時にどのドキュメントを参照すればいいかが一目でわかるようにしてください。

🚀 ステップ7：実際の開発を始める（完了後）

すべてのドキュメントが完成したら、いよいよ開発開始じゃ！

Claude Codeでの開発コマンド例

# 新しい機能を追加する時
claude code "ユーザー登録機能を実装してください。CLAUDE.mdの設計に従って、認証はSupabaseを使用してください"

# エラーハンドリングを実装する時  
claude code "エラーハンドリングを06_error_handling_design.mdに従って実装してください"

# UIコンポーネントを作る時
claude code "ログインフォームを02_component_design.mdのデザインシステムに従って作成してください"

🧸「これなら迷わずに開発できそうだね！」

🐻‍❄️「その通りじゃ！Claude Codeに明確な指示を出せるから、一貫性のあるコードが生成されるのじゃよ」

⏰ 時間配分の目安

初回セットアップ（計3時間）

• コンセプト整理：30分
• フォルダ構造作成：15分
• コア設計ドキュメント：60分
• デザインシステム：45分
• ライブラリ対策：30分
• CLAUDE.md作成：20分

追加ドキュメント（必要に応じて）

• セキュリティ設計：30分
• パフォーマンス設計：30分
• テスト戦略：45分
• CI/CD設計：30分

🧸「3時間かかるの？結構長いね…」

🐻‍❄️「確かに最初は時間がかかるじゃが、この投資で後の開発が格段にスムーズになるのじゃ。しかも一度テンプレートを作れば、次のプロジェクトでは30分程度で準備できるようになるのじゃよ」

🌟 CLAUDE.mdの司令塔としての役割

このファイルの最大の特徴は「タスク別のクイックリファレンスマップ」なのじゃ。たとえば「新しいAPIエンドポイントを作りたい」という時に、どのドキュメントを参照すればいいかが一目でわかるようになっておるのじゃ。

さらに「よくある落とし穴」セクションでは、過去にハマったポイントを事前に警告しておるのじゃよ。「ServerとClient Components間でクラスインスタンスを渡さない」といった、知らないと数時間溶かすような注意点をまとめておるのじゃな。

🧸「これって、人間の開発者にとっても便利そうだね！」

🐻‍❄️「その通りじゃ！数ヶ月後に機能追加する時も、これらのドキュメントがあれば当時の設計思想をすぐに思い出せるのじゃ。それはAIにとっても同じで、過去の設計を参照できることでプロジェクト全体の一貫性が保たれるのじゃよ」

🚀 実際に得られた効果は想像以上じゃった

この準備の効果は絶大だったようじゃな。まず、Claude Codeとの対話がスムーズになったのじゃ。「エラーハンドリングは06_error_handling_design.mdに従って実装して」と伝えるだけで、プロジェクト全体で統一されたエラーハンドリングが実装されるのじゃよ。

さらに実装の迷いがほぼゼロになったのじゃ。「このロジックはどこに書くべきか」「このエラーはどう処理すべきか」といった判断に時間を使うことがなくなり、純粋に機能開発に集中 できるようになったのじゃな。

🧸「でも、これだけの準備をするのは大変じゃない？」

🐻‍❄️「確かに準備は大変じゃが、記事の著者さんも言っておるように、これらは 机上の空論ではなく、実際の開発で痛い目を見た経験から生まれた ものなのじゃ。エラーハンドリングで悩んだから設計書を作り、ライブラリでハマったから対策ドキュメントを作る。そうやって積み上げてきたノウハウの集大成なのじゃよ」

🎉 成功のポイント

完璧を求めすぎない 最初から全24個作る必要はないのじゃ。まずは必要最小限から始めて、開発しながら追加していくのがよいじゃろう。

プロジェクトに合わせてカスタマイズ 元記事の構成をそのまま使うのではなく、お主のプロジェクトの特性に合わせて調整することが大切じゃな。

継続的な改善 実際に開発してみて「このドキュメントは不要だった」「こういう情報も必要だった」という気づきがあれば、どんどん改善していくのじゃ。

📝 わしが特に注目したポイント

この記事で特に感心したのは、全部AIだけで作った という点じゃな。機能要件をClaude OpusやChatGPTでまとめ、ライブラリの調査もAIで行い、最終的にClaude Codeに各種ドキュメントを作らせたのじゃ。

つまり、同じようなことをやりたい人は、この記事の内容をコピペしてClaude Codeに渡すだけで再現できるのじゃよ。これは素晴らしいアイデアじゃな。

🧸「しろくまちゃん、これって他の開発でも応用できそうだね！」

🐻‍❄️「その通りじゃ！個人開発だけでなく、チーム開発でも使えるアプローチじゃな。特に新しいプロジェクトを始める時には、こういった準備が後々の開発効率に大きく影響するのじゃよ」

🌈 個人開発者にとっての意味

この記事が個人開発者にとって特に価値があるのは、AIエージェントとの協業 という新しい開発スタイルに対する具体的な指針を示していることじゃな。

従来の開発では「設計書は後回し」ということも多かったじゃろうが、AIエージェントと協業する場合は 事前の設計が開発効率を大きく左右する ということが分かるのじゃ。

🧸「これからはAIと一緒に開発することが当たり前になりそうだもんね」

🐻‍❄️「その通りじゃ！そして、AIは優秀じゃが万能ではない。人間が適切な指針を与えることで、AIの能力を最大限に活用できるのじゃよ。この記事は、まさにそのやり方を具体的に示してくれておるのじゃな」

また、記事の最後で触れられている「Appcadia」というアプリのコンセプトも興味深いのじゃ。個人開発者が自分のアプリを簡単に公開できるプラットフォームを目指しておるようで、個人開発者同士のコミュニティ形成にも繋がりそうじゃな。

この記事から学べるのは、単なるドキュメント作成術だけでなく、AIエージェントとの効果的な協業方法 そのものなのじゃ。準備8割という考え方は、これからのAI時代の開発において、ますます重要になってくるじゃろうな。

お主も個人開発を始める時は、ぜひこのアプローチを参考にしてみると良いのじゃ。最初は準備に時間がかかるかもしれんが、その分後の開発効率が格段に上がるはずじゃからな ﾌｫﾌｫ 🐻‍❄️✨