Claude Code 設定ガイド【2026年最新】settings.json・CLAUDE.md・サブエージェント

Claude Code の settings.json、CLAUDE.md、permissions、モデル・環境変数、カスタムサブエージェントの使い分けと設定例を、公式資料に沿って解説します。

はじめに

Claude Code の設定は、ひとつのファイルにすべて書くものではありません。実行時の設定、プロジェクトに伝える指示、操作ごとの権限、特定の仕事を任せるサブエージェントを分けると、どこを直せばよいかが見えやすくなります。

本稿では、settings.json、CLAUDE.md、permissions、モデルと環境変数、カスタムサブエージェントを一続きの設定ガイドとして整理します。機能や設定名は2026年9月23日に公式資料で確認しています。

1. 最初に設定の役割を分けましょう

Claude Code の設定を整えるときは、まず次の役割を分けるのが近道です。

settings.json の設定はクライアント側で適用されます。CLAUDE.md はモデルに渡す指示であり、書かれた内容を強制する権限設定ではありません。ファイルに「秘密を読まない」と書くだけで制限したい場合は、CLAUDE.md ではなく permissions などの設定を使います。

公式のsettings.json と優先順位、プロジェクトの記憶と CLAUDE.md、権限設定を、役割ごとに確認してください。

2. settings.json はどこに置けばよいですか？

settings.json は、設定を誰と共有するかで置き場所を選びます。

たとえば、チーム全員に同じ権限ルールを適用するなら、プロジェクト用の設定が候補になります。自分だけが使う API 接続情報や個人の表示設定をリポジトリに含めたくない場合は、個人用またはローカル用の設定を選びます。API キーは設定ファイルに直接書かず、環境変数から読み込んでください。

ターミナル内の /config は、テーマやエディターなど一部の個人設定を変更するメニューです。設定キーをすべて列挙する画面ではないため、権限や環境変数などは設定ファイルで管理する場面があります。保存後に /status を実行すると、読み込まれた設定ソースを確かめられます。

settings.json は厳密な JSON です。コメントや末尾のカンマを入れると設定エラーになります。変更時は既存の JSON 構文も確認してください。

小さな例から始める

次の例は個人設定ファイルに置く最小構成です。テストコマンドは自分のプロジェクトで実際に使うものへ置き換えてください。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

コマンドのパターンを広げるほど、許可される操作も広がります。まずは繰り返し使う読み取りやテストだけを許可し、削除、公開、外部への送信などは個別に判断できる状態にしておくと、設定の意図を追いやすくなります。

3. CLAUDE.md と settings.json はどう使い分けますか？

CLAUDE.md は、Claude Code の各セッションに読み込ませたいプロジェクト指示を書く Markdown ファイルです。たとえば、テストの実行方法、主要なモジュール、レビュー時の確認項目、変更してはいけない領域などを記録できます。

一方、CLAUDE.md の内容はモデルに渡されるコンテキストです。モデルが必ず従うようにクライアントが強制する設定ではありません。機械的に拒否したい操作は permissions に置き、作業方針や判断材料は CLAUDE.md に書く、という分担が基本です。

プロジェクト全体で共有する指示はリポジトリの CLAUDE.md、個人の好みはユーザー領域の CLAUDE.md に置く方法があります。サブディレクトリごとの補足が必要なら、そのディレクトリに追加の指示ファイルやルールを置くこともできます。全員に必要な内容と、個人の手元だけに必要な内容を同じファイルへ混ぜないようにしましょう。

CLAUDE.md に書くと役立つ項目

• よく使う開発・テストコマンド
• 変更前に読む必要がある設計資料
• コードの置き場所と責務
• 変更時に守る命名・形式ルール
• 過去に繰り返し起きた間違いと、その確認方法

細かい実装を長く貼り付けるより、「どのファイルを確認するか」「何を実行するか」「完了をどう判断するか」を短く書くと、指示の目的を保ちやすくなります。CLAUDE.md の構造と読み込み範囲は公式ガイドを参照してください。

4. permissions の allow・ask・deny はどう決めますか？

permissions は、Claude Code がツールやコマンドを実行する際に、許可、確認、拒否を設定する仕組みです。ルールは deny、ask、allow の順で評価されます。許可ルールを追加すれば拒否ルールの例外になる、という関係ではありません。

例として、テストと lint は確認なしで実行できるようにし、作業ディレクトリ直下の .env と .env.* は Read ツールで読めないようにします。この範囲指定は Bash などのコマンド実行を止めるものではありません。権限はツールごとに設定し、実際のルールと範囲は公式の権限ルールで確認してください。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

allow を広く指定すると、意図しない引数まで許可することがあります。最初は完全一致のコマンドを少数だけ許可し、同じ操作を何度も使うことが分かってから必要な範囲へ広げる方法が確認しやすいでしょう。

また、CLAUDE.md に「push はしない」と書く方法と、permissions で push を確認対象にする方法は役割が異なります。前者は指示、後者は実行時のルールです。安全上の境界に関わる操作は、文章だけに頼らず該当する権限設定も確認してください。

5. モデルと環境変数はどこで設定しますか？

通常のモデル選択は、セッション中の /model、設定ファイルの model キー、起動時の --model などから行えます。環境変数にも設定キーと対応するものがあります。具体的な優先順位は設定項目によって異なるため、「環境変数が常に最優先」と決めつけず、設定項目ごとの公式リファレンスを見てください。

環境変数は、そのシェルから起動するプロセスへ値を渡すのに便利です。API キーを共有リポジトリの settings.json や CLAUDE.md に書かず、OS の環境変数、秘密管理機能、または信頼できるシェル設定から渡します。ログや画面共有へキーを貼らないでください。

export ANTHROPIC_MODEL="sonnet"
claude

Windows PowerShell では、現在のシェルに環境変数を設定してから起動できます。

$env:ANTHROPIC_MODEL = "sonnet"
claude

モデル名は利用中のアカウントや接続先で異なる場合があります。例の値をそのまま固定せず、利用可能なモデル一覧と Claude Code の公式設定資料を照合してください。

6. サブエージェントはどんなときに使いますか？

サブエージェントは、調査、レビュー、または特定の作業を独立した役割へ切り分けるときに使います。たとえば、メインの Claude Code に実装を依頼し、別のサブエージェントには変更差分を読み取り専用で確認させる使い方があります。

カスタムサブエージェントは Markdown ファイルで定義し、YAML frontmatter に名前、説明、使えるツール、モデルなどを記述します。プロジェクト内で共有するなら .claude/agents/、自分の全プロジェクトで使うなら ~/.claude/agents/ に置くのが基本です。詳しくは公式のカスタムサブエージェントガイドを参照してください。

次の例は、ファイルの読み取りと検索に限定したレビュー担当です。

---
name: review
description: 変更の影響と見落としを読み取り専用で確認する
tools: Read, Grep, Glob
model: sonnet
---

変更内容を確認し、問題があればファイル名と理由を簡潔に報告してください。
ファイルを編集したり、コマンドを実行したりしないでください。

サブエージェントの指示には、メインの会話を見なくても分かる目的、対象範囲、完了条件を書きます。「さっきの内容を見て」のようにメインの会話へ依存する指示ではなく、必要な前提を依頼文に含めてください。ツールを絞ると、任せる仕事の境界も読み取りやすくなります。

サブエージェントはメインの会話とは別のコンテキストで仕事を行い、完了時に結果を親へ返します。説明に合う作業は Claude Code が委譲先を選ぶことがあります。特定の担当を指名するには、入力中に @ を入力して候補から選ぶか、@agent-<name> の形式で名前を指定します。ここでは name: review と定義しているため、@agent-review と入力します。セッション全体をサブエージェントの役割で起動する場合は、次のように --agent を使います。

@agent-review 変更を読み取り専用で確認してください
claude --agent review

すべての作業を常に並列化するものではありません。小さく独立して確認できる仕事に限定し、複数の作業が同じファイルや結果に依存する場合は順番を考えてください。

7. サブエージェントと Agent Teams は同じですか？

同じではありません。サブエージェントは、ひとつの Claude Code セッションの中で、調査やレビューなどの個別タスクを引き受ける仕組みです。Agent Teams は複数の Claude Code セッションがチームとして作業する仕組みで、メンバー間のメッセージや共有タスク一覧を使います。

Agent Teams は公式資料で experimental と案内されている機能です。利用可否や制限は変わり得ます。現行の the model maker 資料では環境変数による有効化手順が記載されていますが、手元のバージョンと組織設定も確認してから使ってください。公式資料では、Agent Teams は単一セッションより多くの tokens を使う場合があると案内されています。独立した複数セッション間の協調が必要な場合に限り、導入前に現在の制限と組織設定を確認してください。

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

チーム構成が必要な理由がなければ、まず単一セッションとサブエージェントで目的を果たせるかを試すと、設定やタスク分担を増やさずに済みます。

8. BazaarLink の従量 API を使う場合はどう設定しますか？

Claude Code のアカウント課金とは別に、API キーで従量利用する方法があります。BazaarLink を接続先にする場合、Claude Code の API base URL は https://api.bazaarlink.ai/v1 です。API キーは環境変数 ANTHROPIC_AUTH_TOKEN から渡し、以下の例ではキー本体をファイルへ書きません。

export ANTHROPIC_BASE_URL="https://api.bazaarlink.ai/v1"
export ANTHROPIC_AUTH_TOKEN="$BAZAARLINK_API_KEY"
claude

Windows PowerShell では同じ環境変数を設定してから Claude Code を起動します。

$env:ANTHROPIC_BASE_URL = "https://api.bazaarlink.ai/v1"
$env:ANTHROPIC_AUTH_TOKEN = $env:BAZAARLINK_API_KEY
claude

API では入力と出力のトークン量、選ぶモデル、処理内容に応じて費用が決まります。2026年9月23日にBazaarLink のモデル一覧で確認した例は次の通りです。

料金や提供モデルは変わることがあるため、設定する前にリンク先で現在の値を確認してください。API 従量課金は Claude の月額プランとは別の支払い経路です。どちらを選ぶかの考え方はClaude Code の料金ガイドとサブスクと従量課金 API の比較にまとめています。

別のローカルエージェントへ API endpoint を設定する例は、OpenClaw 入門とHermes Agent 入門も参照できます。

9. 設定が反映されないときは何を確認しますか？

設定が想定どおりに動かない場合は、次の順で確認すると原因を絞れます。

1. claude の起動元ディレクトリと、対象の設定ファイルの場所を確認します。
2. settings.json にコメントや末尾のカンマがないか検証します。
3. /status で読み込まれた設定ソースを確認します。
4. /config で変更した設定がどこへ保存されたかを確認します。
5. モデルや環境変数は、使用中のアカウント・接続先・設定項目の優先順位を確認します。
6. permissions はより高いスコープや拒否ルールが許可ルールに優先していないか確認します。
7. 共有設定と個人設定を混ぜていないか、バージョン管理対象を確認します。

設定を一度にたくさん変えると、どの変更が原因か分かりにくくなります。キーを一つずつ変更し、/status と実際の動作を確かめながら進めてください。

まとめ

Claude Code の設定は、settings.json で実行時の設定、CLAUDE.md でプロジェクトの指示、permissions で操作ルール、サブエージェントで役割分担を管理します。CLAUDE.md を権限の代わりに使わず、設定のスコープと共有範囲を決めてから内容を足すことが大切です。

まずは settings.json の読み込み状況を /status で確認し、必要な指示だけを CLAUDE.md に整理し、繰り返し発生する安全な作業に限って permissions の許可を追加してください。サブエージェントは目的が明確で、メイン作業から切り離せる範囲から試せます。

公式資料（2026-09-23確認）

• Create custom subagents
• Orchestrate teams of Claude Code sessions
• Settings files and precedence
• How Claude remembers your project
• Configure permissions
• Model configuration

台湾ドル決済・統一発票・主要 AI モデル・OpenAI 互換 API