こんにちは、とまだです。
みなさん、Claude Codeで開発していて「設計ドキュメントの準備が大変」と思ったことはありませんか？
前回の記事では24種類のドキュメントを手動で準備する方法を紹介しました。
今回は、その続編としてカスタムコマンド一つで必要なドキュメントをすべて自動生成する方法をご紹介します。
しかも、既存のコードを分析して最適なドキュメントを作成。
そして自動でCLAUDE.mdから参照可能にしてくれるんです。
忙しい人のために要約
-
/create-project-docsコマンド一つで全ドキュメント生成 - プロジェクトを分析して必要なドキュメントだけ作成
- 既存ファイルは最新化、新規は自動作成
- CLAUDE.mdに自動で参照リンクを追加
なぜカスタムコマンドが必要だったのか
前回の記事を書いた後、大変多くの方に読んでいただき反響をいただきました！
ただ、自分で改めて読むと「これを再現しようと思うと大変＆メンテもしんどいのでは？」と思い直しました。
24個のドキュメントを作るのは、AI に指示を出して作ったとしても時間がかかります。
しかも、プロジェクトによっては不要なドキュメントもあるでしょう。
たとえば、E2Eテストを導入していないプロジェクトなら、E2Eテスト設計書は要りません。
データベースを使わないプロジェクトなら、DB設計書も不要です。
そこで考えたのが、プロジェクトの状態を自動で判断して、必要なドキュメントだけを生成する仕組みです。
カスタムコマンドの仕組み
Claude Codeには、カスタムコマンドという機能があります。
.claude/commands/ディレクトリにMarkdownファイルを置くと、スラッシュコマンドとして使えるようになるんです。
今回作成したcreate-project-docs.mdは、以下の流れで動作します。
1. プロジェクト分析フェーズ
まず、既存のコードベースを分析します。
- package.json から技術スタックを特定
- ディレクトリ構造からアーキテクチャを推定
- 実装済み機能（認証、DB、テスト等）を検出
- 使用ライブラリとフレームワークを確認
たとえば、schema.prismaがあればデータベースを使っていると判断。
.github/workflows/があればCI/CDを設定していると判断。
このように、ファイルの存在から実装状況を推測していきます。
2. ドキュメント生成フェーズ
分析結果に基づいて、必要なドキュメントを生成します。
必ず作成されるドキュメント
.claude/00_project/
├── project_concept_requirements.md
└── inception_deck.md
.claude/01_development_docs/
├── architecture_design.md
├── development_setup.md
└── type_definitions.md（TypeScriptの場合）
これらは、どんなプロジェクトでも必要な基本ドキュメントです。
条件付きで作成されるドキュメント
実装が確認できた場合のみ作成されます。
- database_design.md → Prisma/Sequelize等があれば
- api_design.md → APIルートがあれば
- test_strategy.md → テストファイルがあれば
- cicd_design.md → ワークフローファイルがあれば
無駄なドキュメントは作らない。
これが重要なポイントです。
3. CLAUDE.md更新フェーズ
最後に、生成したドキュメントへのリンクをCLAUDE.mdに追加します。
## プロジェクト設計ドキュメント
### 📋 プロジェクト要件
- `.claude/00_project/project_concept_requirements.md`
- `.claude/00_project/inception_deck.md`
### 🏗️ 技術設計ドキュメント
（実際に生成されたファイルのリスト）
### クイックリファレンスマップ
| タスク | 主要ドキュメント |
|------|----------------|
| 新機能の追加 | アーキテクチャ → DB → API → フロントエンド |
| APIエンドポイント作成 | API設計 → エラーハンドリング → 型定義 |
Claude Codeがドキュメントを参照する際、このマップがあれば効率的に情報を見つけられます。
実際に使ってみた
では、実際にコマンドを実行してみましょう。
.claude/commands/create-project-docs.md ファイルを配置した後は、Claude Code を起動してから以下のコマンドを実行します。
/create-project-docs
これだけでOKです！
私の環境だと、以下のように生成がスタートしました。
> /create-project-docs is running…
⏺ プロジェクト設計ドキュメントの自動生成を開始します。まずはプロジ
ェクトの現状を分析し、適切なドキュメントを生成します。
⏺ Update Todos
⎿ ☐ プロジェクト構造とパッケージ設定を分析
☐ 技術スタックと実装済み機能を特定
☐ 必須ドキュメント（プロジェクト概要、アーキテクチャ）を生成
☐ 条件付きドキュメント（DB、API、テスト等）を生成
☐ デザインシステムドキュメントを生成
☐ ライブラリ固有ドキュメントを生成
☐ CLAUDE.mdにドキュメント一覧を追記
すべて新規作成だと、10分以上かかるかもしれません。
生成されたドキュメントの品質
気になるのは、自動生成されたドキュメントの品質ですよね。
実際に生成されたarchitecture_design.mdの一部を見てみましょう。
# アーキテクチャ設計
## システム全体像
Learning Nextは、Next.js 15 App Routerを基盤としたモノリシック・アーキテクチャを採用。外部サービス（Clerk、Supabase、Gemini API）との連携により、スケーラブルな教育プラットフォームを構築している。
## アーキテクチャパターン
### 1. ヘキサゴナルアーキテクチャの影響
コアビジネスロジックを中心に据え、外部依存を抽象化したレイヤード設計を採用。
```
┌─────────────────┐ ┌─────────────────┐
│ UI Layer │ │ External APIs │
│ (Components) │ │ (Clerk/Gemini) │
└─────────────────┘ └─────────────────┘
│ │
┌─────────────────────────────────────────┐
│ Application Layer │
│ (API Routes / Server Actions) │
└─────────────────────────────────────────┘
│ │
┌─────────────────┐ ┌─────────────────┐
│ Business Logic │ │ Data Access │
│ (lib/) │ │ (Supabase) │
└─────────────────┘ └─────────────────┘
```
### 2. レイヤー構成
#### プレゼンテーション層
- **Server Components**: デフォルトでサーバーサイドレンダリング
- **Client Components**: インタラクションが必要な箇所のみ
- **UI Components**: 再利用可能なCatalyst UIベース
#### アプリケーション層
- **API Routes**: Edge Runtime優先のRESTful API
- **Server Actions**: フォーム処理・データ変更操作
- **Middleware**: 認証・ルーティング制御
#### ビジネスロジック層
- **Domain Models**: TypeScript型定義 + バリデーション
- **Use Cases**: 複雑なビジネスルール実装
- **Utilities**: 汎用ヘルパー関数
#### データアクセス層
- **Supabase Client**: RLS有効なPostgreSQL接続
- **Static Data**: ビルド時生成のクイズ・コンテンツ
- **Cache Layer**: 階層化されたキャッシング戦略
## ディレクトリ構造
```
src/
├── app/ # Next.js App Router
...
実際のコードを分析しているため、現実に即した内容になっています！
そのため、既に動いているプロジェクトにも導入しやすいというメリットがあります。
既存ファイルの更新機能
さらに便利なのが、既存ファイルの更新機能です。
たとえば、最初に手動で作成したドキュメントがあったとします。
その後、新しいライブラリを追加したり、ディレクトリ構造を変更したり。
そんなときも、コマンドを再実行すれば最新の状態に更新してくれます。
> /create-project-docs
⏺ 既存ドキュメントの更新確認中...
⚠ architecture_design.md - 更新が必要
⚠ database_design.md - 新しいモデル検出
⏺ ドキュメントを更新中...
✓ 新しいAPIエンドポイントを追加
✓ Userモデルのフィールド変更を反映
ドキュメントを一回作ったあとって、更新が面倒なんですよねえ...
ですが、それもカスタムコマンドを一発、週1や月1で叩くだけでOKです！
カスタムコマンドのカスタマイズ
このコマンドは、プロジェクトの特性に応じてカスタマイズも可能です。
たとえば、独自のドキュメントを追加したい場合。
.claude/commands/create-project-docs.mdを編集して、生成ルールを追加できます。
### 条件付き作成（カスタム追加）
- mobile_design.md → React Nativeの設定があれば生成
- blockchain_design.md → Web3ライブラリがあれば生成
- ml_pipeline.md → TensorFlow/PyTorchがあれば生成
プロジェクトの特性に応じて、柔軟に対応できるわけです。
導入のメリット
このカスタムコマンドを導入して感じたメリットは3つあります。
1. 開発開始の高速化
新規プロジェクトでも、既存プロジェクトでも。
コマンド一つでドキュメント環境が整います。
「さあ、開発を始めよう」と思ったときに、同時にドキュメントをサクッと整備できるので、AI駆動開発もスムーズになるはずです。
2. 一貫性の維持
Claude Codeとの対話で、常に同じドキュメントを参照できます。
「データベース設計はdatabase_design.mdを見て」と伝えるだけ。
プロジェクト全体で統一された実装が可能になります。
3. 知識の蓄積
開発が進むにつれて、ドキュメントも成長していきます。
私は個人開発でまずは試しましたが、チーム開発の場面でも役立つはずです。
後から参加したメンバーや、将来の自分にとって良い参考資料になると思います。
まとめ
Claude Codeでの開発を効率化するカスタムコマンドをご紹介しました。
コマンド一つで必要なドキュメントがすべて生成される。
しかも、プロジェクトの実態に即した内容で。
細かい指示を Claude Code に出す必要はありません。
/create-project-docsと打つだけで、開発環境が整います。
ぜひ、みなさんのプロジェクトでも試してみてください！
カスタムコマンドの作り方や、ドキュメント生成のカスタマイズについて質問があれば、コメントでお知らせください。
X（Twitter）でも開発の様子を発信しています。
Claude Code の関連記事
他にも Claude Code や AI 駆動開発の記事を書いていますので、よかったらこちらもご覧ください。