Claude Code/Codexで失敗する5つの理由と回避策

結論: Claude Code / Codexで失敗する理由はタスク設計にある

この記事でいうAIエージェントは、主に Claude Code / Codex のように、ファイルを読み、編集し、コマンドを実行するコーディングエージェントを指します。便利な一方で、曖昧な依頼をすると曖昧なまま手を動かします。

この記事では、個人開発でよく起きる失敗を、実務で直せる形に分解します。

失敗1: Claude Code / Codexにコンテキストを詰め込みすぎる

何が起きるか

「関連しそうな資料を全部渡す」「過去ログを丸ごと貼る」「巨大な仕様書を読ませる」という使い方をすると、AIエージェントは本当に重要な制約を見失いやすくなります。

その結果、次のような症状が出ます。

• 重要な要件を読み落とす
• すでに説明した制約を破る
• 関係ないファイルまで編集する
• 会話が長くなり、修正のたびにコストが増える

回避策

コンテキストは「多いほど良い」ではなく、「作業に必要な範囲だけ」が基本です。

今回渡す情報:
- 実装対象のIssue
- 関連ファイル候補
- 変更してよい範囲
- 変更してはいけない範囲
- 検証コマンド

渡さない情報:
- 過去の雑談ログ
- 関係ない設計メモ
- 解決済みの古いエラー

迷ったら、まずは「調査だけ」を依頼します。

このタスクに必要な関連ファイルだけを調査してください。
まだファイルは変更しないでください。
出力は、関連ファイル、現在の処理フロー、変更候補、リスクに分けてください。

失敗2: AIエージェントに渡すタスク粒度が大きすぎる

何が起きるか

「決済機能を作って」「管理画面をいい感じにして」のような依頼は、AIエージェントにとって範囲が広すぎます。作業範囲が広いほど、設計判断・UI判断・DB判断・セキュリティ判断が混ざり、途中で破綻しやすくなります。

良い粒度 / 悪い粒度

悪い粒度:

ユーザー管理機能を作ってください。

良い粒度:

ユーザー一覧ページに、表示名で絞り込む検索フォームを追加してください。
変更対象は src/pages/users と関連テストのみです。
DBスキーマ、認証、権限ロジックは変更しないでください。

1回の依頼は、理想的には「1つの小さなPR」に収まる粒度にします。

失敗3: テスト無しでClaude Code / Codexに任せる

何が起きるか

AIエージェントは、検証手段がないと「見た目上それらしいコード」を完了扱いにしがちです。人間がレビューするまで壊れていることに気づけないため、後戻りのコストが増えます。

回避策

依頼文に検証方法を必ず含めます。

完了条件:
- npm run build が通る
- npm test が通る
- 追加した挙動のテストを1つ追加する
- 失敗した検証がある場合は、失敗理由を隠さず報告する

テストが存在しないプロジェクトでは、いきなり大きな実装を任せる前に、まず「壊れたことに気づける最小テスト」を作らせます。

失敗4: AGENTS.mdなしで権限境界が曖昧

何が起きるか

AIエージェントはローカルファイルやターミナルにアクセスできるため、便利な反面、危険なファイルも触れてしまいます。

特に避けたい領域は次の通りです。

• .env や秘密鍵
• 本番DB接続情報
• 認証・権限・決済まわり
• デプロイ設定
• 大量ファイルの一括整形

回避策

依頼文に「触ってよい範囲」と「触ってはいけない範囲」を書きます。

変更してよい範囲:
- src/components/SearchForm.tsx
- src/pages/products.tsx
- 関連テスト

変更してはいけない範囲:
- .env*
- prisma/schema.prisma
- 認証処理
- 決済処理
- package.json の依存追加

さらに、プロジェクトルートに AGENTS.md や CLAUDE.md を置き、毎回守るルールとして固定します。

失敗5: 料金・コスト監視をしていない

何が起きるか

AIエージェントは、長い会話、巨大なファイル読み込み、失敗したテストの繰り返しでコストが膨らみます。特に「同じエラーを直し続ける」状態になると、時間と料金の両方を失います。

回避策

同じエラーが2回続いたら、修正を止めて原因分析に切り替えます。

同じエラーが2回続いた場合:
- それ以上コードを変更しない
- エラーの原因仮説を3つ出す
- 追加で確認すべきファイルを列挙する
- 次に試す最小変更を1つだけ提案する

API従量課金で使う場合は、月次上限・アラート・プロジェクト単位の利用ログを先に決めておきます。

まとめチェックリスト

• 1タスクあたり渡すコンテキストを絞っている
• タスク粒度が「1PR分」に収まっている
• テストまたはビルドで失敗を検知できる
• 触ってよいファイルとダメなファイルを分けた
• 同じエラーが続いた時の停止ルールがある
• 月次コスト上限またはアラートを設定した

次に読む

• AIエージェントに実装を任せる前に書くべき指示テンプレート
• LLMアプリのAPIコスト高騰を防ぐ、コンテキスト管理と節約設計
• MCPとhooksを入れる前に決める、AIエージェントの安全境界