こんにちは、とまだです。

最近、Claude Codeで本格的に個人開発アプリを3つほど作ってきました。

ただ、毎回同じような設計で悩んだり、ライブラリの使い方でしばらくハマったり、AIエージェントに同じ説明を繰り返したりしていました。

そこで新しいプロジェクトでは、開発着手前に設計ドキュメントを徹底的に準備するという実験をしてみました。

結果、なんと 24個ものドキュメント ができあがったので、今回はその全貌と、なぜこれらが必要だったのかをお伝えします！

【追記】
おかげさまで大反響で、たくさんの方に読んでいただいたようで嬉しいです！
同様のドキュメントを一発生成＋自動更新するカスタムコマンド作りましたので、よければこちらでサクッと試してみてください。

忙しい人のために先にまとめ

Claude Codeでの開発効率を上げるため、事前に24個の設計ドキュメントを作成
技術設計15個、デザインシステム5個、ライブラリ対策4個の構成
CLAUDE.md という司令塔ファイルで、AIエージェントが迷わないように
過去3つの個人開発で溜めたノウハウを全部詰め込んだ
実装前の準備で、開発中のずれをほぼゼロにする

同じようなことをやりたい人へ

今回のドキュメント準備にあたっては、以下のような流れで進めました。

Claude や ChatGPT を使い、アプリの機能要件をドキュメントとしてまとめる
.claude/00_project/01_appcadia_concept_requirements.md に配置
ハマりそうな外部ライブラリの使い方は Claude Opus や Deep Research を使って調査し、.claude/03_library_docs/ に配置
上記の内容を元に、Claude Code に各種ドキュメントを作らせる

つまり、 全部AIだけで作りました ので、再現性は高いかと思います。

真似してみたい方は今回の記事の内容をぜーんぶコピペし、Claude Code に以下のようなプロンプトを渡すだけで再現できると思います！
長いので、何かファイルに書いておいて Claude Code に渡してもいいかもしれません。
（究極を言えば、記事を最後まで読まなくてもOK！！！！！）

# 背景
これから個人開発アプリを作ります。
機能要件やコンセプトなどは `.claude/00_project/01_appcadia_concept_requirements.md` にまとめてあります。

# 目的
開発を行う上で設計やルールを事前に決めておきたいです。

# 命令
参考情報をもとに、似たような構成で事前にドキュメントを作成してください。

# 参考情報
（ここに本記事の内容をコピペ）

作成したドキュメントの全貌

まず、どんなドキュメントを作ったのか、全体像をお見せします。

.claude/
├── 00_project/                    # プロジェクトの要件
│   ├── 01_appcadia_concept_requirements.md
│   └── 02_inception_deck.md
├── 01_development_docs/           # 技術設計ドキュメント（15個）
│   ├── 01_architecture_design.md
│   ├── 02_database_design.md
│   ├── 03_api_design.md
│   ├── 04_screen_transition_design.md
│   ├── 05_seo_requirements.md
│   ├── 06_error_handling_design.md
│   ├── 07_type_definitions.md
│   ├── 08_development_setup.md
│   ├── 09_test_strategy.md
│   ├── 10_frontend_design.md
│   ├── 11_cicd_design.md
│   ├── 12_e2e_test_design.md
│   ├── 13_security_design.md
│   ├── 14_performance_optimization.md
│   └── 15_performance_monitoring.md
├── 02_design_system/              # デザインシステム（5個）
│   ├── 00_basic_design.md
│   ├── 01_design_principles.md
│   ├── 02_component_design.md
│   ├── 03_animation_system.md
│   └── 04_layout_system.md
└── 03_library_docs/               # ライブラリ対策（4個）
    ├── 01_shadcn_doc.md
    ├── 02_supabase_auth_vitest.md
    ├── 03_supabase_storage_vitest.md
    └── 04_nextjs_app_router_patterns.md

なぜこんなに大量のドキュメントが必要だったのか

正直、最初は「設計書なんて数個でいいでしょ」と思っていました。

ですが、過去に Claude Code や Cursor、GitHub Copilot など AI エージェントを使った個人開発を振り返ると、いつも同じところで詰まっていたんです。

たとえばテストの実装で「このエラーはどう処理すればいいの？」と迷ったり、APIの設計で「このエンドポイントはどこに置くべき？」と悩んだりとかとか。

あとは地味に、デザインがバラバラになってしまうことも多かったです。AIエージェントは優秀ですが、プロジェクト全体の一貫性を保つのは苦手なんですよね。

また、数ファイル単位で見るといい感じの実装になっていても、プロジェクト全体で見ると「なんか統一感がない」「このロジックはどこに書くべき？」といった問題が頻発していました。

これらの問題を解決するには、事前に細かいルールまで決めておく必要があったんです。

技術設計ドキュメント（15個）の役割

技術設計は、開発の骨格となる部分です。それぞれのドキュメントがどんな役割を果たしているか、詳しく見ていきましょう！

アーキテクチャから始まる基盤設計

01_architecture_design.md

システム全体の設計思想を定義しています。私はDDDとClean Architectureを採用することが多いんですが、このドキュメントでは「なぜその設計を選んだのか」「各レイヤーの責任は何か」を明確にしています。

これがあることで、Claude Codeに「このロジックはどこに書くべき？」と迷わせることがなくなりました。たとえば、「ビジネスロジックはdomainレイヤー、DBアクセスはinfrastructureレイヤー」という明確な指針があれば、AIも迷わず適切な場所にコードを生成してくれます。

02_database_design.md

ER図とテーブル定義を詳細に記載しています。カラム名の命名規則、インデックスの方針、リレーションの制約など、データベース設計で決めるべきことは意外と多いんです。これを事前に決めておかないと、後からマイグレーションの嵐になってしまいます。

03_api_design.md

RESTful APIの設計書です。エンドポイントの命名規則、リクエスト/レスポンスの形式、エラーレスポンスの統一フォーマットなどを定義しています。特に重要なのは、成功時とエラー時のレスポンス形式を統一すること。これによって、フロントエンドでの処理が格段に楽になります。

画面とSEOの設計

04_screen_transition_design.md

ユーザーがどのように画面を遷移していくかを定義したドキュメントです。単なる画面一覧ではなく、「どの画面からどの画面へ遷移できるか」「各画面で必要な権限は何か」といった情報も含んでいます。

05_seo_requirements.md

個人開発者にとって特に重要なSEO対策をまとめたものです。メタタグの設定方法、構造化データの実装、サイトマップの生成方法など、検索エンジンからの流入を増やすための施策を具体的に記載しています。

エラーハンドリングと型定義

06_error_handling_design.md

エラーの分類と処理方法を体系化しています。バリデーションエラー、認証エラー、システムエラーなど、それぞれのエラーに対してどのようなメッセージを表示し、どのようにログを残すかを定義しています。

これがあることで、「このエラーはユーザーに見せていいの？」「ログレベルは何にする？」といった判断に迷うことがなくなりました。

07_type_definitions.md

TypeScriptの型定義に関する設計書です。ドメインモデルの型定義はもちろん、APIレスポンスの型、フォームの型など、アプリケーション全体で使用する型を一元管理しています。

開発効率を上げる設計

08_development_setup.md

開発環境のセットアップ手順です。必要なツールのインストール、環境変数の設定、開発用データベースの準備など、新しいメンバー（人間でもAIでも）がすぐに開発を始められるようにしています。

09_test_strategy.md

テスト戦略を定義しています。単体テスト、統合テスト、E2Eテストそれぞれの役割と、どの部分をどれくらいカバーするかの方針を明確にしています。特にTDD（テスト駆動開発）を採用する場合、この設計書は必須です。

10_frontend_design.md

フロントエンドのコンポーネント設計です。コンポーネントの分類（ui/features/layouts）、propsの設計方針、状態管理の方法などを定義しています。

運用を見据えた設計

11_cicd_design.md

CI/CDパイプラインの設計を行っています。GitHub Actionsでどのようなチェックを行うか、デプロイの手順、環境ごとの設定などを記載しています。

12_e2e_test_design.md

E2Eテストの設計書です。クリティカルパス（絶対に動いてほしい機能）の定義と、それらをどのようにテストするかを具体的に記載しています。

セキュリティとパフォーマンス

13_security_design.md

セキュリティに関する設計をまとめています。認証・認可の仕組み、入力値検証、ファイルアップロードの制限など、セキュリティホールを作らないための指針を定義しています。

14_performance_optimization.mdと15_performance_monitoring.

パフォーマンスに関する設計書です。画像の最適化、キャッシュ戦略、Core Web Vitalsの目標値などを定義し、さらにそれらをどのように監視・改善していくかの仕組みも設計しています。

デザインシステム（5個）の重要性

先述の通り、デザインシステムは、見た目の統一感を保つために欠かせません。

今回は触れませんが、AIエージェントに渡すデザインシステムの例は、拙著ですが以下の記事が参考になります。

00_basic_design.md

デザインシステムの概要とクイックスタートガイドです。「とりあえずこれを読めば始められる」という位置づけのドキュメントです。

CLAUDE.md からは、まずこのドキュメントを参照するようにしています。

01_design_principles.md

カラーパレット、タイポグラフィ、スペーシングなどの基本的なデザイン原則を定義しています。「プライマリカラーは#3B82F6」「見出しのフォントサイズは2rem」といった具体的な値を決めておくことで、デザインの一貫性が保たれます。

02_component_design.md

UIコンポーネントの詳細設計です。ボタン、カード、フォームなど、よく使うコンポーネントのバリエーションと使い分けを定義しています。

03_animation_system.md

アニメーションの設計を行っています。どんな時にどんなアニメーションを使うか、イージング関数は何を使うか、アニメーションの長さはどれくらいにするかなど、動きに関する統一ルールを定めています。

04_layout_system.md

レイアウトシステムの設計書です。グリッドシステム、ブレークポイント、コンテナの最大幅など、レスポンシブデザインを実現するための基本設計を定義しています。

ライブラリ対策ドキュメント（4個）の必要性

過去の個人開発で最も時間を無駄にしたのが、ライブラリ固有の問題でハマることでした。

01_shadcn_doc.md

Shadcn UIの全コンポーネントの使い方をまとめたドキュメントです。公式ドキュメントを読めばわかることですが、よく使うパターンや注意点を事前にまとめておくことで、実装時の調査時間を大幅に削減できます。

02_supabase_auth_vitest.mdと03_supabase_storage_vitest.

Supabaseのテストに関するドキュメントです。Supabaseの認証やストレージ機能をテストする際、環境設定やモックの方法で詰まることが多かったので、それらの解決方法を事前にまとめました。

04_nextjs_app_router_patterns.md

Next.js App Routerの実装パターン集です。Server ComponentsとClient Componentsの使い分け、データフェッチングのパターン、エラーハンドリングなど、App Router特有の実装方法をまとめています。

CLAUDE.mdという司令塔ですべてを参照

これらすべてのドキュメントを統括するのが、CLAUDE.mdという特別なファイルで

このファイルは、AIエージェントが迷わないようにするための「司令塔」の役割を果たします。

Claude Code は常にこのファイルを読み込むので、ここから各ドキュメントへのリンクを参照することで、AIエージェントが必要な情報をすぐに取得できるようになっています。

長いので折りたたみにしておきますが、以下のような内容になっています。
（もちろん、これも Claude Code によって生成されました）

CLAUDE.mdの内容

# CLAUDE.md

このファイルは、Claude Code（claude.ai/code）がこのリポジトリで作業する際のガイダンスを提供します。

## プロジェクト概要

Appcadiaは個人開発者がアプリケーションを展示するためのWebプラットフォームです。コンセプトは「登録3分、マーケティング0分」- マーケティングの労力なしにSEOを通じてアプリが発見されるよう支援します。

## アーキテクチャ

このプロジェクトは**DDD（ドメイン駆動設計）とクリーンアーキテクチャ**に従います。

```
src/
├── app/                    # Next.js App Router（プレゼンテーション層）
│   ├── (auth)/            # 認証が必要なルート
│   ├── (public)/          # 公開ルート
│   └── api/               # APIルート
├── application/           # ユースケース
│   ├── usecases/
│   ├── dto/
│   └── ports/
├── domain/                # ビジネスロジック
│   ├── entities/
│   ├── value-objects/
│   ├── services/
│   └── repositories/      # リポジトリインターフェース
├── infrastructure/        # 外部実装
│   ├── repositories/      # Supabase実装
│   └── services/
├── components/            # UIコンポーネント
│   ├── ui/               # 基本コンポーネント（Shadcn UI）
│   ├── features/         # 機能別コンポーネント
│   └── layouts/
└── hooks/                # カスタムReactフック
```

### 主要な設計パターン

1. **リポジトリパターン**: インターフェースの背後でデータアクセスを抽象化
2. **ユースケースパターン**: 各ビジネス操作は個別のユースケース
3. **値オブジェクト**: バリデーションをカプセル化（例：Email、AppId、Slug）
4. **Server/Client コンポーネント分離**: パフォーマンスの最適化
5. **複合コンポーネント**: 複雑なUI用（Card.Header、Card.Bodyなど）

## 開発コマンド

```bash
# 開発（Turbopack使用）
npm run dev

# 品質チェック（コミット前に実行）- 並列実行
npm run check              # lint + format + type-check + 単体テスト
npm run check:all         # check + 統合テスト + ビルド

# 個別コマンド
npm run lint              # ESLint（自動修正付き）
npm run format            # Prettierフォーマット
npm run type-check        # TypeScript型チェック
npm run test              # Vitest単体テスト
npm run test:integration  # 統合テスト
npm run build             # プロダクションビルド

# E2Eテスト（低速、たまに実行）
npm run test:e2e          # PlaywrightでE2Eテスト実行
npm run test:e2e:ui       # UIモードでE2Eテスト実行
npm run test:all          # 全テスト実行（単体 + 統合 + E2E）

# パフォーマンス監視
npm run analyze           # バンドルサイズ分析
npm run lighthouse        # Lighthouseパフォーマンステスト
npm run performance:check # 完全なパフォーマンスチェック

# データベースコマンド（Supabase CLI必須）
npm run db:generate       # DBからTypeScript型を生成
npm run db:migrate        # データベースにマイグレーションを適用
npm run db:seed          # テストデータを投入
```

## テスト戦略

このプロジェクトは**TDD（テスト駆動開発）**と**ゼロ警告ポリシー**に従います。

```
__tests__/
├── unit/                 # 高速な単体テスト（ドメイン層90%カバレッジ目標）
├── integration/          # APIとリポジトリのテスト
└── fixtures/            # テストデータとモック
```

テストを先に書き、テスト実行中のコンソール警告/エラーをゼロにします。

## 環境セットアップ

1. `.env.example`を`.env.local`にコピー
2. Supabase認証情報を設定：
   ```env
   NEXT_PUBLIC_SUPABASE_URL=your_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_key
   SUPABASE_SERVICE_KEY=your_service_key
   ```
3. Supabaseをローカルにインストールして起動：
   ```bash
   npm install -g supabase
   supabase init
   supabase start
   ```

## コアビジネスエンティティ

- **App**: 開発者のアプリケーションを表すメインエンティティ
- **User**: アプリを作成する開発者
- **TechStack**: アプリで使用される技術
- **AppScreenshot**: アプリの視覚的表現
- **DeveloperLink**: ソーシャル/ポートフォリオリンク

## API設計

一貫したレスポンス形式のRESTfulエンドポイント：
```json
{
  "success": true,
  "data": { ... },
  "meta": { "timestamp": "..." }
}
```

エラーレスポンス：
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "ユーザーフレンドリーなメッセージ"
  }
}
```

## 重要な設計上の決定

1. **SEOファースト**: すべてのアプリ詳細ページは適切なメタタグでサーバーレンダリング必須
2. **最小限の登録**: アプリ登録に必要なフィールドは4つのみ（名前、URL、説明、技術スタック）
3. **型安全性**: `any`型を使用しない厳密なTypeScript
4. **エラーハンドリング**: `AppError`基底クラスを拡張した構造化エラークラス
5. **パフォーマンス**: 人気ページにはISR、その他には動的レンダリングを使用

## データベーススキーマ

Supabase（PostgreSQL）を使用し、以下の主要テーブルを持つ：

- `users`: 開発者アカウント
- `apps`: アプリケーションエントリ
- `tech_stacks`: 技術マスターデータ
- `app_tech_stacks`: 多対多の関係
- `app_screenshots`: アプリ画像
- `developer_links`: ソーシャルリンク

すべてのテーブルはUUID主キーを使用し、`created_at`、`updated_at`、および`deleted_at`によるソフトデリートを含みます。

## フロントエンドガイドライン

- デフォルトでServer Componentsを優先
- 必要な場合のみ`'use client'`を使用（フォーム、インタラクティブ性）
- 再利用性のためにジェネリックコンポーネント + アダプターパターンに従う
- スタイリングにはTailwind CSSとCVAを使用
- 適切なローディングとエラー状態を実装
- モバイルファーストのレスポンシブデザインを確保

## 避けるべき一般的な落とし穴

1. ServerとClient Components間でクラスインスタンスを渡さない（プレーンオブジェクトにシリアライズ）
2. `grep`や`find`コマンドを使わない - 代わりにGrep/Globツールを使用
3. ファイルを書く前に必ず存在を確認（WriteよりEditを優先）
4. コードをコミットする前に`npm run check`を実行
5. コンポーネントは小さく、単一責任に集中させる
6. Supabase Authテストでは、常に`jsdom`環境を使用（`node`ではない）
7. セッション汚染を防ぐためにサービスロールとユーザークライアントを分離
8. ライブラリ固有の問題は`.claude/03_library_docs/`を確認

## プロジェクトドキュメントガイド

プロジェクトには`.claude/`ディレクトリに包括的なドキュメントがあります。各ドキュメントをいつ参照すべきかを示します。

### 📋 プロジェクトコンセプトと要件
- **`.claude/00_project/01_appcadia_concept_requirements.md`** - ビジネス要件と機能仕様
- **`.claude/00_project/02_inception_deck.md`** - プロジェクトビジョンと目標
- **使用する場面**: ビジネスロジック、機能要件、またはプロジェクト目標の理解時

### 🏗️ 技術設計ドキュメント

#### システムアーキテクチャ
- **`.claude/01_development_docs/01_architecture_design.md`** - DDDとクリーンアーキテクチャの実装詳細
- **使用する場面**: レイヤーの責任の理解、新機能の追加、リファクタリング時

#### データベース設計
- **`.claude/01_development_docs/02_database_design.md`** - 完全なER図とテーブル定義
- **使用する場面**: データベースクエリの作業、新しいテーブル/カラムの追加、関係の理解時

#### API設計
- **`.claude/01_development_docs/03_api_design.md`** - RESTful APIエンドポイントと契約
- **使用する場面**: 新しいエンドポイントの実装、リクエスト/レスポンス形式の理解時

#### フロントエンド設計
- **`.claude/01_development_docs/04_screen_transition_design.md`** - 画面フローとUI構造
- **`.claude/01_development_docs/10_frontend_design.md`** - コンポーネントパターンとフロントエンドアーキテクチャ
- **使用する場面**: 新しいページの作成、UIコンポーネントの実装、ナビゲーションの理解時

#### SEO要件
- **`.claude/01_development_docs/05_seo_requirements.md`** - SEO最適化戦略
- **使用する場面**: SEOを考慮したページの実装、メタタグの作業時

#### エラーハンドリング
- **`.claude/01_development_docs/06_error_handling_design.md`** - エラーハンドリングパターンと戦略
- **使用する場面**: エラーハンドリングの実装、カスタムエラークラスの作成時

#### 型定義
- **`.claude/01_development_docs/07_type_definitions.md`** - TypeScript型システム設計
- **使用する場面**: 新しい型の作成、ドメインモデルの理解時

#### 開発セットアップ
- **`.claude/01_development_docs/08_development_setup.md`** - 環境セットアップと開発ワークフロー
- **使用する場面**: ローカル環境のセットアップ、開発コマンドの理解時

#### テスト戦略
- **`.claude/01_development_docs/09_test_strategy.md`** - TDDアプローチとテストパターン
- **使用する場面**: テストの作成、テスト構造の理解、TDDの実装時

#### CI/CD
- **`.claude/01_development_docs/11_cicd_design.md`** - GitHub Actionsとデプロイパイプライン
- **使用する場面**: CI/CDワークフローの変更、デプロイプロセスの理解時

#### E2Eテスト
- **`.claude/01_development_docs/12_e2e_test_design.md`** - E2Eテスト設計（Playwright、エラー監視、クリティカルパス）
- **使用する場面**: E2Eテスト実装、ブラウザテスト作成、エラー監視の設定時

#### セキュリティ
- **`.claude/01_development_docs/13_security_design.md`** - セキュリティ設計（認証、入力検証、ファイルアップロード）
- **使用する場面**: セキュリティ実装、認証・認可、ファイルアップロード機能の実装時

#### パフォーマンス
- **`.claude/01_development_docs/14_performance_optimization.md`** - パフォーマンス最適化（Core Web Vitals、画像最適化、キャッシュ戦略）
- **`.claude/01_development_docs/15_performance_monitoring.md`** - パフォーマンス計測・監視（Lighthouse、Web Vitals、プロセス管理）
- **使用する場面**: パフォーマンス改善、SEO対策、画像処理の実装時、継続的な監視体制の構築時

### 🎨 デザインシステム
- **`.claude/02_design_system/00_basic_design.md`** - デザインシステム概要とクイックスタート
- **`.claude/02_design_system/01_design_principles.md`** - デザイン原則、カラーシステム、タイポグラフィ
- **`.claude/02_design_system/02_component_design.md`** - Shadcn UIベースのコンポーネント設計
- **`.claude/02_design_system/02_layout_system.md`** - レイアウトシステムとグリッド設計
- **`.claude/02_design_system/03_animation_system.md`** - アニメーションパターンと実装
- **使用する場面**: UI実装、コンポーネント作成、スタイリング、アニメーション実装時

### 📚 ライブラリドキュメント
- **`.claude/03_library_docs/01_shadcn_doc.md`** - Shadcn UI全コンポーネントの完全ガイド
- **`.claude/03_library_docs/02_supabase_auth_vitest.md`** - Supabase認証のテスト方法（モック戦略、環境設定）
- **`.claude/03_library_docs/03_supabase_storage_vitest.md`** - Supabaseストレージのテスト方法（ファイルアップロード、権限テスト）
- **`.claude/03_library_docs/04_nextjs_app_router_patterns.md`** - Next.js App Routerパターン集（Server/Client Components、データフェッチング）
- **使用する場面**:
  - Shadcn UIコンポーネントの実装時
  - Supabase認証機能のテスト作成時
  - ファイルアップロード機能の実装・テスト時
  - Next.js App Router実装時、ルーティング設計時

### クイックリファレンスマップ

| タスク | 主要ドキュメント |
|------|------------------|
| 新機能の追加 | アーキテクチャ → データベース → API → フロントエンド設計 |
| 新しいAPIエンドポイントの作成 | API設計 → エラーハンドリング → 型定義 |
| データベース変更 | データベース設計 → 型定義 |
| UI実装 | フロントエンド設計 → デザインシステム → コンポーネント設計 |
| スタイリング・アニメーション | デザイン原則 → コンポーネント設計 → アニメーションシステム |
| Shadcn UIコンポーネント実装 | Shadcnドキュメント → コンポーネント設計 |
| テストの作成 | テスト戦略 → アーキテクチャ（レイヤー別） |
| 認証機能のテスト | テスト戦略 → Supabase Auth Vitest |
| ストレージ機能のテスト | テスト戦略 → Supabase Storage Vitest |
| E2Eテスト実装 | E2Eテスト設計 → テスト戦略 |
| セキュリティ実装 | セキュリティ設計 → Supabase Auth Vitest |
| パフォーマンス改善 | パフォーマンス最適化 → SEO要件 |
| パフォーマンス監視 | パフォーマンス監視 → パフォーマンス最適化 |
| App Router実装 | Next.js App Routerパターン → フロントエンド設計 |
| デプロイ/CI | CI/CD設計 → 開発セットアップ |
| エラーハンドリング | エラーハンドリング → 型定義 |
| SEO実装 | SEO要件 → パフォーマンス最適化 |

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

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

ドキュメント作成で得られた効果

Claude Code に書かせたとはいえ、これだけのドキュメントを作るのは正直大変でしたが、その効果は絶大でした。

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

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

さらに、将来の自分への投資にもなります。

数ヶ月後に機能追加する時、これらのドキュメントがあれば、当時の設計思想をすぐに思い出せますからね。

それは AI にとっても同じです。AIエージェントが過去の設計を参照できることで、プロジェクト全体の一貫性が保たれるわけです。

まとめ

Claude Codeでの個人開発を3つ経験して学んだことは、「AIエージェントは優秀だが、プロジェクト全体の一貫性を保つには人間の設計が必要」ということでした。

その答えが、今回の24個のドキュメント群です。
技術設計、デザインシステム、ライブラリ対策という3つの観点から、開発で必要になるであろうすべての決定事項を事前に文書化しました。

特に重要なのは、これらが机上の空論ではなく、実際の開発で痛い目を見た経験から生まれたということです。エラーハンドリングで悩んだから設計書を作り、ライブラリでハマったから対策ドキュメントを作る。そうやって積み上げてきたノウハウの集大成です。

このドキュメント達を元にこれから開発を進めていこうと思うので、またノウハウが溜まったら記事にしたいと思います。

実際に開発してみて「このドキュメントは要らなかった」「こういうドキュメントも必要だった」という発見があれば、それもお伝えしていきますね。

参考：作成中アプリの機能要件をまとめたドキュメント（コンセプトドキュメント）

今回のドキュメント準備とは直接関係ないのですが、これから作ろうとしている Appcadia というアプリのコンセプトをまとめたドキュメントも公開しておきます。

Next.js App Routerを使い、個人開発者が自分のアプリを簡単に公開できるプラットフォームを目指しています。

3日ぐらい Claude Opus と Deep Research を使って練りに練ったコンセプトドキュメントです。興味がある方はぜひご覧ください。

個人開発者の皆さん（自分を含め）に役立つアプリにしたいと思っているので、フィードバックも大歓迎です！

Appcadiaのコンセプトドキュメント

# Appcadia - 個人開発アプリ大全 - 機能要件書（完全版）

- App + Arcadia（理想郷）
- アプリの理想的な展示場所
- 個人開発者による個人開発者のための、アプリ情報共有プラットフォーム

## 1. サービス概要

### コンセプト
**「登録3分、マーケティング0分。良いアプリが、必要な人に届く場所。」**

個人開発者による個人開発者のための、アプリ情報共有プラットフォーム。作ったアプリの情報を登録するだけで、SEO効果により自然に見つけてもらえる。継続的な情報更新により、開発の記録を残しながら、お互いの学びになる場所。

### 背景
- 日本の個人開発者の70%以上がマーケティングを最大の課題として挙げている
- 「良いものを作れば売れる」という誤解から脱却できない開発者が多い
- 開発とマーケティングの時間配分が95%以上というデータも
- 80%の開発者が英語でのコミュニケーションに困難を感じ、Product Huntなどの海外サービスが使いづらい
- 既存の日本語プラットフォーム（Qiita、Zenn）はマーケティング支援機能が不足

### 目的
1. **マーケティング負担の軽減** - 登録するだけで継続的な露出を実現
2. **実践的な知識共有** - 技術選定、コスト、収益化の実例を通じた学び
3. **孤独感の解消** - 同じ悩みを持つ開発者との自然なつながり
4. **開発記録の蓄積** - 振り返りと成長の可視化

## 2. ターゲットユーザー（ペルソナ）

### プライマリペルソナ：エンジニアタイプ
- **属性**：20-30代、個人開発者、技術力はあるがマーケティング苦手
- **課題**：
  - マーケティングに苦手意識、自己宣伝が恥ずかしい
  - 開発は楽しいが、その後の集客で悩む
  - 収益化できるか分からず広告費を使えない
  - SNSでの継続的な発信が負担
- **ニーズ**：
  - 最小限の労力でアプリを知ってもらいたい
  - 他の開発者の成功・失敗事例から学びたい
  - 技術的な質問や相談ができる場が欲しい

### セカンダリペルソナ：学習者タイプ
- **属性**：個人開発を始めたい/始めたばかりの人
- **課題**：
  - 何を作るべきか分からない（アイデア枯渇）
  - 技術選定で迷う、コストが心配
  - 実際の開発プロセスが分からない
- **ニーズ**：
  - 実例を通じて学びたい
  - 現実的なコストや期間を知りたい
  - 経験者に質問したい

## 3. 機能要件

### 3.1 必須機能（MVP）

#### 1. ユーザー認証
- メールアドレス or GitHubアカウントでの登録/ログイン
- プロフィール作成（任意）
- ゲストでの登録も可能だが、編集できなくなるという制限あり

#### 2. アプリ登録時の入力項目一覧

## 🔴 必須項目（4項目のみ）

| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **アプリ名** | サービス名・プロダクト名 | テキスト入力 |
| **URL** | アプリURL、なければGitHub等でもOK | URL入力 |
| **一言説明** | 何をするアプリか（50文字以内） | テキスト入力 |
| **使用技術** | 技術スタック | タグ選択（複数可） |

## 🟡 任意項目

### ビジュアル
| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **アプリロゴ** | 正方形推奨 | 画像アップロード（1枚） |
| **スクリーンショット** | 使用画面、機能説明など | 画像アップロード（最大4枚） |

### アイデア・動機
| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **なぜ作ったか** | 開発の動機・きっかけ | テキストエリア |
| **誰のどんな課題を解決するか** | ターゲットユーザーと解決する問題 | テキストエリア |
| **競合・類似サービスとの違い** | 差別化ポイント | テキストエリア |

### 技術的な学び
| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **使ってよかった技術・ツール** | おすすめポイントも | テキストエリア |
| **今なら違う選択をする技術** | 後悔ポイントと理由 | テキストエリア |
| **一番苦労した実装と解決方法** | 技術的なつまずきと解決策 | テキストエリア |
| **参考にした記事・動画** | 役立ったリソース | URL入力（複数可） |

### 開発プロセス
| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **開発期間** | 企画〜リリースまで | 選択式（1週間以内/1ヶ月/3ヶ月/半年/1年以上） |
| **1日の作業時間** | 平均的な開発時間 | 選択式（1時間/2-3時間/4-5時間/8時間以上） |
| **開発の進め方** | スクラム、個人流など | テキスト入力 |

### コスト情報
| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **初期開発コスト** | ドメイン、素材購入など | 選択式（0円/〜1万円/〜5万円/〜10万円/それ以上） |
| **月額運用コスト** | サーバー代など | 選択式（0円/〜1000円/〜5000円/〜1万円/それ以上） |
| **使用している無料枠・節約テク** | コスト削減の工夫 | テキストエリア |

### 収益化情報
| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **収益化の有無** | 現在の状況 | 選択式（している/検討中/予定なし） |
| **収益モデル** | マネタイズ方法 | 選択式（広告/アプリ内課金/サブスク/買い切り/その他） |
| **月間収益** | おおよその金額 | 選択式（0円/〜1000円/〜1万円/〜10万円/それ以上/非公開） |
| **収益化までの期間** | リリースから初収益まで | 選択式（即日/1ヶ月/3ヶ月/半年/1年以上/まだ） |
| **収益化で工夫した点・失敗談** | 学びや教訓 | テキストエリア |

### 現状と成果
| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **現在のステータス** | アプリの状態 | 選択式（開発中/運用中/メンテナンスのみ/停止中） |
| **ユーザー数** | MAU、DAUなど | テキスト入力（非公開可） |
| **今後追加したい機能** | ロードマップ | テキストエリア |
| **もらって嬉しかったフィードバック** | ユーザーの声 | テキストエリア |

### 開発者情報
| 項目名 | 詳細 | 入力形式 |
|--------|------|----------|
| **開発者リンク** | SNSやブログなど | URL入力（種別選択付き） |
| | - Twitter/X | |
| | - GitHub | |
| | - 個人ブログ | |
| | - Qiita | |
| | - Zenn | |
| | - note | |
| | - YouTube | |
| | - その他 | |

## 入力設計のポイント

- **段階的な充実**：最初は必須4項目だけで公開し、後から情報を追加
- **選択式を多用**：自由記述の負担を減らし、データの統一性を確保
- **「非公開」オプション**：センシティブな情報は公開しない選択肢を用意
- **プレースホルダー**：記入例を表示して入力をサポート

#### 3. アプリ一覧・検索
- 新着順、更新順での一覧表示
- 技術タグでの絞り込み検索
- キーワード検索（アプリ名、説明文）
- 無限スクロール or ページネーション

#### 4. アプリ詳細ページ
- SEO最適化（構造化データ、OGP設定）
- レスポンシブデザイン
- シェアボタン（X、はてブ等）

## 4. 非機能要件

### 4.1 パフォーマンス
- ページ読み込み：3秒以内
- 画像最適化：自動リサイズ、WebP変換
- CDN活用：画像配信の高速化

### 4.2 SEO対策
- 技術キーワードを含むURL設計
- 構造化データの実装
- サイトマップ自動生成
- Core Web Vitalsの最適化

### 4.3 セキュリティ
- HTTPS必須
- XSS、CSRF対策
- 画像アップロードのバリデーション
- レート制限

### 4.4 ユーザビリティ
- モバイルファースト設計
- 直感的なUI（登録3分を実現）
- プログレッシブエンハンスメント
- アクセシビリティ対応

## 5. 技術仕様

### 基本構成
- **フロントエンド**: Next.js 15 (App Router)、TypeScript、Tailwind CSS, Shadcn UI
- **バックエンド**: Next.js API Routes
- **データベース**: Supabase（PostgreSQL）ローカルは Supabase CLI にて検証
- **認証**: Supabase Auth
- **ストレージ**: Supabase Storage（画像）
- **ホスティング**: Vercel
- **その他**:
  - 画像最適化：Next.js Image Optimization
  - SEO：next-seo
  - フォーム：react-hook-form
  - バリデーション：zod
  - テスト: Vitest, Testing Library（+ 統合テスト）
  - Lint: ESLint, Prettier

## 7. 差別化要因

1. **日本語×個人開発×アプリ特化** - 既存サービスにない組み合わせ
2. **登録の手軽さ** - 3分で完了、その後は任意更新
3. **SEO効果** - 技術キーワードでの自然流入
4. **実践的な情報** - 収益、コスト、失敗談まで共有
5. **段階的な情報開示** - 最初は最小限、徐々に充実

## 99. その他

以下、アイデアとしては出たけれども技術的難易度や実装工数が高いため、MVPでは実装しない機能。
メモとして残しておく。

### 3.2 補助的機能（将来実装）

#### 5. Q&A機能
- アプリごとの質問投稿
- 開発者による回答
- ベストアンサー機能
- 質問の検索・タグ付け

#### 6. 開発ストーリー（タイムライン）
- 時系列での更新情報投稿
- 振り返り記事（1週間後、1ヶ月後等）
- バージョンアップ情報

#### 7. 類似アプリ・レコメンド
- 同じ技術スタックのアプリ表示
- 「このアプリを見た人は」機能
- AIによる週間ピックアップ

#### 8. コスト分析
- 技術スタック別の平均コスト
- 無料運用可能なアプリ特集
- コスト削減テクニック共有

#### 9. 開発者ダッシュボード
- 複数アプリの一括管理
- アクセス解析（PV、検索流入キーワード）
- Q&Aの通知管理

#### 10. コミュニティ機能
- 月次振り返り会（オンライン）
- 技術別の情報交換スペース
- もくもく会の開催情報

Claude Code の関連記事

他にも Claude Code や AI 駆動開発の記事を書いていますので、よかったらこちらもご覧ください。

ちょっと宣伝： Claude Code などの Udemy コース作ってます

Claude Code での Vibe Coding や Next.js、Ruby on Rails などの Udemy コースを開講しており、ありがたいことに複数のベストセラーをいただいてます。

自社サイトでは最低価格で受講できるクーポンも配布しているので、よかったら見てやってください。

ご意見や、新講座の要望も大歓迎です！