こんにちは、松山です。
Claude Codeとの対話テクニックをマスターした後、実際のプロジェクトで新たな問題に直面する方が多いです：
「プロジェクトに200個のファイルがあるけど、AIが全体アーキテクチャを理解できるわけない」
「機能を修正させたら、他のモジュールの依存関係を壊してしまった…」
「毎回プロジェクト構造を説明し直すのが面倒！」
今日は、この重要な問題を解決します：AIにプロジェクトのコンテキストを効率的に理解させる方法。
なぜコンテキスト管理が重要なのか？
実際の失敗ケース
シナリオ： ECプロジェクトにクーポン機能を追加
間違ったやり方：
あなた：クーポン機能を追加して
Claude：[coupon.pyを作成したが...]
- 既存のプロモーションシステムを考慮していない
- 計算ロジックが注文モジュールと競合
- データベース設計が既存テーブルと互換性がない
結果：2時間かけてデバッグして競合を解決正しいやり方：
あなた：クーポン機能を追加したい。まず既存のアーキテクチャを理解して：
1. models/ディレクトリの注文とプロモーション関連モデルを確認
2. services/pricing.pyの価格計算ロジックを見る
3. 既存の割引処理方法を理解する
Claude：[分析後]
気づいたこと：
- すでにPromotionモデルが値引きキャンペーンに使用されている
- pricing.pyのcalculate_final_price関数が統一エントリーポイント
- 割引はdiscount_rulesテーブルで設定されている
提案：クーポンをdiscount_rulesの一種として、
既存の価格計算フローを再利用すれば、既存ロジックを壊さない。
結果：30分で完了、競合ゼロ違いは何？
AIにまず現状を理解させて、闇雲に行動させない。
プロジェクト構造の効果的な提示
テクニック1：READMEから始める
ベストプラクティス：
あなた：まずREADME.mdとdocs/ARCHITECTURE.mdを読んで、
プロジェクトの全体アーキテクチャと技術スタックを理解して
Claude：[読み取り後]
了解しました。これはFlaskベースのマイクロサービスプロジェクトですね：
- PostgreSQLデータベースを使用
- Redisでキャッシュ
- Celeryで非同期タスク処理
- レイヤーアーキテクチャ採用：routes -> services -> models
どの機能を追加しますか？ドキュメントがない場合は？
あなた：プロジェクトにアーキテクチャドキュメントがまだない。以下をやって：
1. プロジェクトのディレクトリ構造を分析
2. 主要なモジュールと依存関係を識別
3. シンプルなアーキテクチャ説明を生成
Claude：[分析レポートを生成]テクニック2：プロジェクトナビゲーションテンプレートを使用
.claude/context.mdファイルを作成（オプション）：
# プロジェクトコンテキストクイックリファレンス
## 技術スタック
- バックエンド：Python 3.11 + FastAPI
- データベース：PostgreSQL 14 + SQLAlchemy
- キャッシュ：Redis
- タスクキュー：Celery
## ディレクトリ構造
- `src/api/`：APIエンドポイント定義
- `src/models/`：データモデル
- `src/services/`：ビジネスロジック
- `src/utils/`：ユーティリティ関数
- `tests/`：テストコード
## 重要な規約
- すべてのAPIはJWT認証が必要（/authパスを除く）
- エラーはApiExceptionで統一処理
- データベース操作はservice層で行い、route層で直接アクセスしない
## 重要ファイル
- `src/core/config.py`：設定管理
- `src/core/dependencies.py`：依存性注入
- `src/core/security.py`：認証関連
## 一般的なタスク
- 新しいAPI追加：`src/api/users.py`を参考
- 新しいモデル追加：`src/models/user.py`を参考
- テスト作成：`tests/api/test_users.py`を参考使用時：
あなた：まず.claude/context.mdを読んでプロジェクト規範を理解してから、
商品管理APIを追加して
Claude：プロジェクト規範を理解しました。以下を行います：
- src/api/にproducts.pyを作成
- src/services/にproduct_service.pyを作成
- src/models/にproduct.pyを作成
- JWT認証とApiException規範に従う
- users.pyのコードスタイルを参考テクニック3：段階的なコンテキスト構築
シナリオ： 既存プロジェクトに新機能を追加
ステップバイステップガイド：
# Step 1：全体像を理解
あなた：まずsrc/ディレクトリ構造を確認して、プロジェクトの主要モジュールを教えて
Claude：プロジェクトには以下のモジュールが含まれます：
- auth：認証・認可
- users：ユーザー管理
- orders：注文処理
- payments：決済統合
- notifications：通知サービス
# Step 2：関連モジュールに焦点
あなた：注文モジュールに返金機能を追加したい。
まずsrc/orders/とsrc/payments/の構造を確認して、
既存の注文と決済フローを理解して
Claude：[分析後、現在のフローを提示]
# Step 3：依存関係を識別
あなた：返金には決済インターフェースの呼び出しと通知送信が必要。
paymentsとnotificationsモジュールの呼び出し方を確認して
Claude：了解しました。以下を確認：
- paymentsにrefund_paymentメソッドがある
- notificationsはCeleryで非同期送信
これらの既存機能を再利用します
# Step 4：実装
あなた：いいね、返金機能の実装を開始して
Claude：[既存パターンに従って実装]既存コードベースを説明するテクニック
テクニック4：比喩と類推を使用
良くない説明：
user serviceとauth serviceがあります良い説明：
アーキテクチャはDjangoの設計に似ています：
- models/：Djangoのmodelsに相当
- serializers/：Django REST frameworkのserializersに類似
- views/：Djangoのviewsに対応
- services/：独自に追加したビジネスロジック層
Djangoに慣れていれば、このプロジェクトはすぐ理解できるはずテクニック5：特別な規約を指摘
あなた：プロジェクトにいくつか特別な規約があるので注意：
1. すべての時刻はUTCで保存、表示時にタイムゾーン変換
2. 論理削除：レコードを実際に削除せず、deleted_atを設定
3. IDはUUIDを使用、自動採番の整数ではない
4. 金額は整数で保存（単位：セント）、浮動小数点誤差を回避
注文モジュールを追加するので、これらの規約に従って
Claude：了解しました。以下のようにします：
- 時刻フィールドはdatetime(timezone=True)
- deleted_atフィールドと論理削除メソッドを追加
- idフィールドはUUID型
- 金額フィールドはInteger型（例：amount_cents）テクニック6：参考ファイルを提供
シナリオ： 新しいAPIエンドポイントを追加
あなた：src/api/v1/users.pyのパターンを参考に、
新しいproducts APIを追加。
ポイント：
- 同じルーティングデコレーターを使用
- 同じページネーションロジックを再利用
- エラー処理方法を統一
- レスポンス形式を統一
Claude：users.pyを確認しました。以下を維持します：
- @router.get/postデコレーターを使用
- ページネーションはPaginationParams依存を使用
- 例外はHTTPExceptionを使用
- {"data": ..., "message": "success"}形式で返す依存関係の説明
テクニック7：依存関係図を描く（テキスト版）
あなた：モジュール依存関係を理解して：
routes（API層）
↓ 呼び出し
services（ビジネスロジック層）
↓ 呼び出し
repositories（データアクセス層）
↓ 操作
models（データモデル）
横方向も：
- servicesは他のservicesを呼び出せる
- すべてutils/のユーティリティ関数を呼び出せる
- 下位層が上位層を呼び出すのは禁止（例：repositoryはserviceを呼び出せない）
商品在庫管理を追加するので、この階層化に従って
Claude：階層アーキテクチャを理解しました。以下を作成します：
- routes/products.py（HTTPリクエスト処理）
- services/inventory_service.py（在庫ビジネスロジック）
- repositories/inventory_repository.py（データベース操作）
- models/inventory.py（データモデル）テクニック8：データフローを説明
あなた：ユーザー注文のデータフロー：
1. POST /api/orders → routes/orders.py
2. OrderService.create_order() → 注文作成
3. InventoryService.reserve_stock() → 在庫ロック
4. PaymentService.create_payment() → 決済作成
5. 決済失敗時 → 在庫ロールバック
6. 成功後 → 確認メール送信（非同期）
注文キャンセル機能を追加するので、在庫解放と返金処理をしっかり
Claude：フローを理解しました。注文キャンセルには：
1. 注文ステータスを確認（未発送のみキャンセル可）
2. PaymentService.refund()で返金
3. InventoryService.release_stock()で在庫解放
4. 注文ステータスをCANCELLEDに更新
5. キャンセル通知を非同期送信
トランザクションでアトミック性を確保する必要がありますね？実践：既存プロジェクトでClaude Codeを使用
完全なケース：ブログシステムにコメント機能を追加
背景：
- プロジェクト：Flaskブログシステム
- 要件：記事コメント機能を追加
- 既存：ユーザーシステム、記事システム
Step 1：AIにプロジェクトを理解させる
あなた：これはFlaskブログプロジェクトです。まず以下を実行：
1. README.mdを読む
2. app/models/下の既存モデルを確認
3. app/routes/下のルート構造を確認
4. app/templates/下のテンプレート構成を理解
読み終わったら理解したことを教えて
Claude：プロジェクト構造を理解しました：
技術スタック：
- Flask 2.3 + SQLAlchemy
- Jinja2テンプレート
- Flask-Loginで認証
既存モデル：
- User：ユーザー（id, username, email, password_hash）
- Post：記事（id, title, content, author_id, created_at）
ルート構造：
- auth.py：ログイン・登録
- main.py：トップページ、記事一覧
- post.py：記事詳細、作成、編集
テンプレート継承：
- base.html：基本テンプレート
- 他のテンプレートはbase.htmlを継承
準備完了です。コメント機能の要件を教えてくださいStep 2：要件を詳しく説明
あなた：コメント機能の要件：
1. ログインユーザーが記事にコメント可能
2. コメント者名と時刻を表示
3. 記事詳細ページに全コメントを表示
4. コメントは時刻の降順に並べる
5. 著者は自分の記事の任意のコメントを削除可能
6. コメント者は自分のコメントを削除可能
技術要件：
- 既存のコードスタイルとディレクトリ構造に従う
- Bootstrapスタイルを使用（プロジェクト既存スタイル）
- 適切な権限チェックを追加
Claude：了解しました。以下を行います：
1. Commentモデルを作成（models/comment.py）
2. コメント関連ルートを追加（routes/comment.py）
3. 記事詳細テンプレートを修正してコメント欄を追加
4. 権限チェックデコレーターを追加
5. データベースマイグレーションファイル
始めますか？Step 3：レビューして反復
Claude：[Commentモデルを表示]
class Comment(db.Model):
id = db.Column(db.Integer, primary_key=True)
content = db.Column(db.Text, nullable=False)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
user_id = db.Column(db.Integer, db.ForeignKey('user.id'))
post_id = db.Column(db.Integer, db.ForeignKey('post.id'))
あなた：いいね。でもPostモデルにupdated_atフィールドがあるから、
Commentにも追加して一貫性を保って
Claude：はい、updated_atフィールドを追加します：
updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
あなた：完璧、続けて
[Claudeがルート、テンプレート、マイグレーションファイルを順次作成]Step 4：統合を検証
あなた：すべてのコードが生成されたら、テストスクリプトを生成して、
コメント機能が正常に動作するか検証
Claude：[テストコードを生成]
tests/test_comments.py
あなた：[テストを実行]
すべてのテストが通った！機能完成長い対話でコンテキストの一貫性を保つ
テクニック9：定期的に要約
# 複数ラウンドの対話後
あなた：これまでに何をしたか要約して
Claude：これまでのところ：
1. ✓ Commentモデルを作成
2. ✓ コメントルート（作成、削除）を追加
3. ✓ 記事詳細テンプレートを修正
4. ⏳ まだ必要：権限チェックを追加
5. ⏳ まだ必要：テストを作成
あなた：そう、権限チェックを完成させて
Claude：[作業を続ける、コンテキストは明確]テクニック10：セッションノートを使用
# 複雑なプロジェクトで
あなた：この対話用のノート（session-notes.md）を作成して、
設計決定とTODOを記録して
Claude：session-notes.mdを作成しました：
## コメント機能開発ノート
**日付：** 2025-01-09
**目標：** ブログにコメント機能を追加
### 設計決定
- コメントはネスト非対応（1レベルコメントのみ）
- 論理削除：削除されたコメントは「削除済み」と表示
- Ajaxでコメント送信（ページリフレッシュ不要）
### 完了
- [x] データモデル
- [x] 基本ルート
### TODO
- [ ] 権限チェック
- [ ] Ajax統合
- [ ] ユニットテスト
あなた：いいね、TODOを続けてよくある落とし穴と解決策
落とし穴1：コンテキスト過負荷
問題：
あなた：全100ファイルを読んで、システム全体を理解して
Claude：[トークン制限超過、または理解不十分]解決：
あなた：まずコアの5ファイルを確認：
- config.py
- models/base.py
- services/base_service.py
- routes/__init__.py
- README.md
基本フレームワークを理解してから、必要に応じて具体的なモジュールを深掘り落とし穴2：AIがすべての詳細を覚えていると仮定
問題：
# 30分前に言及した詳細
あなた：さっき言ったあのフォーマットで
Claude：そのフォーマットをもう一度教えてもらえますか？解決：
あなた：話し合ったJSONフォーマットで：
{
"data": {...},
"message": "success",
"code": 200
}
Claude：了解、このフォーマットを使います落とし穴3：既存規範を無視
問題：
Claudeが作成したコードスタイルがプロジェクトと一致しない解決：
あなた：.editorconfigと.pylintrcを確認して、
プロジェクトのコード規範に従って：
- インデント：4スペース
- 行長：最大100文字
- 引用符：シングルクォートを使用
- Import順序：標準ライブラリ → サードパーティ → ローカル
Claude：規範を理解しました。従いますクイックリファレンスカード
コンテキスト構築チェックリスト：
- [ ] README/ドキュメントをAIに提供
- [ ] 主要ディレクトリ構造を説明
- [ ] 技術スタックと依存関係を明確化
- [ ] コード規範を通知
- [ ] 特別な規約を説明
- [ ] 参考ファイル例を提供
- [ ] モジュール依存関係を明確化
効果的なコンテキスト説明テンプレート：
[プロジェクト概要] これはXXXプロジェクト
[技術スタック] YYY技術を使用
[アーキテクチャ] ZZZアーキテクチャパターンを採用
[重要な規約] 以下の特別ルールがある...
[現在のタスク] AAA機能を追加/修正する必要
[参考] BBBファイルの実装を参考にできる次回予告
入門編はこれで終了！次回から実践編に入ります。
次回の『コードリファクタリングの神器：AIに古いコードを最適化させる』では、以下を教えます：
- AIにコード品質を分析させる方法
- 安全なリファクタリング戦略
- パフォーマンス最適化の実践テクニック
- 実例：レガシーPythonプロジェクトをリファクタリング
コンテキスト管理をマスターしたら、AIが本当にあなたのプロジェクトを理解できるようになります。次はもっと複雑なことをやりましょう！
💬 インタラクションタイム
実際のプロジェクトでAIが「コンテキストを理解していない」状況に遭遇したことはありますか？
- A. よくある、AIはプロジェクト規範を無視しがち
- B. たまにある、何度も注意が必要
- C. ほとんどない、今日の方法で基本的に問題なし
- D. まだ実際のプロジェクトで使っていない
ミニ課題： あなたのプロジェクト用に.claude/context.mdを作成して、次回使用時の効果を確認してみてください！
このブログをフォローして、次回から実践編に！ 🚀
このシリーズについて
これは「AI駆動開発実践」シリーズの第4回で、「入門編」の最終回でもあります。次回から「実践編」に入り、もっと実戦的なケースが登場します！
チャレンジの準備はできましたか？次回もお楽しみに！ 👋