コンテキスト・エンジニアリング

問題：Claude Codeの出来栄えが、素晴らしい時とイライラする時とで激しく揺れ動く。あるセッションでは課題を完璧にこなすのに、次のセッションでは同じリクエストでも的外れな回答をしてしまう。どちらのバージョンが返ってくるか予測できない。

即効策：最初からすべての情報をプロンプトに詰め込むのをやめよう。代わりに、情報を段階的にClaudeに渡すのだ：

# Bad: dump everything upfront
claude "Here's my entire codebase architecture, all conventions,
every pattern we use, plus the task..."
 
# Good: let Skills load what's needed, when needed
claude "Build the auth module"
# Skills load authentication patterns only when Claude needs them

プロンプトエンジニアリングとは、質問をうまく表現することだ。コンテキストエンジニアリングとは、適切なタイミングでClaudeに正しい事実を提供することだ。

これは隣接するページとの境界線でもある。設計上の課題が情報フロー（何をプリロードし、何を後回しにし、無関係なコンテキストをどう排除するか）である場合は、このページを参照してほしい。 セッション復旧ルールが必要な場合は、コンテキスト管理を参照のこと。セッション開始時に適切なバンドルをプリロードするタスク固有の方法を知りたい場合は、動的初期コンテキストを参照のこと。

コンテキストエンジニアリングとは何か

コンテキスト・エンジニアリングとは、モデルへの情報の流れを設計する方法のことだ。これを正しく行えば、Claude Codeはあなたの意図を理解するコーディングパートナーのように振る舞い始める。間違えれば、セッション中ずっとそれに振り回されることになる。

問題の構造はこうだ。コンテキストウィンドウとは、トークン単位で測定される有限の作業領域である。指示、取得したドキュメント、ツールの出力、会話履歴が、この領域を共有する。上限に達すると、古いコンテンツは切り捨てられる。整理が不十分だと、Claudeは話の筋を見失ってしまう。

つまり、コンテキストは限られたリソースだ。それをどう構造化するかが、思い描いた機能を確実に実装できるビルドと、あと一歩及ばないビルドを分ける鍵となる。

コンテキストウィンドウの課題

コンテキストが制御不能になると、Claude Codeは4つの典型的なパターンで失敗する傾向がある：

これら4つの兆候を見抜くことを学べ。それこそが、君が戦っているパターンなのだ。

6つの柱のフレームワーク

コンテキスト・エンジニアリングは、6つの相互に関連する概念に基づいている。それぞれがClaude Code内でどのように機能するかを以下に示す：

1. エージェント

AIのエージェントとは、目標を追求できるよう、ツール、メモリ、推論機能と接続されたLLMのことだ。エージェントは、コンテキストに何を取り込むか、何を保持するか、何を破棄するかを決定する。

サブエージェントが実装されると、Claude Codeはシングルエージェントからマルチエージェントへと移行した。コンテキスト・エンジニアリングへの影響は明白だ：

# Single agent: one context window handles everything
claude "Research, plan, build, test, and deploy the payment system"
 
# Multi-agent: specialized contexts, distributed load
# Central AI delegates to focused subagents
claude "Build the payment system"
# → Research agent gathers requirements
# → Backend agent builds Stripe integration
# → Frontend agent creates checkout UI
# → Each agent has clean, focused context

マルチエージェント構成では、各サブエージェントに限定された役割を与えることで、コンテキストの混乱を防ぐ。中央のAIはCTOとなり、専門的な作業を適切なスペシャリストに委ねる。

2. クエリ拡張

実際のユーザーからのプロンプトは、粗削りな部分が多い。クエリ拡張は、作業開始前にそれらを洗練させる。

中央のClaude Codeセッションが共同創業者や開発マネージャーとして設定されていれば、その枠組みから自然に拡張が行われる：

Your input: "fix the auth bug"

Central AI refinement: → Analyze recent changes to auth module → Identify error patterns in logs → Scope to affected files (src/lib/auth.ts) → Generate targeted fix with test coverage

Subagent receives: Clear, scoped task with context 

大まかな文章はまず中央のAIを通過する。サブエージェントに届く頃には、それは生々しい一行の文章ではなく、範囲が明確化されたタスクとなっている。

3. 検索

検索とは、外部情報をオンデマンドでウィンドウに取り込む仕組みだ。トレードオフとなるのはチャンクサイズだ。小さなチャンクは正確だが、周囲の文脈が失われる。大きなチャンクはトークンを消費する代償として、豊富な文脈をもたらす。

現在のClaude Codeにはネイティブな検索機能はない。MCPsやCLIツールによる部分的な回避策は存在するが、まだプラットフォームの強みとはなっていない。現時点では、CLAUDE.mdとSkillsが検索レイヤーとなる：

# CLAUDE.md - Your retrieval substitute
 
## Architecture (always loaded)
 
- Next.js 15, App Router, TypeScript strict

 
## Patterns (reference when needed)
 
See /docs/patterns/ for component conventions

4. プロンプティングのテクニック

ここが、多くの人が見落としがちな部分だ。ウィンドウに情報を詰め込むだけでは、優れた出力が保証されるわけではない。重要なのは順序、タイミング、そしてチャネルである。

研究では常に同じことが示されている。コンテキストウィンドウの最初と最後の方が、中間部分よりも注目を集めるのだ。だからこそ、Skillsはこれほど効果的に機能する。

Conversation start:
├── CLAUDE.md (beginning of context - high attention)
├── Your initial prompt
├── ... conversation history ...
├── Claude's work
└── Skill loads HERE (end of context - high attention)
    └── Fresh, relevant instructions at peak attention

スキルが読み込まれるまで、CLAUDEは最小限の状態で動作する。セッションの途中でスキルが起動すると、その指示はウィンドウの最下部に配置される。まさに注目度の高いゾーンであり、専門知識が必要とされるまさにそのタイミングだ。これがプログレッシブ・ディスクロージャーであり、これにより、初期段階でリソースを消費してしまうCLAUDE.mdが浪費してしまうトークンを回収できるのだ。

5. メモリ

メモリこそが、ステートレスなモデルを、ユーザーとのやり取りを記憶する存在へと変えるものだ。

Claude Codeの真の記憶が表れる：

セッションの追跡機能とライブドキュメントを組み合わせれば、このリポジトリに特化した記憶層が得られる。決定が下されるたびにClaudeがそこに書き込み、翌日戻ってきたときにそこから読み取る。数週間かけて、アシスタントはコードベースを学習していく。

6. ツール

ツールこそが、推論を現実世界に結びつける手段だ。Claude Codeには基本機能が搭載されている：Read、Write、Edit、Bash、そして外部サービス向けのMCPだ。

スキルは新たな可能性をもたらした。Claudeは、実装をコンテキストに読み込まずに実行可能スクリプトを実行できる。これがMCP -S CLIのコンセプトだ。Claudeはプロトコルに従い、内部構造は見えないままになる。

例：Context7のMCP上に構築されたドキュメント調査スキル：

# .claude/skills/documentation-research/SKILL.md
 
---
 
name: documentation-research
description: Fetch library docs using Context7 API
 
---
 
## When to Use
 
User needs current documentation for any library
 
## Workflow
 
1. Resolve library ID via Context7
2. Fetch relevant documentation
3. Apply to current task

 
## Tools Available
 
- mcp**context7**resolve-library-id
- mcp**context7**get-library-docs

Claudeはスキルインターフェースを通じてMCPツールにアクセスする。プロトコル駆動型で、コンテキスト効率が高く、ソースコードの読み込みは不要だ。

違いが明白になる実例

コンテキストエンジニアリングを理解する最も簡単な方法は、同じタスクを「不適切なコンテキスト」と「設計されたコンテキスト」で比較することだ。

例1：セキュリティトリアージ

不適切なバージョン：

claude "check if this auth flow is secure"

そのプロンプトは範囲が広すぎる。Claudeには脅威モデルもシステム境界もなく、どのコードが重要なのか見当もつかない。

最適化されたバージョン：

claude "Review the password reset flow for account-takeover risk.

Scope: - src/auth/reset.ts
- app/api/reset-password/route.ts
- middleware/session.ts

 Focus: - token generation and expiry
- user enumeration
- rate limiting
- replay risk

 Output: 1. concrete issues
2. exploit path
3. exact fix
4. regression test plan"

同じモデル。異なる結果。2つ目のバージョンでは、Claudeにシステム境界、攻撃の視点、出力契約が与えられている。これこそがコンテキストエンジニアリングだ。

例2：大規模なリファクタリング

不適切なバージョン：

claude "migrate our forms to the new validation layer"

最適化版：

claude "Migrate signup + billing forms from ad-hoc validation to Zod.

Read first: - docs/forms/validation-plan.md
- components/forms/*

 Do not touch: - admin flows
- onboarding wizard

 Definition of done: - shared schema extracted
- client + server validation aligned
- error copy preserved
- tests updated for changed messages"

違いはプロンプトの文言を洗練させたことではない。スコープを制御した点にある。これでクロードは、何を読み、何に触れてはならず、何が完了とみなされるかを理解している。

例3：コンテンツ制作パイプライン

不適切なバージョン：

claude "write a post about Claude Code hooks"

改良版：

claude "Write a hooks article for technical readers evaluating Claude Code.

Use: - existing hooks-guide.mdx
- permission-hook-guide.mdx
- session-lifecycle-hooks.mdx

 Must include: - one production workflow
- one failure mode
- one copy-paste config example
- internal links to the three related guides

 Avoid: - generic 'AI changes everything' framing
- repeating definitions already covered in the linked pages"

これで、Claudeは真空状態で文章を書いているわけではない。既知の隣接要素、重複の制約、品質要件を備えた実際のコンテンツシステムに向けて執筆しているのだ。

コンテキスト・エンジニアリングが最も効果を発揮する場面

その効果は、タスクがハイリスクか、あるいは曖昧性が高い場合に最も高まる：

タスクが安価で、曖昧で、元に戻せるものである場合、ずさんなコンテキストでも許容できる。タスクが高コストまたはリスクが高い場合、ずさんなコンテキストこそが偽りの自信を生み出す。

フレームワークの実装

今日：CLAUDE.mdを監査する。検索しやすいレイアウトになっているか？ 重視するパターンは、Claudeが見つけられる場所に配置されているか？

今週：繰り返し行うワークフロー向けのスキルを構築する。各スキルはコンテキストの混乱を防ぐ防護策となる。なぜなら、専門知識はオンデマンドで読み込まれるからだ。

継続的：4つの失敗モードに注意せよ。Claudeが過去の過ちを繰り返したり、あなたの発言を無視したりした瞬間、汚染が始まっている。一からやり直せ。

結論

信頼性の高い出力は、モデルの規模の問題ではない。それは情報フローの問題だ。

6つの柱は相互に補完し合う：

• エージェントがコンテキストをスペシャリスト間で分散させる
• クエリ拡張が乱雑な入力を精緻化する
• 検索（CLAUDE.md/Skills経由）が関連情報を抽出する
• プロンプティングは情報を戦略的に整理する
• メモリはセッション間で状態を維持する
• ツールが機能を効率的に拡張する

これらを正しく実装すれば、Claude Codeはどんなアイデアでも任せられ、構築を信頼できるコーディングパートナーとなる。

次のステップ：

• GA提供状況と統一価格に関する最新情報：100万文字のコンテキストウィンドウガイド
• 33K予約を理解するためのコンテキストバッファ管理
• トークン最適化のためのコンテキスト管理
• 永続化戦略のためのメモリ最適化
• オンデマンドの専門知識読み込みに関するスキルガイド
• マルチエージェントアーキテクチャのためのサブエージェント設計