コンテキスト設計 — context gap を埋める

学習のねらい

AI に質の高いコードを生成してもらうためには、単に「何を作るか」だけでなく「どのような環境で、どのようなルールに基づいて」作るかを伝えることが非常に重要です。 このレッスンでは、AI がコードを生成する際に必要となる「コンテキスト (Context、文脈や背景情報)」を効果的に提供し、context gap (コンテキストの隔たり) を埋める技術を学びます。これにより、AI はよりプロジェクトの意図に沿った、高品質なコードを生成できるようになります。

context gap とは

context gap とは、AI がコードを生成する際に、人間が当たり前だと思っている「プロジェクトの既存の設計、コーディング規約、ファイル構造、使われているライブラリのバージョン」などの情報が不足している状態を指します。 AI は与えられた情報に基づいてしか推論できないため、この gap が大きいほど、意図しないコードやプロジェクトに合わないコードが生成されやすくなります。

既存コード/設計/規約のリンク方法

AI にコンテキストを伝える方法はいくつかあります。

1. プロンプト内で直接指示: 短い規約や特定のコードスニペットであれば、プロンプトに直接記述します。 例: 「Python の ruff format に従ってコードを整形してください。」
2. CLAUDE.md の活用: プロジェクト共通のルールや方針、使っている技術スタックなどを CLAUDE.md にまとめておくと、Claude Code が自動で読み込みます。これは、プロジェクト全体にわたる規約を伝えるのに最適です。 例: 「CLAUDE.md を参照し、記載されているコーディング規約とテスト方針に従ってください。」
3. ファイルパスの指定: 関連する既存のファイルやディレクトリ構造を AI に示し、それらを考慮してコードを生成するよう指示します。 例: 「src/utils/ ディレクトリにある既存のヘルパー関数を参考にしてください。」 例: 「schemas/user.py の Pydantic モデル定義に合わせて、API レスポンスを構築してください。」
4. README.md や設計ドキュメントへのリンク: プロジェクト全体の概要やアーキテクチャ、高レベルな設計思想などを README.md や別途作成した設計ドキュメントに記述し、AI にその参照を促します。 例: 「README.md に記載されているプロジェクトの目的とアーキテクチャを理解した上で、この機能を実装してください。」

@mention / CLAUDE.md / README.md の使い分け

これらのコンテキスト提供方法は、それぞれ得意な範囲があります。

• CLAUDE.md:
  • 用途: プロジェクト全体のコーディング規約、必須のリンター/フォーマッター、テストの実行方法、Git 運用ルールなど、常に守ってほしい共通のルール。
  • 特徴: Claude Code がセッション開始時に自動で読み込むため、毎回指示する必要がありません。
• README.md:
  • 用途: プロジェクトの概要、目的、高レベルなアーキテクチャ、主要な技術スタック、開発環境のセットアップ手順など、プロジェクトの全体像を把握するための情報。
  • 特徴: 人間がプロジェクトを理解するのと同じように、AI も README.md を読むことでプロジェクトの意図を深く理解できます。
• プロンプト内の直接指示やファイルパス指定 (@mention など):
  • 用途: 特定のタスクに特化した指示、参照すべき特定のファイルやコードスニペット、一時的な制約、既存の関数やクラスの利用方法など、そのタスク固有のコンテキスト。
  • 特徴: claude コマンドラインツールでは、ファイル名を直接 @ でメンションして内容を AI に読み込ませることができます。

これらの方法を組み合わせることで、AI はより正確で、プロジェクトに適合したコードを生成できるようになります。

まとめ

AI にとってのコンテキストは、人間にとっての「共通認識」です。 CLAUDE.md でプロジェクトの共通ルールを定義し、README.md で全体像を伝え、そして個別のタスクではプロンプトやファイルパス指定で具体的なコンテキストを提供することで、context gap を最小限に抑え、AI の生成するコード品質を飛躍的に向上させることができます。