Claude Code 完全ガイド：MCP、Hooks から Workflows・企業導入まで

この文書について

これは継続的に更新されるリファレンス文書であり、一度きりのチュートリアル記事ではありません。Claude Code は非常に速いペースで更新されています。2026年9月中旬から10月中旬までのわずか30日間だけでも、npm では25の正式版がリリースされました。

そこで、この文書を通じて更新の過程を継続的に記録していきたいと考えています。一方で、私自身のメモとしての役割も果たす予定です。

このページの方針は次のとおりです。

• ページ上部には、対応する CLI バージョンと最終更新日を常に明記します。日付が古くなっている場合は、公式ドキュメントを確認してください。
• 各章には独立したアンカーがあり、特定の節へ直接リンクできます。

出典：npm 上の @anthropic-ai/claude-code バージョン公開履歴（2026-10-15 確認。2026-09-15 から 10-15 までの正式版を集計し、prerelease は含まない）

60秒クイックスタート

Claude Code をとりあえず動かして、出力を確認したい場合は、次の手順を順番に進めてください。

# 1. Install (pick one)
curl -fsSL https://claude.ai/install.sh | bash   # macOS, Linux, WSL
irm https://claude.ai/install.ps1 | iex          # Windows PowerShell
brew install --cask claude-code                  # Homebrew
winget install Anthropic.ClaudeCode              # WinGet
npm install -g @anthropic-ai/claude-code         # npm (Node.js 22+)

# 2. Verify: prints a version followed by (Claude Code)
claude --version
claude doctor                                    # optional full check

# 3. Launch in your project (first run opens a browser to log in)
cd ~/your-project && claude

# 4. Ask your first question
> what does this project do?

# Switch accounts later, inside Claude Code
/login

Claude Code は必要なプロジェクトファイルを自分で読み込むため、コードを手動で貼り付ける必要はありません。

インストール前に確認する2点

• システム：macOS 13.0 以上、Windows 10 1809 以上（または Windows Server 2019 以上）、Ubuntu 20.04 以上、Debian 10 以上、Alpine Linux 3.19 以上、メモリ 4 GB 以上
• アカウント：Claude の Pro、Max、Team、Enterprise のいずれかのサブスクリプション、または Claude Console アカウントが必要です

インストール方法の選び方

最初の2つは公式が推奨するネイティブインストールで、バックグラウンドで自動更新されます。Homebrew と WinGet は自動更新されません。その後は brew upgrade claude-code または winget upgrade Anthropic.ClaudeCode を自分で実行する必要があります。npm でインストールする場合は、sudo を付けないでください。

Homebrew でインストールした場合、claude-code は stable 版を使用します。通常は最新版より1週間ほど遅れますが、重大な問題がある版はスキップされます。最新版を使いたい場合は、claude-code@latest をインストールしてください。

起動後はまず既定が Auto mode であることを確認

v2.1.284 以降、ターミナルと VS Code の対話型セッションは、権限モードが設定されていない場合、プランやプラットフォームに関係なく、既定で Auto mode になります。分類器がアクションを審査するため、ほとんどのファイル変更やコマンドについて確認を求められることはなくなります。ただし、インストール直後の最初のセッションは Manual mode の場合があります。

自分で確認する形にしたい場合は、Shift+Tab で Manual に切り替えられます。ただし、これは現在の会話にのみ適用されます。毎回 Manual から開始したい場合は、後の章〈権限システムと auto mode〉を参照してください。

次のステップ

まずは任意のプロジェクトを開き、「このプロジェクトは何をしていますか？」と尋ねて、ファイルを読み取れて回答できることを確認してください。操作に慣れたら、外部ツールを接続してください。

出典：Claude Code 公式ドキュメント〈Quickstart〉、〈Advanced setup〉 の System requirements、Install with npm の各節（2026-09-15 確認）；〈Choose a permission mode〉 の Which mode a session starts in 節（2026-09-15 確認）；Claude Code CHANGELOG の 2.1.284（2026-10-02 確認）

MCP（Model Context Protocol）とは

Claude Code で外部ツールを接続したことがあるなら、おそらく同じ経験があるでしょう。MCP の発展が速く、数日おきに新しいものが登場するため、どれをインストールすべきか分からなくなる、という経験です。

まず MCP とは何かを説明します。MCP は差し込みプラグのようなものです。ほかの人がツールを作り、統一された仕様にまとめておけば、あなたはそこに差し込むだけで、Claude Code は同じ方法でデータを読み取ったり、ツールを操作したりできます。MCP がなければ、ツールを一つ接続するたびに、個別に接続処理を実装する必要がありました。

私自身は慎重な方で、他人のものを安易にインストールすることはしません。最終的に残している MCP は、私がおおむね確認したもの、あるいは多くの人に推奨されているものです。新しそうに見えても利用者が少ないものは、しばらく様子を見るようにしています。

では、いつ MCP を接続すべきでしょうか。公式ドキュメントの判断基準は実用的です。ほかのツールのデータを、会話にコピー＆ペーストし続けていると気づいたとき、例えば issue 追跡システムや監視ダッシュボードの場合が、接続すべきタイミングです。接続すると、Claude がそのシステムを直接読み取り、操作できるようになるため、情報を転記し続ける必要がなくなります。

MCP の両端：Host、Client、Server

MCP を機能させるには、両端にそれぞれ要素が必要です。MCP には3つの役割があります。

つまり、Claude Code に MCP を3つ登録すると、その裏側には、それぞれ独立した3本の接続が存在することになります。

接続すると何を利用できるか

サーバーは3種類のものを提供でき、Claude Code での使い方はそれぞれ異なります。

1. Tools（ツール）：実行可能なアクションです。例えばデータベースの照会、API の呼び出し、ファイルの操作などです。いつ呼び出すかは Claude が自分で判断します。
2. Resources（リソース）：コンテンツを提供するデータソースです。例えばファイルの内容やデータベースのレコードなどです。プロンプトに @ と入力すると、ファイルを参照するのと同じように引用できます。
3. Prompts（プロンプトテンプレート）：あらかじめ用意されたプロンプトのテンプレートです。Claude Code ではコマンドとして扱われます。/ と入力すると表示され、名前の形式は /servername:promptname です。

次のステップ

始めたばかりの方には、まず1つだけ試すことをおすすめします。毎日使っている Notion や GitHub などのツールを1つ選び、その MCP を接続して、問題なく使えることを確認してから2つ目を追加してください。接続方法は次の章で説明します。

出典：Claude Code 公式ドキュメント〈Connect Claude Code to tools via MCP〉、MCP 公式ドキュメント〈Architecture overview〉

Claude Code で MCP を設定する方法

MCP を設定したのに別のプロジェクトに移ると消えてしまった、あるいは同僚がプロジェクトを clone したら、なぜか自分の server まで追加されていた、という問題はどれも、おそらく同じ箇所に原因があります。それはスコープです。

同じ server は3つの異なる場所に保存できます。どこに保存するかによって、どのプロジェクトで有効になるか、ほかの人と共有されるかが決まります。

3つのスコープ

ここで混同しやすい点があります。MCP の local は名前が local ですが、プロジェクト内の .claude/settings.local.json に保存されるわけではなく、ホームディレクトリの ~/.claude.json に保存されます。公式ドキュメントでもこの点は特に注意喚起されています。

server を追加する際は、--scope で指定します。

# local (default): only you, only this project
claude mcp add --transport http stripe https://mcp.stripe.com

# project: written to .mcp.json, shared with the team
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# user: only you, across all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

他人のプロジェクトの MCP は、そのままでは実行されない

前の章で触れたとおり、私は他人のものを安易にインストールしません。Claude Code もこの点については同様に慎重です。

project スコープの server は .mcp.json に記述され、リポジトリと一緒に clone されます。そのため公式はセキュリティ上の理由から、対話モードでこれらの server を使用する前に、承認するかどうかを確認します。

注意すべき点は次のとおりです。

• clone したリポジトリは、自分で自分を承認することはできません。 リポジトリ内の .claude/settings.json に enableAllProjectMcpServers が記述されていても、そのフォルダを信頼するまでは無視され、server は「⏸ Pending approval」のままになります。
• 非対話モードでは直接読み込まれます。 claude -p、Agent SDK、またはクラウドで実行する場合は確認ダイアログを表示できないため、project スコープの server はそのまま読み込まれます。これらの環境で他人のプロジェクトを実行する場合は、事前に .mcp.json の内容を確認してください。
• 選択をやり直したい場合は、claude mcp reset-project-choices を実行してください。

4種類の接続方式

判断方法はシンプルです。リモートサービスは HTTP を選びます。ローカルでプログラムを動かす場合は stdio を選びます。server から能動的にデータを送ってくる必要がある場合にのみ、WebSocket を検討します。

API key を .mcp.json に直接書かない

.mcp.json は git で管理されます。キーを直接書き込むと、そのリポジトリを見られるすべての人に公開することになります。環境変数を使用してください。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

• ${VAR}：環境変数 VAR の値に置き換えられます
• ${VAR:-預設值}：設定されていればその値を使用し、未設定の場合はデフォルト値を使用します
• command、args、env、url、headers の各フィールドで使用できます

認証が必要なリモート server

多くのクラウド MCP は認証を必要とし、Claude Code は OAuth 2.0 に対応しています。server を追加したら、Claude Code で /mcp と入力し、ブラウザの手順に従ってログインするだけです。ログイン後、トークンは自動的に更新されます。認可を取り消す場合も、/mcp メニューからクリアできます。

v2.1.288 以降、MCP server がツールの実行途中で追加の OAuth scope を要求した場合、Claude Code が再認証を促すため、/mcp で手動にクリアしてから再度ログインする必要はありません。

次のステップ

まずは claude mcp add で HTTP の server を1つ接続します。例えば Notion の場合は次のとおりです。

claude mcp add --transport http notion https://mcp.notion.com/mcp

次に Claude Code で /mcp と入力し、接続できているか確認してください。接続できない場合は、次の章を参照してください。

出典：Claude Code 公式ドキュメント〈Connect Claude Code to tools via MCP〉 の Installing MCP servers、MCP installation scopes、Project server approvals and workspace trust、Environment variable expansion in .mcp.json、Authenticate with remote MCP servers の各節；Claude Code CHANGELOG の 2.1.288（2026-10-03 確認）

よくある問題のトラブルシューティング

MCP を追加したのに、Claude がまだツールを見つけられないと言う場合は、すぐに削除して再インストールせず、次の順序で一つずつ確認してください。

1. まず状態を確認する

claude mcp list は、各 server の横に状態を表示します。

注意点として、✘ が表示される場合は、Claude Code がその server に接続できないことを意味しており、list コマンド自体が壊れているわけではありません。

複数の server が同時に接続できなくなった場合（例えばネットワークを切り替えた直後など）は、対話画面で /mcp reconnect all と入力すると、接続できない、または認証が必要なすべての server を一括で再試行します（v2.1.284 以降）。

v2.1.287 以降、Claude Code は 2025-11-25 版プロトコルにおける MCP server の URL 提示（例えばログインを促す表示）に対応しています。アップデート後に特定の server に接続できなくなった場合は、その MCP 設定に "bareElicitationCapability": true を追加してください（このフィールドは現時点では公式 CHANGELOG にのみ記載されており、MCP ドキュメントにはまだ説明がありません）。

2. 環境変数が設定されていない

設定で ${VAR} を使用しているものの、その変数が設定されておらず、デフォルト値も指定されていない場合でも、Claude Code はserver を読み込みます。ただし claude mcp list と /mcp で警告が表示され、不足している変数名が示されます。この場合、${VAR} はそのまま文字列として扱われるため、当然 server には接続できません。

そのため、警告が表示されたら、その変数を設定するか、${VAR:-預設值} の形式に変更してください。

3. 自作の stdio server：stdout が汚れている

server が自作の stdio プログラムの場合は、特に注意が必要です。stdio は標準入力と標準出力で MCP メッセージをやり取りするため、MCP 仕様では、server は MCP メッセージ以外のものを stdout に出力してはならないと定められています。console.log が1行でも余分に出力されると、接続が壊れる可能性があります。

デバッグメッセージはすべて stderr に出力してください。仕様では、ログの記録に stderr を使用することが許可されています。

また、v2.1.292 以降、ローカル（stdio）MCP server は既定でプロトコルバージョン 2026-07-28 でネゴシエーションを行います。Bedrock、Vertex、Foundry でも同様です。server が新しいバージョンのプロトコルチェックに応答しない場合、初回接続時に待ち時間が増えますが、その後 7 日間は Claude Code がその情報を記憶し、以降は旧方式で直接接続します。旧来の動作に完全に戻したい場合は、環境変数 MCP_PROTOCOL_NEGOTIATION=legacy を設定してください。

4. MCP を多数接続すると context を圧迫しないか

影響はわずかです。Claude Code は既定で tool search を有効にしています。最初はツール名と server の説明だけを読み込み、完全なツール定義は Claude が実際に必要とした時点で取得します。公式ドキュメントにも、server ごとのツール数に固定の上限はなく、実質的な制限はコンテキストウィンドウの容量であると説明されています。

v2.1.296 以降、MCP ツールの説明と server instructions を事前に context へ送る際の文字数上限が、2,048 文字から 4,096 文字に引き上げられました。説明が長い server でも切り捨てられにくくなっています。

各 server が提供するツールの数は、/mcp パネルで確認できます。

次のステップ

問題が発生したら、まず claude mcp list を1回実行し、状態から、認証が必要か、承認が必要か、環境変数を設定する必要があるかを判断してください。

出典：Claude Code 公式ドキュメント〈Connect Claude Code to tools via MCP〉 の Server status、Configuration warnings、Tool availability、Scale with MCP tool search の各節；MCP 仕様〈stdio transport〉；Claude Code CHANGELOG の 2.1.284、2.1.287（2026-10-02 確認）、2.1.292（2026-10-07 確認）、2.1.296（2026-10-10 確認）

CLAUDE.md とメモリシステム

新しい会話を開くたびに、「このプロジェクトは pnpm を使っている」「テストコマンドはこれ」と Claude に毎回伝え直しているなら、問題は Claude の記憶力が悪いことではなく、各セッションが本来まっさらなコンテキストウィンドウから始まることにあります。

Claude に覚えてもらうため、Claude Code には2つの仕組みがあります。新人の着任に例えると分かりやすいでしょう。CLAUDE.md はあなたが書く引き継ぎマニュアルで、毎日出勤するたびに最初に読み直します。auto memory は Claude 自身の作業メモで、あなたに訂正された内容を自分で記録します。

2つのメモリの違い

どちらも Claude にとっては context であり、強制力のある設定ではありません。Claude はできる限り従いますが、保証はありません。Claude の判断に関係なく必ずブロックすべきアクションには、PreToolUse hook を使用してください。

CLAUDE.md の配置場所

CLAUDE.md は4か所に配置できます。どこに配置するかによって、誰が読み込むかが決まります。

重ねて読み込まれ、上書きされるわけではない

配置場所が分かったら、次に問題になるのは、複数のファイルが同時に存在する場合に、どれが優先されるかです。

答えは、すべてをまとめて読み込むということです。互いに上書きすることはありません。

• 上方向に探索：Claude Code を起動したディレクトリから上位へ、各階層の CLAUDE.md と CLAUDE.local.md が起動時に読み込まれます。
• 遠い順から近い順：起動位置に近いファイルほど後に読み込まれます。同じ階層では、CLAUDE.local.md が CLAUDE.md の後に読み込まれます。
• サブディレクトリは後から読み込み：配下のサブディレクトリにある CLAUDE.md は最初には読み込まれず、Claude がそのサブディレクトリのファイルを読んだ時点で取り込まれます。

複数のファイルをまとめて読み込むため、互いに矛盾するルールが書かれていると、Claude はどちらか一方を任意に選んで従う可能性があります。そのため、定期的に見直し、古くなったものや競合する指示を削除してください。

/init で始める

どこから書けばよいか分からない場合は、プロジェクトで /init を実行してください。Claude がコードを分析し、build コマンド、テスト方法、プロジェクトの慣例を含む CLAUDE.md を生成します。すでに CLAUDE.md がある場合は、改善案を提示し、直接上書きすることはありません。

生成後、コードからは Claude に分からないことを自分で追記してください。より完全なフローを使いたい場合は、先に CLAUDE_CODE_NEW_INIT=1 を設定してください。すると /init が、CLAUDE.md、skills、hooks のどれを設定するかを順番に尋ね、最後に提案内容を確認してからファイルを書き込みます。

効果的な書き方

CLAUDE.md はセッションごとに読み込まれ、トークンを消費するため、書き方が Claude の遵守状況に直接影響します。公式ドキュメントでは、いくつかの指針が示されています。

• 長さ：1ファイルあたり 200 行以内に抑えてください。長くなるほど context を多く占有し、遵守率も下がります。
• 構成：markdown の見出しと箇条書きでグループ化し、一つの長い段落にしないでください。
• 検証可能な具体性：

いつ項目を追加すべきか。公式ドキュメントの判断基準は実用的です。同じ間違いを Claude が2度繰り返したとき、または会話で前回と同じ訂正を再び入力していることに気づいたときは、書き加えてください。逆に、複数のステップからなるワークフローや、コードの一部にだけ関係するルールは、skill や .claude/rules/ に配置するほうが適しています。

補足：v2.1.293 以降、Claude が Bash ツールで単一ファイルを cat、head、tail、sed -n、grep により参照する場合も、そのパスに適用される .claude/rules/ のルールとサブディレクトリの CLAUDE.md が読み込まれるようになりました。以前は Read ツールを使った場合にのみ読み込まれていました。

@ で他のファイルを取り込む

CLAUDE.md では @路徑 を使って他のファイルを参照できます。起動時に展開され、まとめて読み込まれます。

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

• 相対パスは、その行が記述されているファイルを基準とします。作業ディレクトリが基準ではありません。
• 参照されたファイルがさらに別のファイルを参照することもでき、最大4階層までです。
• パスに言及するだけで参照したくない場合は、バッククォートで囲んでください。例：`@README`。
• プロジェクトの CLAUDE.md が作業ディレクトリ外のファイルを参照している場合、初回は承認ダイアログが表示されます。拒否すると、それらの参照は読み込まれません。
• import に分割するのは整理しやすくするためだけで、context の節約にはなりません。参照されたファイルも、起動時に同様に読み込まれます。

AGENTS.md：v2.1.277 以降でネイティブ対応

多くのリポジトリには、Codex、Cursor、Gemini などの Agent が参照する AGENTS.md がすでにあります。以前は Claude Code がこれを読み込まなかったため、CLAUDE.md の1行目に @AGENTS.md と書いて参照する必要がありました。v2.1.277 以降は、プロジェクトに CLAUDE.md（および CLAUDE.local.md）がない場合、Claude Code は AGENTS.md を直接読み込みます。

次の3点を先に整理しておきましょう。

• 統合ではなく、置き換えです。 ロジックは「CLAUDE.md がない場合にのみ AGENTS.md を読む」です。両方存在する場合は、引き続き CLAUDE.md が読み込まれ、AGENTS.md は無視されます。CLAUDE.local.md も同様に扱われる点に注意してください。個人設定のために1つ追加しただけでも、AGENTS.md は読み込まれなくなります。
• 両方を読み込みたい場合は、2つの方法があります。 1つ目は /config を入力し、Project instructions を claude-md-and-agents-md に設定する方法です。これで両方が読み込まれます。2つ目は、CLAUDE.md の1行目に @AGENTS.md と書いて参照する方法です。内容は AGENTS.md 1つだけで管理し、Claude Code 専用のルールは下に記述します。後者は Claude Code のバージョンや設定に依存しないため、複数の Agent 間で安定して動作します。
• v2.1.281 以降、クラウドベンダーでも対応しています。 Amazon Bedrock、Google Vertex AI、Microsoft Foundry、LLM gateway、そしてテレメトリを無効にしたセッションでも、AGENTS.md が読み込まれるようになりました。チーム内で使用している Claude Code のバージョンがまちまちの場合、古いバージョンではこれらのプラットフォームで依然としてこの仕組みが機能しないため、その間は CLAUDE.md を残しておいてください。

どちらを読み込むかは、/config の Project instructions で切り替えてください。

auto memory：Claude 自身のメモ

auto memory は既定で有効になっています。あなたが訂正したり、あるやり方が正しいと確認したりすると、記録する価値があるかどうかを判断し、~/.claude/projects/<project>/memory/ に保存します。

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Index, one line per entry, loaded every session
├── user_role.md        # One memory
├── feedback_testing.md # One memory
└── ...

• 記録する内容：user（あなたの役割と好み）、feedback（あなたによる訂正）、project（進行中の作業、期限、決定事項）、reference（外部情報の所在）の4種類に分けられます。コードから読み取れる内容や、CLAUDE.md にすでに書かれている内容は記録しません。
• 読み込み方法：起動時は MEMORY.md の先頭 200 行または 25KB のみを読み込みます。そのほかのトピックファイルは、必要になった時点で読み込まれます。
• このコンピューターのみ：ほかのコンピューターやクラウド環境には同期されません。
• 無効にする方法：/memory で切り替えるか、プロジェクト設定に "autoMemoryEnabled": false と記述します。環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 を設定することもできます。

Claude に「覚えておいて。必ず pnpm を使う」と伝えると、auto memory に保存されます。CLAUDE.md に書き込みたい場合は、「これを CLAUDE.md に追加して」と明示的に伝えてください。

/memory と /context で確認する

• /memory：ユーザーレベルおよびプロジェクトレベルの CLAUDE.md、CLAUDE.local.md などのファイルを一覧表示します。選択するとエディターで開き、まだ存在しないファイルは直接作成されます。ここで auto memory の有効・無効を切り替えたり、auto memory のフォルダを開いたりして、実際に何を記録したのかを確認することもできます。
• /context：このセッションで実際に読み込まれたファイルを確認できます。Memory files の下に一覧表示されます。Claude が CLAUDE.md に従わなかった場合は、まずここでファイルが読み込まれているかを確認してください。

次のステップ

プロジェクトにまだ CLAUDE.md がない場合は、まず1つだけ行うことをおすすめします。プロジェクトのルートディレクトリで /init を実行し、生成されたファイルを開いてください。理解できない内容や使わない内容は削除し、最もよく繰り返している訂正を1つ追加します。次に新しいセッションを開いたときに /context を実行し、Memory files に表示されることを確認してください。

出典：Claude Code 公式ドキュメント〈How Claude remembers your project〉 の CLAUDE.md vs auto memory、CLAUDE.md files、Auto memory、View and edit with /memory、Troubleshoot memory issues の各節（2026-09-15 確認）。AGENTS.md の節の内容は Claude Code CHANGELOG の 2.1.277（2026-09-19 確認）によるものです。Claude Code CHANGELOG の 2.1.281（2026-10-02 確認）、2.1.293（2026-10-08 確認）（2026-10-15 に〈How Claude remembers your project〉の AGENTS.md の節と照合して更新。）

権限システムと auto mode

Claude Code を使い続けていると、おそらく2つの極端な状態に陥ります。コマンドを1つ実行するたびに確認を求められ、クリックに疲れてしまう状態。もう一つは、すべてを許可してしまい、いつか削除すべきでないものを削除されるのではと不安になる状態です。

この2つは実際には別々に管理するものです。権限モードはビルの警備レベルのようなもので、全体としてどの程度厳しくするかを決めます。権限ルールは入退室の許可リストのようなもので、どのドアは必ず通れるか、必ず確認を求めるか、絶対に通れないかを指定します。まずモードを選び、そのうえで気になる点をルールで補うのがおすすめです。

6種類の権限モード

default は CLI では Manual と表示されます。また、どのモードでも常に適用されるルールがあります。deny ルールは必ずブロックされます。bypassPermissions の場合も同様です。

Shift+Tab で切り替える

会話の途中で Shift+Tab を押すと、モードが順番に切り替わります。auto から1回押すと default に戻り、続いて default → acceptEdits → plan の順になります。auto mode が利用可能な場合は plan の後に並び、そのあと再び default に戻ります。切り替えたモードは、ステータスバーに ⏸ manual mode on、⏵⏵ accept edits on、⏸ plan mode on、⏵⏵ auto mode on のいずれかで表示されます。

次の2つのモードは、この切り替えの循環には含まれません。dontAsk は --permission-mode dontAsk を指定してのみ起動できます。bypassPermissions は起動時に有効にした場合（例：--dangerously-skip-permissions）にのみ、循環に含まれます。いずれかのモードを最初から指定して開始したい場合も、同様に引数を付けて指定します（例：claude --permission-mode plan）。

auto mode の仕組み

auto mode は「確認を求めるかどうか」の判断を、別のモデル（分類器）に任せる仕組みです。各アクションは次の順序で処理され、先に一致したものが適用されます。

1. 記述した allow、ask、deny ルールに一致する場合は、そのルールに従います
2. 読み取り、および作業ディレクトリ内のファイル変更は、そのまま許可されます（.git、.claude などの保護されたパスへの書き込みは除く）
3. それ以外は、分類器が判断します
4. 分類器がブロックした場合、Claude はその理由を受け取り、別の方法を自分で選択します

分類器が既定でブロックするものは、例えば curl | bash のようにダウンロードしてそのまま実行するもの、機密データを外部に送信するもの、本番環境へのデプロイやマイグレーション、force push、git reset --hard などです。既定で許可されるものは、例えば作業ディレクトリ内のファイル操作、lock ファイルに宣言済みのパッケージのインストール、読み取り専用の HTTP リクエスト、作業中のリポジトリの任意のブランチへの push などです。完全な一覧は claude auto-mode defaults を実行して確認できます。

以下の制限事項を先に理解しておいてください。

• 安全性は保証されません。 公式の見解では、大きな方向性を信頼できるタスクに使用し、機密性の高い操作の審査の代わりにはしないでください、とされています。
• 範囲が広すぎる allow ルールは一時的に無効になります。 auto mode に入ると、Bash(*)、Bash(python*) のように任意のプログラムの実行を許可してしまうルールは削除されます。auto mode を抜けると復元されます。Bash(npm test) のように範囲の狭いルールは影響を受けません。
• 会話で「push しないで」と伝えるのは効果がありますが、確実ではありません。 分類器はそれをブロックのシグナルとして扱いますが、毎回会話履歴から読み直されるため、context が圧縮されるとその発言は失われます。確実にブロックしたい場合は、deny ルールとして記述してください。
• 連続してブロックされると手動に戻ります。 連続で3回、またはセッション全体で累計20回ブロックされると、auto mode は一時停止し、再びユーザーに確認を求めるようになります。この2つの数値は変更できません。ブロックされたアクションは /permissions の Recently denied タブに一覧表示され、r を押すと手動で承認して再実行できます。
• 利用可能なモデルに制限があります。 Anthropic API および Claude Platform on AWS では、Claude Opus 4.6 以降、Sonnet 4.6 以降、Haiku 5.5、または Fable モデルが必要です。Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry では、Sonnet 5 以降、Opus 4.7 以降、Haiku 5.5（v2.1.293 以降が必要）、および Fable のみがサポートされます。それ以外のモデルを使用しているセッションは、Manual から開始されます。
• 組織側で無効にできます。 管理者が managed settings で permissions.disableAutoMode を "disable" に設定すると、auto は Shift+Tab による切り替えから除外されます。permissions.disableBypassPermissionsMode でも同様に bypassPermissions をブロックできます。
• 作業ディレクトリ外のファイルの読み取りは、今回だけ許可できます。 v2.1.284 以降、この種の確認には「Yes, but ask again next time」という選択肢が追加されました。今回の読み取りは許可されますが、次に作業ディレクトリ外の読み取りが発生した場合は、引き続き確認を求められます。
• 危険な rm は無期限に待機しません。 --dangerously-skip-permissions および auto mode では、危険な rm に遭遇すると2分間待機します。応答がない場合は、書き換えの提案を添えて拒否され、誰も見ていないセッションでも処理を継続できるようになっています（v2.1.281 以降）。このタイムアウトを無効にしたい場合は、CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1 を設定してください。

分類器はローカルで動くか、サーバー側で動くか

分類器自体もモデルの呼び出しの一つです。ローカルで実行すると、判断が必要なアクションのたびにトークンの追加料金が発生します。この費用は以前、あなたの負担になっていました。

v2.1.278 以降、Claude API と Enterprise のユーザー、および Bedrock、Vertex、Foundry、gateway では、既定でサーバー側の分類器が使用されるようになり、このオーバーヘッドは課金されません。 課金対象のバージョンに実際に戻る場合は、画面に警告が表示されます。

• ローカルの分類器に戻したい場合（Bedrock、Vertex、Foundry、gateway のみ）：CLAUDE_CODE_AUTO_MODE_SERVER=0 を設定してください。
• このセッションがどちら側で動作しているか確認したい場合：/status と入力し、Auto mode server の行を確認してください。

auto mode に関するその他の3つの変更点

いずれも v2.1.271 以降に順次追加されたもので、実際に使うと影響を受ける可能性があります。

• サンドボックスモードでのドメインは、コマンドごとに審査される方式に変わりました。 Bash、PowerShell、Monitor に allowed_domains が追加されました。コマンドがアクセスするホストは、そのコマンドとともに審査され、そのコマンドに対してのみ開放されます。ほかのホストは引き続き拒否されます。curl を1回実行するためにドメイン全体を恒久的に許可する必要はなくなりました。
• skill や slash command 内の ! コマンドは、もはや分類器に任せられません。 代わりに default モードの権限ルールで判断されます。判断できるルールがない場合は、あなたが確認すべきツール呼び出しになります。skill に記述した !`git diff HEAD` は、分類器ではなく permissions の管轄下に置かれます。
• subagent の結果は隔離して扱われます。 subagent がメインの会話に結果を返す際は、専用の受け渡し呼び出しを経由し、分類器による審査を受けます。v2.1.278 以降、結果には「これは subagent の出力です」というヘッダーが付与され、インデントされます。目的は同じです。subagent が取得したテキストが、あなたの指示であるかのように扱われることを防ぐためです。

Claude Code 起動時のモード

ターミナルで新しいセッションを開く場合、次の順序でモードが決まります。

1. 起動引数 --permission-mode または --dangerously-skip-permissions
2. 設定ファイル内の permissions.defaultMode
3. 組み込みの既定値

組み込みの既定値：v2.1.284 以降、ターミナルと VS Code 拡張機能の対話型セッションは、プランやプラットフォームに関係なく auto になります（以前は Enterprise、Console API key、サードパーティプラットフォームでは default でした）。claude -p と Python Agent SDK も、サードパーティプラットフォームまたはテレメトリを無効にしている場合は、v2.1.285 以降 auto mode から開始されます。それ以外の場合は従来どおりです。組織のポリシーで auto の既定値が取り消されている場合は、セッションは default から開始されます。--permission-mode で指定した設定が引き続き優先されます。また、インストールまたはアップグレード直後の最初のセッションは、default になる場合もあります。

ここでつまずきやすい点があります。"auto" をプロジェクトの .claude/settings.json または .claude/settings.local.json に記述しても有効になりません。~/.claude/settings.json に記述する必要があります。逆に、毎回 Manual から開始したい場合も、同じ場所に {"permissions": {"defaultMode": "default"}} と記述します。

allow、ask、deny ルールの書き方

ルールの形式は Tool または Tool(条件) です。3種類のリストの意味は次のとおりです。allow は確認せずに実行、ask は毎回確認、deny はブロックです。

判定の順序は deny → ask → allow で固定されています。最初に一致したものが結果を決定します。記述を正確にしておけば、順序を飛び越えて適用されることもありません。そのため、Bash(aws *) を deny にしていれば、別途 Bash(aws s3 ls) を allow にしていても、やはりブロックされます。

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "deny": ["Bash(git push *)"]
  }
}

よく使う書き方：

Bash ルールを書く際は、次の3点に注意してください。

• * はサブコマンドの後ろに置きます。 Bash(git log *) は git log のみを許可します。Bash(git *) はすべての git コマンドを許可することになります。
• 連結されたコマンドは分割して確認されます。 Bash(safe-cmd *) では safe-cmd && other-cmd は許可されません。各部分すべてが一致する必要があります。
• Bash ルールは安全境界ではありません。 Bash(git push *) は git push origin main をブロックできますが、git -C . push origin main はブロックできません。確実にブロックする必要がある場合は、公式が sandbox または PreToolUse hook との併用を推奨しています。

Read と Edit のパスの書き方にも注意が必要です。// で始まるものがファイルシステムの絶対パス、~/ がホームディレクトリ、単一の / で始まるものは設定ファイルの場所を基準とした相対パスです。そのため、/Users/alice/file は絶対パスではなく、//Users/alice/file と書く必要があります。ルールを強制するのは Claude Code であり、モデル自身が守るわけではありません。CLAUDE.md に書いた「してはいけないこと」は、Claude の行動の方針に影響するだけで、実際にブロックするわけではありません。

ルールを記述する設定ファイル

どの階層に記述されていても、一つでも deny があれば、ほかの階層で許可することはできません。例えば、user 設定で allow、project 設定で deny とすると、結果はブロックになります。逆の場合も同様です。各ルールがどのファイルから来ているかを確認したい場合は、/permissions と入力してください。

次のステップ

まず Claude Code を開き、ステータスバーに表示されているモードを確認してください。そのあと /permissions と入力して、すでに保存されているルールを確認します。次に、絶対に起きてほしくないこと（例えば .env の読み取り）を1つ選び、~/.claude/settings.json の deny に Read(./.env) を追加してください。deny を先に設定してから、auto mode を安心して使うかどうかを判断しましょう。

出典：Claude Code 公式ドキュメント〈Choose a permission mode〉 の Available modes、Which mode a session starts in、Switch permission modes、Eliminate permission prompts with auto mode の各節、および 〈Configure permissions〉 の Manage permissions、Permission rule syntax、Tool-specific permission rules、Settings precedence、Project allow rules and workspace trust の各節（2026-09-15 確認）。分類器の実行場所、allowed_domains、! コマンド、subagent の結果の受け渡しに関する内容は、Claude Code CHANGELOG の 2.1.271 と 2.1.278（2026-09-19 確認）；Claude Code CHANGELOG の 2.1.281、2.1.284、2.1.285（2026-10-02 確認）（2026-10-15 に〈Choose a permission mode〉を照合し、auto mode のモード要件を更新。）

Hooks：決定性のあるレイヤー

CLAUDE.md に「ファイルを変更したら formatter を実行すること」「.env には触れないこと」と書いたことがあれば、おそらく同じ経験があるはずです。書いても、Claude がそれを毎回必ず守るとは保証できない、ということです。

Hooks はこの問題を解決するための仕組みです。処理の流れに取り付けるセンサーのようなもので、取り付け先のポイント（たとえば「Claude がファイルを変更した後」）を決めておくと、そのポイントに到達したときに、書いておいた shell コマンドが必ず実行されます。Claude が覚えている必要も、その時点でどう判断するかを見る必要もありません。

「決定性」と呼ぶ理由

公式ドキュメントの説明は明快です。hooks は、ある処理が必ず実行されることを保証するもので、LLM が実行するかどうかを選ぶのに任せるものではありません。CLAUDE.md に書いたルールは、Claude がそれを読んで自分で判断します。一方、hook として書いたものは、Claude Code が決まったタイミングで直接実行し、ツールの実行前に止めることもできます。したがって判断の基準はシンプルです。「毎回必要なこと」「絶対に許可しないこと」は hook に任せ、状況に応じて判断すべきことは CLAUDE.md に残してください。

よく使う 3 つのイベント

Hook は「イベント」に紐づけます。公式には 30 個以上のイベントがありますが、最初は次の 3 つを覚えておけば十分です。

設定ファイルの書き方

Hook は settings ファイルの hooks の中に書き、全部で 3 層あります。イベント → matcher（絞り込み条件）→ 実行するコマンド。以下は公式の「ファイル変更後に Prettier を自動実行する」例です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Claude Code はイベントのデータを JSON として stdin からコマンドに渡します。そのため、ここでは jq（macOS では brew install jq でインストール）で変更されたファイルのパスを取り出し、Prettier に渡しています。どのファイルに書くかによって適用範囲が変わります。~/.claude/settings.json に書くと、すべてのプロジェクトに有効になります。プロジェクトの .claude/settings.json に書くと、そのプロジェクトだけに有効になり、git で共有してチーム全員と共有できます。共有したくない場合は .claude/settings.local.json に書きます。設定後は /hooks を入力して表示されていることを確認してください。このメニューは閲覧専用で、編集はできません。変更するには JSON を直接編集するか、Claude に変更を頼んでください。

matcher：必要なときだけ発火させる

matcher を書かない場合（または ""、"*" と書いた場合）、そのイベントが発生するたびに発火します。PreToolUse、PostToolUse の matcher はツール名と照合されます。

• 英字、数字、_、-、|、, のみの場合：完全一致で照合します。Edit|Write なら、この 2 つのツールだけに一致します。
• その他の文字を含む場合：正規表現として扱われ、先頭・末尾の指定はありません。Edit.* は NotebookEdit にも一致するので、完全一致させたい場合は ^Edit$ と書いてください。
• 大文字と小文字は区別されます。綴りを間違えると hook は発火しません。Stop は matcher に対応していないため、毎回実行されます。
• Claude は Bash でコマンドを実行してファイルを変更することもあります。Edit|Write だけを照合すると、その場合を取りこぼします。

次のアクションをブロックする方法

コマンドは**終了コード（exit code）**で、Claude Code に次に何をすべきかを伝えます。

最もよく見落とされるのは 3 行目です。Unix の慣習では exit 1 は失敗を表しますが、hooks では何もブロックできません。ブロックするには必ず exit 2 を使ってください。同じ exit 2 でもイベントによって動作は異なります。PostToolUse では stderr の内容が Claude に見えるだけです。Stop では Claude を停止させず、stderr の内容が Claude が続けるべき理由になります。より細かく制御したい場合は exit 0 にして stdout に JSON を出力します。たとえば PreToolUse で hookSpecificOutput の中に "permissionDecision": "deny" を返して拒否し、permissionDecisionReason で理由を Claude に伝えられます。公式の推奨は、1 つの hook では方式を 1 つだけ選ぶことです。exit 2 を使うか、exit 0 と JSON を使うか、どちらか一方にしてください。

hook 自体のエラーもブロックする：onFailure: "block"（v2.1.295 以降）

デフォルトでは、hook の起動失敗、タイムアウト、想定外の終了コードが発生しても、アクションはそのまま実行されます。その hook がセキュリティチェックで、「壊れたら通す」状態を避けたい場合は、command または HTTP タイプの hook 設定に "onFailure": "block" を追加します。hook が起動できない、タイムアウトする、または想定外の終了コードで終了した場合、そのアクションはブロックされます。設定しない場合のデフォルトは "continue" で、通常どおり実行されます。この設定は Stop、SubagentStop、TaskCompleted、TeammateIdle、および async hook には効果がありません。PermissionRequest の hook が失敗した場合は、拒否（deny）になります。

完全な例：Claude に .env を変更させない

まず .claude/hooks/protect-files.sh を作成し、chmod +x .claude/hooks/protect-files.sh を実行して実行可能にします。

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

次に、.claude/settings.json に PreToolUse hook として登録します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

$CLAUDE_PROJECT_DIR は、このセッションを開始した時点のプロジェクトルートです。これを使えば、作業ディレクトリが変わってもスクリプトが見つからなくなることはありません。最後に、.env に 1 行コメントを追加するよう Claude に頼んでください。ブロックされ、Blocked: で始まるメッセージを受け取るはずです。

安全上の注意

• あなたのアカウントの全権限を持ちます。 hook が削除できるファイルは、あなたが削除できるファイルすべてです。設定に追加する前に、コマンドを自分で確認し、テストしてください。
• パスを間違えると、保護は静かに無効になります。 スクリプトが見つからない場合はブロックしないエラーとして扱われ、アクションはそのまま実行されます。タイムアウトでキャンセルされた PreToolUse hook もブロックしません。設定後は、必ず一度実際に発火させて確認してください。
• 他人のリポジトリでは -p に注意。 対話モードでは、そのフォルダを信頼するまで hook は実行されません。しかし claude -p や SDK では、信頼済みとみなされてそのまま実行されます。実行前に .claude/ 内の設定を確認するか、--settings '{"disableAllHooks": true}' を付けて無効にしてください。
• Hook は制限を強める方向にしか働かず、緩めることはできません。 PreToolUse が deny を返せば、bypassPermissions モードでもブロックされます。一方、allow を返しても、settings の deny ルールを上書きすることはできません。

次のステップ

始めたばかりなら、まず 1 つだけ行ってください。「ファイル変更後に Prettier を自動実行する」の設定を、プロジェクトの .claude/settings.json に貼り付け、/hooks で表示されていることを確認します。そのうえで Claude に JS ファイルを 1 つ変更してもらい、フォーマットが自動で整っているかを確認してください。うまく動いたら、.env をブロックする PreToolUse hook を追加します。

出典：Claude Code 公式ドキュメント〈Automate actions with hooks〉 の Auto-format code after edits、Block edits to protected files、How hooks work、Filter hooks with matchers、Configure hook location、Limitations and troubleshooting の各節、および 〈Hooks reference〉 の Matcher patterns、Exit code 2、Exit code 2 behavior per event、Stop、Security considerations の各節（2026-09-15 確認）、ならびに Claude Code CHANGELOG の 2.1.295（2026-10-09 確認）

Skills の仕組み

Claude Code をしばらく使っていると、同じチェックリストや同じデプロイ手順を、新しい会話を開くたびに貼り付け直している、という経験があるかもしれません。あるいは CLAUDE.md がどんどん長くなり、特定の場面でしか使わない手順で埋まってしまう、ということもあるでしょう。

Skill はこの問題を解決するための仕組みです。本棚に並んだ操作マニュアルのようなもので、Claude は普段は背表紙にあたる概要しか見ていません。必要になった場面で初めてマニュアル全体を取り出して、その内容に従って作業します。名前を直接指定して、どのマニュアルを開くかを指示することもできます。

公式ドキュメントの判断基準は実用的です。同じ指示、チェックリスト、複数ステップの手順を会話に何度も貼り付けている場合、あるいは CLAUDE.md の一部が「事実」から「手順」に変わってきている場合は、Skill として書くべきタイミングです。

CLAUDE.md、slash command、subagent との違い

• CLAUDE.md：内容は常に会話の中にあります。Skill は普段は説明文だけを置いておき、完全な内容は使われたときに読み込まれます。そのため、長い参考資料も使われていない間はほとんどコストがかかりません。
• Slash command（カスタムコマンド）：現在は Skill に統合されています。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作成し、使い方は同じです。従来の .claude/commands/ のファイルも引き続き使えます。Skill には次の 3 つの機能が追加されています。補助ファイルを置けるフォルダ、frontmatter で誰が呼び出せるかを制御する機能、そして関連する場面で Claude が自動的に読み込む機能です。新しく書く場合は Skill を使うことをおすすめします。
• Subagent：Skill はデフォルトでは現在の会話の中で実行されるため、それまでに話した内容を読むことができます。frontmatter に context: fork を追加すると、代わりに新しい subagent を起動してそこで実行します。SKILL.md の内容は subagent のタスクになりますが、subagent はあなたの会話履歴を見ることができません。そのため、指示は単独で成立するように書く必要があります。逆に、subagent は skills フィールドで Skill を事前に読み込ませ、参考資料として使うこともできます。

最小構成の例

次の Skill は、git でまだ commit していない変更をまとめ、リスクのある箇所に印を付けます。まずフォルダを作成します。個人用 Skill の場所に置くと、すべてのプロジェクトで使えます。

mkdir -p ~/.claude/skills/summarize-changes

次の内容を ~/.claude/skills/summarize-changes/SKILL.md として保存します。

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

!`git diff HEAD` という行は、Claude Code が先にそのコマンドを実行し、出力に置き換えてから Claude に渡します。そのため Claude が受け取るのは推測ではなく、あなたの実際の diff です。

git プロジェクトを開き、適当なファイルを 1 つ変更して claude を実行してください。テストする方法は 2 通りあります。説明文に合う質問、たとえば What did I change? を入力すると、Claude が自分で Skill を読み込みます。または /summarize-changes を直接入力します。

SKILL.md の構造

SKILL.md は 2 つの部分に分かれます。上部の --- で囲まれた YAML frontmatter は、Claude にいつ使うかを伝えます。下部の markdown の内容は、実行時に従うべき指示です。frontmatter はファイルの 1 行目の --- から始まっている必要があります。そうでなければ、ファイル全体が内容として扱われてしまいます。

すべてのフィールドは任意です。公式は description だけは必ず書くことを推奨しています。よく使われるフィールドは次のとおりです。

description が自動利用を決める

通常の会話では、すべての Skill の説明文が読み込まれ、Claude はどの Skill が使えるかを把握しています。完全な内容は呼び出されるまで読み込まれません。つまり、Claude が自分である Skill を使うかどうかは description だけを見て判断します。そのため、書き方が Skill が使われるかどうかを直接決めます。

• 重要な用途は先頭に書きます。 description と、使う場面を補足する when_to_use フィールドを合わせて、一覧では 1,536 文字を超えると切り詰められます。Skill が多く入っている場合は、一覧全体にも上限があり、最も使われていない Skill の説明文から先に削られます。
• ユーザーが自然に言いそうなキーワードを入れます。 呼び出されないときは、まず What skills are available? と尋ねて、Claude がその Skill を認識しているかを確認してください。そのうえで、説明文を直すか、質問の仕方を変えてみてください。
• 呼び出されすぎる場合は、説明文をより具体的にするか、disable-model-invocation: true を追加してください。

2 つの制御フィールドの違いは次のとおりです。デプロイや commit のように副作用のある処理では、公式は disable-model-invocation: true を推奨しています。コードが問題なさそうに見えたからといって、Claude が勝手にデプロイしてしまうのは避けたいからです。

配置場所

どこに置くかによって、どのセッションで読み込まれるかが決まります。

• 同名の場合は、個人の Skill がプロジェクトの Skill より優先されます（組織が配布したエンタープライズ Skill は、さらに個人の Skill より優先されます）。Plugin の Skill はプレフィックスが付くため、他と名前が衝突しません。
• 個人用 Skill はクラウドには引き継がれません。 Cowork やクラウドセッションは、あなたのコンピューター上の ~/.claude/skills/ を読みません。
• 逆に、claude.ai で有効にした Skill は同期されます。 v2.1.275 以降、claude.ai アカウントでログインしたターミナルセッションは、そのアカウントで有効にした Skill と plugin を同期します。不要な場合は、設定で "syncClaudeAiSkills": false を指定してください（plugin のスイッチは syncClaudeAiPlugins です）。ただし、同期されるのはコピーであることに注意してください。そのフォルダ内のファイルを直接編集しても、アカウントには保存されません。
• 変更後に再起動は不要です。 ~/.claude/skills/ または プロジェクトの .claude/skills/ で Skill を追加、変更、削除すると、その時点のセッションで反映されます。ただし、最上位の skills フォルダがそもそも存在しなかった場合だけは、初めて作成したときに Claude Code を再起動する必要があります。

手動で呼び出す方法

/ に続けて Skill の名前を入力します。個人用とプロジェクト用 Skill のコマンド名はフォルダ名から決まります。frontmatter の name は表示名を変えるだけです。その後に続けて入力したテキストは $ARGUMENTS に渡されます。個別の引数を使いたい場合は $0、$1 を使います。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

/fix-issue 123 を実行すると、Claude は「Fix GitHub issue 123 following our coding standards.」を受け取ります。内容の中に引数の位置が指定されていない場合、Claude Code は最後に ARGUMENTS: <入力したテキスト> を補うため、引数が抜け落ちることはありません。

実例：本格的な Skill はどのような構成か

上の例はファイルが 1 つだけです。実際に使われている Skill がどのような構成になっているかは、Cloudflare がオープンソースで公開している security-audit-skill を見ると分かりやすいです。これは coding agent をセキュリティ監査担当者に変えるもので、Cloudflare 社内の脆弱性探索システムを単一リポジトリで始めるための出発点です。

この例には、この章でこれまで説明してきた内容がよく表れています。

• description で 2 つのモードを明確に分けています。 同じ Skill でも、セキュリティに関する質問に答えるときは参考資料としてだけ使われます。「codebase 全体を監査する」と明示的に依頼された場合にのみ、6 段階の完全なプロセスが実行されます。Skill を読み込むことは、それによる動作を許可することとは別です。この境界は description と、内容冒頭の Operating modes に明記されています。
• 参考資料を複数のファイルに分け、必要な時にだけ読みます。 SKILL.md は 192 行しかなく、原則、用語、プロセスの概要を収めています。メモリ安全性、AI と LLM、HTTP と認証、サプライチェーン、クラウドデプロイなど 10 の分野がそれぞれ 1 つのファイルになっており、SKILL.md がそれを案内します。監査対象に関係のない分野は読み込まれません。全体で約 1,778 行ありますが、普段は context を消費しません。
• フォルダには プログラムを置くこともできます。 markdown のほかに、JSON schema と、依存関係のない 2 つの Node 検証スクリプトが含まれています。プロセスが特定の段階に達すると、これらのスクリプトが実行され、出力された findings.json とカバレッジ記録の形式が正しいかを確認します。Skill は指示だけを置くものではありません。
• subagent の役割分担をプロセスに組み込んでいます。 脆弱性を探すことと、脆弱性を検証することは、別々の agent が行うと定められています。検証を担当する agent の任務は、前の agent の結論を覆す方法を探すことです。役割を parent、Task tool のような中立的な言葉で説明しているため、特定の Claude Code に依存していません。

インストールには Skills CLI を使います。前の「配置場所」の節で説明した 2 つの場所に対応しています。

# project-level
npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit

# personal, all projects
npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit --global

ライセンスは MIT です。SKILL.md をそのままテンプレートとして使い、本格的な Skill が「いつ使うか」と「何に従って作業するか」をどのように分けて書いているかを参考にできます。

次のステップ

おすすめは 1 つだけです。会話に最もよく貼り付けている指示を 1 つ選び、上の例に従って ~/.claude/skills/ に個人用 Skill を作成してください。まず /skill-name で一度実行し、内容が正しいかを確認します。その後、新しい会話を開き、自然な質問で Claude が自動で読み込むかどうかを確認します。読み込まれない場合は、description に戻って修正してください。

出典：Claude Code 公式ドキュメント〈Extend Claude with skills〉 の Create your first skill、Choose where skills load、Frontmatter reference、Control who invokes a skill、Pass arguments to skills、Edit a skill during a session、Run skills in a subagent、Troubleshooting の各節（2026-09-15 確認）。実例の節の内容は cloudflare/security-audit-skill の README と SKILL.md（2026-09-19 確認）に基づきます。claude.ai の同期に関する記述は Claude Code CHANGELOG の 2.1.275（2026-09-19 確認）に基づきます

Subagents と並列化

Claude Code にテストを実行させたり、大量のログを読ませたりしたことがあれば、おそらく同じ経験があるでしょう。作業は終わったのに、会話が後で見ることのない大量の出力で埋まり、その後の回答が遅く、鈍くなっていく。

Subagent はこの問題を解決するための仕組みです。使い走りを任せる助手のようなもので、作業を伝えると、助手がファイルを調べたりコマンドを実行したりして、最後に要約を 1 ページ分だけ返してきます。途中で読んだ大量の資料は助手のところに残るため、あなたの机の上には積み上がりません。

主会話の context を節約できる理由

各 subagent は独立した context window を持ち、独自の system prompt、使用できるツール、権限を持ちます。作業を開始するとき、それまでの会話は見えません。Claude がすでに読んだファイルも見えません。subagent が受け取るのは次のものです。

作業中に読んだファイルや実行結果の出力は subagent の context に残り、主会話に戻ってくるのは最終的な結果だけです。そのため、「vendor/ フォルダを変更しないこと」のように subagent に必ず守らせたいルールがある場合は、委任するときの prompt に改めて書いてください。

組み込みの subagent

設定は不要です。Claude が適切と判断したときに、自動的に委任されます。

Explore と Plan は速度とコストを抑えるため、CLAUDE.md と git status を読み込みません。また、これらは使い捨てで、agent ID を返さないため、完了後に作業を続けることはできません。途中で追加の質問をする必要がある作業には、general-purpose または自分で定義した subagent を使ってください。

カスタム subagent：置き場所

Subagent は、YAML frontmatter を持つ Markdown ファイルです。どこに置くかによって、誰が使えるかが決まります。同名の場合は、優先順位の高いものが採用されます。

プロジェクト用は .claude/agents/ に置いてバージョン管理に含めれば、チーム全員が使えます。個人でよく使うものは ~/.claude/agents/ に置きます。どちらのフォルダもサブフォルダを再帰的に探索しますが、subagent の識別は name フィールドだけで行われ、どのサブフォルダに置かれているかは関係ありません。

ファイルの形式

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

frontmatter は設定を管理し、その下の本文がこの subagent の system prompt になります。必須なのは name と description だけです。よく使うその他のフィールドは次のとおりです。

/agents はウィザードではなく、Claude に作成を頼む方式に変わりました

v2.1.197 以前は、/agents で対話形式の作成ウィザードが開きました。v2.1.198 以降は、実行すると、Claude に作成を頼むか、.claude/agents/ を直接編集するよう案内が表示されるだけです。ファイルの形式と保存場所は変わっていません。そのため、最も速い方法は Claude に次のように伝えることです。

Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements. Make it read-only and have it use Sonnet.

ファイルを保存すると数秒で有効になり、再起動は不要です。例外として、セッション開始時に agents フォルダが存在しなかった場合は、Claude Code を再起動しないと読み込まれません。作成後は 3 通りの呼び出し方があります。prompt の中で名前を直接指定する（委任するかどうかは Claude が判断します）。@ を入力してメニューから選ぶ（例：@"code-reviewer (agent)" look at the auth changes）。この場合は必ずその subagent が使われます。または claude --agent code-reviewer で起動し、セッション全体をその system prompt、ツールの制限、モデルに切り替えます。

並列実行

Subagent は前景と背景に分かれます。前景では、完了するまで主会話がブロックされます。背景では同時に実行でき、権限が必要なツール呼び出しが発生すると、主会話に確認が表示され、どの subagent が尋ねているかが示されます。対話モードではデフォルトで fork mode が有効になっており、Claude が委任した subagent は背景で実行されます。実行中のタスクも Ctrl+B で背景に移せます。

互いに依存しない調査は、一度に複数の subagent に任せられます。

Research the authentication, database, and API modules in parallel using separate subagents

各 subagent はそれぞれ調査を行い、最後に Claude が結果をまとめます。ただし、結果は主会話に戻ってくるため、多くの subagent をそれぞれ長い結果で返させると、やはり context を消費します。委任するときには、要点だけを報告するよう指示するとよいでしょう。同時に実行できる数のデフォルトの上限は 20 で、超えると Concurrent subagent limit reached と表示されます。この上限は CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で調整できます。

v2.1.292 以降、Agent ツールに effort パラメーターが追加されました。「この調査は low effort で実行して」と Claude に直接伝えると、指定した effort レベルで subagent が起動されます。主会話のレベルに合わせる必要はありません。単純な検索や資料の整理はコストを下げるために低くし、深い推論が必要なレビューは高くするとよいでしょう。

いつ使い、いつ使わないか

繰り返し使える手順を主会話の中で実行したい場合は、Skills の方が適しています。会話にすでにある内容について質問したいだけなら、/btw で十分です。

次のステップ

まずは読み取り専用の code reviewer を 1 つ作ってみてください。Claude に ~/.claude/agents/ に Read, Grep, Glob のツールだけを持つ subagent を作成するよう頼みます。コードを変更したら、@ を入力してそれを選び、レビューさせます。報告内容が役に立つと確認できたら、複数の subagent を一度に並列で走らせ、情報を集めることを試してください。

出典：Claude Code 公式ドキュメント〈Create custom subagents〉 の Built-in subagents、Quickstart: create your first subagent、Configure subagents、Work with subagents の各節（2026-09-15 確認）。Claude Code CHANGELOG の 2.1.292、2.1.296（2026-10-10 確認）

コスト管理と context 管理

Claude Code を 1 日中起動したままにしていると、おそらく次のようなことが起きるでしょう。たった 1 行の質問をしただけなのに、使用量が想像よりずっと多い。

原因は context にあります。context は会話のノートのようなものです。質問を 1 つするたびに、Claude Code はノート全体を Claude に渡し直して読ませています。ノートが厚くなるほど、毎回送信されるコストも高くなります。つまり、コストを管理するとは、このノートの厚さを管理することにほかなりません。

まず使用量を確認する

厚さを管理するには、現在どれくらい厚いかを知る必要があります。公式ドキュメントでは次のツールが紹介されています。

/usage の最上部にある Session セクションは次のような表示になります。

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

この画面を見るときは、次の 3 点を知っておいてください。

• 金額は推定値です。 Claude Code がトークン数に料金を掛けて、ローカルで計算したものです。正式な請求額は Claude Console の Usage ページを基準にしてください。
• サブスクリプションプランでは、この金額は見る必要はありません。 Pro、Max のプランの利用量はサブスクリプションに含まれており、Session の金額は請求とは無関係です。同じ画面には、プランの使用量バー、アクティビティ統計、使用量の内訳が別途表示されます。
• /clear でゼロに戻ります。 /clear は新しいセッションを開始するため、金額は $0 から再計算されます。v2.1.211 より前のバージョンではゼロに戻らず、Claude Code を終了するまで累積され続けます。

Pro、Max、Team、Enterprise プランの場合は、/usage の使用量の内訳がより役立ちます。skills、subagents、plugins、各 MCP server がそれぞれ何パーセントを占めているかが表示されます。長い context、cache miss などの動作は、直近の使用量の 10% 以上を占めると強調表示され、削減のための提案も添えられます。d または w を押すと、直近 24 時間と直近 7 日間を切り替えられます。v2.1.299 以降、/usage は max effort、workflows、常駐の context、大きすぎるツール結果についても警告を表示します。これらの数値は、このコンピューターのセッション記録からのみ算出されます。ほかのデバイスや claude.ai の使用量は含まれません。

context はどのように消費されるか

使用量を把握したら、次の疑問は「なぜこんなに多いのか」です。公式ドキュメントでは、セッションを長く続けると使用量が増えていく主な理由が挙げられています。

最初の項目は見落とされやすいものです。Claude Code にはプロンプトキャッシュがあり、繰り返し使われる内容はより安いキャッシュ料金で読み込まれます。ただし、安くなるだけで無料になるわけではありません。1 日中開いたままのセッションで 1 行の質問をすると、やはり会話全体分の使用量が消費されます。

会話そのもの以外にも、CLAUDE.md はセッション開始時に読み込まれます。MCP のツール定義はデフォルトで遅延読み込みされ、Claude が実際にそのツールを使うまでは、ツール名と server の説明だけが context に入ります。

/clear と /compact：新しいノートにするか、古いノートを要約するか

判断の仕方は簡単です。これから行う作業に、それまでの会話が必要かどうか？ 必要なければ /clear を使います。公式ドキュメントでは、API やクラウドプランで料金が異常に高くなる典型的な原因は、長時間セッションを消去せずに続けていることだとも述べられています。/clear の前に /rename でセッションに名前を付けておけば、後で戻りたいときに /resume で見つけられます。

/compact を使うときは、後ろに残しておきたい内容を指定できます。

/compact Focus on code samples and API usage

プロジェクトルートの CLAUDE.md に書いておけば、毎回の要約もその方向に沿って行われます。

# Compact instructions

When you are using compact, please focus on test output and code changes

また、Claude Code は会話が context の上限に近づくと、自動で一度 compaction を実行します。auto-compact の警告が表示されても、使用量が上限に達したわけではなく、context がほぼいっぱいになったという意味です。

アイドル状態が長い会話：idle compaction（v2.1.299 以降）

ターミナルで 200K トークン以上の会話があり、約 54 分間アイドル状態が続くと、Claude Code は 1 時間のプロンプトキャッシュが切れる前に、あらかじめ一度圧縮を行います。そのため、戻ってきて最初に送る発言で context 全体を再処理する必要がなくなります。

• 最低しきい値はデフォルトで 200K トークンです。環境変数 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS で調整できます
• この動作を無効にしたい場合は、settings.json に "idleCompaction": false を記述します
• どちらの設定も、v2.1.290 以降のバージョンで認識されます

モデルの選び方

API やクラウドプランで料金が高くなるもう 1 つの一般的な原因は、Opus をデフォルトモデルとして使い続けていることです。公式の推奨は、ほとんどのコーディング作業は Sonnet に任せることです。Sonnet は Opus より安価です。Opus は、複雑なアーキテクチャの判断や多段階の推論のために取っておきましょう。

• 会話の途中でモデルを切り替える：/model
• デフォルトモデルを設定する：/config
• 単純な subagent のタスク：subagent の設定に model: haiku と書く

extended thinking にもコストがかかります。thinking のトークンは output トークンとして課金され、デフォルトの予算はモデルによって異なり、1 回のリクエストで数万トークンに達することもあります。深い推論が必要ない単純な作業では、/effort を使うか、/model で effort レベルを下げるか、/config で thinking をオフにしてください。Fable モデルは extended thinking が常に有効で、オフにはできません。

トークンを減らす具体的な方法

次のステップ

次に Claude Code を開いたら、まず 2 つのことをしてください。/context を入力して、何に context が占められているかを確認します。次に /model を入力して、デフォルトモデルが Opus のまま固定されていないかを確かめてください。今後、関係のない作業に切り替えるときは、まず /rename を行い、その後 /clear を実行する習慣をつけましょう。

出典：Claude Code 公式ドキュメント〈Manage costs effectively〉 の Track your costs、When a developer asks about a limit、Reduce token usage、Why usage climbs in a long session の各節（2026-09-15 確認）。Claude Code CHANGELOG の 2.1.299（2026-10-14 確認）

Session の管理と Checkpoint での巻き戻し

前の章の推奨に従って、仕事を切り替える前に /clear を実行しているなら、おそらく次の疑問が出てくるでしょう。昨日の会話は、今日また続けられるのか？

続けられます。Claude Code は会話ごとに session を作成し、それをコンピューター上に保存します。ノートを 1 冊ずつ分けて保管しているようなものです。戻り方さえ知っていれば、ウィンドウを閉じても、それまでの文脈が失われる心配はありません。同じ仕組みを使って、巻き戻すこともできます。Claude がファイルを壊してしまった場合は、あるメッセージより前の状態に戻せます。

session に名前を付ける

名前を付けなくても再開はできますが、一覧にはシステムが生成したタイトルしか並ばないため、どのノートがどの作業のものか分かりにくくなります。名前を付けるタイミングは次のとおりです。

claude -n auth-refactor     # 起動時に名前を付ける

/rename auth-refactor

session ピッカーで会話にカーソルを合わせて Ctrl+R を押しても、名前を変更できます。また、plan mode で計画を承認したとき、その会話にまだ名前がなければ、Claude Code が自動で名前を付けます。

名前のない session には、2 つのラベルが付きます。1 つは作業ディレクトリ名に 2 文字の接尾辞を付けたもの（例：my-app-3f）です。これは表示用だけで、再開には使えません（v2.1.196 以降）。もう 1 つは、Haiku などのモデルが最初の発言から生成したタイトルです。こちらは再開に直接使えます。

名前が衝突した場合も、上書きされる心配はありません。このマシン上で別の会話がすでにその名前を使って実行中の場合、Claude Code は元の会話の名前を残し、新しい会話には 2 文字の接尾辞を付けたバリエーション（例：auth-refactor-graceful-unicorn）を付けて、その旨を通知します。

再開する 3 つの方法

--continue は claude -p や Agent SDK で作成された session をスキップします。また、最初の発言が /loop で始まる session もスキップします。完了済みのバックグラウンド session を再開できるのは、v2.1.257 以降です。

ピッカーはデフォルトで現在の worktree と、/add-dir で追加したディレクトリだけを対象にします。見つからない場合は、Ctrl+W を押すとこのリポジトリのすべての worktree に範囲を広げられ、Ctrl+A を押すとこのマシン上のすべてのプロジェクトに広げられます。session ID で再開する場合、v2.1.223 以降は現在のプロジェクトとその worktree を先に検索し、見つからなければほかのプロジェクトを検索します。それ以前のバージョンでは現在のディレクトリだけを検索するため、会話を作成したディレクトリに戻らないと再開できません。

普段はあまり使わないものの、知っておくと役立つオプションが 2 つあります。--session-id では、この会話の ID を有効な UUID として自分で指定できます。--fork-session は、再開と同時に新しい session ID を作成します。元の会話はそのまま残るので、同じ出発点から別の方向を試したいときに便利です。

再開したときに復元されるもの

次の場合は、モデルが元のとおりにはなりません。元のモデルが無効になっている場合、availableModels で許可されていない場合、起動時に --model または ANTHROPIC_MODEL で別のモデルを指定した場合、あるいは Bedrock、Google Cloud、Microsoft Foundry のようにデプロイ ID を使うプラットフォームの場合です。

すべての起動オプションが復元されるわけではありません。 会話が --mcp-config、--settings、--plugin-dir、--fallback-model に依存していた場合、または --add-dir で追加されたディレクトリがあった場合は、再開時にもう一度指定する必要があります。会話の途中で /add-dir によって追加したディレクトリも戻りません。settings.json や settings.local.json などの設定ファイルは、起動のたびに読み直されます。

権限モードについては、第7章の表と対応しています。ターミナルでは、元が bypassPermissions だった場合は、新しい session が起動時に使うモードに変わります。元が plan モードだった場合は、再開しても plan モードのままです（ただし --fork-session で分岐した場合は除きます）。元が auto だった場合は、アカウントの条件が満たされている限り auto のままです。元が Manual だった場合は、設定ファイルの defaultMode で別の指定がない限り、Manual のままです。

元の会話で --agent を使っていて、その agent が元のディレクトリにも現在のディレクトリにも見つからない場合は、Claude Code が警告を表示し、デフォルトのツールで会話を再開します。

また、実行中だったツール呼び出しは再開されません。クラッシュの直前に途中まで実行されていたコマンドは、再実行も補完もされません。Claude は、その出力がない状態で作業を続けます。

長時間経過後の再開：要約するかどうかを尋ねられる

Pro と Max のプランでは、1 時間以上操作されておらず、かつ 10 万トークンを超える会話を再開すると、最初の発言を送信する前にダイアログが表示されます。選択肢は 3 つあります。

• 要約から再開：その場で /compact を実行するのと同じです。トークンは大幅に安くなりますが、要約で省かれた詳細は context に残りません
• 完全に再開：そのまま元に戻します。その後のリクエストはすべて、会話全体のサイズに応じて課金されます
• 今後は確認しない：今回は完全に再開し、今後このダイアログは表示しません

壊してしまった場合：/rewind で戻す

メッセージを送信して新しいターンを開始するたびに、Claude Code は checkpoint を保存します。戻したいときは /rewind を入力するか、入力欄が空の状態で Esc を 2 回押します（入力欄に文字がある状態で Esc を 2 回押すと消去になり、消去された文字は入力履歴に入るため、Up で呼び戻せます）。

メニューには 6 つの選択肢があります。

その checkpoint がファイルの変更を 1 つも追跡していなかった場合、メニューには Restore conversation、2 つの要約の選択肢、Never mind だけが表示されます。

要約はディスク上のファイルには一切影響しません。元のメッセージも記録として残ります。要約の重点を指定したい場合は、カーソルを Summarize の行に合わせてそのまま入力し、Enter を押します。数字キーで選択すると、指示を付けずにそのまま要約されます。

もう 1 つ、救済用の入口があります。同じ Claude Code のプロセス内で以前に /clear を実行していた場合、rewind メニューの一番上に /resume <session-id> (previous session) の行が追加されます。この行を選ぶと、/clear の前の会話に戻れます。この行が有効なのは、Claude Code を終了するか、別の session に切り替えるまでの間だけです。v2.1.191 以降が必要です。

Checkpoint では元に戻せないもの

これは最初に知っておいてください。そうしないと、Checkpoint を何でも元に戻せる仕組みだと誤解してしまいます。

• Bash コマンドで変更されたファイルは対象外です。 Claude が rm、mv、cp でファイルを変更した場合、rewind では戻せません。追跡されるのは、Claude のファイル編集ツールで直接変更されたものだけです。
• subagent が変更したものは、通常は戻せません。 前景で実行される context: fork の Skill だけは、その編集が自分のターン内で行われるため、rewind で戻せます。それ以外の subagent（デフォルトで背景実行される fork Skill、背景の /code-review --fix を含む）が変更したファイルは、git で戻す必要があります。
• 外部からの変更は対象外です。 Claude Code の外で自分が行った変更や、別の会話で同時に行われた変更は、通常は記録されません。
• 割り込みで送信したメッセージには checkpoint がありません。 Claude が作業している途中でキューに入れたメッセージは、その時点のターンにまとめられるため、メニューには表示されません。戻したい場合は、そのターンを開始したプロンプトまで戻すと、ターン全体がまとめて戻ります。
• Symlink とハードリンクはスキップされます。 Restore code を選ぶと、これらのパスはスキップされ、Restored the code, but skipped N files と表示されます。スキップされたファイルは現在の内容のまま残ります。どのファイルがスキップされたかを確認するには、先に /debug でデバッグログを有効にします。ログは ~/.claude/debug/<session-id>.txt に保存されます。

公式ドキュメントにも明記されているとおり、checkpoint は同じ会話の中で素早く元に戻すために設計されたものです。長期的なバージョン履歴や共同作業は、引き続き git に任せるべきです。そのため、大きく変更する作業を始める前には一度 commit しておき、rewind は同じ会話の中の小さなミスのためにとっておくのがよいでしょう。

保存場所と保存期間

会話の記録はデフォルトで ~/.claude/projects/<プロジェクト>/<session-id>.jsonl に保存されます。<プロジェクト> は、作業ディレクトリのパスの英数字以外の文字を - に置き換えた名前です。各行は JSON オブジェクトですが、これは内部形式であり、バージョンによって変わる可能性があります。エクスポートする場合は /export を使い、自分でプログラムを書いて解析しないでください。

Checkpoint のファイルスナップショットは直近 100 件まで保持され、上記の 30 日の保持期間と一緒に削除されます。スナップショットが削除された後に rewind を実行すると、No files were restored と表示されて失敗します。もっと長く残しておく必要がある場合は、cleanupPeriodDays を大きくしてください。

次のステップ

次に作業を始める前に、1 つだけ行ってください。claude -n <作業名> で起動するか、起動後にすぐ /rename を実行します。そうしておけば、明日 claude --resume で開いたときに、どの会話がどの作業かすぐ分かります。さらに、何か壊れたタイミングで Esc を 2 回押し、rewind の 6 つの選択肢を一度確認しておきましょう。どれが会話だけを戻し、どれがファイルも一緒に戻すのかを知っておけば、必要になったときに慌てずに済みます。

出典：Claude Code 公式ドキュメント〈Sessions〉 の Resume a session、What a resumed session restores、Permission mode on resume、Resume from a summary、Name your sessions、Where transcripts are stored、Where the session picker looks の各節、および 〈Checkpointing〉 の Automatic tracking、Rewind and summarize、Rewind past a cleared conversation、How checkpoints work、Limitations、Not a replacement for version control の各節（2026-09-18 確認）（2026-10-15 に〈Manage sessions〉の Permission mode on resume の節と照合して更新。）

Plugins と Marketplace

第 9 章と第 10 章で skill と subagent を作ったあと、次のような問題に直面するかもしれません。これらはすべて自分の ~/.claude/ 以下に置かれているため、別のコンピューターに移したり、同僚に使ってもらったりするには、フォルダを 1 つずつコピーしなければなりません。

Plugin は、それらをまとめてパッケージ化する仕組みです。Plugin は独立して持ち運べるパッケージで、Skill、subagent、hook、MCP server、既定の設定をまとめて含めることができます。Marketplace は、これらのパッケージを並べたカタログです。ソースを 1 つ指定すると、その中からインストールするものを選べます。

Plugin に含められるもの

Plugin のルートディレクトリには、次のものを配置できます。それぞれが 1 つの機能に対応しています。

Plugin 内の skill には接頭辞が付き、呼び出し名は /<plugin 名>:<skill 名> になります。パッケージ全体で skill が 1 つだけの場合は、skills/ を作らず、SKILL.md をルートに直接置くこともできます。

他人の Plugin をインストールする

/plugin を入力すると、Discover、Installed、Marketplaces、Errors、Stats のタブを持つパネルが開きます。クリックして操作できます。コマンドで操作したい場合は次のとおりです。

/plugin install github@claude-plugins-official   # install from a marketplace
/plugin list --enabled                           # what is on right now
/plugin disable <name>@<marketplace>             # turn it off, keep it installed
/plugin uninstall <name>@<marketplace>

公式 marketplace の名前は claude-plugins-official で、Anthropic が管理しています。インタラクティブモードを初めて起動したときに自動で登録されます。自動で登録されなかった場合は、手動で追加してください。

/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add anthropics/claude-plugins-community   # community one, add it yourself

Marketplace のソースには、GitHub の owner/repo、Git URL、リモート URL、ローカルパスを指定できます。また、/plugin marketplace list、update <名前>、remove <名前> で管理できます。

あるディレクトリに初めて plugin をインストールするときは、Claude Code がそのディレクトリを信頼するかどうかを尋ねます。git リポジトリでは一度答えれば、そのリポジトリ全体に適用されます。

ここは慎重に考えておくとよいでしょう。Plugin は hook と MCP server を同時に持てるため、インストールしたものは、あなたのコンピューター上でコマンドを実行する可能性があります。インストールする前にソースを確認してください。公式 marketplace、または多くの人が使っていて実績のあるものであれば比較的安心です。新しく見えて、まだ利用者が少ないものは、hooks/ と .mcp.json を開いて内容を確認してから判断してください。

v2.1.271 以降、インストールまわりのセキュリティにいくつかの穴が塞がれました。知っておくと役立つ点は次のとおりです。

• npm ソースの plugin はインストールスクリプトを実行しなくなりました。 npm pack --ignore-scripts で取得し、整合性を検証する方式に変わったため、パッケージ内の postinstall がコンピューター上で実行されることはありません。
• --marketplace で一度にまとめて指定できます。 /plugin install <plugin> --marketplace <ソース> を使うと、まだ追加されていない marketplace は、先に追加するかどうかを尋ねられます。2 段階の操作は不要です。v2.1.292 以降は、コマンドライン版の claude plugin install --marketplace <ソース> も対応しています。必要に応じて先に marketplace を追加し（claude plugin marketplace add と同じポリシーチェックを適用）、その中から plugin をインストールします。
• インストール時に設定を済ませられます。 claude plugin configure <plugin> は、plugin のオプションと未設定の項目を一覧表示します。--values-stdin を付けると、標準入力から新しい値を保存できます（v2.1.285 以降）。claude plugin install --config では、<server>.<key>=<value> の形式で、plugin に含まれる .mcpb MCP server のパラメーターを設定できます。インストール後に /plugin → Configure を開いて回る必要がありません。
• CI では -y を使わないでください。 claude plugin install と claude plugin update は --accept-command <sha256> に対応しています。これは、直前の --json 出力に表示されたコマンドだけを受け入れる仕組みです。内容が変わっていれば通過しないため、自動化にチェックを 1 つ入れられます。
• claude.ai アカウントで有効にした plugin は、ターミナルに同期されます。 第 9 章の skill の同期と同じ仕組みです。"syncClaudeAiPlugins": false で無効にできます。

インストール後に plugin の内容を変更した場合も、再起動は不要です。

/reload-plugins            # apply changes in the current session
/reload-plugins --force    # when the cache needs rebuilding too

自分で作る

ディレクトリの構成は次のとおりです。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── hello/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
└── .mcp.json

plugin.json は実際には省略可能です。ない場合、Claude Code は標準の場所にあるコンポーネントをそのまま読み込みます。作成する場合、必須なのは name だけですが、他のフィールドも記入することをおすすめします。やや詳しい例は次のとおりです。

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

version は省略できます。省略した場合は、git の SHA がバージョンとして使われます。name は skill の接頭辞も決めるため、短い名前にしておくとよいでしょう。

公開する前でも、ローカルのフォルダを指定するだけでテストできます。

claude --plugin-dir ./my-plugin     # load one plugin for this session
claude --plugin-dir ./plugins       # v2.1.265+: load every plugin in the folder
claude plugin validate ./my-plugin  # check the structure and schema

フォルダを指定すると、Claude Code はまずそのフォルダ直下に plugin の内容があるかを確認します。なければ、「多数の plugin を含むフォルダ」とみなし、.claude-plugin/plugin.json を持つそれぞれのサブフォルダを 1 つの plugin として扱います。

claude plugin eval で検証する

skill と hook を書き終えたあとで最も難しいのは、それが本当に Claude の動作を良くしているかどうかを判断することです。claude plugin eval は、まさにそれを行うためのコマンドです。テストケースのセットを使って plugin を実行します。各ケースはデフォルトで 3 回ずつ実行され、さらに plugin を入れていない比較グループでも実行して、両者の差を報告します。v2.1.269 以降が必要です。

claude plugin eval init                        # interview, writes cases and graders
claude plugin eval .                           # run every case
claude plugin eval . --runs 1 --ablation none  # single arm, cheaper
claude plugin eval . --trust-plugin            # for CI, skips the trust prompt

ケースは evals/<ケース名>/ に置きます。その中の prompt.md にプロンプトを書き、graders/ の下にはグレーダー（採点器）を 1 ファイルにつき 1 つ配置します。グレーダーは 6 種類あります。

実行が終わると、evals/results/<タイムスタンプ>/ に aggregate-result.json と report.html が生成されます。終了コードは CI にそのまま接続できます。0 はすべてのケースが基準を満たしたこと、1 は基準を下回ったか、信頼プロンプトが拒否されたこと、2 は一部しか実行されなかったこと（コスト上限や認証の失敗など）を意味します。

事前に知っておくべき点があります。eval の実行ごとと、採点モデルの呼び出しごとに料金がかかります。また、eval は隔離された環境で実行されるため、個人の設定、他の plugin、メモリ、MCP server は読み込まれません。そのため、測定されるのはその plugin 自体の効果だけです。

次のステップ

まずは 1 つインストールすることから始めてください。/plugin を入力して、公式 marketplace から毎日使いそうなもの（例えば GitHub に関係するもの）を選びます。1 週間使ってみて、問題なく使えることを確認してから、2 つ目を追加します。自分の ~/.claude/skills/ に 2、3 個のよく使う skill がたまったら、それらを 1 つの plugin フォルダにまとめ、claude --plugin-dir でローカルにテストしてから、marketplace に公開して他の人にも使ってもらうかどうかを決めてください。

出典：Claude Code 公式ドキュメント〈Create plugins〉 の Create your first plugin の各節、〈Discover and install prebuilt plugins〉 のインストールと marketplace の各節、および 〈Test plugins with evals〉 の Requirements、Graders、Run evals の各節（2026-09-18 確認）。インストールのセキュリティの節の内容は Claude Code CHANGELOG の 2.1.271 と 2.1.275（2026-09-19 確認）に基づきます。Claude Code CHANGELOG の 2.1.285（2026-10-02 確認）、2.1.292（2026-10-07 確認）（2026-10-15 に〈Plugins reference〉の Manifest の節と照合して更新。）

モデル、Effort レベル、Fast mode

前の章では、plugin を使ってツールをパッケージ化する方法を説明しました。ただ、ツールがどれだけ揃っていても、最終的に回答の質と請求額を決めるのは次の 2 つです。どのモデルを使うか、そしてそれにどれだけ考えさせるか。

Claude Code はこの 2 つを分けて扱っています。モデルは基礎的な能力を決め、effort レベルは回答する前にどれだけ力を入れて考えるかを決めます。この 2 つを理解しておくほうが、Opus と Sonnet のどちらにするかで迷い続けるよりも役に立ちます。

現在使えるモデル

完全な model ID を覚える必要はありません。エイリアスを覚えておけば十分です。default、best、fable、opus、sonnet、haiku、opusplan、それに長いコンテキスト版の sonnet[1m]、opus[1m] があります。

エイリアスが実際にどのモデルに対応するかは、使用するプラットフォームによって異なります。

fable にはプラットフォームごとの対応表はありません。デフォルトでは Fable 5.1 に対応し、Claude apps gateway の session だけが Fable 5 になります。

どのモデルがデフォルトになるかは、プランとプラットフォームによって異なります。Pro、Max、Team、Enterprise、Anthropic API、そして Claude Platform on AWS、Amazon Bedrock、Google Cloud Agent Platform では、デフォルトは Opus 5.5 です。Microsoft Foundry のデフォルトは Sonnet 4.5 です。Fable はどのプランやプラットフォームでもデフォルトではありません。v2.1.280 以降、Pro と Team Standard のデフォルトも Sonnet から Opus に変わりました。 現在の最新モデルは Opus 5.5（claude-opus-5-5、v2.1.280）と Sonnet 5.5（claude-sonnet-5-5、v2.1.284）で、どちらも 1M コンテキストです。API の価格は 100 万トークンあたり、Opus 5.5 は入力 $4、出力 $20、Sonnet 5.5 は入力 $2、出力 $10 です。

また、v2.1.285 以降、カスタムの ANTHROPIC_BASE_URL を使う session では、1M のウィンドウを持つモデル（Opus 4.7 以上、Sonnet 5 以上、Fable）のロングコンテキストがそのまま使われます。gateway が 200K までしか対応していない場合は、/autocompact 200k を入力してください。Bedrock、Vertex、Foundry、Claude apps gateway では、Opus 4.7 以上と Fable も v2.1.287 以降、[1m] を付けなくても 1M がデフォルトになります。200K のままにしたい場合は CLAUDE_CODE_DISABLE_1M_CONTEXT=1 を設定します。さらに v2.1.288 以降、/autocompact の設定はモデルごとに分けて保存されるため、モデルを切り替えても互いに上書きされません。

軽量な Haiku も更新されました。v2.1.293 以降、Anthropic API の haiku エイリアスは Haiku 5.5（claude-haiku-5-5）に対応します。1M コンテキストで、価格は 100 万トークンあたり、入力 $0.10、出力 $0.50 です。ただし、プロンプトが 100K トークンを超えるリクエストでは、そのリクエスト全体が $0.50／$2.50 に切り替わります。超過した部分だけではありません。長さを判定する際には、キャッシュの読み取りと書き込みのトークンも含めて計算されます。

モデルを切り替える方法は、影響の大きい順から次のとおりです。/model <エイリアス> は今の会話だけを変更します。claude --model <エイリアス> は起動時に指定します。環境変数 ANTHROPIC_MODEL、settings.json の model があり、最後が ANTHROPIC_DEFAULT_MODEL（v2.1.236 以降。新しい会話のデフォルト値にのみ影響します）です。

opusplan というエイリアスは覚えておく価値があります。計画の段階では Opus を使い、実装の段階に入ると Sonnet に戻します。先によく考えてから手を動かすタイプの作業に向いています。

Effort レベル：どれくらい考えさせるか

同じモデルでも、考える力の入れ具合を調整できます。

ほとんどのモデルのデフォルトは high ですが、Opus 5.5、Sonnet 5.5、Haiku 5.5 のデフォルトは medium で、Opus 4.7 のデフォルトは xhigh です。切り替え方法は次のとおりです。

claude --effort xhigh                  # at startup
export CLAUDE_CODE_EFFORT_LEVEL=medium # environment variable

/effort          # interactive slider
/effort high     # set it directly

設定ファイルでは、effortLevel（デフォルト値）、modelSettings（モデルごとに記憶される レベル）、maxEffortLevel（上限）に対応します。

思考そのものにも料金がかかります。thinking のトークンは output トークンとして課金されます。そのため、単純な作業は low または medium に設定したほうが、常に high を使うよりも安く、速く済みます。extended thinking を完全にオフにしたい場合は MAX_THINKING_TOKENS=0 を設定できますが、Opus 5.5、Sonnet 5.5、Haiku 5.5 と Fable は例外で、これらのモデルでは thinking をオフにできません（/config には Thinking can't be turned off と表示されます）。

ultracode は effort レベルではなく、Claude が dynamic workflow を使って多数の subagent を自動で調整するための切り替えです。v2.1.284 以降、/effort の中で独立したスイッチになりました（Tab キーを押すか、/effort ultracode on / off と入力します）。xhigh を強制されることはなくなり、どの effort レベルでも有効にできます。 これについては次の章で詳しく説明します。

また、v2.1.280 以降、/effort はモデルごとにレベルを記憶するようになりました。古いバージョンで保存されたレベルは、Opus 5.5 のような新しくリリースされたモデルには適用されません。これらのモデルはデフォルトのレベルから始まるため、改めて選択し直す必要があります。

Fast mode：同じ Opus を 2.5 倍速く

Fast mode はモデルを切り替えるものではありません。同じ Opus を別の API 設定で動かし、速度を料金よりも優先させるものです。応答は最大 2.5 倍速くなります。対応しているのは Opus 5.5、Opus 5、Opus 4.8 で、Sonnet と Haiku は対象外です。v2.1.280 以降、デフォルトは Opus 5.5 です。Opus 4.7 の fast mode は 2026 年 7 月 24 日に削除されました。これはリサーチプレビューであり、機能、価格、提供範囲は変更される可能性があります。

価格は 100 万トークンあたり、Opus 5.5 は入力 $8、出力 $40、Opus 5 と Opus 4.8 は入力 $10、出力 $50 です。注意すべき点は、有効にした瞬間に、会話全体の context がキャッシュされない価格で 1 回入力として計算されることです。そのため、有効にするなら会話の最初に有効にしてください。途中で有効にすると、かえって高くなります。

/fast        # toggle
/fast on     # in a cloud session

設定ファイルの fastMode でデフォルトのオン・オフを決められます。fastModePerSessionOptIn を使うと、会話ごとに手動で有効にするよう要求できます（v2.1.257 以降）。

Pro と Max では、先に Settings の Usage で利用枠を有効にする必要があります。Team と Enterprise では、オーナーが Admin Settings で有効にします。Bedrock、Google Cloud Agent Platform、Microsoft Foundry、Claude Platform on AWS では利用できません。

モデルが停止したときのフォールバック

メインのモデルが過負荷になったり、一時的に利用できなくなったり、再試行しても意味がないサーバーエラーが発生したりした場合は、別のモデルに自動で切り替えて処理を引き継がせることができます。

claude --fallback-model sonnet,haiku

{ "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"] }

フォールバックのチェーンは最大 3 つのモデルです。切り替えは現在のターンだけに影響し、subagent にも同じ設定が適用されます。認証、請求、レート制限、リクエストサイズの超過などのエラーはフォールバックを起動しません。モデルを切り替えても解決しないためです。

また、内容に応じて自動で切り替わる仕組みもあります。Fable 5.1、Fable 5、Opus 5.5 は、生物学に関する内容では Opus 5 に、セキュリティに関する内容では Opus 4.8 に切り替わります。Sonnet 5.5 は、セキュリティに関する内容では Sonnet 5 に切り替わり、生物学に関する内容では直接拒否します。Opus 5 は、セキュリティに関する内容では Opus 4.8 に切り替わり、生物学に関する内容では同じく拒否します。この動作を望まない場合は、/config で「モデルの切り替え」の項目をオフにするか、"switchModelsOnFlag": false を設定してください。

コストを抑える組み合わせ方

普段はデフォルトのモデルのままにしておけば十分で、頻繁に切り替える必要はありません。本当に慎重に考える必要がある作業（アーキテクチャや、原因の特定が難しいバグ）のときだけ、opusplan に切り替えるか、effort を xhigh に上げてください。文案の修正やテストの実行のような作業は medium まで下げましょう。節約されるのは時間でもあり、お金でもあります。Fast mode は急ぎの場面に向いていますが、必ず会話の最初に有効にしてください。途中で有効にすると高くつきます。

次のステップ

今のうちに一度、現状を確認してください。/model を入力して現在どのモデルかを確かめ、/effort を入力してどの段階にいるかを確かめます。次に、今日行った小さな作業を 1 つ選び、effort を medium に下げて同じ作業をもう一度実行し、結果が悪くなっていないかを比べてみてください。高い effort を必要としない作業は下げてしまって構いません。そうすれば /context も請求額も、より良い数字になるはずです。

出典：Claude Code 公式ドキュメント〈Model configuration〉 の Model Aliases、Model Resolution by Provider、Effort Levels、Fallback Model Chains、Automatic Model Fallback の各節、および 〈Fast mode〉 の全文、ならびに 料金ページ（2026-10-15 確認）。Claude Code CHANGELOG の 2.1.280、2.1.284、2.1.285、2.1.287（2026-10-02 確認）、2.1.288（2026-10-03 確認）、2.1.293（2026-10-08 確認）

Worktree と複数セッションによる同時作業

第10章の subagent は、「一つの作業を多くのステップに分ける」問題を解決するものです。しかし、互いに無関係な作業を二つ同時に抱えている場合、たとえばログインフローを変更しながら CI を修正する場合は、ウィンドウを二つ開いてそれぞれで Claude Code を動かすと、両方が同じ作業ディレクトリを変更するため、途中で互いのファイルを壊し合ってしまいます。

Git worktree は、元から存在する解決策です。同じ repo に複数の作業ディレクトリを用意し、それぞれが自分のブランチに留まりつつ、履歴とリモートは共有します。Claude Code はこれを組み込んでおり、会話ごとに自分の worktree の中で作業できるため、互いのファイルが衝突しません。

Worktree を作成して作業する

claude --worktree auth-refactor   # create a named worktree and start there
claude -w auth-refactor           # same thing, short form
claude --worktree                 # no name: one is generated, e.g. bright-running-fox
claude --worktree "#1234"         # branch from a PR

既定では repo のルートに .claude/worktrees/<名前>/ が作成され、ブランチ名は worktree-<名前> になります。このフォルダは .gitignore に追加してください。

すでに会話中で隔離したくなった場合は、Claude に頼んで worktree を作成してもらうこともできます。その場合は EnterWorktree を使って作成されます。現在どの worktree があるかを確認したり、手動で削除したりする場合は、従来の git コマンドを使います。

git worktree list
git worktree remove <path>

どのブランチから作成し、どう削除するか

既定では既定のブランチから新しく作成されます。現在の HEAD から作成したい場合は、設定を変更します。

{ "worktree": { "baseRef": "head" } }

終了時には、クリーンで名前のない worktree は自動的に削除されます。名前が付いている、または変更がある worktree については、残すか削除するかを確認されます。claude -p のような非対話モードでは後片付けは行われないため、git worktree remove を自分で実行してください。subagent やバックグラウンドセッションが使用した worktree は、cleanupPeriodDays に従って定期的に削除されます。

もうひとつ便利なファイルがあります。.worktreeinclude です。worktree は新しい作業ディレクトリであり、git で無視されているファイルはコピーされません。そのため .env のようなファイルは見当たらなくなります。.gitignore の書式でそれらを列挙しておくと、新しい worktree を作るたびにコピーされます。

.env
.env.local
config/secrets.json

worktree 内のセッションを再開するには v2.1.212 以上が必要です。古いバージョンでは、トランスクリプトの位置の追跡に問題が生じます。

agent view で全セッションを確認する

複数の会話を同時に動かしていると、次に知りたくなるのは「どれが終わったか」「どれがあなたの回答を待っているか」です。

claude agents              # full-screen dashboard
claude agents --cwd <path> # only sessions under this directory
claude agents --json       # for scripts

画面上では、会話ごとに先頭に状態記号が表示されます。その形はプロセスの状態を表します。✻ または動きのある ✽ はセッションが実行中、またはあなたの入力を待っている状態、∙ はプロセスが終了していること（返信または attach すると、保存された会話から再起動します）、✢ は /loop が次の実行までスリープしている状態です（実行回数とカウントダウンが表示されます）。完了・失敗・停止は色で区別されます。緑は完了、赤は失敗、灰色は停止、黄色はあなたの入力待ち、アイコンが暗くなっているのはアイドル状態です。よく使うキーは、Enter または → でそのセッションに入る、Space でプレビューの開閉、Ctrl+R で名前変更、Ctrl+X で停止（もう一度押すと削除）、Ctrl+S でグループ化方法の切り替え、? で全ショートカットの表示です。

画面に入らずに使えるコマンドもあります。

claude attach <id>     # open that session in this terminal
claude logs <id>       # print its recent output
claude stop <id>       # stop it
claude rm <id>         # remove it from the list
claude daemon status   # check the supervisor process

v2.1.290 からは、claude attach と claude logs の引数として、完全な id のほかに、セッション名の一部だけを指定することもできます。

Agent teams：複数のセッションを互いに連携させる

さらに上の層が agent teams です。ひとつの会話がリーダーとなって作業の分担と取りまとめを行い、他のチームメイトはそれぞれ独立した context を持ち、互いに直接メッセージを送れます。この機能は既定で無効になっており、自分で有効にする必要があります。

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

有効にしたら、自然言語でタスクと必要な役割を説明すると、Claude がチームメイトを作成します。タスクは共有のタスクリストに置かれ、保留中・進行中・完了の三つの状態を持ち、依存関係も設定できます。前の作業が完了していなければ、後続の作業は取得できません。ファイルロックは、同じファイルを同時に変更することを防ぎます。タスクとメールボックスは、それぞれ ~/.claude/tasks/{team-name}/ と ~/.claude/teams/{team-name}/inboxes/ に保存されます。

チームメイトの表示先は選べます。既定の in-process では、すべて同じターミナルで実行されます。auto は tmux または iTerm2 の中で自動的にウィンドウを分割します。tmux または iterm2 を指定することもできます（iTerm2 は v2.1.186 以上が必要で、it2 と iTerm2 の Python API のインストールも必要です）。VS Code の内蔵ターミナル、Windows Terminal、Ghostty はウィンドウ分割に対応していません。

制限事項は事前に把握しておいてください。/resume と /rewind ではチームメイトは復元されず、再開した会話ではチームメイトがすでに存在しません。claude -p の下では、チームメイトは通常の subagent に退化します。チームメイトはさらにチームメイトを作成できません。一つのセッションにつきチームは一つだけです。

四つの並列方式の選び方

コスト面は心づもりが必要です。subagent の結果はメインの会話に集約されるため、比較的抑えられます。agent teams では、チームメイトがそれぞれ独立したインスタンスなので、トークン消費は明らかに多くなります。

次のステップ

次に二つの作業を同時に進めることになったら、二つ目のためにウィンドウを新たに開くのではなく、claude -w <名前> で worktree を開いてそこで作業してください。その前に、.claude/worktrees/ を .gitignore に追加し、.worktreeinclude に .env を記載しておくことを忘れないでください。両方を起動したら、別のターミナルで claude agents を実行し、状態記号を見ながら、どちらから先に応答するかを決めます。

出典：Claude Code 公式ドキュメント〈Run parallel sessions with worktrees〉の Start Claude in a worktree、Customize worktree creation、Copy gitignored files into worktrees、Clean up worktrees の各節、〈Agent View〉の Opening Agent View、Key Commands、State Icons、Keyboard Shortcuts の各節、および〈Orchestrate teams of Claude Code sessions〉の Enable agent teams、Assign and claim tasks、Choose a display mode、Compare with subagents、Limitations の各節（2026-09-18 確認）、Claude Code CHANGELOG の 2.1.290（2026-10-06 確認）（2026-10-15 には〈Agent view〉の Read session state を照合し、状態記号を更新。）

自動化：headless モード、CI、スケジュール実行

これまでは、あなたがターミナルの前に座って、一文ずつ指示してきました。しかし、あなたが立ち会う必要のない作業もあります。たとえば、毎朝昨日の issue を整理する、PR を開くたびに自動で review を一周させる、決まったチェックを CI に組み込む、といったものです。

この章では、Claude Code を会話ツールから、呼び出せるプログラムへと変える方法を説明します。人が操作しない状態で実行する方法、GitHub に接続する方法、時間を決めて自動で実行させる方法です。

headless モード：claude -p

-p（または --print）を付けると対話画面には入らず、実行後に結果を出力して終了します。成功時は 0、失敗時は 0 以外を返すため、そのまま shell script に組み込めます。

claude -p "summarise today's git log" --output-format json
cat error.log | claude -p "what failed here?"   # stdin, up to 10MB

--output-format には text（既定）、json、stream-json の三種類があります。出力形式を固定するには、--output-format json と組み合わせて --json-schema を使えます。

権限については特に注意が必要です。-p では同意ボタンを押せる人がいません。また、権限モードを指定しない場合は、組み込みの初期モードで起動します（auto の可能性もあります）。そのため、明示的に指定しておくのが安全です。事前に許可しておくか、「確認せず拒否する」と明言するかのどちらかにしてください。

claude -p "run the tests" --allowedTools "Read,Bash"   # pre-approve
claude -p "..." --permission-mode dontAsk               # no prompts
claude -p "..." --permission-prompts none               # refuse everything that needs asking

CI をより速く、より安定して動かすためのオプションが、もうひとつあります。--bare です。これは hook、Skill、カスタムコマンド、subagent、plugin、MCP server、auto memory、CLAUDE.md の自動読み込みをすべてスキップします。つまりクリーンな環境になり、どのマシンで実行しても結果が同じになります。注意点として、bare モードでは OAuth ログインと system keychain は読み込まれないため、ANTHROPIC_API_KEY を自分で設定する必要があります。

実行終了時の挙動も確認しておいてください。claude -p は、バックグラウンドの作業が完了するまで終了しません。主会話が起動したバックグラウンドコマンド（例：dev server）は、それが終了するか時間上限に達するまで待ちます。subagent と workflow は、その結果が最終出力に含まれるため、完了するまで待ちます。Monitor のような監視やアイドル待機は、連続して最大10分まで待ちます（CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS で調整でき、0 に設定すると上限がなくなります）。前回の会話を引き継ぐ場合は、--continue と --resume <session-id> が -p の下でも同じように使えます。

GitHub Actions に接続する

手軽な導入方法は、対話モードで /install-github-app と入力することです。GitHub App のインストール、認証用 secret の追加、workflow ファイルを追加する PR の作成までを行ってくれます。GitHub CLI と repo の管理権限が必要です。手動で導入する場合は、自分で App をインストールし、ANTHROPIC_API_KEY または CLAUDE_CODE_OAUTH_TOKEN という secret を追加して、workflow ファイルをコピーします。

workflow の実行方法は二種類あり、違いは prompt を指定するかどうかだけです。

• prompt を指定しない：対話モード。issue や PR のコメントで誰かが @claude と書くまで待機します
• prompt を指定する：自動モード。イベントが発生した時点で実行され、人の操作を待ちません

誰がトリガーできるかにも制限があります。既定では書き込み権限を持つ人のみが対象です。それ以外の人は allowed_non_write_users に追加する必要があります。bot アカウントは allowed_bots に追加する必要があります。

クラウドベンダーを利用する場合は、workflow で対応するスイッチを変更します。Bedrock では use_bedrock: "true" と OIDC の AWS_ROLE_TO_ASSUME を組み合わせ、Google Cloud Agent Platform では use_vertex: "true" と Workload Identity Federation を組み合わせ、Microsoft Foundry では use_foundry: "true" と Entra アプリケーションの変数一式を組み合わせます。

認証情報はすべて GitHub Secrets を通してください。ファイルに直接書き込まないでください。workflow の権限は必要最小限に留めてください。Claude が作成した変更は、マージする前に必ず自分で確認してください。

スケジュール：定期的に自動実行させる

クラウドのスケジュール機能は routines と呼ばれます。claude.ai/code/routines で作成するか、CLI で /schedule を使って作成できます。Anthropic がホストするクラウド環境（または組織が自前で用意した環境）で実行されるため、あなたのコンピュータを起動しておく必要はありません。トリガーは三種類あります。

一回限りの実行は、実行時刻になると自動的に無効化されます。また、他のスケジュール実行と毎時の上限（アカウントごとに毎時100回）を共有しており、これは別枠ではありません。環境では、パッケージマネージャーやクラウド API などの一般的なドメインが既定で許可されています。カスタムドメインを追加するには、環境設定の Network access で変更してください。

同じ会話の中で一つの作業を繰り返すだけなら、/loop を使えば十分で、クラウドのスケジュールは必要ありません。

/loop 5m <prompt>   # every five minutes
/loop <prompt>      # Claude picks the interval, between 1 minute and 1 hour

「三点にデプロイを確認するようリマインドして」と直接言うこともでき、その場合はリマインダーが作成されます。このようなスケジュールタスクは七日後に期限切れになります。会話を再開したとき、期限切れでないものは一緒に戻ってきます。会話が終了すると、すべて削除されます。

Channels：Telegram などから作業を送り込む

Channels を使うと、Telegram、Discord、iMessage のメッセージを、実行中の会話に送り込めます。つまり、外出先からでも作業を依頼できます。これはリサーチプレビューの機能で、Bun が必要です。Bedrock、Vertex、Foundry には対応していません。

/plugin install telegram@claude-plugins-official
/telegram:configure <token>

その後 Claude Code を終了し、--channels を付けて再起動すると、bot がメッセージの受信を開始します。

claude --channels plugin:telegram@claude-plugins-official

bot にメッセージを送ってペアリングコードを受け取り、戻ってきてペアリングします。

/telegram:access pair <code>

セキュリティの仕組みを正しく理解してください。各 channel には独自の送信者許可リストがあり、リストに載っている ID のみがメッセージを送信できます。Telegram と Discord では、ペアリングコードで人をリストに追加します。iMessage では、自分自身との会話は自動的に許可され、他の連絡先は手動で追加します。/telegram:access policy allowlist を実行すると、リストに含まれる人だけが使える状態に制限できます。リストに載った人は、ツール呼び出しをリモートで承認することもできるため、このリストは権限リストとして扱い、安易に人を追加しないでください。Team と Enterprise では既定で無効になっており、Owner が管理画面で channelsEnabled を有効にする必要があります。

次のステップ

まずは小さな一歩から始めてください。毎日手動で行っているチェックを、一行の claude -p にまとめ、読み取りだけを許可する --allowedTools を付けて、出力が正しいかを試してみてください。安定したら、CI に組み込むか、routine にして定期実行させるかを決めます。GitHub Actions に手を加える前に、secret が正しく設定されていること、workflow の権限が広げすぎになっていないことを確認してください。

出典：Claude Code 公式ドキュメント〈Headless mode〉の Basic usage、Start faster with bare mode、Get structured output、Auto-approve tools、Background tasks at exit の各節、〈GitHub Actions〉の Setup、Interactive and automation modes、Protect your credentials の各節、〈Routines〉の Add a schedule trigger、Add an API trigger、Add a GitHub trigger、Usage and limits の各節、〈Scheduled tasks〉の /loop と Seven-day expiry の各節、および〈Channels〉の Supported channels、Security、Enterprise controls の各節（2026-09-18 確認）（2026-10-15 には〈Headless mode〉、〈Routines〉、〈Channels〉を照合して更新。）

Dynamic Workflows と ultracode

第10章の subagent は、「一人に調べさせる」ものです。数人程度を一度に派遣するならそれでも十分です。しかし「500 個のファイルすべてを一通りスキャンする」「同じ問題を六つの角度からそれぞれ調べ、相互に検証する」といった作業では、メインの会話が一巡ごとに次の手順を決めていくと、中間結果でコンテキストがあふれ、どこか一箇所でも間違えると最初からやり直しになります。

Dynamic workflow は別のやり方をとります。まず Claude が JavaScript のスクリプトを書き、そのスクリプトが何個の agent を派遣するか、どれを先に、どれを後に実行するか、結果をどう集めるかを決めます。スクリプトはバックグラウンドで実行され、その間もあなたの会話は続けられます。中間結果はスクリプトの変数に保存されるため、あなたのコンテキストは消費しません。

workflow を使うタイミングと subagent を使うタイミング

数十個の agent を派遣し、かつ手順が固定されている作業の場合にのみ、workflow を使う価値があります。

起動方法

最も簡単な方法は、文の中に ultracode というキーワードを入れることです。すると Claude が、その作業のための workflow スクリプトを書きます。その他の方法は次のとおりです。

キーワードは、人間が入力した場合にのみ有効になります（対話入力、IDE 拡張、Remote Control、そして Agent SDK で { kind: "human" } と表示された入力）。-p、webhook、PR のコメント、スケジュールタスクに含まれていても有効になりません（v2.1.210 から）。これは意図的な設計です。issue のコメントに誰かがキーワードを仕込むだけで、自動化が大量のトークンを消費してしまうのを防ぐためです。

キーワードが強調表示されたものの、今回は使いたくない場合は、Option+W（macOS）または Alt+W を押して取り消せます。完全に無効にしたい場合は、/config で Ultracode keyword trigger をオフにしてください。

実行前に Claude がまず計画を提示します。auto モードでは初回のみ確認し、manual モードでは毎回確認し、bypass モードでは確認しません。

スクリプトの中身

スクリプトの先頭は必ず meta ブロックで、純粋なオブジェクトリテラルでなければならず、name と description を含みます。変数や関数呼び出しとして書くと、その workflow は / の自動補完リストに表示されなくなります。

よく使う関数は五つあります。

Node を普段使っている人が踏みやすい制限が二つあります。スクリプト内ではモジュールを動的に読み込めません。import() があると、実行前に失敗します。また、Date.now()、Math.random()、引数なしの new Date() を使うと、直接エラーになります。タイムスタンプが必要な場合は、外部から args を通して渡してください。実行したい処理はすべて agent のタスクに入れ、スクリプトはスケジューリングのみを担当させてください。

schema の検証に失敗した場合は再試行されます。五回試しても通らなければエラーを返します。回数は MAX_STRUCTURED_OUTPUT_RETRIES で調整できます。

規模、コスト、中断後の再開

既定で同時に16個の agent が実行されます（CPU に応じて減らされます）。CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS を使えば、1 から 256 の間で調整できます（v2.1.269 以上が必要）。一回の parallel や pipeline は最大 4,096 項目までで、超えた場合は黙って切り捨てられるのではなく、明示的に拒否されます。一回の実行での agent 数は最大 1,000 個で、ループが暴走するのを防ぎます。25 個の agent または 150 万トークンが必要と予測された場合は警告が表示されますが、実行はブロックされません。

設定ファイルの workflowSizeGuideline は、Claude に規模の目安を伝えられます。small は 5 個未満、medium（既定。Pro プランでは small）は 10 個未満、large は 50 個未満、unrestricted は制限なしです。

すべての workflow agent に同じモデルを統一して使わせたい場合は、CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL を設定できます（v2.1.296 以降）。他の subagent は、それぞれの設定に従います。

コストを抑える鍵は prompt cache です。同じ一群の agent が共通の接頭辞を使う場合、二つ目以降はキャッシュを読み取れます。既定では、最初の agent がキャッシュを作成できるように、5 秒ずらして開始されます（CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS）。キャッシュは既定で 5 分間保持されます。subagentPromptCacheTtl を 1h に設定することもできますが、API 課金の場合は一時間キャッシュの書き込み単価が高くなるため、ご自身でトレードオフを判断してください。

実行中に使用量の上限に達した場合、実行は失敗ではなく一時停止されます。枠がリセットされると自動的に再開されます（v2.1.271 以上、対話モード、かつ autoContinueAtUsageLimit が有効な場合に限ります）。待機は最大二回までで、三回目で失敗になります。

完了していない実行を再開する場合、完了済みの agent は保存済みの結果をそのまま返し、中断または失敗した agent は再実行されます。さらに、その後に続く agent も一緒に再実行されます。結果は ~/.claude/projects/<session>/ に保存され、保存データが見つからない場合は nothing to resume と報告され、黙って最初から実行されることはありません。

すべての有料プラン、API、Bedrock、Google Cloud Agent Platform、Microsoft Foundry で利用できます。Pro では /config で有効にする必要があり、組織の管理者は managed settings で全体を無効にできます。

次のステップ

最初は、自分でスクリプトを書こうとしないでください。普段 Claude に頼んでいるものの、毎回時間がかかって不満な大きな作業を一つ選びます。たとえば「repo 全体をスキャンして、古い API を使っている箇所をすべて見つける」などです。文に ultracode を加えると、どれだけの agent を派遣し、どのフェーズに分けるかの計画が出てきます。規模が大きすぎると感じたら、まず workflowSizeGuideline を small に設定し、慣れてきてから広げてください。

出典：Claude Code 公式ドキュメント〈Orchestrate subagents at scale with dynamic workflows〉の When to use a workflow、Have Claude write a workflow、Let Claude decide with ultracode、Where the keyword works、What the saved script looks like、Edit a saved script、Behavior and limits、Prompt caching in a fan-out、Set a size guideline、When a run hits your usage limit、Resume after a pause の各節（2026-09-18 確認）；Claude Code CHANGELOG の 2.1.284、2.1.296（2026-10-10 確認）

ターミナル以外での利用先

ここまでのドキュメントでは、ターミナルの中の Claude Code について説明してきました。しかし、同じアカウント、同じ設定で、IDE、デスクトップアプリ、ブラウザ、スマートフォン、さらには Slack からも利用できます。それぞれでできることは少しずつ異なります。

この章は対照表で、どの場面でどれを使うべきかを判断する助けになります。

VS Code と JetBrains

VS Code は 1.94 以上が必要です。拡張機能マーケットプレースで Claude Code を検索すればインストールできます。インストール後は、エディタ内でインライン diff を見たり、@ でファイルに言及したり、計画をレビューしたり、複数のタブでそれぞれ別の会話を動かしたり、過去の会話を見たりできます。制限事項として、/plugin や /resume など CLI 専用のコマンドは使えません。また、拡張機能に同梱されている CLI はグラフィカルインターフェース専用のため、ターミナルで使う場合は別途インストールが必要です。

JetBrains 系（IntelliJ、PyCharm、WebStorm など）では、先に CLI をインストールしてから、JetBrains Marketplace からプラグインを入れ、IDE を再起動します。Cmd+Esc または Ctrl+Esc で呼び出せます。変更は IDE 独自の diff ビューアで表示され、選択したコードは自動的に会話に渡されます。また、IDE の lint やシンタックスエラーも読み取れます。リモート開発の場合は、リモートホストにプラグインをインストールする必要があります。WSL2 の既定の NAT ネットワークでは、別途ファイアウォールのルールを設定する必要があります。

どちらも Pro、Max、Team、Enterprise のいずれかの有料プラン、または Claude Console アカウントが必要です。API キーは不要です。

デスクトップアプリ

claude.com/download からダウンロードできます。作業スペースの整理やプレビューサーバーの起動に加えて、特徴的なのはコンピュータ操作です。クリック、入力、ドラッグ、ショートカットキーの送信、ネイティブアプリの起動ができ、macOS ではバックグラウンドでの実行も可能です。Settings の General で有効にします。macOS では、アクセシビリティと画面収録の権限も付与する必要があります。

これはリサーチプレビューであり、コンピュータ操作はサンドボックスなしで動作します。提供されているのは Pro と Max のみで、Team と Enterprise は対象外です。ターミナルにも対応する機能があります。/mcp と入力して computer-use を見つけて有効にしてください。macOS のみ対応、対話モードのみ（-p では使えません）で、同時に画面をロックできるのは一つの会話のみです。

クラウドセッションと Slack

クラウドセッションは Anthropic がホストする環境（または組織が自前で用意した環境）で動作するため、あなたのコンピュータの電源を切っても動き続けます。ブラウザで claude.ai/code を開くか、ターミナルで claude --cloud "作業の説明" を実行します。複数のタスクを同時に投げるのに向いており、環境には git、npm、Python などのツールが用意されています。GitHub App を接続すると、PR を自動で修正することもできます。制限として、対応しているのは GitHub（GitHub Enterprise Server を含む）のみで、GitLab と Bitbucket は使えません。利用量はその他の利用と共有されます。組織が IP 許可リストを設定している場合は、アクセスがブロックされます。

Slack では、チャンネルで @Claude と書くことで作業を依頼できます。Claude は thread の文脈を自動的に読み取り、クラウドセッションにルーティングして作業を行います。PR を開くこともでき、記録は引き続き claude.ai/code に残ります。制限は多くあります。対応は GitHub のみ、一つの会話で開けるのは PR 一件だけ、信頼できる会話でのみ使用可能、ダイレクトメッセージは非対応です。さらに、この旧バージョンは Pro と Max のアカウントにのみ応答し、ワークスペースがすでに Claude Tag に接続されている場合は使えません。Team と Enterprise では Claude Tag を使う必要があります。すでに Claude Tag に接続されたワークスペースでは、旧バージョンの bot は 2026-10-05 以降無効になっています。

Remote Control：スマートフォンからローカルの会話に接続する

これはクラウドセッションとは異なるので、区別してください。Remote Control は、あなたのローカルで実行中の会話に、claude.ai/code またはスマートフォンアプリを通じてリモートで接続するものです。プログラムは引き続きあなたのコンピュータ上で動作し、ファイルやツールもローカルにあるため、ローカルの MCP server もそのまま使えます。

claude remote-control      # standby mode in a local terminal
claude --remote-control    # start an interactive session with it on

会話の中にいる場合は /remote-control と入力します。VS Code では /rc です。接続すると、会話の進行状況はデバイス間で同期され、どのデバイスからでもメッセージを送信できます。ファイルや写真を添付したり、git diff を確認したりすることもできます。切断された場合は自動的に再接続され、その間のメッセージは接続が戻るまでキューに入ります。Bedrock、Vertex AI、Foundry は非対応です。Team と Enterprise では既定で無効になっており、管理者が有効にする必要があります。

Chrome 拡張機能

Chrome 拡張機能（Chrome、Edge、Brave、Arc、Vivaldi、Opera で利用可能。1.0.36 以上が必要）をインストールし、ターミナルで claude --chrome を実行すると、ブラウザを操作できます。クリック、入力、スクリーンショット、console の読み取り、フォーム入力、ファイルアップロード、GIF の録画が可能で、すでにログインしているサイト上での作業もできます。/chrome と入力すると、状態を確認したり、既定で有効にしたりできます。WSL は非対応です。認証には /login を使う必要があり、API キーでの認証は使えません。Bedrock、Vertex、Foundry も非対応です。v2.1.290 からは、プロジェクトの設定ファイル（.claude/settings.json など）によって Chrome を自動的に有効にすることはできなくなりました。--chrome、/chrome、または自分のユーザー設定を使ってください。

対照表

プラットフォーム間で session を移動する方法は次のとおりです。--teleport はクラウドセッションをローカルのターミナルに引き戻して続行しますが、これは一方向です。その後の変更はクラウドに同期されません。--cloud はターミナルから新しいクラウドセッションを開始します。デスクトップアプリの Continue in メニューでは、ローカルのこの会話をクラウドに送れます。VS Code もクラウドセッションを引き戻せますが、同様に、引き戻した後は claude.ai に同期されなくなります。

次のステップ

すべてを導入する必要はありません。最も普段の作業スタイルに近いものを一つ選んでください。一日中 IDE で作業するなら IDE 拡張を入れてください。席を離れることが多いなら、まず Remote Control を試してみてください。ローカルで claude remote-control を実行し、スマートフォンから接続して、動作がスムーズかどうかを確認します。「コンピュータの電源を切りたいが、作業がまだ終わっていない」という場面に実際に遭遇したら、そのときにクラウドセッションを開いてください。

出典：Claude Code 公式ドキュメント〈VS Code〉、〈JetBrains IDEs〉、〈Desktop〉、〈Claude Code on the web〉、〈Remote control〉、〈Claude Code with Chrome〉、〈Computer use〉、〈Slack〉 の各ページの Prerequisites、Get started、Capabilities、Limitations の各節（2026-09-18 確認）、および Claude Code CHANGELOG の 2.1.290（2026-10-06 確認）（2026-10-15 には〈Claude Code in Slack〉を照合して更新。）

settings.json の全体像

前の各章では、さまざまな設定を断片的に紹介してきました。権限は permissions に、hook は hooks に、保持日数は cleanupPeriodDays に書きます。しかし同じ設定を複数のファイルに書けるため、書く場所を間違えると効きません。第7章の auto の例が、ユーザー層に書いたときにのみ有効になるものだったのは、まさにそのためです。

この章では、設定システム全体を広げて見ていきます。どの層があり、どれが他を上書きし、よく使うキーにはどのようなものがあるかを説明します。

五つの層：どれが上書きするか

上から下の順に、上位が下位を上書きします。

環境変数はこの積み重ねには含まれず、キーごとに個別に決まります。たとえば ANTHROPIC_MODEL は設定ファイルの model を上書きしますが、ANTHROPIC_DEFAULT_MODEL は設定ファイルに記載がない場合にのみ有効になります。

ファイルの作られ方

三種類のファイルは、作られ方がそれぞれ異なります。ユーザー設定は、初めて /config を実行したときに作成されます。プロジェクトのローカル設定は、最初に常駐権限を承認したときに自動的に作成され、Claude Code が .gitignore に追加してくれます。プロジェクトの共有設定は、自分で作成します。

形式は厳密な JSON です。// のコメントは書けず、余分なカンマも不可です。$schema の行を一行加えて https://json.schemastore.org/claude-code-settings.json を指定すると、エディタがスペルミスをチェックしてくれます。

よく使うキー

リスト型のキー（permissions.allow など）は、各層で統合されます。上書きではありません。単一の値のキーのみ、上位の層が下位の層を上書きします。この違いは、ルールをどこに書くべきかを決めます。チーム全員が守るべき deny ルールはプロジェクトの共有設定に、個人的な習慣はユーザー設定に書いてください。

設定が効かないとき

ファイルを書き換える前に、まず三つのコマンドで何が起きているかを確認してください。

/config    # open the config UI; also /config verbose=true for one-liners
/status    # shows which settings files were loaded (the Setting sources line)

claude doctor   # find broken or invalid settings files

/status の Setting sources の行が最も役立ちます。今回実際に読み込まれたファイルの一覧が表示されます。効くはずのファイルがその一覧に現れない場合、通常はパスか層の指定が間違っています。JSON の形式が壊れている場合は、claude doctor が指摘してくれます。

三つのファイルの役割

• ~/.claude/settings.json：権限の既定モード、モデルと effort の好み。これらは人に紐づくものです。
• .claude/settings.json：このプロジェクトの hook、deny ルール、全員に統一してほしい設定。バージョン管理に含めます。
• .claude/settings.local.json：このマシンでのみ使うもの（例：ローカルのテスト URL）。バージョン管理には含めません。

次のステップ

今すぐ /status を実行して、Setting sources にどのファイルが挙がっているか、想定と一致するかを確認してください。次に ~/.claude/settings.json を開き、$schema の行を追加してください。以後、タイプミスがあればエディタがその場で指摘します。もし設定を壊してしまった場合は、claude doctor がどこが壊れているかを教えてくれます。

出典：Claude Code 公式ドキュメント〈Settings〉の Settings files and precedence、Find or create your settings files、Use the /config menu の各節、および〈Settings reference〉の各設定キーの説明（2026-09-18 確認）；Claude Code CHANGELOG の 2.1.281、2.1.282（2026-10-02 確認）、2.1.299（2026-10-14 確認）

エンタープライズへの導入とセキュリティ

前章の五層の設定では、最上位の層が管理設定です。個人ではあまり必要になりませんが、企業のお客様向けの案件を担当している場合や、会社が Claude Code をチーム全体に配布する場合には、次のような課題が出てきます。全員に特定のモデルだけを使わせることはできるか。特定のコマンドを禁止できるか。データが外部に流出しないか。

この章では、管理者側の仕組みを整理します。個人のユーザーは、これらの仕組みがあることを知っておけば十分です。

管理設定の置き場所

複数のファイルに分けたい場合は、同じ場所に managed-settings.d/ フォルダを作成し、その中に *.json を置きます。ファイル名の順に統合されます。

配布方法は四種類あり、いつから有効になるかが異なります。ファイルは変更後すぐに有効になります。MDM または OS のポリシー、Windows レジストリは約30分です。claude.ai 管理画面のサーバー側設定は約60分です（起動時に一度読み込まれ、その後は毎時ポーリングされます）。

複数の管理ソースが同時に存在する場合は、managedSourcesBehavior がどう扱うかを決めます。既定は first-wins で、最も優先度の高いソースを使います。merge に設定すると、キーごとに統合されます。単一の値は上位のものが採用され、リストは結合され、ロックは最も厳しいものが採用されます。優先度は高い順に、サーバー側、MDM、managed-settings.json ファイル、Windows HKCU レジストリです。

管理者がロックできるもの

管理ソースからしか設定できず、ユーザーが変更できない設定があります。

• 権限：permissions.deny、allowManagedPermissionRulesOnly、permissions.disableBypassPermissionsMode
• MCP：allowedMcpServers、deniedMcpServers、managedMcpServers、allowManagedMcpServersOnly
• モデル：availableModels、enforceAvailableModels、modelPicker、さらに availableModelsMatch（"exact" に設定すると、availableModels の各項目は記載されたバージョンのみ許可されます。新しいモデルは記載しないと使えません。v2.1.283 から）と deniedModels（availableModels で許可されていても、ブロックされるモデル。v2.1.283 から）
• API プロバイダー：allowedProviders で、このマシンが利用できるプロバイダーを制限します。例：Anthropic API、カスタムエンドポイント、Bedrock、Vertex AI、Foundry、gateway（v2.1.285 から）
• サンドボックス：sandbox.filesystem.allowManagedReadPathsOnly、sandbox.network.allowManagedDomainsOnly
• Plugin と marketplace：blockedMarketplaces、strictKnownMarketplaces、allowManagedHooksOnly、allowedChannelPlugins
• ログインとバージョン：forceLoginMethod、disableSideloadFlags、requiredMinimumVersion、requiredMaximumVersion

実際に最初に設定すべきものは三つです。permissions.deny で絶対に触れてはいけないパスやコマンドを遮断する。disableBypassPermissionsMode で、誰も権限チェックを丸ごと飛ばせないようにする。requiredMinimumVersion で、問題のある古いバージョンに留まる人が出ないようにする。

Bedrock または Vertex を利用する

企業のお客様からよく求められるのは、自社のクラウドアカウントを使うことです。どちらも環境変数で設定します。

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=my-profile
export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'   # pin the version
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-5'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'

Bedrock に必要な IAM 権限は bedrock:InvokeModel、InvokeModelWithResponseStream、ListInferenceProfiles、GetInferenceProfile で、リソースは inference-profile と foundation-model の ARN を指定します。認証は、AWS プロファイル、環境変数、Bedrock API キー、IAM Identity Center SSO の順に確認されます。Vertex の最小権限は roles/aiplatform.user で、認証は Application Default Credentials、gcloud の設定、またはサービスアカウントキーを使います。

モデルのバージョンを固定するのは意図的です。エイリアスはプラットフォーム側で更新されるため、固定しておかないと、ある朝突然全員の挙動が変わってしまうおそれがあります。

前の各章で紹介した機能の中には、この二つのプラットフォームでは使えないものがあります。計画する前に確認してください。fast mode、Remote Control、Chrome 拡張機能、channels は、Bedrock、Vertex、Foundry のいずれでも利用できません。

セキュリティに関する仕組み

• /security-review：現在のブランチに対して安全性チェックを実行し、安全でない書き方を見つけます。
• /sandbox：Bash のサンドボックスの境界を設定します。ファイルシステムは既定で作業ディレクトリに、ネットワークは特定のドメインに制限されます。管理ソースからこれらを固定することもできます。
• /permissions：現在有効な権限ルールを確認・編集します。
• claude doctor：設定ファイルの問題を診断します。
• cleanupPeriodDays：ローカルのトランスクリプトを何日間保持するかを決めます。クラウドセッションは隔離された仮想マシンで実行され、認証には短期間のスコープ付きトークンが使われます。

認証情報、SOC 2、ISO 27001 などのコンプライアンス文書は、Anthropic の Trust Center（https://trust.anthropic.com）にあります。お客様から資料を求められた場合は、このリンクを直接渡すのが最も早いです。

次のステップ

会社への導入を担当している場合は、まず一台のマシンに managed-settings.json を配置し、次の三つだけを記載してください。permissions.deny の禁止リスト、disableBypassPermissionsMode、requiredMinimumVersion。/status で Setting sources に表示されることを確認してから、他のメンバーに配布してください。個人ユーザーの場合、この章で覚えておくべきことは一つだけです。会社支給のコンピュータでは、設定を変更しても効かないものがあります。まず /status を確認し、それから IT 部門に相談してください。

出典：Claude Code 公式ドキュメント〈Managed settings〉の Where each mechanism stores the policy、Choose a delivery mechanism、Keys only a managed source can set、How Claude Code combines managed sources の各節、〈Security〉の Privacy safeguards の各節、〈Amazon Bedrock〉と〈Google Vertex AI〉の Configure Claude Code の各節（2026-09-18 確認）；Claude Code CHANGELOG の 2.1.283、2.1.285（2026-10-02 確認）