Claude Code: プロジェクト初期化と構造
最終更新:2026-08-31
Claude Code はプロジェクトに入ると自動的にプロジェクト構造を分析しますが、CLAUDE.md を通じて積極的にガイドすることもできます。
💡 ヒント: プロジェクト初期化は Claude Code がファイルを読み取るだけでなく、「暗黙の規約」— コーディングスタイル、ディレクトリ規範、テスト戦略などをどう理解するかです。CLAUDE.md はこれらの規約の明示的な担い手です。
📋 前提条件: 第5章 - VS Code と JetBrains 統合
1. 学ぶ内容
- Claude Code がプロジェクト構造を理解する方法
- 異なるフレームワークプロジェクトの初期化機能
- CLAUDE.md の役割と自動生成
- コンテキストウィンドウとプロジェクトサイズ
- 大規模プロジェクトの最適化戦略
2. Claude Code がプロジェクトを理解する仕組み
(1) 自動分析フロー
graph TB
A[プロジェクトディレクトリに入る] --> B[CLAUDE.md を読み取り]
B --> C[ディレクトリ構造をスキャン]
C --> D[フレームワーク/言語を特定]
D --> E[主要設定ファイルを読み取り]
E --> F[コンテキストを構築]
| ステップ | 読み取るファイル | 目的 |
|---|---|---|
| CLAUDE.md | ルート CLAUDE.md | プロジェクトの規約と指示を取得 |
| 設定ファイル | package.json、pom.xml、go.mod 等 | 技術スタックと依存関係を特定 |
| ディレクトリ構造 | src/、lib/、tests/ 等 | コード構成を理解 |
| README | README.md | プロジェクト概要を取得 |
(2) 認識される技術スタック
| 設定ファイル | 認識 | 自動動作 |
|---|---|---|
package.json |
Node.js プロジェクト | npm/yarn/pnpm を使用 |
pom.xml |
Java Maven | mvn コマンドを使用 |
go.mod |
Go プロジェクト | go コマンドを使用 |
requirements.txt |
Python プロジェクト | pip/pytest を使用 |
▶ 例1:プロジェクト分析の出力
TEXT
📖 参照専用
$ claude
╭─ Claude Code ──────────────────────────────╮
│ Project Analysis: │
│ Type: Node.js / TypeScript │
│ Framework: Express.js │
│ Test: Jest │
│ Package: npm │
│ Structure: │
│ src/ │
│ routes/ (12 route files) │
│ models/ (8 model files) │
│ middleware/ (4 files) │
│ utils/ (6 utility files) │
│ tests/ │
│ config/ │
│ Key deps: express, mongoose, jest │
╰─────────────────────────────────────────────╯
3. CLAUDE.md プロジェクト設定
(1) CLAUDE.md の自動生成
BASH
# Claude Code にプロジェクトを分析させて CLAUDE.md を生成
claude /init
(2) CLAUDE.md の手動作成
MARKDOWN
# CLAUDE.md
## Project Overview
Eコマース管理システム、Express + TypeScript + Prisma 使用
## Tech Stack
- Runtime: Node.js 20
- Framework: Express 4.x
- ORM: Prisma 5.x
- Test: Vitest
- Lint: ESLint + Prettier
## Common Commands
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
## Code Conventions
- ES Module 構文を使用
- すべての API レスポンスは統一フォーマット { code, data, message } を使用
- エラー処理はカスタム AppError クラスを使用
- ルートファイルは src/routes/ に配置
- 各ルートファイルに対応するテストファイルを作成
## Don'ts
- var は使用せず、const/let のみ使用
- mongoose を直接使用せず、Prisma を使用
- 明示的に要求されない限り prisma/schema.prisma を修正しない
▶ 例2:異なるプロジェクトの CLAUDE.md
MARKDOWN
<!-- Go プロジェクト CLAUDE.md -->
# CLAUDE.md
## Project
RESTful API サービス、Go 1.22 + Gin + GORM
## Commands
- Run: `go run ./cmd/server`
- Test: `go test ./...`
- Build: `go build -o bin/server ./cmd/server`
## Conventions
- 標準プロジェクトレイアウト(cmd/、internal/、pkg/)を使用
- エラーリターンは pkg/errors パッケージを使用
- すべてのハンドラは gin.Context を受け取る
- データベース操作は repository レイヤーのみ
4. プロジェクト構造のベストプラクティス
(1) Claude Code に優しい構造
| 特徴 | 優しい | 優しくない |
|---|---|---|
| ディレクトリの深さ | 3-4階層、明確な命名 | 10階層以上のネスト |
| ファイル命名 | 一貫した命名規則 | 恣意的な命名 |
| 設定ファイル | 標準的な場所 | 散在 |
| テストの場所 | 集中または隣接 | テストなし |
| ドキュメント | README + CLAUDE.md | ドキュメントなし |
5. マルチ言語/マルチモジュールプロジェクト
(1) Monorepo サポート
TEXT
📖 参照専用
my-monorepo/
├── CLAUDE.md # グローバル設定
├── packages/
│ ├── frontend/
│ │ └── CLAUDE.md # フロントエンドサブプロジェクト設定
│ ├── backend/
│ │ └── CLAUDE.md # バックエンドサブプロジェクト設定
│ └── shared/
│ └── CLAUDE.md # 共有ライブラリ設定
(2) サブディレクトリの独立設定
BASH
# 異なるサブディレクトリで Claude Code を起動すると対応する CLAUDE.md を読み取る
cd packages/frontend && claude # frontend/CLAUDE.md を読み取り
cd packages/backend && claude # backend/CLAUDE.md を読み取り
6. 総合例:完全なプロジェクト初期化
BASH
# Alice の完全なプロジェクト初期化
# 1. プロジェクトを作成
mkdir ecommerce-api && cd ecommerce-api
npm init -y
# 2. git を初期化
git init
# 3. Claude Code を起動してプロジェクトスケルトンを生成
claude "Initialize an Express + TypeScript project:
1. Configure tsconfig.json
2. Set up ESLint + Prettier
3. Create src/ directory structure (routes, controllers, models, middleware, utils)
4. Configure Jest testing
5. Create .gitignore
6. Generate CLAUDE.md"
# 4. 生成された CLAUDE.md を確認
cat CLAUDE.md
# 5. 必要に応じて CLAUDE.md を調整
# 6. 初期状態をコミット
git add -A && git commit -m "feat: project initialization"
❓ よくある質問
Q CLAUDE.md と README.md の違いは?
A README は人間向けのプロジェクト説明です。CLAUDE.md は Claude Code 向けの作業指示です。CLAUDE.md はコーディング規約、共通コマンド、制約により焦点を当てます。
Q プロジェクトが大きすぎて Claude Code がすべてを読み取れない場合は?
A Claude Code はすべてを読み込むのではなく、重要なファイルをインテリジェントに選択します。CLAUDE.md で作業範囲を指定してコンテキスト消費を減らすこともできます。
Q CLAUDE.md はルートディレクトリになければなりませんか?
A ルートの CLAUDE.md はグローバル設定です。サブディレクトリにも CLAUDE.md を配置でき、Claude Code はそれらをマージします。
Q CLAUDE.md を git にコミットすべきですか?
A 推奨します。チームで共有するプロジェクト規約は個人の設定よりも価値があります。機密情報は CLAUDE.md に書かないでください。
Q /init で生成された CLAUDE.md が不正確な場合は?
A 手動で編集してください。/init は補助に過ぎません。CLAUDE.md の正確性には人間の確認と調整が必要です。
Q Monorepo のすべてのパッケージに CLAUDE.md が必要ですか?
A 必須ではありません。パッケージが類似している場合はルートの CLAUDE.md 1つで十分です。大きく異なる場合は個別設定を推奨します。
📖 まとめ
- Claude Code はプロジェクト構造を自動分析し、技術スタックを特定
- CLAUDE.md はプロジェクト規約の明示的な担い手。
/initで自動生成可能 - Claude Code に優しいプロジェクト:明確なディレクトリ、一貫した命名、標準的な設定
- 大規模プロジェクトは CLAUDE.md で作業範囲を制限し Token 消費を削減
- Monorepo はマルチレベル CLAUDE.md 設定をサポート
📝 練習問題
- 基本 (⭐): 既存のプロジェクトで
claude /initを実行し、生成された CLAUDE.md が正確か確認してください。 - 応用 (⭐⭐): プロジェクト規約、共通コマンド、制約を含む完全な CLAUDE.md を手動で作成してください。
- 高度 (⭐⭐⭐): Monorepo 向けにマルチレベル CLAUDE.md 設計を行い、各サブプロジェクトが独立して動作できるようにしてください。