大規模プロジェクトでのClaude Code活用戦略

大規模プロジェクト向けCLAUDE.mdテンプレート

# CLAUDE.md

## プロジェクト概要
- 名前: ECサイト管理システム
- 技術スタック: Laravel 11 + Vue 3 + MySQL
- アーキテクチャ: クリーンアーキテクチャ（Domain/UseCase/Infrastructure/Presentation）

## ディレクトリ構成（重要な部分のみ）
```
app/
├── Domain/          # ビジネスロジック（エンティティ、値オブジェクト、リポジトリI/F）
├── UseCase/         # ユースケース（アプリケーションサービス）
├── Infrastructure/  # 外部連携（DB実装、API、メール）
└── Presentation/    # UI層（コントローラー、リクエスト、リソース）
```

## コーディング規約
- PSR-12準拠
- リポジトリパターンでDB層を抽象化
- ユースケースは必ずCommand/Queryパターン
- テストは各UseCase単位で記述

## 主要モジュール
- 商品管理: app/Domain/Product/
- 注文管理: app/Domain/Order/
- ユーザー管理: app/Domain/User/
- 決済: app/Infrastructure/Payment/

## よくある作業パターン
- 新機能追加: Domain → UseCase → Infrastructure → Presentation の順で実装
- バグ修正: テストで再現 → 修正 → テスト確認

# 悪い例：曖昧な参照
「商品の在庫管理を修正して」

# 良い例：具体的なファイルパスとコンテキスト
「app/Domain/Product/StockService.phpのdecrement()メソッドを修正してください。
関連ファイル：
- app/Domain/Product/Stock.php（在庫エンティティ）
- app/UseCase/Order/PlaceOrderUseCase.php（呼び出し元）
- tests/Unit/Domain/Product/StockServiceTest.php（テスト）
問題：在庫が0未満になるケースがある。」

サブエージェントが有効なケース

• 複数ファイルの調査：「このインターフェースを実装しているクラスをすべて見つけて」
• パターン適用：「すべてのコントローラーにCSRFチェックを追加して」
• テスト生成：「app/UseCase/配下の全ファイルにテストを生成して」
• コードレビュー：「直近のコミットの変更をレビューして」

大規模プロジェクト向け除外パターン

# .gitignore（基本の除外）
node_modules/
vendor/
dist/
build/
*.log
.env
*.sqlite

# Claude Code向け追加除外
# （.claudeignoreまたはプロンプトで指定）
docs/api-reference/     # 大量の自動生成ドキュメント
storage/                # ストレージディレクトリ
public/assets/          # コンパイル済みアセット
database/seeders/data/  # 大量のシードデータ
tests/fixtures/         # 大きなテストフィクスチャ

プロジェクト規模: 500ファイル、5万行

成果：各セッション15〜20分、合計1.5時間で実装完了。コンテキストオーバーフローなし。

プロジェクト規模: 300ファイル、コーディング規約なし

戦略：CLAUDE.mdに「現在のコード品質」と「目標の品質」を記載し、ファイル単位でリファクタリング

# CLAUDE.mdに記載した内容
## リファクタリング方針
- 現状：生のSQLクエリ、グローバル変数、関数ベース
- 目標：PDOプリペアドステートメント、クラスベース、PSR-4
- 手順：1ファイルずつ変換、テスト追加、動作確認
- 優先順位：1)セキュリティ問題 2)保守性 3)パフォーマンス

成果：1日10〜15ファイルのペースでリファクタリング。各ファイルを独立したセッションで処理し、CLAUDE.mdのチェックリストで進捗を管理。