コーディングエージェント時代のコンテキストエンジニアリング実践ガイド

Last updated at 2025-10-12Posted at 2025-10-12

Claude Code、Cursor、GitHub Copilot、Codexを使いこなすための必須知識

📚 はじめに：この記事の位置づけ

本記事は、コーディングエージェントを日常的に使うエンジニア向けの実践的なガイドです。

より詳細な技術的背景や理論については、以下の完全解説記事をご参照ください：

📖 コンテキストウィンドウの処理フローと動作メカニズム完全解説

上記の記事では：

コンテキストウィンドウの技術的詳細
1ターンあたりの処理フローの完全な説明
予算管理アルゴリズムと数式モデル
実装レベルの疑似コード
LLMアプリケーション開発者向けの深い解説

が網羅されています。

本記事は、その知識をコーディングエージェント（Claude Code、Cursor、Copilot等）での実務に応用することに特化しています。

なぜ今「コンテキストエンジニアリング」なのか

あなたは経験していませんか？

あなた: 「さっき決めた設計方針で実装して」

エージェント: 「申し訳ございません、設計方針が見当たりません。
              もう一度教えていただけますか？」

あなた: 「は？さっき30分かけて説明したじゃん...」

これ、コンテキストウィンドウの限界に引っかかってます。

コーディングエージェントの"記憶力"の真実

ツール	コンテキストウィンドウ	実効的に使える範囲
Claude Code	最大200K tokens	実質50-100K程度が安定
Cursor	最大128K tokens	プロジェクト全体は厳しい
GitHub Copilot	数K tokens	現在のファイル中心
Codex	8-32K tokens	かなり限定的

要するに: どんなに賢いAIでも、「一度に見られる情報量」には物理的な限界があります。

その限界の中で何を見せるか、何を捨てるか、どう要約するか——それが「コンテキストエンジニアリング」です。

コーディングエージェントで起きる「あるある」問題

問題1: 「プロジェクトの全体像を理解してくれない」

# あなたのプロジェクト構造
my-app/
├── src/
│   ├── components/  (50 files)
│   ├── hooks/       (30 files)
│   ├── utils/       (20 files)
│   └── ...
├── docs/
│   └── architecture.md  (重要！)
└── ...

# エージェントが実際に見ているもの
"現在開いているファイル1つ" 😱

原因: エージェントは「あなたが明示的に見せたもの」しか知らない

対策: 後述の「プロジェクトコンテキスト設計」参照

問題2: 「さっきまで覚えていたのに急に忘れる」

ターン1-5:  完璧に動いてる ✅
ターン6-10: まだ大丈夫 ✅
ターン11:   あれ？設計変わってない？ ⚠️
ターン15:   完全に別人... 💀

原因: 古い会話がウィンドウから押し出された

対策: 後述の「決定事項の固定化」参照

問題3: 「コード生成が途中で切れる」

// エージェントの出力
export function complexFunction() {
  // すごく長い処理...
  // ...
  // ...
  // [ここで突然終了]

原因: 出力用の余白（Scratch領域）が不足

対策: 後述の「Scratch領域の確保」参照

問題4: 「関連ファイルを見つけられない」

あなた: 「UserService を使って実装して」

エージェント: 「UserService が見つかりません」

あなた: 「src/services/user.ts にあるじゃん！」

原因: ファイル検索の範囲・方法が不適切

対策: 後述の「効果的なファイル参照」参照

コンテキストウィンドウの基礎知識

コンテキストウィンドウとは？

作業机の比喩で理解しましょう：

┌──────────────────────────────────┐
│  あなたの作業机（コンテキスト）          
│                                     
│  📋 仕様書（固定で常に見える）          
│  📝 会話履歴（新しいものから順に）       
│  📁 関連ファイル（検索で取得）          
│  🔧 ツール出力（実行結果）              
│  📄 空きスペース（生成用の余白）         
│                                     
│  [机のサイズ = ウィンドウサイズ]        
└──────────────────────────────────┘

机が小さい（ウィンドウが狭い）と:

資料を全部広げられない
古い資料を片付けないと新しいのが置けない
作業スペースがなくなって仕事ができない

ウィンドウの構成要素

領域	内容	優先度
Pinned	プロジェクト仕様、制約、出力ルール	最高（常に表示）
History	最近の会話要約	高（新しいほど重要）
Evidence	参照コード、ドキュメント	高（質問に応じて変動）
Scratch	AIの思考・出力用余白	必須（これがないと生成品質が落ちる）

トークン数の感覚を掴む

// 約100トークン
function getUserById(id: string): Promise<User> {
  return db.users.findUnique({ where: { id } });
}

// 約500トークン
// そこそこ複雑なコンポーネント全体

// 約2000トークン
// 中規模のファイル1つ分

// 約10000トークン
// 大規模なファイルまたは複数の関連ファイル

目安:

日本語は英語の約1.5倍のトークンを消費
コメント多用はトークン消費が激しい
JSON/YAMLは意外と重い

実践パターン集

パターン1: プロジェクトコンテキストの設計

❌ よくない例

# プロジェクトルートに何もない
# エージェントは毎回ゼロから推測

✅ 良い例

<!-- .ai/context.md -->
# プロジェクトコンテキスト

## プロジェクト概要
Eコマースサイトのバックエンド API（Node.js + Express + Prisma）

## アーキテクチャ
- Clean Architecture採用
- レイヤー: Controller → UseCase → Repository
- 認証: JWT（有効期限24時間）

## コーディング規約
- TypeScript strict mode必須
- 関数は単一責任の原則
- エラーは必ずcustomエラークラスを使用

## ディレクトリ構造
src/
├── controllers/  # HTTPリクエスト処理
├── usecases/     # ビジネスロジック
├── repositories/ # データアクセス
└── entities/     # ドメインモデル

## 重要な決定事項
- [2024-10-10] ユーザーIDはUUID v4を使用
- [2024-10-11] 決済処理は非同期（イベント駆動）
- [2024-10-12] 画像はS3、パスのみDBに保存

使い方:

# Cursor / Claude Code
毎回の会話開始時に「@.ai/context.md を読んで」

# または .cursorrules / .claudefiles に設定

パターン2: 決定事項の固定化（/compact パターン）

長い対話の途中で重要な決定をしたら、その場で固定化：

<!-- .ai/decisions.md に追記 -->

## 2024-10-12: ユーザー認証フロー変更

### 決定内容
- リフレッシュトークンを導入（有効期限7日）
- アクセストークン（15分）とリフレッシュトークン（7日）の二段構え

### 理由
- UXとセキュリティのバランス
- モバイルアプリでの頻繁な再ログイン回避

### 影響範囲
- `src/auth/token.service.ts` 全面改修
- `src/controllers/auth.controller.ts` 修正
- DBマイグレーション必要

### コード変更概要
\`\`\`typescript
// Before
generateToken(userId: string): string

// After  
generateTokenPair(userId: string): { 
  accessToken: string, 
  refreshToken: string 
}
\`\`\`

効果: エージェントが「なぜこの設計なのか」を常に参照できる

パターン3: 効果的なファイル参照

❌ よくない例

あなた: 「UserServiceを修正して」

エージェント: 「どのファイルですか？」

✅ 良い例（方法1: 明示的指定）

あなた: 「@src/services/user.service.ts のfindByEmail()を
        エラーハンドリング追加して」

✅ 良い例（方法2: ファイルマップ活用）

<!-- .ai/filemap.md -->
# 主要ファイルマップ

## 認証関連
- `src/auth/token.service.ts` - JWT生成・検証
- `src/auth/auth.middleware.ts` - 認証ミドルウェア
- `src/controllers/auth.controller.ts` - ログイン/ログアウトAPI

## ユーザー管理
- `src/services/user.service.ts` - ユーザーCRUD
- `src/repositories/user.repository.ts` - DBアクセス
- `src/entities/user.entity.ts` - ユーザーモデル

## 決済
- `src/services/payment.service.ts` - 決済処理
- `src/queues/payment.queue.ts` - 非同期決済ジョブ

あなた: 「@.ai/filemap.md を見て、ユーザー管理の
        user.service.tsを修正して」

パターン4: Scratch領域の確保（長文生成時）

❌ よくない例

// 巨大なファイルを全部渡して
// 「リファクタリングして」
// → 途中で生成が切れる

✅ 良い例

// ステップ1: 小さく分割
あなた: 「user.service.tsのfindByEmail()だけリファクタリングして」

// ステップ2: 段階的に
あなた: 「OK。次にfindById()も同じパターンで」

// ステップ3: 最後に統合
あなた: 「全メソッドのリファクタリングが完了したら、
        ファイル全体を出力して」

ポイント:

一度に大量の出力を求めない
段階的に進める
各ステップで確認

パターン5: RAG的アプローチ（大規模プロジェクト）

大規模プロジェクト（100+ファイル）では、検索→要約→参照のパターン：

# ステップ1: 関連ファイルを検索
あなた: 「"authentication"に関連するファイルをリストアップして」

エージェント: 
- src/auth/token.service.ts
- src/auth/auth.middleware.ts
- src/controllers/auth.controller.ts
- ...

# ステップ2: 必要なファイルのみ参照
あなた: 「@src/auth/token.service.ts と 
        @src/auth/auth.middleware.ts を読んで、
        JWTトークンの生成ロジックを説明して」

# ステップ3: 修正実施
あなた: 「理解した。では token.service.ts に
        リフレッシュトークン機能を追加して」

ツール別最適化テクニック

Claude Code

特徴:

コンテキストウィンドウが大きい（200K tokens）
プロジェクト全体を理解する能力が高い
ターミナルとの統合

最適化:

# .claudefiles を活用
.ai/
├── context.md      # プロジェクト概要
├── decisions.md    # 重要な決定事項
└── conventions.md  # コーディング規約

# claude-code.config.json
{
  "alwaysInclude": [
    ".ai/context.md",
    "README.md"
  ],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "**/*.test.ts"  // テストは必要時のみ
  ]
}

Tips:

/compact コマンドで定期的に要約
長い対話は /reset で新規開始（決定事項は事前に保存）
ターミナル出力は要約して保存

Cursor

特徴:

IDEとの深い統合
ファイル単位の理解が得意
Ctrl+K でインラインコード生成

最適化:

# .cursorrules
# プロジェクト全体のルールを記述

You are an expert TypeScript developer.

## Project Context
This is an e-commerce backend API.
Architecture: Clean Architecture (Controller → UseCase → Repository)

## Rules
1. Always use async/await, never callbacks
2. Error handling: Use custom error classes
3. Database: Prisma ORM
4. Testing: Jest + supertest

## File Patterns
- Controllers: Handle HTTP only
- UseCases: Business logic only  
- Repositories: Data access only

## When modifying code:
- Update related tests
- Add JSDoc comments
- Follow existing patterns

Tips:

Ctrl+L でチャット開始時に @codebase で全体把握
関連ファイルは Ctrl+クリックで自動追加
頻繁に使う定義は「ピン留め」機能を活用

GitHub Copilot

特徴:

コンテキストウィンドウが小さい（数K tokens）
現在のファイル中心
補完に特化

最適化:

// ファイルの先頭にコンテキストを書く

/**
 * User Service
 * 
 * Architecture: Clean Architecture
 * Layer: UseCase layer
 * 
 * Dependencies:
 * - UserRepository (data access)
 * - EmailService (notification)
 * 
 * Error Handling:
 * - Throw UserNotFoundError when user doesn't exist
 * - Throw EmailAlreadyExistsError on duplicate email
 */

export class UserService {
  // Copilot はこの情報を元に補完してくれる
}

Tips:

ファイル内にコンテキストを書く（JSDoc、コメント）
型定義を明確に
関連する他ファイルのimportを先に書く（Copilotが参照する）

Codex（OpenAI API）

特徴:

プログラマブル
カスタマイズ性が高い
コンテキストウィンドウは中程度（8-32K tokens）

最適化:

# カスタムプロンプトでコンテキストを制御

def generate_code_with_context(prompt: str):
    # プロジェクトコンテキストを読み込み
    with open('.ai/context.md', 'r') as f:
        project_context = f.read()
    
    # 関連ファイルを検索
    relevant_files = search_relevant_files(prompt)
    
    # コンテキストを構築
    context = f"""
# Project Context
{project_context}

# Relevant Files
{relevant_files}

# Task
{prompt}
"""
    
    # Codex に送信
    response = openai.Completion.create(
        engine="code-davinci-002",
        prompt=context,
        max_tokens=1000
    )
    
    return response.choices[0].text

よくある失敗と対策

失敗1: 「全部教えようとして失敗」

❌ あなた: 「このプロジェクトは...（5000行の説明）...
          だから、ユーザー登録機能を作って」

エージェント: [コンテキスト限界でパフォーマンス低下]

対策: 必要最小限から始める

✅ あなた: 「@.ai/context.md を読んで。
          ユーザー登録機能の仕様は...（簡潔に）」

失敗2: 「コンテキストを更新しない」

# 3週間前の仕様のまま
❌ .ai/context.md: 「認証はBasic認証」

# 実際は先週JWTに変更済み
✅ 実コード: JWT使用中

→ エージェントが混乱

対策: 重要な変更時は即座に更新

# Git hookで自動リマインド
# .git/hooks/post-commit

#!/bin/bash
echo "🤖 .ai/context.md を更新しましたか？"

失敗3: 「生成が途中で切れても放置」

❌ エージェント: [長いコードを生成中...]
              // ... [ここで終了]

あなた: 「まあいいや、自分で続き書くか」

対策: 継続を依頼する

✅ あなた: 「続きを生成して」

または

✅ あなた: 「最後まで生成できるよう、
          不要なコンテキストを削除して再生成」

失敗4: 「エージェントの"記憶"に頼りすぎ」

❌ [50ターン後]
あなた: 「最初に決めた認証方式で実装して」

エージェント: 「最初の決定が見つかりません」

対策: 重要な決定は必ず文書化

✅ .ai/decisions.md に記録 → 常に参照可能

上級テクニック

テクニック1: コンテキスト階層化

大規模プロジェクトでは階層的にコンテキストを管理：

.ai/
├── context.md          # L1: プロジェクト全体（常に読む）
├── architecture/
│   ├── backend.md      # L2: バックエンド設計（必要時）
│   ├── frontend.md     # L2: フロントエンド設計（必要時）
│   └── database.md     # L2: DB設計（必要時）
├── modules/
│   ├── auth.md         # L3: 認証モジュール詳細
│   ├── payment.md      # L3: 決済モジュール詳細
│   └── ...
└── decisions/
    ├── 2024-10.md      # 月次決定事項
    └── ...

使い分け:

# 全体的な質問
「@.ai/context.md プロジェクト全体の構成を教えて」

# 特定モジュールの質問  
「@.ai/context.md @.ai/modules/auth.md 
 認証周りを修正したい」

テクニック2: 動的コンテキスト生成

スクリプトで自動生成：

// scripts/generate-ai-context.ts

import { generateProjectStructure } from './utils';

async function generateContext() {
  const structure = await generateProjectStructure();
  const recentCommits = await getRecentCommits(30); // 直近30件
  const openIssues = await getOpenIssues();
  
  const context = `
# Auto-Generated Project Context
Last Updated: ${new Date().toISOString()}

## Project Structure
${structure}

## Recent Changes (Last 30 commits)
${recentCommits.map(c => `- ${c.message}`).join('\n')}

## Open Issues
${openIssues.map(i => `- #${i.number}: ${i.title}`).join('\n')}
`;

  await fs.writeFile('.ai/context-generated.md', context);
}

// package.json
{
  "scripts": {
    "ai:context": "tsx scripts/generate-ai-context.ts"
  }
}

テクニック3: コンテキスト圧縮

トークンを節約：

// ❌ 冗長
const userRepository = {
  /**
   * Finds a user by their unique identifier
   * @param userId - The unique identifier of the user
   * @returns A promise that resolves to the user object
   * @throws UserNotFoundError if the user doesn't exist
   */
  findById: async (userId: string): Promise<User> => {
    // Implementation...
  }
}

// ✅ 簡潔（でも明確）
const userRepository = {
  // Find user by ID. Throws UserNotFoundError if not found.
  findById: async (userId: string): Promise<User> => {
    // Implementation...
  }
}

削減できるトークン: 約60% 🎉

テクニック4: セマンティック検索の活用

ベクトルDBでスマートに検索：

// scripts/semantic-search.ts
import { OpenAIEmbeddings } from 'langchain/embeddings/openai';
import { MemoryVectorStore } from 'langchain/vectorstores/memory';

// プロジェクトファイルをベクトル化
const vectorStore = await MemoryVectorStore.fromTexts(
  allProjectFiles.map(f => f.content),
  allProjectFiles.map(f => ({ path: f.path })),
  new OpenAIEmbeddings()
);

// 質問に関連するファイルを検索
const relevantFiles = await vectorStore.similaritySearch(
  "ユーザー認証の実装",
  5 // 上位5件
);

console.log('関連ファイル:', relevantFiles.map(f => f.metadata.path));

テクニック5: コンテキスト使用量のモニタリング

// エージェント使用時のモニタリング

class ContextMonitor {
  private maxTokens = 100000;
  private currentUsage = 0;
  
  track(operation: string, tokens: number) {
    this.currentUsage += tokens;
    const percentage = (this.currentUsage / this.maxTokens) * 100;
    
    console.log(`[${operation}] Tokens: ${tokens}`);
    console.log(`Total Usage: ${this.currentUsage}/${this.maxTokens} (${percentage.toFixed(1)}%)`);
    
    if (percentage > 80) {
      console.warn('⚠️  Context window is 80% full. Consider compacting.');
    }
    
    if (percentage > 95) {
      console.error('🚨 Context window critically full! Compact NOW!');
    }
  }
  
  reset() {
    this.currentUsage = 0;
    console.log('✅ Context reset');
  }
}

// 使用例
const monitor = new ContextMonitor();

monitor.track('Load context.md', 1500);
monitor.track('Load user.service.ts', 800);
monitor.track('Search relevant files', 5000);
// ...

まとめ: コンテキストエンジニアリングのベストプラクティス

✅ 必ずやること

プロジェクトコンテキストを文書化
- .ai/context.md を作成
- 仕様、制約、規約を明記
重要な決定事項を記録
- .ai/decisions.md に追記
- 理由・影響範囲も書く
ファイル参照を明示的に
- @filepath で明確に指定
- または .ai/filemap.md で整理
定期的なコンパクション
- 長い対話は区切って要約
- 決定事項を固定化
Scratch領域を確保
- 大量の出力は段階的に
- ウィンドウ使用量をモニタリング

❌ やってはいけないこと

コンテキストの詰め込みすぎ
- 必要最小限に絞る
- 不要なファイルは削除
古い情報のまま放置
- 仕様変更したら即座に更新
- 定期的にレビュー
エージェントの"記憶"に依存
- 重要なことは必ず文書化
- 口頭指示だけで済ませない
生成途中で妥協
- 切れたら継続を依頼
- または分割して生成
ツールの特性を無視
- 各ツールの得意・不得意を理解
- 適材適所で使い分け

おわりに

コンテキストエンジニアリングは、**AIエージェントとの"対話設計"**です。

エージェントは賢いですが、あなたが適切にコンテキストを設計しないと、その能力を発揮できません。

この記事のテクニックを使えば：

✅ エージェントが「忘れる」ことが減る
✅ コード生成の品質が向上する
✅ 長期的なプロジェクトでも安定して使える
✅ チーム全体で知見を共有できる

今日から始められること:

.ai/context.md を作る（5分）
プロジェクトの概要を書く（10分）
次のエージェント使用時に参照する（1秒）

たったこれだけで、コーディング体験が劇的に変わります。

参考リンク

付録: テンプレート集

A. .ai/context.md テンプレート

# プロジェクトコンテキスト

## プロジェクト概要
[プロジェクトの簡潔な説明]

## 技術スタック
- Backend: [技術]
- Frontend: [技術]
- Database: [技術]
- Infrastructure: [技術]

## アーキテクチャ
[アーキテクチャパターン]

## ディレクトリ構造

[主要ディレクトリの説明]


## コーディング規約
- [規約1]
- [規約2]
- ...

## 制約・要件
- [制約1]
- [制約2]
- ...

## 外部サービス連携
- [サービス1]: [用途]
- [サービス2]: [用途]

B. .ai/decisions.md テンプレート

# 重要な決定事項

## YYYY-MM-DD: [決定事項のタイトル]

### 決定内容
[何を決めたか]

### 理由
[なぜその決定をしたか]

### 影響範囲
[どのファイル・モジュールに影響するか]

### 実装メモ
[実装時の注意点]

---

C. .cursorrules テンプレート

You are an expert [Language] developer working on [Project Type].

## Project Context
[Brief project description]

## Technical Stack
- [Tech 1]
- [Tech 2]

## Coding Standards
1. [Standard 1]
2. [Standard 2]

## Architecture
[Architecture pattern]

## When writing code:
- [Rule 1]
- [Rule 2]

## When refactoring:
- [Rule 1]
- [Rule 2]

## Error Handling
- [Approach]

## Testing
- [Testing framework and approach]

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

コーディングエージェント時代のコンテキストエンジニアリング実践ガイド

📚 はじめに：この記事の位置づけ

目次

なぜ今「コンテキストエンジニアリング」なのか

あなたは経験していませんか？

コーディングエージェントの"記憶力"の真実

コーディングエージェントで起きる「あるある」問題

問題1: 「プロジェクトの全体像を理解してくれない」

問題2: 「さっきまで覚えていたのに急に忘れる」

問題3: 「コード生成が途中で切れる」

問題4: 「関連ファイルを見つけられない」

コンテキストウィンドウの基礎知識

コンテキストウィンドウとは？

ウィンドウの構成要素

トークン数の感覚を掴む

実践パターン集

パターン1: プロジェクトコンテキストの設計

❌ よくない例

✅ 良い例

パターン2: 決定事項の固定化（/compact パターン）

パターン3: 効果的なファイル参照

❌ よくない例

✅ 良い例（方法1: 明示的指定）

✅ 良い例（方法2: ファイルマップ活用）

パターン4: Scratch領域の確保（長文生成時）

❌ よくない例

✅ 良い例

パターン5: RAG的アプローチ（大規模プロジェクト）

ツール別最適化テクニック

Claude Code

Cursor

GitHub Copilot

Codex（OpenAI API）

よくある失敗と対策

失敗1: 「全部教えようとして失敗」

失敗2: 「コンテキストを更新しない」

失敗3: 「生成が途中で切れても放置」

失敗4: 「エージェントの"記憶"に頼りすぎ」

上級テクニック

テクニック1: コンテキスト階層化

テクニック2: 動的コンテキスト生成

テクニック3: コンテキスト圧縮

テクニック4: セマンティック検索の活用

テクニック5: コンテキスト使用量のモニタリング

まとめ: コンテキストエンジニアリングのベストプラクティス

✅ 必ずやること

❌ やってはいけないこと

おわりに

参考リンク

付録: テンプレート集

A. .ai/context.md テンプレート

B. .ai/decisions.md テンプレート

C. .cursorrules テンプレート