AIエージェントが「知っているはず」を間違える理由 — コンテキスト設計の実務

Claude CodeやCursorでエージェント開発を毎日している人なら、必ず経験する現象がある。昨日はできていたのに、今日は同じことを頼んでもできない。「もう一度やってみてください」と念押しすると動く。これをモデルの気まぐれだと思いがちだが、実は構造的な問題だ。指示を足すほど、他の指示は薄まる。エージェントに与える情報はすべて1つの入力列に平坦化される。その中で各トークンが受ける「注意」の総量は有限だ。500行のCLAUDE.mdに書いた1行は、50行に書いた1行より確実に弱い。Anthropicの公式ドキュメントも「CLAUDE.mdは200行を目安に」と明記している。それを超えた分は、書いた本人が思っているほど効いていない。

さらに厄介なのは、指示書に書いてあるルールが、セッションの途中で静かに消えることだ。ルート直下のCLAUDE.mdは/compact後も再読込されるが、ディレクトリ単位の局所規約は消える。長いセッション終盤で「なぜかこのディレクトリだけ規約が守られない」が起きるのは、そのルールが今この瞬間コンテキストに載っていないからだ。モデルが気まぐれなのではなく、コンテキストの構造に問題がある。対策は、情報を変化の速度で3層に分けることだ。不変層（組織の基本方針）・構造層（ファイル配置やレイヤー設計）・作業層（今週のバグ修正）。ルートのCLAUDE.mdには不変なものだけ書き、局所規約は消えることを前提に設計する必要がある。

複数ツール（Claude Code・Cursor・Copilot）を組み合わせると、規約が分裂する。手で管理すればズレる。最終的な解決策は、規約をドキュメントではなくビルド成果物として扱うことだ。マスタから自動生成すれば、更新漏れも矛盾も起きない。エージェント運用の成熟度は、プロンプトの工夫ではなく、コンテキストの設計力で決まる。「書いてある」と「効いている」の差を埋めることが、組織でAIを安定稼働させるための最初の関門だ。