Source: https://aiprimetech.io/ja/blog/claude-code-cli-guide/ 2026年19日（6月） · 6分 · ツール # Claude CodeとターミナルAIコーディングツールの新たな波 A 著者 [AI Prime Tech](https://aiprimetech.io/ja/) · AI支援による執筆 午前2:13時、私はターミナル上のコーディングエージェントが「失敗しているテストを直すだけ」のために、1.8百万もの入力トークンを費やすのを見ていました。実際のバグは、三行のスキーマの不整合でした。エージェントの能力が低かったのではなく、制約の与え方が不適切だったのです。エージェントはリポジトリを何度も読み直し、広範囲のテストコマンドを繰り返し実行し、巨大なスタックトレースをモデルに貼り戻し、必要な箇所だけの差分で済むのにファイル全体の書き直しを求め続けていました。 この出来事をきっかけに、私はCLIコーディングエージェントの運用方法を変えました。 Claude Code、Aider、Cline、OpenCodeのようなツールは、単に git diff ボタンが付いたチャットボットではありません。シェル、エディター、ファイルシステム、時にはブラウザーを取り巻く、API駆動の制御ループです。特にClaude Opus 4.8、Sonnet 4.6、GPT-5.5、Gemini 3のような高性能モデルや、Fable 5のような長いコンテキストを扱うシステムと組み合わせると、生産性を大きく高められます。その一方で、単一ターンのAPI呼び出しに慣れたチームが驚くほどの速度で、気づかないうちにトークンを消費することもあります。 この記事では実践的な観点から、ターミナル型コーディングエージェントが実際に何をするのか、モデルAPIをどう使うのか、エージェントの反復ループがトークンのコスト構造をなぜ変えるのか、そして長時間のセッションが高額な見せかけの作業に終わらず、有用であり続けるように私がどう設定しているのかを説明します。 ## CLIコーディングエージェントの実体 ターミナル上のコーディングエージェントは通常、五つの要素を組み合わせたものです。 - 最先端モデルまたはオープンモデルとのチャットループ - リポジトリのインデクサーまたはファイル探索レイヤー - シェルコマンドとファイル編集のためのツール実行レイヤー - パッチ適用の仕組み - 会話履歴とセッション状態のための永続化レイヤー 自動補完との決定的な違いは、自律的に行動できることです。自動補完はカーソル位置のコードを予測します。エージェントは、ファイルを調べ、テストを実行し、コードを変更し、失敗を調査して、反復することを自ら判断できます。 典型的なループは次のようになります。 ``` User task ↓ Agent builds prompt from instructions + repo context + prior messages ↓ Model proposes actions: read file, edit file, run command ↓ CLI executes allowed actions ↓ Results are added back into context ↓ Model plans next step ↓ Repeat until done or stopped ``` このループこそが、こうしたツールを強力だと感じさせる理由です。同時に、コストとレイテンシーが、通常の「一つ質問して、一つ回答を得る」APIの使い方とは異なる挙動を示す理由でもあります。 実際には、予想外のコストの大半はフィードバック経路から生じます。コマンド出力、ファイル内容、過去のメッセージ、差分が、後続のターンに繰り返し含まれるためです。 ## Claude Code、Aider、Cline、OpenCode：同じパターンの異なる形 ツールごとに操作スタイルは異なりますが、基本的な設計パターンは似ています。 | ツール | 主な操作環境 | 代表的な強み | よくあるコストリスク | Claude Code | ターミナルに特化したエージェント | シェルとリポジトリを密接に連携させたワークフロー、強力な計画・編集ループ | 長時間の自律的なセッションによるコンテキストの蓄積 | Aider | Gitを認識するCLIペアプログラマー | 差分を中心とした編集、対象ファイルの明示的な指定 | コンテキストへの過剰なファイル追加 | Cline | エディター中心のエージェント | VS Codeとの統合、ツール使用の可視化 | 大量のターミナル出力やブラウザー出力のコンテキストへの取り込み | OpenCode | ターミナルとエディターでのエージェントワークフロー | モデル選択の柔軟性とローカルワークフローの制御 | プロバイダーの設定ミスや広範囲のリポジトリ走査 重要な違いは「どれが最も賢いか」ではありません。ツールがどれだけのコンテキストを送信するか、ファイルをどう選択するか、履歴をどう要約するか、そしてシェル実行をどれだけ制御できるかです。 たとえばAiderは、関連するファイルを意図的に追加すると、うまく機能する傾向があります。Claude Codeはより自律的で、リポジトリ内を動き回るシニアエンジニアのように感じられることもありますが、その自律性ゆえに、権限と作業範囲を慎重に設定する必要があります。Clineはエディター内で使うのに便利で、特に操作を見守りたい場合に適していますが、エディターでの便利さが、高コストな手順を承認しすぎることにつながる場合があります。 OpenCode型のワークフローは、プロバイダーを柔軟に選びたいチームに魅力的です。難しいアーキテクチャ設計にはClaude、実装にはGPT、大量のコンテキストの調査にはGemini、低コストなローカル処理やセルフホストでの処理にはQwen、DeepSeek、Kimi、MiniMax、Llamaのようなオープンモデルを使用できます。 ## これらのエージェントがAPIをどう使うか 「このバグを修正して」という依頼ひとつが、数十回のAPI呼び出しにつながることがあります。 エージェントの各ステップで使うリクエストボディを簡略化すると、次のようになります。 ``` { "model": "claude-sonnet-4.6", "messages": [ { "role": "system", "content": "You are a coding agent. Follow repo instructions. Use tools safely." }, { "role": "user", "content": "Fix the failing invoice total test." }, { "role": "assistant", "content": "I will inspect the test and related invoice code." }, { "role": "tool", "name": "read_file", "content": "tests/test_invoice_totals.py contents..." } ], "tools": [ { "name": "read_file" }, { "name": "apply_patch" }, { "name": "run_shell" } ] } ``` 実際の実装はさまざまですが、基本的なパターンは共通しています。 - CLIがコンテキストを収集します。 - モデルが次の操作を決定します。 - CLIがその操作を実行します。 - 結果がモデルに戻されます。 - モデルが処理を続けます。 ツールをモデルに公開する方法は、通常、大きく分けて二通りあります。 ### テキストベースのツールプロトコル 一部のエージェントは、モデルに構造化されたテキストを出力させます。 ``` RUN: pytest tests/test_invoice_totals.py -q ``` CLIがそれを解析して実行します。この方法はシンプルで移植性に優れていますが、壊れやすい面もあります。モデルがコマンドを変則的な形式で出力した場合に備え、実行基盤にはガードレールが必要です。 ### ネイティブの関数呼び出し ほかのエージェントは、モデルAPIのツール呼び出しや関数呼び出しを使います。モデルは、構造化されたツール呼び出しを返します。 ``` { "tool_name": "run_shell", "arguments": { "command": "pytest tests/test_invoice_totals.py -q", "timeout_seconds": 60 } } ``` こちらは検証しやすい方法です。エージェントは、危険なパターンに一致するコマンドを拒否したり、ネットワークアクセスに承認を求めたり、書き込み先をワークスペース内に制限したりできます。 どちらの設計でも、コストがかかるのはシェルコマンドそのものではありません。そのシェルコマンドを取り巻く、増え続けるプロンプトです。 ## エージェントのループがトークンのコスト構造を変える理由 通常のAPI連携では、入力トークンを2,000、出力トークンを500やり取りする程度かもしれません。エージェントによるコーディングセッションでは、次のような流れになることがあります。 | ステップ | 起きること | 入力トークンの傾向 | 出力トークンの傾向 | 1 | ユーザーが修正を依頼 | 少量 | 計画 | 2 | エージェントがファイルを読む | 中程度 | ツールへのリクエスト | 3 | エージェントがコードを編集 | 中程度から多量 | パッチ | 4 | テストが失敗 | ログ全体を含めると多量 | 原因の診断 | 5 | エージェントがさらにファイルを読む | 履歴により増加 | ツールへのリクエスト | 6 | エージェントが再試行 | さらに増加 | パッチ | 7 | テスト全体を実行すると別の箇所で失敗 | 生の出力をそのまま貼り付けると非常に多量 | 要約・切り分け 注意点は、入力トークンが大半を占めることが多いということです。各ループで、システム指示、会話履歴、選択されたファイル、ツールの出力、要約が再送信される場合があります。キャッシュやコンテキスト圧縮を使っても、長時間の自律的なセッションは高額になりかねません。モデルが状況を把握せずに行動するのを避けるには、十分な状態情報が必要だからです。 トークン数を膨らませる要因には、よく見られるものが四つあります。 - ファイル全体のコンテキスト：関係するのは二つの関数だけなのに、900行のファイルを送信すること。 - 冗長なテスト出力：依存関係の警告、進捗バー、無関係な失敗を含めること。 - 繰り返されるリポジトリのスキャン：次のコマンドを実行し、 find, tree、または rg 広範囲にわたる出力を再びコンテキストに取り込むこと。 - 際限なく増える会話履歴：判断を要約する代わりに、失敗した試みをすべて保持すること。 混乱したセッションで実際に起きているのは、「エージェントがより深く考えている」ということではありません。多くの場合、古くなったコンテキストがより多く見えているだけです。重要な情報が埋もれると、トークンが増えることでモデルの動作が遅くなり、精度も下がることがあります。 ## 考え方：プロンプト単位ではなく、ループ単位で予算を考える 私は費用を見積もるとき、ループ単位で考えます。 小規模で対象が明確なタスクは、次のようになるかもしれません。 ``` 8 turns × 12k input tokens average = 96k input tokens 8 turns × 1.5k output tokens average = 12k output tokens ``` 方向が定まらないタスクは、次のようになるかもしれません。 ``` 35 turns × 55k input tokens average = 1.9M input tokens 35 turns × 3k output tokens average = 105k output tokens ``` ユーザーのプロンプトは同じでも、コスト構造は大きく異なります。 問題の構造を理解するのに、正確な料金は必要ありません。エージェントのセッションの規模は、次の要素に応じて大きくなります。 ``` total cost ≈ Σ(input_tokens_per_step × input_price) + Σ(output_tokens_per_step × output_price) + tool/runtime overhead ``` 出力トークンは、エージェントが文字を出力する様子を見るため、目に見えます。入力トークンはCLIが組み立てるため、見えません。予算管理が重要なのは、この見えない側です。 ## エージェント作業に使うモデルの選び方 私は、すべての作業に同じモデルを使うことはほとんどありません。 ターミナルエージェントでは、作業段階に合ったモデルを選ぶべきです。 | 作業段階 | 最適なモデルの種類 | 理由 | リポジトリの事前調査 | 長いコンテキストに対応するモデル、または低価格で十分な能力を持つモデル | 完璧な編集ではなく、幅広い読み取りが必要 | アーキテクチャの決定 | 推論能力の高いモデル | トレードオフの判断が必要 | パッチの生成 | コーディング能力の高いモデル | 正確な差分が必要 | テスト失敗の切り分け | 高速な中位モデル | パターン照合で対応できることが多い | 機械的なリファクタリング | ガードレールを備えた低価格モデルまたはオープンモデル | 反復的で検証可能な作業 実用的な構成では、大半のコーディングにSonnetクラスのモデル、難しいデバッグや設計にOpus/GPT-5.5クラスのモデル、大規模な調査にGemini/Fable系の長いコンテキストに対応したモデル、ローカルでのlintのようなリファクタリングにオープンモデルを使うことが考えられます。具体的な名前は変わっても、この使い分けは有効です。 よくある間違いは、ループ全体に最も高価なモデルを使うことです。そうすると、高価なモデルが割高なトークンを費やして読み込むのは、 node_modules周辺のノイズやテストの警告、生成ファイルです。最も能力の高いモデルは、それを本当に必要とする判断のために取っておきましょう。 ## 効果のある設定のヒント 最適な設定は「最大限の自律性」ではありません。「限定された権限で、すばやくフィードバックを得ること」です。 ### 1. 生成ファイルとベンダーファイルを除外する どのコーディングエージェントにも、除外リストが必要です。まずは、検索やレビューから除外しているものと同じものを指定しましょう。 ``` node_modules/ dist/ build/ coverage/ .venv/ __pycache__/ target/ vendor/ *.lock *.min.js *.map ``` 依存関係の解決が関わるタスクでは、私は通常、ロックファイルを全体的な除外対象にはしません。ただし、デフォルトのコンテキストからは除外します。必要なときに、ロックファイルを明示的に取り込めます。 ### 2. テストコマンドの対象を絞る 反復のたびに、エージェントがデフォルトでテストスイート全体を実行しないようにしましょう。段階的に実行するコマンドを用意します。 ``` # First loop: fastest relevant test pytest tests/billing/test_invoice_totals.py -q # Second loop: nearby package pytest tests/billing -q # Final confidence check pytest -q ``` JavaScriptまたはTypeScriptの場合： ``` pnpm test invoice-total.test.ts -- --runInBand pnpm lint src/billing pnpm test ``` 狙いは実行時間の短縮だけではありません。出力が小さくなれば、次のループのプロンプトも小さくなります。 ### 3. コマンド出力に上限を設ける エージェントが出力制限に対応しているなら、それを使いましょう。対応していなければ、自分でコマンドをラップします。 ``` pytest tests/billing -q 2>&1 | tail -120 ``` 出力の多いビルドでは、次のようにします。 ``` pnpm test 2>&1 | grep -E "FAIL|Error|Expected|Received|at " | head -200 ``` 注意が必要です。フィルタリングによって、有用なコンテキストが隠れることがあります。私は最初の失敗の後にこれを使います。失敗する前には使いません。まず失敗の様子を把握し、その後で繰り返し実行する際の出力を制限します。 ### 4. 書き直しではなく差分を求める 大きなファイルについては、エージェントに明示的に次のように伝えましょう。 ``` Make the smallest safe patch. Do not rewrite unrelated functions. Show a concise diff summary before running tests. ``` これによりリスクが減り、通常は出力トークンも減ります。さらに重要なのは、コードレビューを無理なく行える状態に保てることです。 ### 5. 計画と実行を分ける ある程度複雑な変更では、私はよく次のように始めます。 ``` Inspect the relevant files and propose a plan. Do not edit yet. Limit repo inspection to payment, invoice, and tax modules unless needed. ``` その後、計画を承認し、実装を任せます。これにより、「エージェントが理解する前に編集してしまう」という失敗パターンを避けられます。 ## 長時間のセッションで支出を管理する 長時間のセッションは、CLIエージェントが真価を発揮する場であり、危険も伴う場です。 実際の作業で私が使っている支出管理のチェックリストは次のとおりです。 - セッションの目標を設定する：「 test_invoice_rounding を通す」を目標にし、「課金を修正する」のような目標にはしません。 - 可能な限り対象ファイルを指定する：すべてをエージェントに探させるのではなく、正確なパスを渡します。 - 方針転換後はコンテキストをリセットする：タスクが変わったら、要約を添えて新しいセッションを始めます。 - 失敗を手動で要約する：3,000行のログ全体ではなく、重要な30行を貼り付けます。 - 意図的に上位モデルへ切り替える：明確な障害に直面した場合にのみ、より高性能なモデルを使います。 - 同じループを繰り返したら止める：エージェントが同じように二度失敗したら、介入します。 適切なリセット用プロンプトは、次のようなものです。 ``` We are fixing invoice rounding. Known facts: - Failure is in tests/billing/test_invoice_totals.py::test_round_half_even - Expected 10.24, actual 10.25 - Decimal quantization happens in src/billing/money.py - Tax calculation calls round_money() from src/billing/tax.py Continue from this summary. Inspect only those files first. ``` このようなプロンプトは、失敗した会話全体を引きずるよりも、コストを抑えられ、内容も明確になる場合があります。 ## APIキー、プロバイダー、ルーティング ほとんどのCLIエージェントは、モデルプロバイダーのAPIと直接通信することも、互換性のあるゲートウェイを経由することもできます。エンジニアリング上の主な検討事項は次のとおりです。 - 認証：APIキーの保存場所と、シェルの履歴やログに漏れる可能性。 - モデルのルーティング：どのモデルがどのフェーズを担当するか。 - レート制限：エージェントのループでは、短時間にリクエストが集中することがあります。 - 可観測性：セッションごとのトークン使用量とコストのレポート。 - データの境界：コードを外部APIに送信してよいかどうか。 最小限の環境設定は、多くの場合、次のようになります。 ``` export ANTHROPIC_API_KEY="..." export OPENAI_API_KEY="..." export GEMINI_API_KEY="..." ``` チームでは、モデルの選択と使用量の記録を行うラッパースクリプトを使うのが私の好みです。 ``` #!/usr/bin/env bash set -euo pipefail export AGENT_MODEL="${AGENT_MODEL:-sonnet}" export AGENT_MAX_OUTPUT_TOKENS="${AGENT_MAX_OUTPUT_TOKENS:-4096}" export AGENT_SESSION_BUDGET_USD="${AGENT_SESSION_BUDGET_USD:-10}" coding-agent "$@" ``` 複数モデルに対応したゲートウェイを使う場合は、Claude、GPT、Gemini、オープンモデルへの通信を共通のインターフェースでルーティングすると便利です。重要なのはロゴの一覧ではなく、使用量を確実に集計でき、モデル単位で制御できるかどうかです。 ## リポジトリの指示ファイルに書く内容 ほとんどのエージェントは、何らかの形式のリポジトリ指示ファイルに従います。私は短く、実務に直結する内容にしています。 ``` ## Agent Instructions - Prefer minimal diffs over rewrites. - Do not run full test suites until targeted tests pass. - Never edit generated files in `dist/`, `build/`, or `coverage/`. - Use `rg` for search. - Before large refactors, propose a plan and wait. - If a command emits more than 200 lines, rerun with a narrower command. ``` これは礼儀の問題ではありません。ループの進み方を形作るものです。エージェントはそれでも間違えますが、適切な指示があれば、無駄の繰り返しを減らせます。 よくある落とし穴は、長すぎる指示ファイルが背景の雑音になってしまうことです。エージェントへの指示が、スタイルの理念を語る300行の文章になっていると、モデルは重要な三つの運用上の制約を見落とすかもしれません。価値の高いルールを先頭に置いてください。 ## レイテンシ：もう一つのコスト トークンの支出が許容範囲でも、レイテンシによって作業の流れが途切れることがあります。 エージェントのレイテンシは、次の要因から生じます。 - モデルの推論時間 - ツールの実行時間 - ファイルのインデックス作成時間 - テストの実行時間 - 人による承認待ち 短いループでは、「次の有用な観測結果が得られるまでの時間」を最適化します。15秒の対象を絞ったテストは、6分かかるCI全体のシミュレーションより有効です。4秒で構文エラーを正しく特定する小型モデルは、美しい説明を作るのに45秒かける高級モデルより有効です。 最良のセッションは、ペアプログラミングのように感じられます。 ``` inspect → patch → targeted test → inspect failure → patch → targeted test → final suite ``` 最悪のセッションは、CIの形だけをまねているように感じられます。 ``` scan repo → edit many files → run everything → drown in logs → repeat ``` ## 制約と失敗パターン ターミナルエージェントは便利ですが、魔法ではありません。 次のような場合には苦戦します。 - リポジトリに、テストでは把握されていない隠れた実行時依存関係がある。 - タスクに、コードの変換よりもプロダクトに関する判断が求められる。 - エラーが外部サービスや不安定な状態に依存している。 - コードベースに、誤解を招く抽象化や古いドキュメントがある。 - エージェントが必要な検証コマンドを実行できない。 もっともらしく見えても、誤った修正を生成することもあります。テストが不十分な場合には、特によく起こります。エージェントが動作を検証できない場合、その出力は若手エンジニアの未レビューのパッチと同様に扱ってください。役立つ可能性はありますが、自動的に信頼してはいけません。 セキュリティも重要です。ツールの承認モデルを理解せずに、機密性の高いリポジトリでエージェントに無制限のシェルアクセスを与えてはいけません。「コマンドの実行」には、制限されていない限り、環境変数の表示、ファイルの変更、パッケージのインストール、ネットワークへのアクセスも含まれます。 ## 実践上のポイント - CLIコーディングツールは、単発のプロンプトではなく、API駆動の制御ループとして扱ってください。 - ループ回数とコンテキストのサイズ、特にコマンド出力を減らして、コストを最適化してください。 - 高性能なモデルは、すべての機械的な手順ではなく、難しい推論に使ってください。 - リポジトリの指示は短く、実務に直結し、エージェントの振る舞いに焦点を当てた内容にしてください。 - まず対象を絞ったテストを行い、最後に広範な検証を行ってください。 - 長いセッションでは、古い履歴を持ち越さず、簡潔な要約を使ってリセットしてください。 - 入力トークンに注意してください。エージェントを使ったコーディングでは、見えにくいコストの発生源です。 - エージェントが同じ失敗する戦略を繰り返したら、止めて介入してください。 Claude Code、Aider、Cline、OpenCodeは、実際に起きている変化の一部です。コーディング支援は、提案エンジンから、ターミナル上で動く協働相手へと移行しています。最も恩恵を受けるのは、単に「エージェントを有効にする」チームではありません。コンテキストを絞り、安全なツールを使い、支出を把握できるようにし、各段階で検証するという形で、ループを設計するチームです。 [コーディング](/ja/blog/tag/coding/)[Claude](/ja/blog/tag/claude/)[エージェント](/ja/blog/tag/agents/) A [AI Prime Tech](https://aiprimetech.io/ja/) このブログはAI Prime Techが公開しています。記事の草稿はAIの支援を受けて作成されています。モデルID、料金、制限など、バージョンによって異なる詳細については、利用の判断に用いる前に公式ドキュメントで確認してください。 Claude APIをより低価格で利用 Claude Opus 5.5、Sonnet 5、Haiku 4.5、Fable 5.1に加え、GPT-6のモデルを、単一のAPIキーで利用できます。従量課金制で、サブスクリプションは不要です。 [APIキーを取得 →](/register) AI Prime Techは独立したサードパーティのAPIゲートウェイです。Claude™およびAnthropic®はAnthropic, PBCの商標です。提携や推奨を示唆するものではありません。