AIコーディングエージェントが失敗する本当の理由と「読んでから書く」Context Engineering入門

「AIにコードを直してもらったのに、なぜか別の場所が壊れてた…」そんな経験、ありませんか？😅

実はこれ、AIが「コードを書けない」から起きる問題じゃないんですよね。AIが読まずに書き始めてしまうことが根本的な原因なんです。

今回は、コーディングエージェントの失敗パターンと、それを防ぐContext Engineering（コンテキスト・エンジニアリング）というアプローチをわかりやすく解説します！

Contents

🤖 コーディングエージェントはなぜ失敗するのか？
📚 Context Engineering（コンテキスト・エンジニアリング）とは？
🛠️ Pythonで試す：エージェントに渡すコンテキスト構築の例
🎯 プロンプトを長くすればいいわけじゃない
まとめ

🤖 コーディングエージェントはなぜ失敗するのか？

AI coding agent / Photo by Daniil Komov via Pexels

AIエージェントが起こしがちな失敗を整理するとこんな感じです。

✅ 数ファイルだけ開いてアーキテクチャを「推測」する
✅ 間違った場所を編集してしまう
✅ リスクのないパスしかテストしない
✅ 「修正しました！」と自信満々なサマリーを返す

プルリクエストは一見きれいに見えても、後からテナント境界の破壊・マイグレーションの見落とし・隠れた副作用が発覚する…というパターンです。怖いですよね。

イメージとしては、設計図をちゃんと読まずにリフォームを始めてしまう職人さんみたいな感じです。腕はいいのに、情報が足りない。

📚 Context Engineering（コンテキスト・エンジニアリング）とは？

Context Engineeringとは、AIエージェントが編集を始める「前に」、十分なコンテキスト（背景情報・構造・依存関係）を与えてあげる設計手法のことです。

つまり一言でいうと、「まず読ませてから、書かせる」という考え方です。

具体的には以下のような情報をあらかじめ与えます。

📁 ディレクトリ構造の全体像
🔗 モジュール間の依存関係
⚠️ 変更してはいけない境界（テナント境界など）
🧪 テストカバレッジの範囲
📝 既存のアーキテクチャの意図・ドキュメント

🛠️ Pythonで試す：エージェントに渡すコンテキスト構築の例

実際にPythonでコンテキスト情報を収集して、エージェントへのプロンプトに含める簡単なサンプルを見てみましょう。

import os

def collect_context(root_dir: str, max_depth: int = 3) -> str:
    """エージェントに渡すためのディレクトリ構造を収集する"""
    lines = []

    for dirpath, dirnames, filenames in os.walk(root_dir):
        # 深さを計算して制限
        depth = dirpath.replace(root_dir, '').count(os.sep)
        if depth >= max_depth:
            dirnames.clear()  # これ以上深く掘らない
            continue

        indent = '  ' * depth
        lines.append(f"{indent}📁 {os.path.basename(dirpath)}/")

        # Pythonファイルだけ列挙（関係ないファイルは省く）
        for filename in filenames:
            if filename.endswith('.py'):
                lines.append(f"{indent}  📄 {filename}")

    return '\n'.join(lines)


def build_agent_prompt(task: str, root_dir: str) -> str:
    """エージェントへのプロンプトにコンテキストを含める"""
    context = collect_context(root_dir)

    # まず読ませてから書かせる！がポイント
    prompt = f"""## プロジェクト構造（まずこれを把握してください）
{context}

## 変更してはいけない境界
- `core/tenant/` 配下はテナント分離ロジックのため直接編集禁止
- `migrations/` は自動生成のため手動編集禁止

## タスク
{task}

上記の構造を十分に理解した上で、影響範囲を明示してから変更案を提示してください。
"""
    return prompt


# 使い方
prompt = build_agent_prompt(
    task="ユーザー認証のバリデーションロジックをリファクタリングしてください",
    root_dir="./myproject"
)
print(prompt)

ポイントをまとめるとこんな感じです👇