Skip to Content
Docs08. コーディングエージェントClaude Code 実践ガイド
中級coding-agentscost-managementprompt-caching更新: 2026-10-03この記事の誤りを報告

この記事の音声は準備中です。

音声の一覧・再生リストへ

Claude Code 実践ガイド

この記事の目的

Claude Code の拡張機能(スキル・サブエージェント・フック・worktree 並列・headless)を使いどころから理解し、消費(トークン・使用量上限)を抑えながら業務を効率化できるようになります。製品の選定判断は Claude Code が正で、本記事は「導入済みの人が使いこなす」段階を扱います。

対象読者

  • Claude Code を対話中心に使っており、拡張機能・自動化・コスト管理を体系的に押さえたいエンジニア
  • チームに Claude Code の運用標準(スキル・設定・計測)を整備したい人

前提知識

本文

最終確認日: キャッシュ TTL・effort 変更条件、CI 上限、self-hosted environments は 2026-09-10、Agent teams の倍率・Routines 等の状態は 2026-08-18、その他は 2026-07-06 の公式情報に基づきます。細かな挙動は採用バージョンと参考資料で確認してください。

機能の使いどころ

公式ドキュメントは各機構の「使いどき」を明文化しています。判断基準ごと押さえるのが早道です。

機構使いどき(公式基準)
スキル(.claude/skills/)「同じ指示・チェックリストをチャットに繰り返し貼っているとき」「CLAUDE.md の一節が手順書に育ったとき」。旧カスタムスラッシュコマンドはスキルに統合されており(.claude/commands/ も継続動作)、本文は使用時のみロードされます
サブエージェント(.claude/agents/)「副次タスクがメイン会話を検索結果・ログで溢れさせるとき」。コンテキスト温存に加え、安いモデルへのルーティングによるコスト制御が公式の効用に挙げられています
fork(/fork)同じ文脈を引き継ぐ分岐作業。親のプロンプトキャッシュプロンプトの固定部分(前方一致)の処理結果を再利用し、入力コストと応答開始までの時間を削減する仕組み。固定部分を先頭に置くプロンプト構造が前提。を初回から再利用できるため、新規サブエージェントより安い選択肢です
フック「LLM の判断に頼らず、必ず起きてほしい決定論的な処理」(編集後の自動フォーマット、保護ファイルのブロック、コンパクションコンテキスト上限に近づいた際に、会話履歴を要約・圧縮して容量を確保する仕組み。トリガ設計と「必ず残す情報」の定義が要で、決定の消失は議論のループを招く。後のコンテキスト再注入など)
プラグインチーム・複数プロジェクトへの配布。「まず .claude/ で試作し、共有段階でプラグイン化」が公式推奨です
plan モードアプローチが不確か・複数ファイル変更・不慣れなコードのとき。**「diff を一文で説明できるならプランは省け」**という不使用基準まで公式が明記しています
チェックポイント長時間タスクの「ここまで完了した」を再開可能な形で永続化したもの。ツール実行の完了やフェーズ境界などの意味のある単位で切る。信頼性とトークンコスト制御の両方の仕組み。(/rewind)「リスクのある試行をやらせて、ダメなら巻き戻す」。bash 経由のファイル操作は追跡されない点に注意(恒久履歴は git)
worktree(claude -w <name>)同一リポジトリでの並列セッション。ブランチと作業ツリーを自動作成し、無変更なら終了時に自動削除されます
auto memoryCLAUDE.md = 人が書く指示 / auto memory = Claude が書く学習という分担。「これを覚えて」は auto memory へ、「CLAUDE.md に追加して」は規約へ、と発話で使い分けられます

スキルの設計では、起動制御(手動専用 disable-model-invocation / Claude 専用 user-invocable: false)と、起動後は本文がセッションに残り続ける(継続コスト)ことを踏まえて、SKILL.md は 500 行以下・詳細は補助ファイルに分ける公式推奨に従います。

コスト削減: 公式テクニックの要点

公式の大原則は 1 つです: 「トークンコストはコンテキストサイズに比例する」。コスト最適化 の一般原則が、Claude Code では次の操作に対応します。

  1. コンテキストの能動管理 — 無関係な作業に移るときは /clear(古い文脈は以後の全メッセージで課金され続けます)。後で戻るなら /rename してから /clear し、/resume で復帰します
  2. コンパクションはタスクの区切りで — 自動発火をタスク途中に食らうのではなく、区切りの良いところで /compact(残すものの指示も付けられます)。捨てたい経路に入り込んだときは /compact ではなく /rewind — キャッシュ済みの位置へ戻るため安上がりです
  3. CLAUDE.md は 200 行以下を目標に、手順はスキルへ — CLAUDE.md は毎セッション全ターンで課金されます。特定ワークフローの詳細手順はスキル(使用時のみロード)に移すのが公式推奨です
  4. MCPツールやデータソースを LLM アプリケーションに接続するための標準プロトコル。概要は ツール使用、接続の実務は ツール接続標準(MCP とエコシステム) より CLI ツール — gh・aws 等の CLI はツール定義のコンテキストを追加しないため、MCP サーバーよりコンテキスト効率が良いと公式が明記しています。/context で何が消費しているかを確認し、未使用の MCP は外します
  5. フック・スキルへの前処理オフロード — 公式例: 1 万行のログを読ませる代わりに、フックが ERROR 行だけを grep して返す(数万→数百トークン)
  6. モデルと思考量の使い分け — 大半のコーディングは中位モデルで足り、上位モデルは複雑な設計判断に温存します。サブエージェントには軽量モデルを割り当てます。thinking トークンは出力として課金されるため、単純作業では effort を下げ、単発の深掘りはプロンプト内の ultrathink で済ませます
  7. Agent teams は高コスト — 公式が「teammates が plan モードで動く場合、標準セッションの約 7 倍」(2026-08 時点)と条件付きで明記する構成です。使うなら小さなチーム・軽量モデルで

**プロンプトキャッシュの「踏み抜きどころ」**も公式がリスト化しています。読み取り単価はモデル別で、従来の「通常入力の約 1 割」を全モデルへ一般化せず、Fable 5.1 等を含む採用モデルの料金表で比較します。TTL の既定は、主会話がサブスクリプション内の利用で 1 時間、API キー・クラウドプロバイダー・使用クレジット消費中は 5 分です。サブエージェント等は原則 5 分で、一部のサービス側補助要求は例外です。

Claude Code v2.1.242 以降では、主会話は promptCacheTtl / CLAUDE_CODE_PROMPT_CACHE_TTL、その他は subagentPromptCacheTtl / CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL で 5m または 1h を選べます。優先順位は、FORCE_PROMPT_CACHING_5M=1 → 対象の環境変数 → 対象の設定 → サブエージェントの experimental cacheTtl(v2.1.248 以降、usage credits 中の 1h は無視)→ 旧 ENABLE_PROMPT_CACHING_1H=1 → 既定です。旧変数は廃止されたわけではありません。1 時間 TTL の利用可否・書き込み費用は接続先ごとに確認します。

日常で踏みやすいのは次の 3 つです:

  • セッション途中のモデル切替はモデル別キャッシュを再構築します。effort 変更も多くの構成で失効しますが、v2.1.260 以降の Fable 5.1 を API キーまたは Claude subscription で使う場合は維持できます。Bedrock・Google Cloud Agent Platform・Claude apps gateway、実験 beta 無効化、HIPAA 構成はこの例外の対象外です
  • opusplan 設定での plan モード出入り(そのたびにモデルが切り替わる)
  • アップグレード直後に長いセッションを resume(公式が「最も高価なリクエストになり得る」と明記)

測定: /usage(スキル / サブエージェント / MCP 別の内訳)、/context、ステータスラインの常時表示が個人向け、組織は OpenTelemetry(コスト・トークンメトリクスに skill.name・agent.name・mcp_server.name 属性が付き、スキル別・サブエージェント別のコスト帰属が可能)です。headless の --output-format json は total_cost_usd を返すため、自動化の呼び出し単位でコストを集計できます。

業務効率化・自動化

  • headless(claude -p): 全 CLI オプション併用可・stdin パイプ対応で、--output-format json(+ --json-schema で構造化出力LLM の出力を JSON Schema などの機械可読なスキーマに従わせる技術。後続の処理がコードである出力(分類・抽出・スコア)に使う。)が CI の基本形です。CI では --bare(CLAUDE.md・スキル・MCP 等の自動発見をスキップし、必要なものだけ明示注入)が公式推奨で、「どのマシンでも同じ結果」を得られます
  • ファンアウト: タスクリストを生成し、claude -p をループで回す一括処理パターンです。公式手順は「2〜3 ファイルで試してプロンプトを磨いてから全量実行」— 自動化パターン の「対話で成功してから自動化」の実装形です
  • GitHub Actions: @claude メンション応答と、prompt 指定の自動実行(cron・PR イベント)の 2 モード。コスト制御は 反復上限の明示指定(例: claude_args: "--max-turns 10")+ ワークフローのタイムアウト + concurrency 制限の 3 点セットが公式推奨です。CLI の --max-turns は既定で無制限、Action の claude_args も既定は空です。10 は設定例で、未指定の終了条件にはできません。API キーは Secrets、Bedrock 等では OpenID Connect(OIDC)によるキーレス認証が推奨されます。リポジトリのスキルを prompt: /skill-name で起動でき、PR ごとのコードレビュー等を定型化できます
  • GitLab CI/CD: beta で、メンテナンスは GitLab 社です。実体は headless 実行のジョブで、max_turns と timeout_minutes で上限を設けます
  • Routines(research preview): 「プロンプト + リポジトリ + コネクタ」をクラウド環境で定期・API・GitHub イベント起動する仕組みです。Anthropic 管理環境に加え、Team / Enterprise は既定 off の self-hosted environments public beta を選べます(CLI v2.1.224 以降)。自社ホストで実行しても推論・キューは Anthropic 側にあり、外向き HTTPS が必要です。ZDR 組織・Security・Code Review は対象外です。承認プロンプトなしの完全自律実行のため、既定の防御(プッシュ先は claude/ プレフィックスブランチのみ、ネットワークは許可リスト制)を理解して使います。日次実行数の上限があり、実行一覧のグリーン表示は「インフラエラーなし」の意味でタスク成功ではない、という公式の注意はスケジュール自動化一般の教訓です(自動化パターン の通知・検証設計)

品質を上げる公式プラクティス

公式ベストプラクティスの中核は「コンテキストウィンドウが最重要の管理対象リソース」という原則と、次の運用です。

  • 検証手段を渡す(最上位のプラクティス) — 「Claude が実行できるチェック(テスト・ビルド・スクリーンショット比較)を渡せ。見守るセッションと離席できるセッションの違いはそこにある」。成功を主張させるのではなく、証拠(テスト出力・実行結果)を出させます。バグ修正は「再現する失敗テストを先に書いてから直す」依頼が公式の型です
  • Explore → Plan → Implement → Commit の 4 フェーズ — 不確かなタスクの標準形。小さな修正はスキップします(前述の「diff 一文」基準)
  • 早めのコース修正 — Esc で即中断 → 巻き戻し → やり直し。「同じ問題で 2 回以上訂正したら、コンテキストは失敗アプローチで汚染されている。/clear して学びを織り込んだプロンプトで再開する方がほぼ常に勝る」(依頼設計 の仕切り直しと同じ判断です)
  • インタビューパターン — 大きめの機能は「Claude に自分をインタビューさせて SPEC.md に仕様を書かせ、新しいセッションで実装」する 2 段構えが公式に案内されています
  • Writer / Reviewer 分離 — 別セッションの新鮮なコンテキストでレビューさせるとバイアスがかからない、というマルチセッション活用。敵対的レビューでは「正しさと要件に影響する gap だけ挙げさせる」(全部追うと過剰設計になる)という注意書きまで公式にあります
  • 5 つの失敗パターン(公式)— 何でも 1 セッションに詰める / 訂正の繰り返し / 肥大した CLAUDE.md / 検証なしの信頼 / 際限ない調査。本章の各記事の原則と一致します

実務での注意点

アンチパターン

  • 1 セッションに何でも詰め込む(kitchen sink) — 消費が毎ターン膨らみ、性能も落ちます。→ タスク間で /clear、長期タスクは区切りで /compact、戻る可能性があれば /rename + /resume を使います
  • キャッシュ条件を確認せずモデル・effort を頻繁に切り替える — モデル切替と多くの構成の effort 変更では履歴を再読します。→ Fable 5.1 の維持条件を区別し、キャッシュ統計と品質を見て切替を判断します
  • CLAUDE.md に手順書を書き続ける — 毎セッション・毎ターンの固定費になります。→ 「消したら Claude はミスするか?」で選別し、手順はスキルへ移します
  • Routines・Actions に検証なしのタスクを載せる — 完全自律実行では「成功したように見える失敗」を誰も見ていません。→ 機械検証(テスト・チェックスクリプト)と結果の通知先を先に設計します

チェックリスト

  • タスク間の /clear・区切りでの /compact・失敗時の /rewind を使い分けているか
  • 採用モデル・接続先・バージョンごとのキャッシュ維持条件と TTL を把握しているか
  • CLAUDE.md がスリムで(目安 200 行以下)、手順はスキルに移してあるか
  • サブエージェント・定型タスクに軽量モデルを割り当てたか
  • /usage・/context(組織は OpenTelemetry)で消費の内訳を確認できるか
  • 委任・自動化するタスクに検証手段(テスト・期待出力)を渡しているか
  • CI・Routines で上限(--max-turns・タイムアウト・日次キャップ)を理解して設定したか

関連トピック

参考資料

TODO・未確認事項

変わりやすい項目(定点観測)

自動化・業務効率化パターンOpenAI Codex 実践ガイド