サイトアイコン 協栄情報ブログ

AIにあなたのプロジェクトを理解させる：コンテキスト管理のテクニック

dapeng

こんにちは、松山です。

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を使用

完全なケース：ブログシステムにコメント機能を追加

背景：

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：規範を理解しました。従います

クイックリファレンスカード

コンテキスト構築チェックリスト：

効果的なコンテキスト説明テンプレート：

[プロジェクト概要] これはXXXプロジェクト
[技術スタック] YYY技術を使用
[アーキテクチャ] ZZZアーキテクチャパターンを採用
[重要な規約] 以下の特別ルールがある...
[現在のタスク] AAA機能を追加/修正する必要
[参考] BBBファイルの実装を参考にできる

次回予告

入門編はこれで終了！次回から実践編に入ります。

次回の『コードリファクタリングの神器：AIに古いコードを最適化させる』では、以下を教えます：

コンテキスト管理をマスターしたら、AIが本当にあなたのプロジェクトを理解できるようになります。次はもっと複雑なことをやりましょう！

💬 インタラクションタイム

実際のプロジェクトでAIが「コンテキストを理解していない」状況に遭遇したことはありますか？

ミニ課題： あなたのプロジェクト用に.claude/context.mdを作成して、次回使用時の効果を確認してみてください！

このブログをフォローして、次回から実践編に！ 🚀

このシリーズについて

これは「AI駆動開発実践」シリーズの第4回で、「入門編」の最終回でもあります。次回から「実践編」に入り、もっと実戦的なケースが登場します！

チャレンジの準備はできましたか？次回もお楽しみに！ 👋

モバイルバージョンを終了