Claude Media
Agent SDK settingSources — Claude Codeの機能をどこまで制御できるか
Agent SDKClaude Code解説

Agent SDK settingSources — Claude Codeの機能をどこまで制御できるか

Agent SDKのsettingSourcesが制御するCLAUDE.md・Skills・Hooksの範囲と、制御が及ばない5つの入力を表で整理しています。

読了目安 約10分

Agent SDKがClaude Code機能を使える理由

Agent SDKはClaude Codeと同じ基盤の上に作られています。そのため、CLAUDE.mdによるプロジェクト指示・Skills・Hooksといったファイルシステム由来の機能を、SDKのセッションでもそのまま使えます。settingSourcesを省略すると、query()はClaude Code CLIと同じくユーザー設定・プロジェクト設定・ローカル設定を読み込みます。プログラムから何も設定しなくても、CLIで動いていた設定がSDKでもそのまま動く設計です。

裏を返すと、settingSourcesはこのファイルシステム読み込みそのものを止めるスイッチでもあります。settingSources: []を渡すと、プログラムで明示的に設定した内容だけがセッションに反映されます。マルチテナントでホスト側の設定を持ち込みたくない用途では、この止め方が起点になります。SDKでエージェントを最小構成から組み立てる手順はClaude Agent SDK入門にまとまっています。

settingSourcesが制御する3つのソース

settingSources(Pythonはsetting_sources)は、"project" / "user" / "local"という3つの文字列の配列で指定します。<cwd>はcwdオプションで渡した作業ディレクトリ、省略時はプロセスのカレントディレクトリです。

ソース読み込む内容場所
"project"読み込む内容プロジェクトのsettings.jsonとhooks、CLAUDE.mdと.claude/rules/*.md、skills・commands・subagents場所<cwd>/.claude/が基点
"user"読み込む内容ユーザーのsettings.json、CLAUDE.mdと~/.claude/rules/*.md、skills・commands・subagents場所~/.claude/配下
"local"読み込む内容CLAUDE.local.md、.claude/settings.local.json場所<cwd>/.claude/が基点

「場所」の探索範囲は入力の種類ごとに違います。settings.jsonとhooksは<cwd>/.claude/のみが対象で、親ディレクトリへのフォールバックはありません。CLAUDE.mdとrulesは<cwd>と各親ディレクトリを、skills・commands・subagentsは<cwd>からリポジトリルートまでの各ディレクトリとadditionalDirectories(add_dirs)で渡したディレクトリの.claude/配下を探索します。CLAUDE.local.mdも<cwd>と各親ディレクトリが対象で、settings.local.jsonだけは<cwd>/.claude/のみです。

settingSourcesを省略した場合の既定値は["user", "project", "local"]です。3つとも指定したのと同じ状態からセッションが始まります。

CLAUDE.mdはレベルごとに読み込みタイミングが違う

CLAUDE.mdは"project" / "local" / "user"のどれを含むかで、置き場所と読み込まれるタイミングが変わります。プロジェクトルートのCLAUDE.mdは"project"が含まれていればセッション開始時に読み込まれ、cwdより上の親ディレクトリにあるCLAUDE.mdも同じタイミングで読み込まれます。一方、cwdより下のサブディレクトリにあるCLAUDE.mdは、エージェントがそのサブツリー内のファイルを実際に読みに行ったときに初めて読み込まれます。

CLAUDE.local.mdは"local"が含まれているときだけ、~/.claude/CLAUDE.mdは"user"が含まれているときだけ読み込まれます。すべてのレベルは足し算で扱われ、プロジェクトとユーザーの両方にCLAUDE.mdがあれば両方とも見えます。優先順位を決めるハードルールは無いため、内容が矛盾するときの挙動はClaudeの解釈次第です。矛盾を避けるか、より具体的なファイル側に「プロジェクトの指示はユーザー側の既定値より優先する」のように明記しておきます。何も書かずに矛盾したまま両方読み込ませると、実行のたびに結果が変わり得ます。チームで複数人がCLAUDE.mdを触るプロジェクトほど、この明記を後回しにするとハマりやすい部分です。

CLAUDE.mdの実践的な書き方はClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンにまとまっています。

SkillsとHooksへの影響

SkillsはsettingSourcesが"project"または"user"を含んでいるときだけファイルシステムから発見されます。skillsオプションで呼び出せる範囲を絞る前に、まずこの発見条件を満たしている必要があります。両方とも外した状態でskills: "all"を渡しても、発見されるSkillsが0件なので許可リストの効果自体が発生しません。

Hooksは2経路が並走します。プロジェクトの.claude/settings.jsonに書いたシェルコマンド形式のfilesystem hooksと、query()に直接渡すプログラム形式のhooksコールバックです。settingSourcesにそのソースが含まれていればfilesystem hooksは自動的に読み込まれ、コールバック側と同じライフサイクルで両方とも実行されます。すでにプロジェクトの.claude/settings.jsonにhooksがあり、settingSources: ["project"]を渡しているなら、追加の設定なしでSDKセッションでもそのhooksが動きます。

filesystem hooksが対応する5形式は次の通りです。

形式内容
"command"内容シェルスクリプトの実行
"http"内容エンドポイントへのPOST
"mcp_tool"内容接続済みMCPサーバーのツール呼び出し
"prompt"内容LLMによる評価
"agent"内容検証用エージェントの起動

filesystem hooksはメインエージェントとそこから派生したsubagentsの両方で発火します。設定と実用パターンはClaude Code Hooks完全ガイドが詳しく扱っています。

settingSourcesが制御しない5つの入力

ここが公式ドキュメントで最も見落としやすい部分です。settingSourcesはユーザー・プロジェクト・ローカルの3ソースだけを制御し、それ以外の入力は値に関わらず読み込まれます。

入力挙動止める方法
Managed policy設定挙動組織のOAuthログイン・APIキー認証セッションでホストから取得される止める方法SDK側から無効化できない
~/.claude.jsonのグローバル設定挙動常に読み込まれる止める方法envのCLAUDE_CONFIG_DIRで置き場所を変更
自動メモリー(~/.claude/projects/<project>/memory/)挙動セッション開始時にシステムプロンプトへ読み込まれる止める方法autoMemoryEnabled: falseまたはCLAUDE_CODE_DISABLE_AUTO_MEMORY=1
claude.aiのMCPコネクタ挙動claude.aiログインのセッションで読み込まれる止める方法strictMcpConfig: trueまたはdisableClaudeAiConnectors: true
サンドボックスの認証情報を守る設定挙動sandbox.credentialsのdeny・credentials.filesのmaskは除外指定でも適用される止める方法~/.claude/settings.jsonから該当エントリを削除

各項目の補足です。Managed policy設定はMDMのplist・レジストリポリシー・管理設定ファイルなど、エンドポイント側で管理されたポリシーを指し、組織側の設定である以上SDK側からは触れません。自動メモリーはWrite・Editという標準ツールで書き込まれるため、これらのツールを有効にしている限り新しいメモリーが増え続けます。claude.aiのMCPコネクタはclaude setup-tokenで発行した長期トークンでは読み込まれず、mcpServers: {}を渡しても抑制されません。サンドボックスの認証情報を守る設定は、コマンドサンドボックスが動くときにsettingSourcesがユーザー設定を除外していても制限としてそのまま適用されます。

settingSources: []を渡しても、この5つは値に関わらず読み込まれます。ホストのファイルシステムから完全に切り離されたセッションを作りたいときは、この一覧を「別枠」として意識しておく必要があります。

マルチテナント運用でsettingSourcesだけに頼らない

複数のテナントを1つのプロセス群で扱うデプロイでは、settingSourcesのデフォルト値をそのまま使わないことが公式ドキュメントで明示されています。理由は単純で、上の5つの入力はホスト単位・組織単位で共有されるため、テナントごとにディレクトリを分けたつもりでも、ホストレベルの設定やプロジェクトごとの自動メモリーが混ざり込む余地が残るからです。

具体的に何が起きうるかを考えると分かりやすくなります。テナントAとテナントBを同じホスト上の別プロセスで動かしていて、settingSourcesをデフォルトのまま使っていたとします。ホストの~/.claude/projects/<project>/memory/にテナントAのセッションが書き込んだ自動メモリーは、同じプロジェクトディレクトリを使う別セッションの起動時にシステムプロンプトへそのまま読み込まれます。ディレクトリの持ち方次第では、意図せずテナント間で情報が持ち越される経路になります。

推奨される構成は、テナントごとに独立したファイルシステムでプロセスを分け、settingSources: []とenvのCLAUDE_CODE_DISABLE_AUTO_MEMORY=1を組み合わせることです。

const options = {
  settingSources: [], // ユーザー・プロジェクト・ローカル設定を読み込まない
  env: {
    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1" // 自動メモリーへの書き込みも止める
  }
};

この2つを組み合わせても、テナントの認証情報が組織のOAuthログインなら、サーバー管理設定は別途取得されます。ファイルシステムを分離するだけでは組織側のポリシーまでは切り離せません。これは設定漏れというより、ポリシーの適用範囲がプロセスの外側にある以上、SDK単体では制御しきれない領域だと捉えたほうが正確です。セッション・ハーネス・サンドボックスをどう分離するかという設計論はManaged Agentsの設計思想でも扱っています。

機能ごとに何を使うか

CLAUDE.md・Skills・Subagents・Hooks・MCPはどれも「Claudeの挙動を拡張する」点で似ていますが、向いている用途は分かれます。

やりたいこと使う機能SDK側の設定
エージェントが常に守る規約を設定する使う機能CLAUDE.mdSDK側の設定settingSourcesに"project"を含めれば自動で読み込む
関連するときだけ読み込む参考資料を持たせる使う機能SkillsSDK側の設定settingSources + skillsオプション
再利用可能なワークフロー(デプロイ・レビュー等)を用意する使う機能ユーザー起動SkillsSDK側の設定settingSources + skillsオプション
独立したサブタスクを新しいコンテキストに切り出す使う機能SubagentsSDK側の設定agentsパラメータ + allowedTools: ["Agent"]
ツール呼び出しに決定的なロジックを挟む(監査・遮断・変換)使う機能HooksSDK側の設定hooksパラメータのコールバック、またはsettingSources経由のシェルスクリプト
外部サービスへの構造化されたツールアクセスを与える使う機能MCPSDK側の設定mcpServersパラメータ

有効にした機能はどれもコンテキストウィンドウを消費します。CLAUDE.mdは毎セッション読み込まれるのに対し、Skillsは使われたときだけ本文が展開されるため、コンテキストコストの効き方が異なります。すべてのプロジェクト規約をCLAUDE.mdに詰め込むと、使われない情報まで毎回コンテキストへ乗ってしまいます。頻繁に参照する短い規約はCLAUDE.mdに、たまにしか使わない長い手順書はSkillsに振り分けると、同じ情報量でもコンテキストの消費を抑えられます。

この判断はsettingSourcesの設計そのものにも波及します。CLAUDE.mdとSkillsの両方を"project"ソースに頼っている構成では、settingSourcesを絞る操作が両方に同時に効きます。片方だけを止めたい場合、settingSourcesのオンオフではなく、CLAUDE.mdの記述量そのものを削るか、Skillsをskillsオプション側で個別に絞るほうが的確です。

よくある質問

settingSourcesを指定しないとどうなりますか

["user", "project", "local"]を指定したのと同じです。Claude Code CLIと同じ設定源からすべて読み込まれます。

組織のサーバー管理設定はsettingSources: []で止まりますか

止まりません。組織のOAuthログインや直接設定したAPIキーでセッションが認証されていれば、対応するサーバー管理設定はsettingSourcesの値に関わらず取得されます。

プロジェクトのsettings.jsonは親ディレクトリからも読み込まれますか

読み込まれません。プロジェクトのsettings.jsonとhooksは<cwd>/.claude/だけが対象で、親ディレクトリへのフォールバックはありません。CLAUDE.mdやSkillsのような親ディレクトリ探索とは扱いが違います。

Agent teamsもsettingSourcesで制御しますか

しません。複数のClaude Codeインスタンスがタスクリストを共有しながら連携するAgent teamsは、SDKのオプションで直接構成する機能ではなく、1つのセッションがチームリードとして振る舞うCLI側の機能です。

settingSourcesとsystemPromptはどう使い分けますか

用途が異なります。CLIとSDKの両方で同じ指示を共有したいならCLAUDE.md経由のsettingSourcesが向き、SDKのアプリケーションだけに閉じた指示を注入したいならsystemPromptでCLAUDE.mdを介さずに直接渡す方法が向きます。両方を併用しても構いません。

まとめ

settingSourcesはCLAUDE.md・Skills・Hooksの一部・プロジェクトとユーザーのsettings.jsonという3ソースの読み込みを制御しますが、managed policy設定・グローバル設定・自動メモリー・claude.aiのMCPコネクタ・サンドボックスの認証情報を守る設定という5つはこの制御の外にあります。ホストの設定から隔離したセッションを作るときは、settingSourcesだけで完結すると考えず、この5つの入力を個別に止める必要があるかどうかを確認します。

この記事を共有:XはてブLinkedIn

関連する記事

Agent SDK をもっと見る →