先に結論
コーディングエージェントはCLIが使えても、プロジェクトの全てを理解しているわけではない。
人間の新任SEと同じで、前提と場所（what・where）が示されなければ簡単に迷子になり、誤った作業を進めてしまう。
だから、最低限「何をやるか」と「どこを触るか」を人にもAgentにも明示しよう。
なぜこの記事を書いたか
同僚にこんなことを言われた。
「コーディングエージェント(codex CLI)ってCLI使えるんですよね？
じゃあ、ファイルの場所とか教える意味なくないですか？」
正直、かなり違和感を覚えた。というか、物凄くむっとした。
この違和感の正体を言語化したくて、この記事を書いている。
よくある誤解：コーディングエージェント全知全能説
最近よく見かける誤解がこれ。
- CLIが使える
- ファイルを検索できる
- コードを読める
だから 「プロジェクトの全体像を勝手に理解して正しく実装してくれる」 と期待してしまう。だが、これは完全に間違いだ。
人に置き換えてみると何が起きるか
コーディングエージェントを「人」に置き換えてみるとわかりやすい。
全ては雑なマネージャーの指示のせい...
CLIが使えるAgentを「PJの全体を理解している存在」として扱うと、この構図がそのまま再現される。
なぜそれが起きるのか（Agentの構造的限界）
1. コンテキストウィンドウの物理的制限
AIモデルにはコンテキストウィンドウというトークン数の上限があり、会話が長くなるほどプロンプトも長くなる
👉 https://openai.com/index/unrolling-the-codex-agent-loop/
この上限には入力と出力の両方が含まれ、中規模以上のプロジェクトでは全てのコードや規約を読み込むだけで簡単に埋まってしまう。
OpenAIのCookbookでも、長いやり取りでは過去の履歴や冗長なツール結果がコンテキストを圧迫し、エージェントが効率や正確さを失うため、コンテキスト管理が必須であると説明している
👉 https://cookbook.openai.com/examples/agents_sdk/session_memory
2. セッション間で情報が自動的に引き継がれない
多くのコーディングエージェントはセッションごとに独立した状態で動作する。セッションを切り替えると、それまでの会話や操作履歴がリセットされるので、以前の文脈を引き継ぐことはできない。
-
Codex CLI — OpenAIは「履歴を保持して作業を再開したい場合は
resumeサブコマンドを使え」と説明している。Codexは会話のトランスクリプトをローカルに保存しているが、codex resumeで明示的にセッションを再開しない限り、新しい会話はゼロから始まる
👉 https://developers.openai.com/codex/cli/features/#resuming-conversations -
Claude Code — Anthropic製のCLIでも、セッションは自動で引き継がれない。公式ドキュメントでは、Claude Code のセッションは ephemeral（一時的）であり、新しい実行は毎回「fresh（まっさら）」な状態から始まると説明されている。
そのため、前回の作業内容やプロジェクトに関する理解はセッションを跨いで保持されない。作業を継続したい場合は、resume / continue といった明示的な操作が必要になる。
👉 https://code.claude.com/docs/en/how-claude-code-works#work-with-sessions -
Cursor — Cursor では、チャットを新規作成（セッションリセット）すると start fresh となり、過去の文脈は自動では引き継がれないことが公式フォーラムで説明されている。
👉 https://forum.cursor.com/t/if-i-change-a-model-will-the-new-model-know-the-previous-context/43939?utm_source=chatgpt.com
このように、Codex CLI・Claude Code・Cursor いずれもデフォルトではセッションを跨いだ保持はしない。継続的な会話を望む場合は同一セッション内で対話することが基本線である
また、セッションを跨ぎたい場合はメモリ機能、外部ファイルなどで状態を引き継ぐ工夫が必要になる。
つまり、セッションを跨ぐということは毎回新任SEがプロジェクトに初参加してくるのと同じで、前提知識が無ければ迷子になって当然だ。
3. Agentは止まらない
エージェントは「指示されたタスクを完遂するためにループを回し続ける」ように設計されている。Codexのエージェントループでは、モデルがツール呼び出しを要求しなくなるまでツールを呼び出し、結果を再びプロンプトに追加し続ける仕組みが説明されている
👉 https://openai.com/index/unrolling-the-codex-agent-loop/
つまり、方向が誤っていても止まらずに突き進むため間違った指示を与えるとそのまま実行されてしまう。
💀CLIの実行権限をAgentに委譲してる場合は特に💀
じゃあどうすればいいのか
答えはシンプルだ。
5W1Hのうち、最低限 「what（何をするか）」と「where（どこを触るか）」を明示すること である。
Agent は魔法使いではない。
実装フェーズに入った瞬間、Agent が最初にやる仕事はほぼ必ず
「このプロジェクトで、どこを読めばいいのか？」という 探索 だ。
この探索を人間側が肩代わりし、
「what（やりたいこと）」と「where（触る場所）」をセットで渡すことで、
- 無駄なリポジトリ探索を減らせる
- 修正箇所の取り違えを防げる
- コンテキストウィンドウを本来の思考に使わせられる
という効果が出る。
この設計思想が最も分かりやすく現れているのが Agent Skills だ。
Skills は「自己能力獲得」の話ではなく、
- what：この Agent は何をするのか
- where：どの知識・手順・ファイルを参照するのか
を明示的に分離し、それを数珠つなぎにすることで
トークン効率と再現性を最大化する仕組み になっている。
つまり、Skills が示している本質は
「Agent に能力を与えること」ではなく、
「what と where を明示すれば、Agent は迷わず動ける」 という点にある。
この原則は、Skills に限らず
通常の実装 Agent においてもまったく同じだ。
👉https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills
人にもAgentにも効く「良い指示」の例
丁寧なマネージャーは人を幸せにする✨
運用方法は何でもいい
-
AGENTS.mdに書いて渡してもいい。 - ファイルやMCPを記憶補助として使ってもいい。
- タスク指示に具体的に記載してもいい。
重要なのはただ一つ、指示内容に対して「what」と「where」が分かるかどうかを常に確認することだ。
最後に
エージェントは魔法ではない。人間相手でも起きる事故は、エージェント相手でも普通に起きる。だからこそ、what と where を渡そう。
私は、雑なマネージャーが大嫌いです。