Claude Code CLI ガイド：インストール、設定、コマンド、環境変数

TL;DR: Claude Code は、コードベースを読み取り、コマンドを実行し、権限、hooks、MCP 連携、subagents の階層化されたシステムを通じてファイルを変更する agentic CLI です。5つの中核システム（設定、権限、hooks、MCP、subagents）を習得すると、生産性を大きく引き上げられます。各タスクに合うモデル tier を選びましょう。複雑な推論には Opus、一般的な作業には Sonnet、高速な探索には Haiku が向いています。品質だけを重視するなら Opus に統一してもかまいません。必ず毎回実行すべき処理には、プロンプトではなく hooks を使ってください。v2.1.174–176（2026年6月12日）時点では、新しい enforceAvailableModels 管理設定により、availableModels allowlist で Default モデルも制限できるようになりました（ユーザー/プロジェクト設定で管理リストを広げることはできません）。セッションタイトルは会話の言語で生成されます（language 設定で固定できます）。さらに、新しい footerLinksRegexes と wheelScrollAccelerationEnabled 設定、VSCode の /usage attribution ダイアログ、hook の if 条件が Read/Edit/Write のパスパターンに一致するようにする修正も含まれています。¹⁷² v2.1.173（2026年6月11日）時点では、[1m] サフィックス付きの Fable 5 モデル名が自動的に正規化/除去されます。Fable 5 はデフォルトで 1M context を含むため、このサフィックスは不要です（意味があったのは Opus/Sonnet の場合だけでした）。v2.1.172（2026年6月10日）時点では、sub-agents が自分自身の sub-agents を再帰的に spawn できるようになり、最大5階層まで対応しました。Bedrock は AWS_REGION が未設定の場合に ~/.aws から region を読み取り（/status に source が表示されます）、/plugin には marketplace 検索バーが追加され、claude_code.lines_of_code.count OTEL metric には model attribute が追加されました。v2.1.170（2026年6月9日）時点では、Opus より上位の新しいモデル tier である Claude Fable 5 が追加され、claude update 後に Claude Code で /model fable から選択できます（low〜max の effort scale 全体に対応しますが、thinking を無効化することはできません）。Opus 4.8 は引き続き agentic default です。v2.1.169（2026年6月8日）時点では、--safe-mode（および CLAUDE_CODE_SAFE_MODE）により、トラブルシューティング用にすべてのカスタマイズを無効化したクリーンなセッションを起動できます。/cd は prompt cache を壊さずにセッションを新しい working directory へ移動し、disableBundledSkills は組み込みの skills と slash commands をモデルから隠します。v2.1.166（2026年6月6日）時点では、fallbackModel 設定により primary が過負荷のときに最大3つのバックアップモデルを連鎖できます。glob "*" は MCP deny rules で機能し、MAX_THINKING_TOKENS=0 / --thinking disabled によって think-by-default モデルの thinking を完全にオフにできます。v2.1.154（2026年5月28日）時点では、Opus 4.8 が high effort をデフォルトとする新しい default になり、/effort xhigh level が追加されました。dynamic workflows は /workflows 経由でバックグラウンドの数十〜数百の agents を orchestrate します。Opus 4.8 の Fast mode は標準 rate の2倍のコストで2.5倍の速度になり、lean system prompt は Haiku/Sonnet/Opus 4.7 以前を除くすべてのモデルで default になりました。/simplify は cleanup-only review に戻り（/code-review --fix とは別です）、claude agents は ! <command> を受け付けて background shell sessions を spawn できます。plugins は defaultEnabled: false を宣言でき、streaming tool execution は常に有効です。また stdio MCP servers は env で CLAUDE_CODE_SESSION_ID と CLAUDECODE=1 を受け取ります。v2.1.153 では plugin marketplaces に skipLfs が追加され、/model が default として保存されるようになり（session-only にするには s を押します）、status-line env に COLUMNS/LINES が入りました。v2.1.152 では /code-review --fix（finding を working tree に適用）、skill frontmatter の disallowed-tools、/reload-skills、新しい MessageDisplay hook event、SessionStart hook の reloadSkills/sessionTitle outputs、pluginSuggestionMarketplaces 管理設定、セッション途中の --fallback-model 切り替えが導入され、auto-mode opt-in は削除されました。^{162 163 164 165 166 167 168 169 170 180 171}

Claude Code はプログラミング知識を持つチャットインターフェースではなく、agentic system として動作します。 CLI はコードベースを読み取り、コマンドを実行し、ファイルを変更し、git workflows を管理し、MCP 経由で外部サービスに接続し、複雑なタスクを専門化された subagents に委任します。すべては、開発者の実際の働き方に統合される command-line interface を通じて流れます。2026年2月時点で、公開 GitHub commits の4%（1日あたり約135,000件）は Claude Code によって author されており、research preview から13か月で42,896倍に成長しました。また、Anthropic 自身のコードの90%は AI-written です。¹⁰³

Claude Code をなんとなく使うか、効果的に使うかの違いは、5つの中核システムに集約されます。 これらを習得すれば、Claude Code は力を倍増させる存在になります。

1. 設定階層: 挙動を制御します
2. 権限システム: 操作を gate します
3. Hook system: 決定的な自動化を可能にします
4. MCP protocol: 機能を拡張します
5. Subagent system: 複雑なマルチステップタスクを処理します

重要ポイント

• 効果を左右するのは5つのシステムです: 設定階層、権限、hooks、MCP、subagents が、挙動から自動化までのすべてを制御します。
• 作業は Delegation Layer に押し出します: subagents は探索をクリーンな context windows に分離し、summary だけを返すことで context bloat を防ぎます。
• Hooks は実行を保証しますが、プロンプトは保証しません: モデルの挙動に関係なく毎回実行すべき linting、formatting、security checks には hooks を使ってください。
• Model tiering は品質を犠牲にせずコストを抑えます: subagent の探索は安価なモデルに回し、本当に architectural reasoning が必要な場面に Opus を残しましょう。品質だけを重視するなら Opus に統一してもかまいません。
• MCP は Claude を toolchain に接続します: databases、GitHub、Sentry、3,000以上の integrations により、Claude はファイル読み取りと bash commands を超えて拡張されます。

私は数か月かけて、本番コードベース、CI/CD pipelines、enterprise deployments の中で Claude Code を限界まで使い込みました。このガイドは、その経験を、始めた当時に欲しかった完全な参照資料として凝縮したものです。すべての機能に、実際の syntax、現実的な設定例、経験豊富なユーザーでもつまずく edge cases を含めています。

読み進め方を選ぶ

このガイドの使い方

これは5,000行を超えるリファレンスです。最初から最後まで通読する必要はありません。自分の経験レベルに合う場所から始めてください。

特定の flags、commands、configuration keys を探すには、ブラウザの Ctrl+F / Cmd+F を使ってください。末尾の Quick Reference Card には、主要な commands を一覧できる summary があります。

関連する Deep Dives

これらの blog posts では、Claude Code の特定の側面を詳しく掘り下げています。

60秒クイックスタート

Claude Codeを実行して出力を確認したいだけなら、次の順番で進めてください。

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

これで完了です。このセクション以降では、インストール方法の選択肢、権限とhooksの設定、MCPサーバーの接続、Enterpriseデプロイまで詳しく扱います。ただし、始めるために必須のものはありません。

前提条件: Node 18+ が必要なのは従来のnpm経由の場合だけです。推奨されるネイティブインストーラーにはNode依存はありません。macOS / Linux / Windows 10+ がサポートされています。Claude Pro、Max、Team、Enterpriseのサブスクリプション、または従量課金のAnthropic APIキーで利用できます。プラットフォーム別の詳細、トラブルシューティング、ネイティブバイナリのパス（v2.1.113以降のデフォルト）については、Claude Codeをインストールするには？をご覧ください。このガイドの最新リリース根拠は、v2.1.154に照らして確認済みです。¹⁸⁰

Claude Codeの仕組み: メンタルモデル

機能に入る前に、Claude Codeのアーキテクチャが使い方全体にどう影響するかを理解しておきましょう。このシステムは3つのレイヤーで動作します。

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Core Layer: メインの会話です。すべてのメッセージ、ファイル読み取り、ツール出力は、共有ウィンドウのコンテキストを消費します（標準は200Kトークン⁹¹、Opus 4.6または拡張コンテキストモデルでは1Mトークン）。コンテキストが埋まると、Claudeは以前の判断を追えなくなり、品質が低下します。このレイヤーではトークンごとにコストが発生します。

Delegation Layer: Subagentsはクリーンなコンテキストで起動し、焦点を絞った作業を行い、要約を返します。探索結果でメインの会話が膨らむことはなく、結論だけが戻ります。探索にはより安価なモデル層へsubagentsを振り分けることもできますし、品質をコストより重視するなら最初から最後まで主要モデルを使うこともできます。

Extension Layer: MCPは外部サービス（データベース、GitHub、Sentry）に接続します。Hooksは、モデルの挙動に関係なくシェルコマンドの実行を保証します。Skillsは、Claudeが自動的に適用するドメイン知識をエンコードします。Pluginsは、これらすべてを配布用にパッケージ化します。

重要なポイント: 多くのユーザーはCore Layerだけで作業し、コンテキストが膨らみコストが増えていく様子を見ることになります。上級ユーザーは、探索や専門的な作業をDelegation Layerに任せ、Extension Layerを自分のワークフロー向けに設定し、Core Layerはオーケストレーションと最終判断にだけ使います。

目次

1. Claude Codeをインストールするには？
2. クイックスタート: 最初のセッション
3. Core Interaction Modes
4. Configuration System詳解
5. どのモデルを選ぶべきですか？
6. Claude Codeのコストは？
7. 判断フレームワーク
8. 権限システムはどのように動作しますか？
9. Hooksはどのように動作しますか？
10. MCP（Model Context Protocol）とは？
11. Subagentsとは？
12. Extended Thinking Modeとは？
13. Output Styles
14. Slash Commands
15. Skillsはどのように動作しますか？
16. Plugin System
17. Memoryはどのように動作しますか？
18. 画像とマルチモーダル入力
19. Voice Mode
20. Git連携はどのように動作しますか？
21. IDEでClaude Codeを使うには？
22. 高度な利用パターン
23. Remote & Background Agents [RESEARCH PREVIEW]
24. ChromeのClaude
25. SlackのClaude Code [RESEARCH PREVIEW]
26. Web上のClaude Code [RESEARCH PREVIEW]
27. パフォーマンス最適化
28. 問題をデバッグするには？
29. Enterpriseデプロイ
30. キーボードショートカット参照
31. ベストプラクティス
32. Workflow Recipes
33. 移行ガイド
34. 読者別ガイダンス
35. クイックリファレンスカード
36. Changelog
37. References

Claude Codeをインストールするには？

システム要件

Claude CodeはmacOS 13以上、Ubuntu 20.04以上/Debian 10以上、Windows 10以上（ネイティブまたはWSL）で動作します。システム要件として最低4 GBのRAMとアクティブなインターネット接続が必要です。⁹² シェルの互換性はBash、Zsh、Fishで最適に動作します。

Windowsの場合、WSL 1とWSL 2の両方が動作します。ネイティブWindowsを好む場合はGit Bashも利用可能です。Alpine Linuxやその他のmuslベースのシステムでは追加パッケージが必要となります。

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

プラットフォームサポート対応表

インストール、アップデート、アンインストールの早見表

ひと目で確認できる早見表です。すべての方法、すべてのコマンド、バージョン確認を1画面にまとめました。以下のサブセクションで各方法の詳細とトラブルシューティングを説明します。

v2.1.113以降、正規のCLIはバンドル版JavaScriptではなく、プラットフォームごとのオプション依存関係を介してネイティブClaude Codeバイナリを起動するようになりました。テスト済みのディストリビューションにはネイティブインストーラーをご利用ください。npmパスは引き続き動作しますが、v2.1.15で最初に追加された非推奨通知が表示されます。

インストール方法

ネイティブインストール（推奨）

ネイティブバイナリはNode.jsへの依存がなく、最もクリーンな利用体験を提供します。

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

特定のバージョンをインストールする場合は次のとおりです。

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

NPMインストール（非推奨）

注： v2.1.15以降、npmインストールには非推奨通知が表示されます。現在はネイティブバイナリが推奨インストール方法です。claude installで移行できます。

npmが依然として必要なレガシー環境では次のように実行します。

npm install -g @anthropic-ai/claude-code

npmインストールでは絶対にsudoを使用しないでください。下流のすべてを複雑にする権限の問題を引き起こします。

既存インストールからの移行

古いnpmベースのインストールがある場合は、ネイティブバイナリへ移行してください。

claude install

認証オプション

Claude Codeは3つの認証パスをサポートしており、それぞれ異なるトレードオフがあります。

Claude Console（API billing）

platform.claude.com（旧console.anthropic.com）を通じてAnthropicのAPIに直接接続します。アカウントを作成し、課金を設定してCLIから認証を行います。Consoleでは、APIへのフルアクセスを伴う従量課金が利用できます。「Claude Code」専用ワークスペースが自動的に作成されます。このワークスペース用のAPIキーは作成できませんが、使用状況をモニタリングできます。

Claude ProまたはMaxサブスクリプション

claude.aiアカウントの認証情報を使用します。サブスクリプションは月額プランで、WebインターフェースとCLIの利用の両方をカバーします。コストを予測しやすくしたい個人ユーザーにとって、サブスクリプションは課金を簡素化します。

エンタープライズプラットフォーム

AWS Bedrock、Google Vertex AI、Microsoft Foundryは、それぞれ既存のクラウド課金関係を活用したエンタープライズグレードのアクセスを提供します。Bedrockセットアップウィザード（v2.1.92以降）： ログイン画面のインタラクティブなウィザードが、AWS認証、リージョン選択、認証情報の検証、モデルピン留めをガイドします。¹³⁷ Vertex AIセットアップウィザード（v2.1.98以降）： Google Cloud向けの対応ウィザードが、GCP認証、プロジェクトおよびリージョン設定、認証情報の検証、モデルピン留めをガイドします。¹⁴² Vertex AI mTLS Workload Identity Federation（v2.1.121以降）： Vertex AIがX.509証明書ベースのWorkload Identity Federation（mTLS Application Default Credentials）に対応しました。クライアント証明書から発行される短命のGCPトークンを使用するため、サービスアカウントのJSONは不要です。¹⁵⁴ OS CA証明書のトラスト（v2.1.101以降）： エンタープライズTLSプロキシがデフォルトで動作するようになりました。Claude CodeはOSの証明書ストアを信頼します。バンドルされたCAのみを使用するにはCLAUDE_CODE_CERT_STORE=bundledを設定してください。¹⁴³

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

プロキシ経由またはLLMゲートウェイを介したエンタープライズデプロイメントの場合は次のとおりです。

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

検証

claude doctor

このコマンドはインストールタイプ、バージョン、システム設定、検出されたあらゆる問題を報告します。

認証管理（v2.1.41以降）

REPLに入ることなく認証を管理できます。⁹⁰

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

アカウントや組織を切り替える際の一般的なワークフローは次のとおりです。

claude auth logout && claude auth login

関連項目：認証エラーのトラブルシューティングについては問題のデバッグ方法を参照してください。

アップデート

Claude Codeはデフォルトで自動アップデートが有効になっており、起動時およびセッション中に定期的にチェックします。アップデートはバックグラウンドでダウンロードされ、次回起動時に適用されます。

自動アップデートを無効にするには次のとおりです。

export DISABLE_AUTOUPDATER=1

またはsettings.jsonで設定します。

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

手動アップデートは次のとおりです。

claude update

アンインストール

ネイティブインストール（macOS/Linux/WSL）：

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

ネイティブインストール（Windows PowerShell）：

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

設定のクリーンアップ（すべての設定を削除）：

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

クイックスタート：はじめてのセッション

1. インストールと起動：

claude                           # Launch in current directory

2. プロジェクトに移動：

cd ~/my-project && claude        # Or launch from any git repo

3. Claude に作業を依頼：

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. セッション中に使える主要なショートカット：

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. 後で再開する：

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

エキスパートのヒント： プロジェクトのルートに CLAUDE.md ファイルを作成し、ビルドコマンド、コーディング規約、アーキテクチャに関するメモを記述しましょう。Claude はセッションごとにこのファイルを読み込みます。品質向上のために最も効果的な一手です。

主要なインタラクションモード

インタラクティブな REPL

引数なしで Claude Code を起動すると、インタラクティブな read-eval-print ループに入ります。

cd your-project
claude

REPL はターンをまたいで会話のコンテキストを保持します。クエリを直接入力し、応答を受け取り、/exit または Ctrl+D で終了するまで続けられます。

セッションの焦点を絞るために、最初のプロンプトを指定して起動することもできます。

claude "explain the authentication flow in this project"

エキスパートのヒント： REPL はコンパクション処理をまたいで状態を保持します。コンテキストが大きくなりすぎると、Claude は重要な決定事項やコードスニペットを保持しながら、古い会話を自動的に要約します。/compact で手動でトリガーすることも、何を保持するかをカスタム指示で追加することもできます。

ノンインタラクティブモード

プリントモード（-p）は単一のクエリを実行して終了します。

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

スクリプトでパースしやすい構造化された出力を得るには：

claude -p "count lines by file type" --output-format json

JSON 出力には自動化に必要なすべての情報が含まれます。

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

ストリーミング出力をリアルタイムで処理するには：

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

出力フォーマットのオプション：

終了コード：

-p モードでのエージェント動作の制御：

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-4-5-20250929

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

CI/CD 統合のパターン：

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

セッション管理

セッションは継続のために会話履歴を保持します。複数セッションにまたがる複雑な作業では、セッションの永続化が不可欠です。

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

PR にリンクされたセッション（v2.1.27+、v2.1.119+ で拡張）： 特定の pull request または merge request にリンクしたセッションを開始できます。v2.1.119 以降、--from-pr は github.com に加えて、GitLab MR、Bitbucket PR、GitHub Enterprise PR の URL を受け付けます。⁷⁴¹⁵²

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

セッション中に gh pr create で PR を作成すると、セッションは自動的にその PR にリンクされます。これにより、特定の PR の作業を後から簡単に再開できます。フッターの PR バッジは、prUrlTemplate 設定（v2.1.119+）を使ってカスタムのコードレビュー URL を指すように設定できます。チームが PR から別のレビューツールにリンクしている場合に便利です。¹⁵²

/resume が PR URL を受け付けるようになりました（v2.1.122+）。 /resume の検索ボックスに PR URL を貼り付けると、その PR を最初に作成したセッションが見つかるようになりました。github.com、GitHub Enterprise、gitlab.com（およびセルフホスト型 GitLab）、bitbucket.org に対応しています。¹⁵⁴

名前付きセッション： セッションは起動時または進行中に名前を付けられます。

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

注意： --session-id には有効な UUID が必要です（例：550e8400-e29b-41d4-a716-446655440000）。人が読みやすいセッション名を使うには、代わりに /rename と --resume を使用してください。

Claude Code はセッションを JSONL トランスクリプトとして保存します。エージェントの実行ではユニークな agentId 値が割り当てられ、トランスクリプトは agent-{agentId}.jsonl として保存されます。再開時には以前の会話の完全なコンテキストが保持されます。

プランモード

プランモードでは、Claude を読み取り専用の探索に制限します。ファイル編集、bash 実行、破壊的なアクションはすべて不可です。Claude は実装方針を設計し、それをプランファイルに書き出して、実行前にあなたの承認を待ちます。

プランモードに入る：

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

仕組み：

1. Claude がプランモードに入ります（複雑なタスクで自動的に、または Shift+Tab で）
2. 読み取り専用ツールを使ってコードベースを探索します：Read、Glob、Grep、WebSearch、WebFetch
3. .claude/plans/{session-slug}.md にプランを書き出します
4. ExitPlanMode でプランモードを終了し、レビュー用にプランを提示します
5. 承認、変更依頼、または却下をします

プランモードで利用可能なツール： Read、Glob、Grep、LS、WebSearch、WebFetch、AskUserQuestion。編集ツール（Edit、Write、Bash、NotebookEdit）はブロックされます。

プラン承認後（v2.1.32+）： Claude は 3 つの選択肢を提示します。 - 「Yes, clear context and auto-accept edits」（Shift+Tab）— プラン用にフルコンテキストで新しく開始 - 「Yes, and manually approve edits」— コンテキストを保持し、変更ごとに承認 - 「Yes, auto-accept edits」— コンテキストを保持し、Claude が編集ごとの承認なしで実行

承認時にコンテキストを自動クリアする のが推奨ワークフローです。プランに新鮮なコンテキストウィンドウを与えることで、プランへの忠実度が大幅に向上します。古い会話による干渉がなくなり、Claude がより長く軌道を保てるようになるのです。

プランモードを使うべき場面： - アーキテクチャ上の判断を伴う新機能の実装 - 先にアプローチをレビューしたい複数ファイルにまたがるリファクタリング - 修正の前に探索が必要な、馴染みのないコードベース - 複数の有効なアプローチが存在し、入力を加えたいあらゆるタスク

エキスパートのヒント： プランモードに費やす時間が長いほど、Claude の実装成功率は高まります。プランモードは事実上タダで使える探索です。リスクのあるツール呼び出しもなく、無駄な編集も発生しません。積極的に活用しましょう。

設定システムの詳細

Claude Code は階層型の設定システムを使用します。上位レベルが下位レベルを上書きし、enterprise 設定は一切回避できないため、この階層を理解することが重要です。

設定階層

上級者向けのヒント: 共有プロジェクトで個人設定を使う場合は、.claude/settings.local.json を使用します（.gitignore に追加してください）。バージョン管理に含めるチーム全体の設定には、.claude/settings.json を使います。

settings.json 完全リファレンス

主要なオプションをすべて示す完全な設定例です。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-4-6-20260312-v1:0",
    "vertex": "claude-opus-4-6@20260312",
    "foundry": "anthropic.claude-opus-4-6"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

skillOverrides は、チームに大規模な skill ライブラリがありつつ、ランタイムで公開する範囲をより厳密にしたい場合に便利です。off を使うと、モデルと slash picker の両方から skill を非表示にできます。user-invocable-only では、モデル選択からは外しつつ、名前指定では呼び出せる状態を維持できます。name-only では、完全な説明なしで skill 名だけを表示できます。¹⁵⁶

新しい設定（v2.1.174–176）:

• availableModels / enforceAvailableModels（managed、v2.1.175+）: availableModels の allowlist は、セッションで選択できるモデルを制限します。enforceAvailableModels: true を指定すると、この allowlist は Default モデルにも適用されます。許可されていないモデルに解決される Default は、最初の許可モデルにフォールバックします。また、user/project 設定で managed の availableModels リストを広げることはできなくなります。関連する修正（v2.1.176）により、alias の選択が ANTHROPIC_DEFAULT_*_MODEL 経由でブロック済みモデルへリダイレクトできてしまう抜け道も塞がれ、/fast は allowlist 外のモデルへ切り替えることを拒否するようになりました。¹⁷²
• language（v2.1.176 の改良）: 応答言語の設定に加えて、セッションタイトルもデフォルトで会話の言語で生成されるようになりました。タイトルの言語を固定したい場合は、language を設定します。¹⁷²
• footerLinksRegexes（v2.1.176）: フッター行に表示される、regex に一致したリンクバッジです。user または managed 設定で構成できます。¹⁷²
• wheelScrollAccelerationEnabled（v2.1.174）: fullscreen mode でマウスホイールのスクロール加速を無効にするには、false に設定します。¹⁷²

環境変数リファレンス

認証と API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

モデル設定:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (Max/Team Premium default)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
CLAUDE_CODE_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

クラウドプロバイダー設定:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]

動作制御:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]

ツール設定:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

ネットワークとプロキシ:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI とターミナル:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

OpenTelemetry exporters + 機密フィールドの gating:¹⁸¹

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set

v2.1.121+ LLM-request span attributes: stop_reason、gen_ai.response.finish_reasons、user_system_prompt が LLM-request span に出力されるようになりました。user_system_prompt は PII を含む可能性があるため、OTEL_LOG_USER_PROMPTS=1 の背後で gating されています。¹⁵⁴

v2.1.122+ event-level changes: api_request と api_error log event の数値 attributes は、文字列ではなく数値として出力されるようになりました。これにより、schema を厳密に型付けしていた下流の OTel collector の問題が修正されます。Claude Code が @-mention を解決したときに、新しい claude_code.at_mention log event が発火します。¹⁵⁴

API / モデル制御:¹⁸¹

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:¹⁸¹

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)

Shell / IDE:¹⁸¹

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

Enterprise / auth:¹⁸¹

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)

Skill 変数（v2.1.69+）:

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

SDK caller identity（v2.1.51+）:

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=[email protected]        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

デバッグ:

ANTHROPIC_LOG=debug                             # Enable API request logging

どのモデルを選ぶべきですか？

タスクごとに適切なモデルを選ぶことは、コストと品質の両方に大きく影響します。Claude Code では、複数のレベルで柔軟にモデルを切り替えられます。

利用可能なモデル

Claude Fable 5（2026年6月9日）: Opus の上位に位置する新しい model tier です。Anthropic で最も強力かつ最も知的なモデルであり、テストされたほぼすべての benchmark で最先端の性能を示し、数百万 tokens の context にわたって一貫性を保てるよう設計されています。Fable 5 は、一般利用向けに安全化された「Mythos-class」の frontier model です。cyber、bio-chem、model-distillation の query では Opus 4.8 に fallback する safety classifiers が組み込まれています（Claude Mythos 5 は同じモデルですが、認可された研究者向けにこれらの safeguards が解除されています）。Claude Code では v2.1.170（2026年6月9日）から選択可能になりました。claude update を実行してから /model fable を使います（短い alias です。/model claude-fable-5 と best alias でも選択できます）。subscription plans には 2026年6月22日まで段階的に展開されています。Model ID: claude-fable-5。Fable 5 は default で 1M context window を含むため、[1m] suffix は不要です。また v2.1.173（2026年6月11日）時点で、claude-fable-5[1m] という model name は自動的に claude-fable-5 に正規化され、suffix が取り除かれます（この suffix は、1M を [1m] の後ろに gate している Opus/Sonnet でのみ意味がありました）。最大 output は 128K です。Pricing は input が $10/MTok、output が $50/MTok で、Opus 4.8 のおよそ 2 倍です。そのため、日常的な編集ではなく、本当に難しい推論に限って使いましょう。request surface は Opus 4.8 と共通です（adaptive thinking のみ。temperature/top_p/top_k と budget_tokens は削除）。ただし 1 つ新しい注意点があります。明示的な thinking: {type: "disabled"} は 400 を返すため、thinking なしで実行する場合は thinking parameter 自体を完全に省略してください。¹⁷⁴

Claude Code に限って言えば、Fable 5 は Opus 4.8 と同じく、full effort scale（low/medium/high/xhigh/max、default は high）をサポートします。Fable 5 では thinking をオフにできません。session thinking toggle、alwaysThinkingEnabled setting、MAX_THINKING_TOKENS=0 はいずれも効果がなく、常に adaptive に推論します。fable family の config surface は Opus の knob と対応しています。ANTHROPIC_DEFAULT_FABLE_MODEL は fable alias が解決されるモデルを固定します（Bedrock/Vertex/Foundry で有用です）。DISABLE_PROMPT_CACHING_FABLE は Fable を prompt caching から外します。enterprise gateways では content-based automatic fallback が適用されます。Opus 4.8 は引き続き Claude Code の agentic default です（default で high effort、最難関タスクでは /effort xhigh）。絶対的な上限が必要なときだけ、/model fable で Fable 5 を明示的に選びます。¹⁷⁴

Opus 4.7（2026年4月16日）: 前世代の flagship で、現在も完全に利用できます。1M token context window を standard pricing で利用でき、long-context premium はありません。最大 output は 128K、adaptive thinking のみ（extended thinking は削除）で、coding や agentic workloads の出発点として推奨される新しい xhigh effort level が追加されています。¹⁴⁵ reliable knowledge cutoff は 2026年1月です。training data cutoff は 2026年1月です。Model ID: claude-opus-4-7。Pricing は Opus 4.6 と同じく $5/$25 per MTok で、5-min cache write は $6.25、1-hr cache write は $10、cache read は $0.50 per MTok です。¹⁴⁴ Opus 4.7 は SWE-Bench で Opus 4.6 の 3 倍の production tasks を解決し、CursorBench では 70%（4.6 は 58%）を記録し、Anthropic の 93-task internal coding benchmark で resolution を 13% 引き上げています。¹⁴⁴ 新しい tokenizer を使用します。同じ text でも token counts はおおむね 1×〜1.35× になると考え、max_tokens の余裕と compaction triggers を増やしてください。¹⁴⁵ Vision は最大 2,576 px / 3.75 MP の画像を、1:1 pixel coordinates でサポートします。¹⁴⁵

Opus 4.7 coding benchmarks（2026年4月）:¹⁵¹

Opus 4.7 は SWE-bench Verified で、広く引用される GPT-5-Codex baseline を 12.7 上回り、SWE-bench Pro では GPT-5.4（57.7%）を 6.6 上回っています。Terminal-Bench 2.0 では、GPT-5.3-Codex が GPT-5.4（77.3% vs 75.1%）をなお僅差で上回り、どちらも Opus 4.7（69.4%）を上回っています。benchmark の優位性は流動的です。複数四半期にわたる選択を決める前に、vendor pages を確認してください。

plan 別の default model（Claude Code）:¹⁴⁷

Opus 4.7 には Claude Code v2.1.111 以降が必要です。claude update を実行して upgrade してください。¹⁴⁷ Bedrock、Vertex、Foundry では、Opus 4.7 は explicit full model names または ANTHROPIC_DEFAULT_OPUS_MODEL pins で公開されており、default では opus alias からは利用されません。¹⁴⁷

Opus 4.7 における Messages API の breaking changes（caller-visible）:¹⁴⁵

• Extended thinking の budget_tokens は削除されました。代わりに thinking: {type: "adaptive"} を使います。Adaptive thinking は default ではオフです。thinking field のない request は thinking なしで実行されます。
• temperature、top_p、top_k に non-default value を設定すると HTTP 400 が返ります。これらの parameters は省略し、prompting でモデルを誘導してください。
• Thinking content は default で responses から省略されます。visible reasoning を復元するには thinking.display: "summarized" を設定します（product が thinking をユーザーへ stream する場合は必須です）。

Task budgets（beta header task-budgets-2026-03-13）を使うと、output_config.task_budget により、full agentic loop 全体に対する token target をモデルへ伝えられます。minimum は 20K tokens です。¹⁴⁵

Opus 4.6（legacy）: claude-opus-4-6 で引き続き利用でき、1M context と 128K max output を備えています。より良い agentic coding のために Opus 4.7 への移行を検討してください。Opus 4.6 は当初 2026年2月5日に出荷されました。⁷⁹¹⁴⁴ v2.1.117（2026年4月22日）時点で、Pro と Max subscribers は Opus 4.6 と Sonnet 4.6 で default が high effort になりました（以前は medium）。Opus 4.7 は xhigh のままです。この変更により、4月23日の postmortem に記録された 3月4日 → 4月7日の effort downgrade 後に、intelligence が回復しました。¹⁵²¹⁵³

Sonnet 4.6（2026年2月17日）: バランス型モデルです。claude.ai と Claude Cowork 全体で、Sonnet 4.5 を default として置き換えました。⁹³ Pricing は Sonnet 4.5 と同じ（$3/$15 per MTok）です。消費 tokens を減らしながら agentic search performance が改善されています。extended thinking、adaptive thinking、1M token context window（beta）をサポートします。64K max output（v2.1.77 では upper bound 128K）。¹¹⁹ Knowledge cutoff: 2025年8月（reliable）、2026年1月（training data）。Model ID: claude-sonnet-4-6。

Claude Mythos Preview（2026年4月7日）: Project Glasswing のもとで提供される、防御的 cybersecurity work 向けの research-preview frontier model です。¹³⁹ invitation-only で、一般には利用できません。Anthropic は Opus 4.7 について、cyber dimensions では Mythos より意図的に 低い 能力にしていると説明しています。これは safety tradeoff です。また、より高い access が必要な正当な security researchers 向けに、https://claude.com/form/cyber-use-case で Cyber Verification Program を開設しています。¹⁴⁶

これらの価格差が重要な理由: 典型的な coding session では、50K〜200K input tokens と 10K〜50K output tokens を消費します。Haiku なら 1 session あたり $0.10〜$0.45 です。Opus では同じ session が $0.50〜$2.25 になり、5 倍高くなります。Opus は、本当に難しい問題のために取っておきましょう。¹

各モデルを使うタイミング

Haiku: exploration、単純な file searches、短い質問を行う subagents に使います。Opus より約 5 倍安く、応答も高速です。深い推論が不要な background tasks に最適です。

Sonnet: コストが重要な日々の開発における workhorse です。機能の実装、bug 修正、tests の作成、code review など、ほとんどの coding tasks に対応できます。Sonnet 4.6 は Sonnet 4.5 と比べて agentic search が改善され、token efficiency も向上しており、adaptive thinking support と standard pricing での 1M context window を備えています。⁹³ Opus 4.7（2026年4月16日）時点で、Claude Code が Opus を default にするのは Max と Team Premium plans のみです。Pro、Team Standard、Enterprise、API accounts では、Enterprise と API が 2026年4月23日に Opus 4.7 へ切り替わるまで、Sonnet 4.6 が default のままです。¹⁴⁷ より安い tokens、速い latency、subagent economics が必要な場合は Sonnet を使います。

Opus: 2026年4月16日時点の flagship tier であり、Max と Team Premium plans の default です。¹⁴⁴¹⁴⁷ 高コストの推論は、効果が見合う場面に限定してください。たとえば、architectural decisions、難しい debugging、複雑な systems の理解、security analysis、長期的な agentic work です。Opus 4.7 は SWE-Bench で Opus 4.6 の 3 倍の production tasks を解決し、CursorBench では 70%（58% から上昇）を記録し、93-task internal coding benchmark で resolution を 13% 引き上げています。¹⁴⁴ Claude Code では Opus 4.7 の default が xhigh effort で、/effort（v2.1.111+）により調整できます。¹⁴⁶¹⁴⁷ Auto Mode は、Max subscribers が Anthropic API 経由で Opus 4.7 を使う場合、--enable-auto-mode なしで利用できます。他の plans/providers では、plan-specific かつ admin-controlled availability があります。¹⁴⁶ 1M context は standard pricing で、long-context premium はありません。知っておくべき behavior changes: Opus 4.7 は instructions により字義通り従い、response length を task complexity に合わせ、default で起動する subagents が少なくなり、過度な validation-forward phrasing を減らした、より直接的な tone を採用します。prompt に interim progress messages や double-check behavior を強制する scaffolding が含まれている場合は、取り除いてみてください。¹⁴⁵

Opusplan: planning には Opus（reasoning quality が最も重要な部分）、execution には Sonnet（speed が重要な部分）を使う hybrid mode です。最高の plan は欲しいが、個々の edit ごとに Opus-level reasoning は不要な complex refactoring に非常に向いています。

モデルの切り替え

session 中:

> /model opus
> /model sonnet
> /model haiku

startup 時:

claude --model opus

environment 経由:

export ANTHROPIC_MODEL=opus

settings.json 内:

{
  "model": "claude-sonnet-4-5-20250929"
}

subagents 専用:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Fallback model chain（v2.1.166+）: fallbackModel setting は、primary model が overloaded または unavailable の場合に順番に試す fallback models を最大 3 つ設定します。--fallback-model flag（以前は mid-session switch のみ）も、startup から interactive sessions に適用されるようになりました。¹⁷⁶

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

API が予期しない non-retryable error を返した場合、Claude Code は failure を表示する前に fallback model でその turn を 1 回 retry するようにもなりました。そのため、一時的な primary-model problem で turn が落ちるのではなく、gracefully に degrade します。¹⁷⁶

v2.1.178 時点で、compaction も fallback chain を尊重します。primary model が mid-compaction で overloaded または unavailable になった場合、compaction step は turn を失敗させるのではなく、設定済みの fallbackModel/--fallback-model chain に fallback します。長い autonomous run では、通常なら回復可能な compaction が一時的な model error によって session を落としてしまう隙間を、これで塞げます。¹⁷³

Extended Context

大規模な codebase や長い session では、1M token context を有効にします。

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 with 1M context

または session 内で:

> /model sonnet[1m]
> /model opus[1m]

Opus 4.7、Opus 4.6、Sonnet 4.6 はいずれも、full 1M token context window を standard pricing で含みます。long-context premium はありません。¹⁴⁸ 900K-token request は、9K-token request と同じ per-token rate で課金されます。Prompt caching と batch processing discounts は、full context window 全体で standard rates のまま適用されます。

Max、Team、Enterprise subscriptions では、Opus with 1M context は自動的に含まれます。[1m] suffix は不要です（v2.1.75、2026年3月13日以降 default で有効）。¹¹⁷¹⁴⁷ Pro では、1M context は extra usage 経由でアクセスできます。API と pay-as-you-go users は、standard per-token rates で full 1M access を利用できます。¹⁴⁷

model picker で 1M context variants を無効にするには、CLAUDE_CODE_DISABLE_1M_CONTEXT=1 を設定します。

現在のモデルを確認する

> /status

この command は、current model、account info、applied settings、その他の session state を表示します。

Model picker labels（v2.1.51+）: /model picker は pinned versions について、raw model IDs ではなく人間が読める labels（例: “Sonnet 4.6”）を表示するようになりました。新しい versions がある場合は upgrade hints も表示されます。⁹⁸

Fast Mode（v2.1.36+）

Fast mode は 同じモデル から大幅に速い output を提供します。安いモデルへ切り替えるものではありません。session 中に /fast で toggle できます。⁸⁶

> /fast            # Toggle fast mode on/off

Pricing（Opus 4.6 fast mode）:

Fast mode は research preview で、Opus 4.6-only です。6× base pricing で約 2.5× 速い output を提供します。¹⁴⁹ /fast を有効にすると、別のモデルを使っていた場合でも session は自動的に Opus 4.6 へ切り替わります。/fast を無効にしても、/model で切り替えるまでは Opus 4.6 のままです。Fast mode は Opus 4.7、Sonnet、Haiku、Bedrock/Vertex/Foundry 経由では利用できません。extra usage が有効である必要があり、Team/Enterprise では admin enablement も必要です。

fast mode を使うタイミング: - latency が bottleneck になる小さな変更を素早く iterate する場合 - speed が cost より重要な tests、boilerplate、repetitive code を生成する場合 - 類似 tasks のリストを順番に処理する場合

fast mode を使わない方がよいタイミング: - 長時間実行される agentic tasks（6x rates では cost がすぐ積み上がります） - background subagent work（output を待っている人がいません） - 予算を意識する sessions

Opus 4.6 fast mode は full 1M context window を含みます（v2.1.50+）。Fast mode pricing は 1M context 全体で flat です。追加の long-context surcharge はありません。⁹⁶¹⁴⁹

Expert tip: Fast mode は opusplan と組み合わせるものではありません（opusplan はすでに Opus と Sonnet を混在させます。fast mode が影響するのは Opus 4.6 のみです）。latency が cost より重要なときは fast mode を直接使い、autonomous work や batch work では無効にしてください。/fast には extra usage が必要です。Team/Enterprise admins は先に有効化する必要がある場合があります（v2.1.37 fix）。⁸⁶¹⁴⁹

Effort Control（v2.1.111+、Opus 4.7）

Opus 4.7 では、speed/intelligence tradeoff を調整する新しい effort dial が導入されています。session 中に /effort を使います。

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

Claude Code は Opus 4.7 で default が xhigh effort になりました。xhigh は Opus-4.7-only です。他のモデルは high に fallback します。Claude Managed Agents は effort を自動で処理します。effort parameter は Messages API の concept です。¹⁴⁵¹⁴⁶

Max の Auto Mode（v2.1.111+）

Auto Mode は、--dangerously-skip-permissions のより安全な置き換えです。Max subscribers は、Anthropic API 経由の Opus 4.7 で、--enable-auto-mode なしに利用できます。¹⁴⁶ Sonnet-4.6 classifier が各 action を execution 前に review し、intent match と safety を確認します。Note（v2.1.111+）: --enable-auto-mode flag は削除されました。Auto Mode で session を開始するには、代わりに --permission-mode auto を使います。Auto Mode は Pro では利用できません。Anthropic の permission modes docs によると、Anthropic API では default で direct です。Bedrock/Vertex/Foundry（v2.1.158+）: これらの gateways では、Auto Mode が Opus 4.7 と Opus 4.8 で CLAUDE_CODE_ENABLE_AUTO_MODE=1 による opt-in になりました。¹⁷⁹

defaults を失わずに custom rules を使う（v2.1.118+）。 以前の versions では、autoMode.allow、autoMode.soft_deny、autoMode.environment は either-or でした。独自リストを定義すると、built-in safety rules を失っていました。$defaults sentinel がこれを解決します。配置したちょうどその位置で built-in list に inline 展開されるため、その前後に custom rules を重ねられます。¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

“Don’t ask again” opt-in（v2.1.118+）。 Auto Mode opt-in prompt に “Don’t ask again” option が追加されました。頻繁に使う users は、flag を script せずに explainer を抑制できます。¹⁵²

v2.1.105〜v2.1.114 の新しい Commands¹⁴⁶¹⁵⁰

Session Recap（v2.1.108+）

paused session に戻ったときに context を表示する、新しい session-level feature です。default で有効で、/config または CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0 から opt-out できます。model は Skill tool 経由で built-in slash commands（/init、/review、/security-review）も invoke できます。これは subagent/skill pattern を拡張するものです。¹⁴⁶

Push Notifications（v2.1.110+）

Remote Control で “Push when Claude decides” が有効に設定されている場合、Claude は新しい push-notification tool により、自身の判断で mobile push notifications を送れるようになりました。既存の Remote Control mobile/web surface と組み合わせて使います。¹⁴⁶ /context、/exit、/reload-plugins も Remote Control clients から動作するようになりました。

Windows PowerShell Tool（v2.1.111+、rollout）

Claude Code は native Windows PowerShell tool を段階的に展開しています。Linux/macOS では CLAUDE_CODE_USE_POWERSHELL_TOOL=1 で有効にします（PATH 上に pwsh が必要です）。Windows では、rollout 中の opt-in/opt-out を同じ変数で制御します。¹⁴⁶

Permission-mode auto-approval（v2.1.119+）。 PowerShell tool commands は、Bash commands と同様に permission mode で auto-approval を受けられるようになりました。PowerShell(Get-*:*) のような allow rules と既存の pattern syntax により、read-only operations では prompt を bypass できます。Linux/macOS で teams がすでに得ている operator ergonomics と揃います。¹⁵²

Permission Reduction: Read-Only Bash（v2.1.111+）

glob arguments を持つ read-only Bash patterns（例: ls *.ts、cat src/*.md）と、cd <project-dir> && で始まる commands は、permission prompt を trigger しなくなりました。¹⁴⁶ /less-permission-prompts と組み合わせることで、日常の workflows で interruptions が大幅に減るはずです。

Distributed Tracing（v2.1.110+）

SDK と headless sessions は、environment から TRACEPARENT と TRACESTATE を読み取るようになり、Claude Code runs を distributed traces に link できます。debugging のために full API request/response bodies を OpenTelemetry log events として emit するには、OTEL_LOG_RAW_API_BODIES=1（v2.1.111+）と組み合わせます。¹⁴⁶

Native Binary Distribution（v2.1.113+）¹⁵⁰

v2.1.113 では、CLI の launch 方法が変わります。claude は bundled JavaScript を実行する代わりに、per-platform optional dependency 経由で native Claude Code binary を spawn するようになりました。installation と update commands はそのままで、teams が rollout scripts を変更する必要はありません。

Prompt Editor Shortcuts（v2.1.113+）¹⁵⁰

prompt editor には、multiline input での readline-style navigation と fullscreen viewport scrolling が追加されました。

これらは default で有効です。keybinding config は不要です。

Subagent Stall Timeout（v2.1.113+）¹⁵⁰

mid-stream で stall した subagents は、黙って hang する代わりに、10 分後に明確な error で fail するようになりました。streaming APIs における stuck-process coverage を広げるには、CLAUDE_STREAM_IDLE_TIMEOUT_MS（v2.1.84+）と組み合わせます。

v2.1.114 Stability Fix¹⁵⁰

v2.1.114（2026年4月18日）には 1 つの fix が含まれています。agent-teams の teammate が tool permission を request したときに、permission dialog が crash することがありました。Agent Teams を使っている場合は upgrade してください。

Claude Codeのコストはどれくらいか

コストを把握し管理することは、Claude Codeを持続的に活用するうえで欠かせません。モデルの能力についてはModel Selection、タスクごとに適切なモデルを選ぶ方法についてはDecision Frameworksもあわせてご覧ください。

コストの確認

> /cost

出力例：

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

サブスクリプションユーザーの場合、/costでモデル別およびキャッシュヒット別の内訳が表示され、どのモデルがトークンを消費し、どれだけがキャッシュから提供されたかを正確に確認できます（v2.1.92以降）。¹³⁷

サブスクリプションプラン

レート制限（2025年8月）： Anthropicは有料サブスクライバー向けに週次のレート制限を導入しました。Maxサブスクライバーはレート制限を超える追加利用量を、標準のAPIレートで購入できます。¹⁴

レート制限の倍増（2026年5月6日）： Code with Claude SFイベント期間中、AnthropicはPro、Max、Team、およびシートベースのEnterpriseプラン全体でClaude Codeの5時間レート制限を倍増させ、ProおよびMaxアカウントのピーク時間帯の制限を撤廃し、Claude Opusモデル向けのAPIレート制限を「大幅に」引き上げました。これを支える容量基盤となるのがSpaceX Colossus 1の契約です。「月内に300メガワットを超える新規容量（22万基以上のNVIDIA GPUs）」を確保しています。¹⁵⁷

APIトークン料金（2026年4月）¹¹⁴⁴

API課金ユーザーの場合、100万トークンあたりの料金は次のとおりです：

1Mコンテキスト料金（2026年4月）： Opus 4.7、Opus 4.6、Sonnet 4.6、およびMythos Previewはすべて、1Mを標準のMTokあたりレートで提供しており、長文コンテキストの追加料金は発生しません。¹⁴⁸ これは最近の統一化によるもので、Opus 4.6またはSonnet 4.6が200K入力トークンを超えると入力2倍／出力1.5倍を支払うという以前の説明はもはや有効ではありません。レガシーのOpus 4.5以前のモデルは、元の料金体系を維持しています。

データレジデンシー料金： inference_geoを介して米国限定の推論を指定すると、キャッシュの読み取り・書き込みを含むすべてのトークン料金に1.1倍の乗数が加算されます（Opus 4.6以降のモデル）。¹⁴⁸

Prompt cachingは繰り返しの入力コストを大幅に削減します。キャッシュ書き込みはベースの1.25倍（5分キャッシュ）または2倍（1時間キャッシュ）ですが、キャッシュ読み取りはわずか0.1倍で、90%の節約となります。RAGシステムや繰り返しコンテキストを持つコードアシスタントでは、キャッシングによりコストを88〜95%削減できます。

Batch APIは、夜間のテストスイートのような非緊急タスクに対し、24時間のターンアラウンドで50%の割引を提供します。

複数アカウントポリシー⁵²

Claudeアカウントを複数持てるか？ 正当な利用目的であれば可能です。Anthropicは、明確に異なる用途のためであれば複数アカウントを明示的に許可しています。

許可されるケース：

技術的な上限： - 同一の電話番号で最大3アカウントまで認証可能 - 同一IP/ネットワークからの複数の有料サブスクリプションは明示的にサポート - アカウントは完全に分離されており、チャットやプロジェクトの相互移行は不可

禁止されるケース（Usage Policyに基づく）： - BAN後にBANを回避する目的でのアカウント作成 - 検出を逃れるためにアカウント間で悪意のある活動を調整すること - レート制限や無料枠を回避するための複数アカウント利用

実例： 2026年1月、パワーユーザーのJeffrey Emanuel氏（@doodlestein）が保有していた22のMaxアカウントが自動フラグ付けされ、一時的にBANされました。Anthropicの従業員Thariq氏（@trq212）が正当な利用を確認後、4時間以内に解決しています。仕事と個人プロジェクトの両方で複数アカウントを使いClaude Codeを本格的に活用するのは、まさにこのサービスが想定する使い方ですが、システムを欺こうとしてはいけません。

判断に迷ったら： Anthropic Supportに連絡し、特定の利用構成について書面で確認してもらいましょう。

コスト要因

実際のコスト例

コスト削減のヒント： 探索系のサブエージェントにHaikuを、実装にSonnetを使うと、すべてSonnetを使う場合と比べて通常40〜50%のコスト削減になります。

チームのコスト管理

チーム規模別の推奨TPM/RPM：

隠れたツール料金

トークン単価とは別に、一部のツールには個別の料金が発生します：⁹

これらはエージェントループで積み重なります。Bashを使った100回反復のデバッグサイクルでは、オーバーヘッドだけで約24,500の追加入力トークンが消費されます。

コスト削減戦略

1. サブエージェントにはHaikuを使用：探索のほとんどはSonnetを必要としません
2. Prompt cachingを有効化：デフォルトで有効ですが、無効化されていないか確認しましょう
3. 最大ターン数を設定：claude --max-turns 5で会話の暴走を防止
4. 探索にはplan modeを使用：実行されない＝意図しない高コスト操作も発生しません
5. 積極的にコンパクト化：コンテキストが小さい＝トークンが少ない
6. 出力を制限：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. 非緊急業務にはBatch API：入力・出力トークンともに50%オフ

利用状況のモニタリング

• Claude Console：platform.claude.com（AdminまたはBillingロールが必要）
• ワークスペース上限：ワークスペースごとに支出上限を設定
• Bedrock/Vertex：ネイティブのクラウドコストモニタリングを利用
• LiteLLM：サードパーティプロバイダーと組み合わせたユーザー単位の詳細追跡向け

バックグラウンドのトークン使用

一部の操作はバックグラウンドでトークンを消費します： - /resume用の会話サマライズ - /costおよび/statusコマンド - 自動コンパクト化

通常は1セッションあたり$0.04未満です。

Claude Code Analytics API（Team/Enterprise）⁴⁶

組織のClaude Code利用分析と生産性メトリクスに、Admin API経由でプログラムによりアクセスできます。

エンドポイント： GET /v1/organizations/usage_report/claude_code

要件： - Admin APIキー（sk-ant-admin...） - TeamまたはEnterpriseプラン - Admin、Billing、またはDeveloperロール

利用可能なメトリクス：

リクエスト例：

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

ユースケース： - 開発者の生産性分析（セッション、コミット、PR） - ツール利用メトリクス（Edit、Writeなどの承認・拒否率） - チームをまたいだコスト追跡と配分 - AIコーディングツールのROI根拠

注意： データはアクティビティ完了から1時間以内に表示されます。一貫性のため、レスポンスには1時間以上経過したデータのみが含まれます。

意思決定フレームワーク

機能の存在を知っているだけでは不十分です。それぞれをいつ使うべきかを知る必要があります。これらの意思決定ツリーは、知識を行動に変えるものです。

どのモデルを使うべきか？

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 4.7 (xhigh effort default)
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.75/task
                           Balance: Best overall when cost matters

目安: Opus 4.7はMaxとTeam Premiumのデフォルトです。Pro/Team Standard/Enterprise/APIでは、Sonnet 4.6がデフォルトとなります（Enterprise + Anthropic APIは2026年4月23日にOpus 4.7に切り替わります）。¹⁴⁷ サブエージェントにはHaikuに下げましょう。Sonnetの回答が浅く感じる場合はOpusにエスカレーションしてください。エージェントチーム（v2.1.32+）を使えば、Opusが複数のエージェントを調整し、異なるサブタスクで並列作業させることができます。⁷⁹

コマンド vs スキル vs サブエージェント vs エージェントチーム？

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook vs プロンプト？

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

拡張思考をいつ使うべきか？

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

セッション中にAlt+Tで切り替えができます。思考バジェットを高くするほどコストも増えます。最小から始めて、回答が急ぎすぎだと感じた場合にのみ増やしましょう。

Opus 4.6 の適応的思考: Opus 4.6は問題の複雑さに応じて思考の深さを自動的に調整します。ほとんどのタスクでは、明示的な思考バジェット制御は必要ありません。Opusは難しい問題ではスケールアップし、シンプルな問題では高速に動作します。手動での思考切り替えは、Sonnetで深い分析を強制したい場合に最も有用となります。

どの実行サーフェスを選ぶか？

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

エージェントチーム vs サブエージェント vs 並列セッション

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

どのHookタイプを使うか？

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

/fast をいつ使うか？

Is response speed more important than depth right now?
│
├── YES → Use /fast
│         Same Opus 4.6 model, faster output
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fastは現在のセッションで高速モードを切り替えます。同じモデル（Opus 4.6）を使用し、出力速度を最適化しています。安価なモデルには切り替わりません。

権限システムはどのように動作しますか？

Claude Codeの権限システムでは、実行できる操作を細かく制御できます。セキュリティとワークフロー効率の両方にとって、この仕組みの理解は重要です。組織全体で権限を強制する管理設定については、Enterprise Deploymentも参照してください。

権限ティア

読み取り専用ツール（自動承認）： - Read - ファイル内容を読み取る - Glob - パターンでファイルを検索する - Grep - ファイル内容を検索する - WebSearch - Webを検索する - LSP - コードインテリジェンス（定義へ移動、参照検索、ホバー docs）¹⁸

LSP Toolの機能（v2.0.74+）： LSP toolはIDEのようなコードインテリジェンスを提供します。 - 定義へ移動：シンボルが定義されている場所へジャンプします - 参照検索：コードベース全体でのシンボルの使用箇所を一覧表示します - ホバー docs：任意のシンボルの型情報とドキュメントを取得します - TypeScript、Python、Go、Rust、およびLSP対応のその他の言語で動作します - language serverが利用可能である必要があります（通常はtoolchainと一緒にインストールされます）

変更ツール（承認が必要）： - Edit - 既存ファイルを変更する - Write - 新しいファイルを作成する - Bash - shellコマンドを実行する - WebFetch - URLの内容を取得する - NotebookEdit - Jupyter notebookを変更する

変更ツールを初めて実行すると、Claude Codeは承認を求めます。明示的に別の設定をしない限り、承認はセッション中保持されます。

権限モード

コード実行設定ファイルは、acceptEditsでもプロンプト対象になりました（v2.1.160）。 acceptEditsは通常の編集を自動承認しますが、v2.1.160以降は、暗黙のコマンド実行を可能にするファイルを書き込む前に停止してプロンプトを表示します。対象は、shell起動ファイル（.zshenv、.zlogin、.bash_login）、~/.config/git/、build-tool設定（.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/など）です。理由は、これらのいずれかを編集すると、次のshell、install、commitが実行経路になり得るためです。そのため、通常なら編集を通す信頼済みプロジェクト用モードでも、意図的なゲートが入ります。これは既存の.claude/、.git/、.vscode/への書き込み保護と同じ脅威モデルを、「編集が実行に変わる」より広い種類のファイルへ拡張したものです。¹⁷⁸

Auto Mode（v2.1.85+）： --dangerously-skip-permissionsのより安全な代替です。別のclassifierモデル（Sonnet 4.6）が実行前に各アクションをレビューし、ユーザーの意図と一致していて安全かどうかを確認します。¹²⁴

動作の流れ： - 読み取り専用アクションと作業ディレクトリ内のファイル編集は自動承認されます - カスタムのallow/denyルールが先に解決されます - それ以外はすべてclassifierによる評価に送られます - ブロックされた場合、Claudeは自動的に別のアプローチを試します

デフォルトで自動ブロックされるもの：curl | bash、mainへのforce-push、本番deploy/migration、大量のcloud削除、IAM/権限変更、機微データの外部送信。¹²⁵

Circuit breaker：セッション中に連続3回ブロック、または合計20回ブロックされると、手動プロンプトに一時的に戻ります。¹²⁵

# Enable at startup
claude --enable-auto-mode

# Or cycle into it during a session
Shift+Tab  # Cycles through: default → acceptEdits → auto → plan

利用可能範囲：まずTeam planユーザー、その後EnterpriseとAPI。Sonnet 4.6またはOpus 4.6が必要です。¹²⁴

YOLO Mode（v2.0.68+）： safety classifierなしで完全自律動作させるには、--dangerously-skip-permissionsフラグを使用します。このフラグは、ファイル編集、bashコマンド、すべてのtool callに対してyesと答えます。「dangerous」という語は意図的です。ほとんどのユースケースでは、Auto Modeが推奨される代替です。⁵⁴

claude --dangerously-skip-permissions

CLIでmodeを設定します。

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

セッション中に切り替えます。

Shift+Tab  # Cycles through modes

settings.json内：

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

権限ルールの構文

細かなルールで特定の操作を制御できます。ルールは順番に評価され、最初に一致したものが適用されます。

Bashコマンドパターン：

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

アスタリスクはprefix matchingを行います。Bash(npm run test:*)は、npm run test、npm run test:unit、npm run test:integrationを許可します。

重要な制限： Bashパターンはprefixのみに一致し、regexではありません。Bash(curl http:*)のようなパターンは、URLの前にoptionsが来るため、curl -X GET http://...には一致しません。確実にブロックするには、コマンド全体をdenyしてください：Bash(curl:*)。

ファイル操作パターン：

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

パス構文： - 相対パス：Edit(src/**) - 作業ディレクトリからの相対 - 設定ファイルからの絶対風パス：Edit(/build/**) - 設定ファイルの場所からの相対 - 真の絶対パス：Edit(//tmp/**) - //で始まります - ホームディレクトリ：Read(~/.zshrc)

MCP toolパターン：

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

ワイルドカード構文mcp__server__*を使うと、特定のMCP serverのすべてのツールをallowまたはdenyできます。³² ワイルドカード構文は、信頼済みserverのすべてのツールをすばやく有効化したり、信頼できないソースのserver全体をブロックしたりする場合に便利です。

v2.1.166以降、denyルールではtool-nameの位置にもglobを指定できます。tool-name slotに裸の"*"を置くとすべてのツールをdenyできるため、いったんすべてをブロックしてから狭い範囲だけallowで戻せます。一方、allowルールでは非MCPのglobは拒否されます。同じ方法で広くallow-allすることはできないため、デフォルトの姿勢は制限的に保たれます。¹⁷⁶

パラメータレベルの一致 — Tool(param:value)（v2.1.178）：

ツール名に加えて、ルールはツールの入力パラメータにも一致できます。値には*をワイルドカードとして使えます。

{
  "deny": [
    "Agent(model:opus)"
  ]
}

Agent(model:opus)は、Opusティアで起動されるsubagentをすべてブロックします。単にpromptで避けるよう求めるだけではなく、spawn自体がdenyされます。これにより、権限制御は「どのツールか」から「どのように呼び出されるか」まで拡張され、promptレベルの依頼ではなく決定的なルールになります。これは管理設定enforceAvailableModelsと組み合わせて使えます。allowlistでセッションに存在するmodelティアを定義し、Tool(model:...)ルールでsubagentがそれらをどう使うかを制約します。¹⁷³

WebFetchパターン：

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

追加ディレクトリ

Claudeのアクセスを現在のプロジェクト外へ拡張します。

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

追加ディレクトリは、monorepoの場合や、Claudeが隣接ディレクトリのコードを参照する必要がある場合に不可欠です。

Sandbox Mode

filesystemとnetworkの分離を有効にします。

> /sandbox

またはsettingsで設定します。

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

sandbox化されている場合： - filesystemアクセスはプロジェクトディレクトリに制限されます - networkアクセスは制御されます - 一部のコマンドはsandbox制限から除外されます - autoAllowBashIfSandboxedがtrueの場合、Bashコマンドは自動許可されます

Expert tip: Sandbox modeは、信頼できないコードベースでClaudeを実行する場合に非常に有効です。見慣れないプロジェクトを探索するときや、追加の保護レイヤーが欲しいときに有効化してください。Anthropicの内部テストでは、sandboxingにより権限プロンプトが84%減少することがわかっています。³⁸ sandboxはfilesystemとnetworkの分離にOSレベルのprimitives（macOS seatbelt、Linux bubblewrap）を使用するため、prompt injectionが成功したとしても完全に封じ込められます。Anthropicは、自社agentを構築するチーム向けにsandbox runtimeをopen-source化しています。⁸²

セキュリティノート（v2.1.34+）： sandbox.excludedCommandsまたはdangerouslyDisableSandboxでsandboxingから除外されたコマンドは、以前はautoAllowBashIfSandboxedが有効な場合にBash ask permission ruleを回避できましたが、これはv2.1.34で修正されました。⁸⁷ v2.1.38以降、sandbox modeでは.claude/skillsへの書き込みがブロックされ、prompt injectionがskill定義を変更することを防ぎます。⁸⁸ v2.1.77では、denyRead領域内で読み取りアクセスを再許可するsandbox filesystem設定allowReadが追加されました。ディレクトリツリーの大半をブロックしつつ、特定のsubdirectoryだけをwhitelistしたい場合に便利です。¹¹⁹

.claude/ agent-config exemption（v2.1.121+）： --dangerously-skip-permissionsは、.claude/skills/、.claude/agents/、.claude/commands/への書き込みでプロンプトを表示しなくなりました。¹⁵⁴

ネストされた.claude/の解決（v2.1.178）： ネストされた.claude/skillsディレクトリ内のskillsは、そのディレクトリ配下のファイルで作業すると自動的に読み込まれるようになりました。repo rootからだけではありません。名前が衝突した場合、ネストされたskillは<dir>:<name>として参照できるため、両方を利用できます。プロジェクトの他のsurfaceも同じように解決されます。agent、workflow、output-style名がネストされた.claude/ディレクトリ間で衝突した場合、作業ディレクトリに最も近いものが優先され、project-scopeのworkflow saveは最も近い既存の.claude/workflows/を対象にします。monorepoやrepo-of-reposでは、単一のflatなglobal surfaceではなく、packageごとのtoolingがcontextに応じて有効になります。¹⁷³

カスタムbubblewrapおよびsocatパス（v2.1.133+）： sandbox.bwrapPathとsandbox.socatPathの管理設定により、管理者はLinux/WSL deploymentで非標準のbubblewrapおよびsocat binaryの場所を指定できます。distributionがこれらのツールを$PATH外にインストールする場合や、組織がhardened buildをvendorしている場合に便利です。¹⁶⁰

v2.1.113でのセキュリティ強化：¹⁵⁰

• sandbox.network.deniedDomains は、より広いallowedDomainsワイルドカードでは許可されるhostであっても、特定のhostをブロックします。pastebin、file drop、既知の悪意あるhostを、allow policy全体を書き換えずに遮断するにはblocklistを使用します。
• Wrapper-command denyルール。 Bash denyルールは、env、sudo、watch、ionice、setsidなどのexec wrapperで包まれたコマンドにも一致するようになりました。Bash(rm:*)のようなルールは、env rm -rf、sudo rm -rf、および類似のbypass patternも捕捉します。
• Bash(find:*) allowルールは、find -execやfind -deleteを自動承認しなくなりました。 これらのflagはコマンドを実行したりファイルを削除したりするため、Claude Codeは通常の権限パスに送ります。
• macOSの削除保護。 Bash(rm:*) allowルールは、/private/etc、/private/var、/private/tmp、/private/homeを危険な削除対象として扱うようになりました。/var、/etc、/tmpは/private/へのsymlinkであるため、以前のルール形状ではcanonical targetを見逃していました。

Hooksはどのように動作しますか？

Hooksは、Claude Codeのワークフロー内の特定の時点で、決定論的なシェルコマンドを実行します。Claudeにアクションを促すプロンプトとは異なり、hooksはモデルの挙動に関係なく実行を保証します。チーム標準の強制や反復タスクの自動化に不可欠です。command、prompt、agent hooksを含む「どのHookタイプを使うか？」の判断ツリーについては、判断フレームワークをご覧ください。

プロンプトではなくhooksを使う理由: Claudeに「ファイルを編集した後は必ずPrettierを実行して」と伝える方法は、ときどき機能します。ただし、Claudeは忘れたり、速度を優先したり、その変更は「小さすぎる」と判断したりする可能性があります。Hooksなら実行が保証されます。すべてのEditまたはWriteでフォーマッターが毎回、例外なく起動します。コンプライアンス、セキュリティ、チーム標準では、確率的な動作より決定論的な動作が優れています。⁴

利用可能なイベント

Hook設定

settings.jsonまたは専用のhooks.jsonでhooksを定義します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

matcherフィールドは、どのツールがhookをトリガーするかを決定します。

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Hook入出力プロトコル

HooksはstdinでJSONを受け取ります。

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Hookイベントの拡充（v2.1.69+）: すべてのhookイベントは、subagentまたは--agentセッションからトリガーされた場合にagent_idとagent_typeフィールドを含むようになりました。また、status line hookコマンドにはworktreeフィールドも含まれます。¹¹⁰

Stop/SubagentStop hooks（v2.1.47+）は、Claudeの最終応答テキストを含む追加のlast_assistant_messageフィールドを受け取ります。これにより、hooksはtranscriptファイルを解析せずに出力を検査できます。

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

ブロックなしのソフトフィードバック（v2.1.163+）: StopおよびSubagentStop hooksは、JSON出力でhookSpecificOutput.additionalContextを返すことで、hookエラーとしてラベル付けされずに、Claudeへフィードバックを渡しターンを継続できます。以前は、Stop hookで実質的に使える手段はexit-2ブロックだけでした（これはエラーとして扱われ、連続ブロック上限にもカウントされます）。additionalContextにより、「ここが不足しています、続けてください」という案内を、ループと衝突せずに渡すための誘導チャネルが追加されました。¹⁷⁷

終了コードが挙動を制御します。 - 0: 成功: 操作は続行されます。Stdoutはverbose mode（Ctrl+O）で表示されます。UserPromptSubmitとSessionStartでは、stdoutがコンテキストに追加されます。 - 2: ブロックエラー: 操作は停止します。StderrはClaudeへ返されるエラーメッセージになります。 - 1, 3, etc.: 非ブロックエラー: 操作は続行されます。Stderrはverbose modeで警告として表示されます。

高度な制御では、hooksはJSONを出力できます。

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

PreToolUseのdecision control（推奨形式）: PreToolUse hooksは、より豊かな制御のためにhookSpecificOutputを使います。3つの結果（allow/deny/ask）に加え、ツール入力の変更とコンテキスト注入が可能です。⁸⁹

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

注: PreToolUseでは、トップレベルのdecisionとreasonフィールドはdeprecatedです。代わりにhookSpecificOutput.permissionDecisionとhookSpecificOutput.permissionDecisionReasonを使ってください。他のイベント（PostToolUse、Stopなど）では、引き続きトップレベルのdecisionを使います。⁸⁹

UserPromptSubmitのセッションタイトル（v2.1.94+）: UserPromptSubmit hooksは、hookSpecificOutput.sessionTitleでセッションタイトルを設定できます。¹⁴⁰

Async Hooks（2026年1月）

Hooksは、Claude Codeの実行をブロックせずにバックグラウンドで実行できるようになりました。hook設定にasync: trueを追加します。⁸¹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

async hooksを使う場面: - セッションを遅くすべきでない通知（Slack、email、Pushover） - バックグラウンドで実行できるログ記録やtelemetry - 重要度の低い後処理（analytics、backups）

async hooksを使わない場面: - フォーマット（次の編集前に完了する必要があります） - 検証（失敗時にブロックする必要があります） - ツールの入力／出力を変更する必要があるhook

Prompt-BasedおよびAgent-Based Hooks（v2.1.32+）

シェルコマンドhooks（type: "command"）に加えて、Claude Codeは、スクリプトではなくAI reasoningで条件を評価する2種類のLLM駆動hookタイプをサポートします。⁸⁹

Prompt hooks（type: "prompt"）は、高速なClaudeモデルにsingle-turn promptを送信します。モデルは許可する場合に{ "ok": true }、ブロックする場合に{ "ok": false, "reason": "..." }を返します。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

HTTP hooks（type: "http"）は、イベントのJSON入力をPOSTリクエストとしてURLに送信し、JSONを受け取ります。webhooks、外部通知サービス、またはAPIベースの検証に使います（v2.1.63+）。¹⁰⁴

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

HTTP hooksはcommand hooksと同じdecision形式を使います（decisionとreasonを含むJSONを返します）。sandboxingが有効な場合は、sandbox network proxy経由でルーティングされます。SessionStart/Setupイベントではサポートされません。

Agent hooks（type: "agent"）は、ツールアクセス（Read、Grep、Glob）を持つsubagentを起動してmulti-turn verificationを行います。実際のファイルやテスト出力の検査が必要な確認で使います。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

HookのJSON入力のプレースホルダーとして$ARGUMENTSを使います。どちらのタイプもmodel（デフォルトはfast model）とtimeoutフィールドをサポートします。対応イベント: PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、UserPromptSubmit、Stop、SubagentStop、TaskCompleted。TeammateIdleはprompt/agent hooksをサポートしません。

MCP Tool Hooks（v2.1.118+）

Hooksはtype: "mcp_tool"を通じてMCPツールを直接呼び出せるようになりました。サーバーを呼び出すBash subprocessでラップする必要を回避できます。¹⁵²

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

これは、ユーザーがすでに設定しているMCPサーバーと相性がよいです。/mcpから到達できる任意のツールは、hookから呼び出せます。

PostToolUse Hooksのduration_ms（v2.1.119+）

PostToolUseとPostToolUseFailureのhook入力には、権限プロンプトとPreToolUse hooksを除いたツール実行時間であるduration_msが含まれるようになりました。¹⁵² 遅いツールの検出、監査ログ、ツール別レイテンシ指標に便利です。

# Stderr-flagged warning when an Edit takes more than 10 seconds
DUR=$(jq -r '.duration_ms')
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $TOOL_INPUT_FILE_PATH" >&2
fi

すべてのツールに対するupdatedToolOutput（v2.1.121+）

v2.1.118では、MCP Tool HooksにhookSpecificOutput.updatedToolOutputでツール出力を置き換える機能が追加されました。v2.1.121以降、同じフィールドが任意のPostToolUse hookで使えます。組み込みツール（Bash、Read、Edit、Glob、Grepなど）、subagent tools、MCP toolsが対象です。ユースケースには、任意のツール出力からの機密情報のredact、後続コンシューマー向けの構造正規化、agentが結果を読む前のmetadata注入があります。¹⁵⁴

Hook環境変数

Hooksはパス解決のために環境変数へアクセスできます。⁸⁹

SessionStartから環境変数を永続化する:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

HTTP hook security（v2.1.51+）: 環境変数をheadersへ補間するHTTP hooksでは、明示的なallowedEnvVarsリストが必要になりました。これにより、header値を通じた任意の環境変数の外部流出を防ぎます。HTTP hooksは、sandboxingが有効な場合にsandbox network proxy経由でもルーティングされ、domain allowlistが強制されます。HTTP hooksはSessionStart/Setupイベントではサポートされません。⁹⁸

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Hook workspace trust（v2.1.51+）: statusLineとfileSuggestion hookコマンドは、interactive modeで実行する前にworkspace trustの承認が必要になりました。これにより、潜在的なセキュリティ経路が閉じられます。⁹⁸

実用的なHook例

編集後にTypeScriptファイルを自動フォーマットする:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

すべてのbashコマンドをログに記録する:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

機密ファイルへのアクセスをブロックする:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0

コード変更後にテストを実行する:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

カスタム通知システム:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

プロンプトへ動的コンテキストを注入する:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Hookデバッグ

hooksのトラブルシューティングにはdebug modeを有効にします。

claude --debug

Debug modeでログに記録される内容: - Hook実行時間 - 入出力データ - エラーメッセージとstack traces - Decision results（allow/reject/ask）

Hook source display（v2.1.75+）: hookがユーザー確認を必要とする場合、permission promptにhookのsource（settings、plugin、またはskill）が表示されるようになりました。どのコンポーネントがアクセスを要求しているかを特定しやすくなります。¹¹⁷

Component-Scoped Hooks（v2.1.0+）

Hooksはfrontmatterを使って、Skills、subagents、slash commands内に直接定義できます。これらのhooksはコンポーネントのライフサイクルにスコープされ、そのコンポーネントがactiveな場合にのみ実行されます。³⁴

hooksを埋め込んだSkill:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

対応イベント: PreToolUse、PostToolUse、Stop

onceオプション（skillsとslash commandsのみ）は、hookがセッションごとに1回だけ実行されることを保証します。クリーンアップやfinalizationタスクに便利です。

長時間セッションの戦略

夜間または無人のClaude Codeセッションでは、手動介入なしでClaudeを軌道に乗せ続けるようにhooksを設定します。重要なポイントは、lintingとtesting hooksをガードレールとして使い、継続前にClaudeへ問題修正を強制することです。⁵⁷

「テストが通るまで停止しない」パターン:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

夜間セッションの戦略:

1. Pre-flight check: Setup hookを使って、環境の準備ができていることを検証します
2. Continuous validation: PostToolUse hooksが各変更後にテストを実行します
3. Gate completion: Stop hooksが、Claudeが「done」と宣言する前にすべての受け入れ条件を検証します
4. Notification: Stop hooksは、Claudeが完了したり詰まったりしたときにSlack/Pushoverで通知できます

完全自律の夜間実行には、sandboxed container内で--dangerously-skip-permissionsと組み合わせます。Claudeは、テストが通るか選択肢を使い果たすまで反復し続けます。

MCP（Model Context Protocol）とは？

MCP は、標準化されたプロトコルを通じて、外部ツール、データベース、API、サービスへのアクセスを Claude Code に拡張します。エコシステムは爆発的に成長し、MCP は現在、月間 1 億ダウンロード、3,000 を超えるサーバーが MCP.so にインデックスされており（2026 年 1 月時点）、AI とツールおよびデータを接続する業界標準としての地位を確立しています。³⁴⁷ MCP を理解することは、既存のツールチェーンに Claude を統合する上で不可欠です。

開発者にとって MCP が重要な理由： MCP がなければ、Claude Code はファイルの読み取りと bash コマンドの実行しかできません。MCP があれば、Claude は本番データベースのクエリ、Jira チケットの作成、GitHub PR のレビュー、Sentry エラーのチェック、そしてチームが使用するあらゆる API との対話を、すべて自然言語のリクエストから実行できます。このプロトコルは AI ツールが外部サービスに接続する方法を標準化し、ベンダーロックインを防ぎます。MCP を他の拡張メカニズムと比較していつ使うべきかについては、Decision Frameworks を参照してください。

リモート MCP サポート（2025 年 6 月）

Claude Code はネイティブの OAuth 認証を備えたリモート MCP サーバーをサポートするようになりました。²¹ ローカルサーバーを管理することなく、ツールやデータソースに接続できます。一度認証するだけで、Claude Code がトークンの更新を自動的に処理します。

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

SDK mcp_authenticate redirectUri（v2.1.121+）： Agent SDK の mcp_authenticate は redirectUri パラメータを受け取り、カスタム URI スキームでの OAuth を完了できます。デフォルトのループバックリダイレクトを使用できないデスクトップアプリや claude.ai コネクタフローに必要です。¹⁵⁴

claude.ai MCP コネクタ（v2.1.46+）

Claude Code は claude.ai アカウントで設定された MCP コネクタを使用できるようになりました。これにより Web と CLI のギャップが埋まります。claude.ai インターフェースを通じて設定した MCP サーバーは、ローカルで再設定することなく、Claude Code で自動的に利用可能になります。⁹⁵

オプトアウト： 環境変数または settings.json の env ブロックで ENABLE_CLAUDEAI_MCP_SERVERS=false を設定すると、claude.ai MCP サーバーの読み込みを防げます。¹⁰⁴

MCP Tool Search（v2.1.7+）

MCP サーバーが高機能化するにつれて（50 個以上のツールを公開するものもあり）、ツールの説明が過剰なコンテキストを消費し始めました。MCP Tool Search は、必要なときにのみツールの説明を動的にロードすることでこの問題を解決します。AI ツールのレイジーローディングの一形態です。⁴⁷

パフォーマンスへの影響： 内部ベンチマークでは、劇的な精度向上が示されています： - Opus 4: MCP 評価で 49% → 74% - Opus 4.5: MCP 評価で 79.5% → 88.1% - トークンオーバーヘッドの削減：85%

仕組み： MCP ツールの説明がコンテキストウィンドウの 10%（デフォルトのしきい値）を超えると、Claude Code は実際に必要になるまで完全な説明のロードを延期します。Claude にはツール名は見えますが、説明はオンデマンドで取得します。

設定：

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

値： - true - 常に Tool Search を有効化 - false - 常に無効化（すべてのツール説明を事前にロード） - auto:N - ツールがコンテキストの N% を超えたら有効化（0-100）

エキスパートのヒント： Tool Search を有効にすれば、コンテキスト制限を気にせず、より多くの MCP サーバーに接続できます。95% のコンテキスト削減により、これまでコンテキストを取り合っていたサーバーが平和に共存できるようになります。

MCP Always-Load Override（v2.1.121+）

Tool Search はツールが必要になるまで完全な説明のロードを延期します（しきい値：mcpToolSearchAutoEnable、デフォルト auto:10）。毎回使うことが見込まれる信頼済みサーバーについては、サーバーごとに alwaysLoad: true でオプトアウトできます。そのサーバーのすべてのツールがセッション開始時にプロンプトにロードされ、ToolSearch のラウンドトリップは発生しません：¹⁵⁴

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

MCP 起動時の自動リトライ（v2.1.121+）： 起動時にエラーが発生したサーバーは、切断と判定される前に最大 3 回までリトライされるようになりました。遅い親プロセスと競合する stdio サーバーや、コールドスタートのバックエンドの背後にある HTTP サーバーで便利です。¹⁵⁴

MCP Elicitation（v2.1.76+）

MCP サーバーは、対話型ダイアログを通じてタスクの途中でユーザーから構造化された入力を要求できるようになりました。¹¹⁸ MCP サーバーが追加情報を必要とする場合（例：ブランチの選択、プロジェクト名の入力、アクションの確認）、elicitation リクエストを送信し、Claude Code がそれをフォームフィールドまたはブラウザ URL としてレンダリングします。

フック統合： 2 つの新しいフックイベント、Elicitation（ダイアログ表示前）と ElicitationResult（ユーザーの応答後）により、elicitation の応答をプログラムから傍受、検証、または上書きできます。これにより、MCP サーバーのプロンプトをポリシーで事前入力または制約するエンタープライズワークフローが実現できます。

MCP Result Size Override（v2.1.91+）

MCP ツールの結果はデフォルトでは切り詰められます。サーバーは結果ごとに _meta["anthropic/maxResultSizeChars"] アノテーションで上書きでき、最大 50 万文字まで許可できます。¹³⁶ データベーススキーマ、API レスポンス、ファイル内容など、大きなペイロードを切り詰めずに返したい場合に役立ちます。

対話型 MCP セットアップウィザード

引数なしで claude mcp add を実行すると、MCP サーバーを追加するためのステップバイステップのインターフェースが起動します。ウィザードはトランスポートタイプの選択、認証、設定を順に案内します。⁸

トランスポートタイプ

HTTP（リモートサーバーに推奨）：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE（非推奨だが機能する）：

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio（ローカルサーバー）：

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows では stdio に cmd ラッパーが必要です：

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

スコープ管理

MCP サーバーは 3 つのスコープに存在し、明確な優先順位があります（local が project を上書きし、project が user を上書きする）：

インストール時にスコープを指定します：

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

設定ファイル形式

.mcp.json ファイルはプロジェクトレベルのサーバーを定義します：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}