この記事で分かること
- 「プロンプトエンジニアリング」と「コンテキストエンジニアリング」の違い
- CLAUDE.mdの本質的な役割と設計思想
-
.claude/ディレクトリ全体を使った文脈設計のパターン - 出力品質を変える具体的なBefore/After例
- よくある設計ミスとその回避策
はじめに — プロンプトを磨いても品質が上がらない理由
AIコーディングエージェントの出力に不満を感じたとき、多くの人は「プロンプトの書き方が悪いのでは」と考えます。確かにプロンプトは重要です。しかし、AIエージェントとの協業においては、プロンプトは情報入力のごく一部にすぎません。
Anthropic社がClaude Coworkのベストプラクティスで明確に述べていることがあります。
共同作業セッションにおいて、プロンプトは最も重要度の低い部分。コンテキスト・構造・スキル・制約こそがアウトプットの質を左右する。
これは、AIに「何を聞くか」よりも、AIが判断するための文脈全体をどう設計するかが重要だという意味です。この文脈全体の設計を、コンテキストエンジニアリングと呼びます。
前提知識
- AIコーディングエージェント: コードの生成・修正・レビューなどを自律的に行うAIツールです。Claude Code、Cursor、GitHub Copilotなどが代表例です
- プロンプト: AIへの入力テキスト（指示文）のことです
- コンテキストウィンドウ: LLM（大規模言語モデル）が一度に処理できる情報量の上限です。人間の「短期記憶」に相当します
- CLAUDE.md: Claude Codeがセッション開始時に自動で読み込む設定ファイルです。他のツールにも同様の仕組みがあります（CursorのCursorrules、CodexのAGENTS.mdなど）
プロンプトエンジニアリングとコンテキストエンジニアリングの違い
プロンプトエンジニアリングは「AIへの質問の仕方」を工夫する技術です。一方、コンテキストエンジニアリングは、指示文だけでなくAIが仕事をするために必要な文脈全体を設計する技術です。
プロンプトエンジニアリングがカバーするのは上図の「プロンプト」の部分だけです。コンテキストエンジニアリングは、AIがアクセスできるすべての情報——ルール、履歴、ツール、メモリ——をトータルに設計します。
たとえ話で説明しましょう。新しく入社したエンジニアに仕事を頼む場面を想像してください。
| やること | プロンプトエンジニアリング | コンテキストエンジニアリング |
|---|---|---|
| 例え | 毎回口頭で細かく指示する | 引き継ぎ書・社内Wiki・過去の議事録を渡す |
| 効果 | その場では動けるが、毎回説明が必要 | 自律的に判断でき、回を重ねるほど精度が上がる |
| スケール | 自分が付きっきりでないと動けない | 一度設計すれば誰でも同じ品質で委任できる |
CLAUDE.mdは「引き継ぎ書」である
コンテキストエンジニアリングの出発点は、CLAUDE.md（または相当するファイル）です。
ここで最も重要な考え方があります。
CLAUDE.mdは「設定ファイル」ではなく、新しくチームに入ったエンジニアに渡す「引き継ぎ書」である。
引き継ぎ書に「良いコードを書け」とは書きません。「このプロジェクトでは関数は30行以内。超える場合は分割理由をコメントに残すこと」——引き継ぎ書にはこういう具体的な行動指針を書きます。
# ❌ 曖昧な指示（AIが解釈を迷う）
テストをしっかり書くこと
# ✅ 具体的な行動指針（判断基準が明確）
テストは必ずArrange-Act-Assertパターンで記述する。
カバレッジ80%以上を維持。カバレッジが下がるPRはマージ禁止。
この視点で書くと、CLAUDE.mdに「何を書くべきか」が自然と明確になります。
.claude/ディレクトリ全体で設計する
CLAUDE.mdだけで考えてはいけません。Claude Code開発責任者のBoris Chernyが公開したベストプラクティスでも、.claude/ディレクトリ全体を使った設計が推奨されています。
your-project/
├── CLAUDE.md ← 判断品質に直結する最重要ルールだけ
├── .claude/
│ ├── rules/
│ │ ├── code-style.md ← コーディング規約の詳細
│ │ ├── testing.md ← テスト方針
│ │ └── security.md ← セキュリティルール
│ ├── commands/ ← カスタムコマンド（ワークフロー自動化）
│ └── skills/ ← 複雑なタスクの定型化
├── tasks/
│ ├── todo.md ← 現在のタスク一覧
│ └── lessons.md ← 過去の失敗と学び
設計の分担を整理すると、以下のようになります。
| 要素 | 役割 | 設計の狙い |
|---|---|---|
| CLAUDE.md | 判断の「軸」となる原則 | 判断品質を上げる |
| rules/ | トピック別の詳細ルール | CLAUDE.md本体をスリムに保つ |
| commands / skills | ワークフローの自動化 | 作業を標準化する |
| tasks/ | 状態管理・経験知 | 記憶を永続化する |
なぜCLAUDE.mdに全部書いてはいけないのか
CLAUDE.mdの内容はコンテキストウィンドウを常に消費します。コーディング規約・テスト方針・Git運用・セキュリティルール——これらを全部書くと500行を超え、実際のタスク処理に使える領域が減ります。さらに、情報が多すぎると後半のルールが無視されやすくなるという報告があります。
CLAUDE.mdは300行以内に収め、詳細はrules/に分離するのがベストプラクティスです。
rules/配下のファイルはClaude Codeが自動で読み込むため、明示的にインポートする必要はありません。
実践: Before/Afterで見る出力品質の変化
ケース1: コーディング規約
Before（CLAUDE.mdなし）
「ユーザー登録APIを作って」と依頼すると、AIはフレームワークのデフォルトスタイルで実装します。エラーハンドリングの方針やバリデーションのルールはAIが「いい感じ」に解釈するため、既存コードと一貫性がありません。
After（コンテキストエンジニアリング適用後）
# CLAUDE.md
## アーキテクチャ
- エラーハンドリングはResult型（例外は使わない）
- バリデーションはzodスキーマで入力層に集約
- ビジネスロジックはドメイン層に配置。コントローラーに書かない
同じ「ユーザー登録APIを作って」という指示でも、プロジェクトの規約に沿ったコードが最初から生成されます。
ケース2: UI/デザインの一貫性
Vibe Coding（AIにUIを任せる開発スタイル）で特に効果が大きいのが、デザイントークンの事前定義です。
# .claude/rules/design-system.md
## デザイントークン
- Primary: #2563EB, Secondary: #64748B
- フォント: Inter（本文）、JetBrains Mono（コード）
- 角丸: 8px統一（例外なし）
- スペーシング: 4px基準の倍数のみ使用
## 禁止事項
- インラインスタイルの使用禁止
- ページごとに色を変えない
- ボタンのパディングをページごとに変えない
デザインシステムを先に定義するだけで、ページ間の色・フォント・余白のばらつきが解消されます。これはClaude Code利用者の間で「最も効果が高いコツ」として広く共有されている手法です。
ケース3: 失敗の繰り返し防止
# tasks/lessons.md
## 2026-02-15: Redis接続プール共有でデッドロック
- 原因: 複数のgoroutineが同一接続プールを共有
- 対策: 接続はリクエスト単位で取得・解放する
- 関連ファイル: internal/cache/redis.go
## 2026-03-01: マイグレーション実行でダウンタイム
- 原因: ALTER TABLEがテーブルロックを取得
- 対策: pt-online-schema-changeを使用する
過去の教訓をファイルに記録しておくだけで、AIは同じミスを回避できます。これは人間のチーム運営でも有効な手法ですが、AIエージェントではセッションをまたいで記憶が消えるため、特に重要です。
コンテキスト設計の5原則
ここまでの内容を整理し、コンテキストエンジニアリングの設計原則をまとめます。
原則1: 書くのは「Claudeが推測できないこと」だけ
AIはコードを読めば分かることを改めて教える必要はありません。標準的な言語規約も学習済みです。CLAUDE.mdに書くべきは、コードベースを読んだだけでは分からない判断基準・暗黙知・チーム固有のルールです。
# ❌ 書く必要がないこと
TypeScriptを使用している（コードを見れば分かる）
# ✅ 書くべきこと
TypeScriptのstrictモードを有効化している。
any型は禁止。型が不明な場合はunknownを使い、型ガードで絞り込む。
原則2: 短くヒューマンリーダブルに
CLAUDE.mdは人間が読んでも分かる文章で書きます。JSONやYAMLのような機械的なフォーマットよりも、自然言語の箇条書きのほうがAIにもよく伝わります。
原則3: 判断基準を明文化する
「良い」「適切な」「しっかり」のような曖昧な表現は避けます。AIが迷わず判断できる具体的な基準を書きます。
| 曖昧な表現 | 具体的な基準 |
|---|---|
| テストをしっかり書く | テストカバレッジ80%以上を維持する |
| 適切なエラーハンドリング | エラーはResult型で返す。例外はI/O境界のみで使用 |
| コードを簡潔に保つ | 関数は30行以内。超える場合は分割理由をコメントに残す |
原則4: 情報を階層化する
すべてをCLAUDE.mdに書かない。重要度と変更頻度で配置場所を分けます。
原則5: 育てるものとして扱う
コンテキストエンジニアリングは一度設計して終わりではありません。プロジェクトが進むにつれ、新しい判断基準や教訓が生まれます。
成熟度に応じた取り組みの段階を以下に示します。
| 段階 | 取り組み | 期待効果 |
|---|---|---|
| 基礎 | CLAUDE.mdにルール・構造を記述 | 「毎回説明する」がなくなる |
| 発展 | 判断基準・教訓を外部ファイルとして構造化 | 同じミスの繰り返しがなくなる |
| 理想 | AIとの対話を通じて文脈を継続的に更新 | 「あうんの呼吸」で期待以上の成果が出る |
週に一度、PRレビューやバグ修正のタイミングで「この教訓はCLAUDE.mdに追記すべきか？」と自問する習慣をつけるだけで、コンテキストは自然と成熟していきます。
よくある落とし穴
| アンチパターン | 何が起きるか | 対策 |
|---|---|---|
| 全部入りCLAUDE.md | 500行超えてコンテキストウィンドウを圧迫。後半のルールが無視される | 300行以内に。詳細はrules/に分離 |
| 設定ファイル風の記述 | 「良いコードを書け」→ AIが独自解釈 | 引き継ぎ書のように具体的な行動指針を書く |
| 一度作って放置 | プロジェクトが進むとルールが陳腐化 | 週次でレビューし、教訓を追記する |
| 機密情報の混入 | APIキーやパスワードが漏洩するリスク | CLAUDE.mdには絶対に書かない。環境変数で管理 |
| コードで分かることを書く | トークンの無駄遣い | AIが推測できない情報だけに絞る |
まとめ
コンテキストエンジニアリングとは、AIに「何を聞くか」ではなく、AIが正しく判断するための文脈全体を設計する技術です。
始め方は3ステップだけです。
- CLAUDE.mdを作る — プロジェクトの技術スタック・コーディング規約・頻用コマンドを書く（30分）
- 引き継ぎ書として推敲する — 「新人エンジニアに渡して、これだけで仕事を始められるか？」と自問する
-
詳細を分離する — 長くなったら
.claude/rules/にトピック別ファイルを作る
プロンプトを何十回も書き直すより、CLAUDE.mdに「関数は30行以内」と一行書くほうが、以降のすべてのセッションで効きます。プロンプトの改善は一度きりですが、コンテキストの改善は複利で効き続けます。
まずは今日、プロジェクトのルートにCLAUDE.mdを作ることから始めてみてください。