[AI] AIコーディングエージェントのグッドプラクティスとアンチパターン

Cursor・Claude Code・OpenAI Codex を毎日触っていると、「こう使うなら良い」「こう使うとこういう問題が起きる」 というのが自分の中で溜まってきます。それをユースケース別に整理してみました。このブログ自体も Claude Code で運用していて(前に書いた記事がそれ)、そこで痛い目に遭って学んだことも入っています。

⚠️ 料金・仕様・モデル名は変動が速い領域です。数値は 2026年7月時点の目安として読み、契約や大規模実行の前に各公式ドキュメントで再確認してください。

大原則:コンテキストは有限で高価な資源

エージェント活用の巧拙は、突き詰めると 「コンテキストという有限資源をどう管理するか」 に集約されます。トークンの過剰消費・精度低下・暴走——ありがちな非効率のほとんどは、コンテキストを長く・大きく持ち回りすぎることが原因です。

前提を1つ。エージェントは各ステップ(ファイル読込・編集・コマンド実行・検索)が個別のモデル呼び出しで、それまでの累積コンテキストを毎ステップ丸ごと再送します。つまり扱う対象が増えるほど、トークン消費は線形ではなく二乗的に膨らむ。ここが分かっているかどうかが、以降のグッド/バッドの分かれ目になります。

原則は3つだけ。

1. 1タスク = 1つの明確なアウトカムに絞る(大きいものは分割する)
2. 機械的にできる処理はLLMに渡さず、スクリプトで決定的に処理する
3. 必ず検証(テスト/diffレビュー)とセットで走らせる

以下、ユースケース別に見ていきます。

1. 大規模リファクタ・全体走査

大量のファイルにまたがる変換(命名統一、API移行、パターン置換など)。エージェントが最も輝きそうで、実は最もコストが跳ねやすい領域です。

❌ アンチパターン 「リポジトリ全体をまとめてリファクタして」と、1タスクで丸投げする。

エージェントは「読む → 直す → 次を読む」を延々続け、各ステップで累積コンテキスト(それまで読んだ全ファイル)を再送します。触るファイル数に対してトークンが二乗的に増え、総トークンの大半が「同じコンテキストの再読」で占められる状態に。キャッシュ読みは単価が安くても、実作業量の何倍もの再送が積み上がるので、時間もクレジットも溶けます。おまけに機械的な変換までLLMに任せると、挙動が静かに変わるリスクを人間がレビューしきれません。

ざっくり試算です。ファイル100本・各5K・前提コンテキスト50Kの一括リファクタ:

方式	概算トークン	説明
累積ループ型(丸投げ)	約30M	ステップkで「50K + これまで読んだ全ファイル」を再送
1ファイル = 独立処理型	約5.5M	各回「50K + 対象1ファイル」だけ。50Kはキャッシュ共有可

同じ作業でも 5〜20倍の差が出ます。

✅ グッドプラクティス:codemod-first 変換の性質で3つに分け、機械的な部分はLLMに渡さないのが要点です。

種別	例	対応
① 決定的	リネーム、import整理、API 1:1置換	LLM不使用。codemod / LSP rename / lint —fix
② 規則的だが揺れあり	class component → hooks	LLMには「codemodを書かせる」だけ使い、全体適用。残りだけLLM
③ 意味理解が必要	各関数のエラーハンドリング適正化	1ファイル = 新規コンテキストで独立処理(長い対話にしない)

推奨フロー:

1. LLMで「変換パターン」を確定(サンプル数ファイルで対話、短く)
2. それをcodemodに落とす(機械的な部分はここで9割片付く)
3. codemodを全体適用 → git diff でレビュー
4. codemodで拾えなかった残りだけ、1ファイル = 新規コンテキストでLLM処理

代表的なツールは、言語と変換種別で選びます。ast-grep(言語横断の構造置換)、jscodeshift / ts-morph(JS/TS)、libcst / rope(Python)、comby(言語横断)、LSPの rename、eslint --fix / ruff --fix あたり。

ℹ️ 要は「LLMは変換ルールを見つける頭脳として使い、実際の一括適用は決定的なツールにやらせる」。ここを分けるだけで、コストも安全性も一段変わります。

2. 長時間セッション・コンテキスト管理

❌ アンチパターン 1つの長大なセッションで無関係なタスクを次々こなし、失敗した試行の上に修正を積み重ねていく。

コンテキストが上限に近づくほど、モデルは初期制約を忘れ、要件を読み違え、細部でミスを増やします(いわゆる context rot)。窓が1Mに広がってもこの性質は変わりません。「広いから全部1セッションに詰めればいい」は誤りです。

✅ グッドプラクティス

• 無関係なタスク間では /clear でコンテキストをリセットする
• 2回続けて誤った方向に行ったら、修正を積み重ねず、学んだことを織り込んだ鋭いプロンプトで新セッションを切り直す。 失敗履歴で膨れた長いセッションより、ほぼ常に良い結果になります
• コードベース調査のような大量ファイル読込は、サブエージェント/別コンテキストに逃がし、要約だけを受け取る。メイン会話をクリーンに保てます

このブログで記事を書かせるときも、記事ごとに /clear してから始めるようにしています。前の記事の文脈を引きずると、途端に「それっぽいけど噛み合っていない」出力が増えるので。

3. 指示ファイル(CLAUDE.md / AGENTS.md)

❌ アンチパターン プロジェクトの癖・ルール・背景を、指示ファイルに片っ端から詰め込む。

長すぎる指示ファイルは、モデルが半分を無視し、重要なルールがノイズに埋もれます。しかも毎ターン全行ぶんのトークンを消費し続ける。「多いほど良い」ではなく 「簡潔さが性能要件」 です。

✅ グッドプラクティス

• 200行以内を目安に維持する。先頭にテスト/ビルド/lintの正確なコマンドを置く(いちばんROIが高いセクション)
• linterやformatterが決定的に守れるスタイルルールは書かない(LLMにやらせるのは遅く高価)
• 状況依存の詳細は、サブファイルや skills に逃がして遅延ロードする。指示ファイルは「RAM」、それ以外は「ディスク」と捉える

つい先日、このブログのリポジトリにも AGENTS.md を1本置いて、CLAUDE.md と GEMINI.md はそこへのシンボリックリンクにしました。実体を1ファイルに寄せておくと、どのエージェントを使っても同じルールが効くし、二重メンテもなくなります。

4. タスクの投げ方(計画とスコープ)

❌ アンチパターン スコープを切らずに「◯◯を調べて」「これを実装して」といきなり編集まで走らせる。

範囲を絞らない「調査」は数百ファイルを読み込み、コンテキストを氾濫させます。あるいは的外れな実装を全速力で進め、気づいたときにはもうディスクに書き込まれている。

✅ グッドプラクティス

• 3ステップ以上/設計判断を伴うタスクは、先に計画だけ立てさせて人間がレビューしてから実行に移す(各ツールのPlan mode)。「30秒の計画が30回のエージェントループを防ぐ」。計画変更はタダ、コード変更は数時間
• 1タスク = 1アウトカムに絞る。プロジェクト全体を1タスクに投げない
• 曖昧なタスクは「逆インタビュー」——先にエージェントに質問させて仕様を固める——も有効

5. 検証

❌ アンチパターン それらしく動きそうな出力を、実行もレビューもせずに受け入れ、マージする。

エージェントは「もっともらしいが端のケースを外した」コードを、自信満々に出してきます。検証しないまま取り込むと、静かなバグが混入する。

✅ グッドプラクティス

• テスト/型チェック/lint/diff目視を Definition of Done に含める
• 大きめの変更はTDD的に。先に失敗するテストをcommit → 「テストを通すまで実装(テスト自体は変更禁止)」と指示 → 人間が検証ループを回す
• 実装後、diffだけを新しいコンテキストのレビュアー(別サブエージェント等)に渡して評価させると、生成時の思考に引きずられず独立チェックできる

6. モデル選択とコスト

モデル階層(mini / medium / 上位など)の違いは、「トークン単価が変わるだけ」ではありません。 上位モデルほど、大規模な文脈の保持、あいまいな失敗からの推論、多段階の計画、アーキテクチャ的判断、長時間の一貫性、想定外の状態からの復帰、といった能力が質的に高い。だから選び分けは「コスト最適化」であると同時に、「品質を落とさないための判断」でもあります。

❌ アンチパターン その1:全部を上位モデル・高effortで回す

reasoning effort を最上位にすると、同じ作業でも3〜5倍のトークンを消費します。補完や定型作業に上位モデル + 最高effortは過剰で、品質は上がらないままコストとレイテンシだけ増える。

❌ アンチパターン その2:難しいタスクを節約目的で軽量モデルに投げる

設計判断・大規模移行・込み入ったバグを、コスト削減のために mini 級に任せる。軽量モデルは長い文脈の一貫性やあいまいさの解決が弱く、「もっともらしいが破綻した」出力を返しがちです。これは遅いのではなく質的に失敗するので、手戻りでかえって高くつく。「トークン量だけの問題ではない」核心がここです。

✅ グッドプラクティス:タスクの難易度にモデルの能力を合わせる

モデル名は頻繁に変わるので、あくまで2026年時点の目安として:

タスクの性質	向く階層	例
補完・ボイラープレート・定型変換・高volume・サブエージェントの実行役	高速/軽量	Claude Haiku, GPT mini系, Gemini Flash
日常のコーディング、テスト作成、小〜中規模リファクタ	汎用/中位	Claude Sonnet, GPT mid / Codex系
アーキテクチャ設計、大規模移行、難バグ、計画・スコープ策定・コードの批評	上位/推論	Claude Opus, GPT-5.5, Gemini Pro

上位モデルを使うべきサイン:正解が一意でない/複数ファイルに整合性が要る/要件があいまいで解釈が要る/長時間の自律実行で一貫性が要る/判断が下流に波及する(計画・設計)。 軽量モデルで十分なサイン:変換規則が明確/対象がローカルで閉じている/大量に同種処理を捌く/レイテンシが最優先(インライン編集)。

マルチエージェントの定石は、「強いモデルで計画し、安いモデルで実装」。判断が下流に波及する部分(計画・調整・レビュー)に上位モデルを充て、量の出る実装や大量のファイル操作は軽量モデルに流す。サブエージェント(子)に軽量モデルを割り当てるのが、コスト対効果の良い定番です。

2つのレバーは別物として扱うのがコツ:

• モデル階層(軽量 ↔ 上位)= 到達できる知能の天井
• reasoning effort(low ↔ xhigh)= 同一モデル内で思考にどれだけトークンを使うか。既定は medium で、high / xhigh は本当に難しいときだけ

そして忘れがちな前提。よく練られたプロンプト + 中位モデルは、雑な指示 + 上位モデルにしばしば勝ちます。 迷ったら「まず上位モデル」ではなく「まずタスクを明確化」。モデル選択よりタスク定義のほうが効くことが多いです。

その他、コスト面のメモ:

• Cursorではルーチンを Auto mode に寄せる(低コストモデルを自動選択し、クレジットプールを消費しない)
• 一部モデルは入力が一定量(例:gpt-5.5 は272Kトークン)を超えるとセッション全体の単価が上がる。巨大コンテキストの常用は料金面でも不利
• 使用状況ダッシュボードを常時可視化し、想定外の消費を早期に検知する

7. 権限・セキュリティ

❌ アンチパターン 本番クレデンシャルのあるリポジトリで、確認なしの全自動モードでエージェントを放牧する。

危険なコマンド実行、意図しないファイル改変、シークレット露出のリスク。エージェントは有用な操作と危険な操作を必ずしも区別しません。

✅ グッドプラクティス

• deny rules / allowlist / sandbox を先に設定してから走らせる
• Claude Codeは deny を先に評価するので、.env や secrets を deny に入れるとモデルから「見えなく」なり、Hookでブロックするより安全
• Codexは確認モード(Suggest)から始め、信頼できるリポジトリだけ auto-edit / full-auto に緩める
• 秘密情報のフィルタリングは、ゲートウェイやCIの層でも検討する

ツール別クイックリファレンス

Cursor

• エージェントの各ツール呼び出しが、個別のモデル呼び出しとして課金される。標準モードは25 tool call、Max Modeは200 tool callで truncation を解除し全コンテキストを使う(= 走査系で消費が跳ねやすい)
• .cursor/rules は alwaysApply: false とglob指定で、必要なときだけロードする
• Auto / Composer を既定に、フロンティアモデルは判断所だけ手動選択。Max Modeは「本当に広い文脈が要る」ときだけ

Claude Code

• CLAUDE.md を毎セッション先頭で自動ロード。200行以内、先頭にコマンド
• サブエージェント(.claude/agents/)は独立コンテキスト。汎用より機能特化が良い
• /clear(タスク間リセット)、/compact(要約圧縮)、Plan mode(編集前に計画)を使い分ける

OpenAI Codex

• CLI / IDE拡張 / アプリの3サーフェスが同一設定(AGENTS.md・skills・MCP)を共有。AGENTS.md はルートから近いファイルが優先、上限あり(既定32KiB)
• AGENTS.md のテストコマンドは「完了」の定義として実行されるよう学習されている。TDDと好相性
• サンドボックスは Suggest → auto-edit → full-auto と段階的に緩める。/plan で計画先行

チーム運用チェックリスト

最後に、コードレビューや自分の運用で見返せるよう、チェックリストの形にまとめておきます。

• 一括系タスクは「まずスクリプト化を検討 → 無理な部分だけLLM」をレビュー観点に入れる
• CLAUDE.md / AGENTS.md を200行以内で維持し、先頭にテスト/ビルド/lintコマンド
• 「1タスク = 1アウトカム」をルール化し、全体を1タスクに投げない
• 3ステップ以上のタスクは計画先行(Plan mode)
• タスク難易度にモデル階層を合わせる(計画・難所は上位、定型・高volumeは軽量)
• 検証(テスト/型/lint/diff目視)なしのマージを禁止
• シークレットは deny / allowlist / sandbox で先に囲う
• 使用状況ダッシュボードを常時可視化する

まとめ

細かい話をいろいろ書きましたが、効いてくるのは結局この3つです。

• コンテキストを小さく保つ(1タスク=1アウトカム、無関係な話は /clear)
• 機械的な処理はLLMに渡さない(codemodやlintで決定的に)
• 検証とセットで走らせる(diffと計画は人間が握る)

丸投げして最強モデルに全部やらせる、が一番コストも事故も増える。判断と検証は人間が持って、速さと手数をエージェントに任せる。 この役割分担は、このブログを Claude Code で運用してみた話とまったく同じ結論でした。

参考リンク

• Claude Code ベストプラクティス
• OpenAI Codex ガイド(AGENTS.md)
• Cursor 料金・モデル

⚠️ 料金・context上限・モデル名・プラン構成は各社とも頻繁に変わります。本記事の数値は目安とし、契約や大規模実行の前に必ず公式で再確認してください。