Agent SDK で Claude Code 機能を使う：settingSources と CLAUDE.md

Claude Agent SDK は Claude Code と同じ土台の上に作られているので、SDK で作るエージェントからも、Claude Code と同じファイルベースの機能（プロジェクトの指示を書いた CLAUDE.md とルール、スキル、フックなど）を使えます。どの設定ファイルを読み込むかを決めるのが settingSources オプションです。この記事では公式ドキュメント「Use Claude Code features in the SDK」に沿って、読み込み元の選び方、settingSources に関係なく読まれる入力、CLAUDE.md・スキル・フックの扱い、目的に応じた機能の選び方を整理します。

settingSources で読み込む設定を選ぶ

settingSources を省略すると、query() は Claude Code CLI と同じファイルシステム上の設定を読みます。ユーザー・プロジェクト・ローカルの各設定、CLAUDE.md、.claude/ 配下のスキル・エージェント・コマンドです。省略は ["user", "project", "local"] を渡すのと同じ意味になります。逆にこれらを使わず、コードで渡した設定だけで動かしたいときは settingSources: [] を渡します。オプション名は TypeScript では settingSources、Python では setting_sources です。

次の例は、ユーザーとプロジェクトの設定だけを読み込みます。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me refactor the auth module",
  options: {
    // "user" は ~/.claude/、"project" は cwd の ./.claude/ から読む
    settingSources: ["user", "project"],
    allowedTools: ["Read", "Edit", "Bash"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio


async def main():
    async for message in query(
        prompt="Help me refactor the auth module",
        options=ClaudeAgentOptions(
            setting_sources=["user", "project"],
            allowed_tools=["Read", "Edit", "Bash"],
        ),
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

それぞれの読み込み元と場所は次のとおりです。<cwd> は cwd オプションで渡した作業ディレクトリ（未指定ならプロセスのカレントディレクトリ）です。

注意点として、プロジェクトの settings.json は <cwd>/.claude/ からだけ読まれ、親ディレクトリへはさかのぼりません。additionalDirectories の各項目は Claude Code に --add-dir として渡されるので、"project" を含めていれば、そのディレクトリのスキル・コマンド・サブエージェントも読み込まれます。

settingSources で制御できない入力

settingSources が扱うのはユーザー・プロジェクト・ローカルの3つだけで、次の入力は値に関係なく読まれます。

このため公式は、マルチテナントの隔離を query() の既定に頼らないよう警告しています。SDK のプロセスがホスト側の設定やディレクトリごとのメモリを拾ってしまうからです。マルチテナント構成では、テナントごとに別のファイルシステムで動かし、settingSources: [] と env の CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 を指定します。サーバー管理設定はファイルシステムを分けても取得される点にも注意が必要です（隔離の考え方は「Agent SDK の安全なデプロイ」参照）。

CLAUDE.md とルールの読み込み

CLAUDE.md と .claude/rules/*.md は、コーディング規約・ビルドコマンド・設計方針などプロジェクトの前提をエージェントに渡すファイルです。settingSources に "project" が入っていれば、セッション開始時に読み込まれ、毎回プロンプトで繰り返さなくても規約に沿って動きます。

どのレベルも足し合わせで、プロジェクトとユーザーの両方に CLAUDE.md があればエージェントは両方を見ます。レベル間に厳密な優先順位は無く、指示が食い違ったときの結果は Claude の解釈次第です。矛盾しないルールを書くか、より具体的なファイルに「このプロジェクトの指示はユーザー既定より優先する」のように明記するよう勧められています。CLAUDE.md を使わず systemPrompt で直接文脈を渡すこともでき（「Agent SDK のシステムプロンプト設定」参照）、対話の Claude Code と SDK エージェントで同じ文脈を共有したいときに CLAUDE.md が向いています。書き方は「CLAUDE.md でプロジェクトを覚えさせる」で扱っています。

スキルとフックを使う

スキルは、専門知識や呼び出せるワークフローを Markdown で渡す仕組みです。毎回読まれる CLAUDE.md と違い、起動時には説明だけが渡され、関係するときに本文が読み込まれます。スキルは settingSources を通じてファイルシステムから見つけられ、query() の skills オプションを省略すると、見つかったユーザー・プロジェクトのスキルが有効になり Skill ツールも使えます（CLI と同じ挙動）。絞りたいときは skills に "all"、スキル名のリスト、または全部無効にする [] を渡します。skills を指定すると SDK が Skill ツールを allowedTools に自動で加えますが、tools を明示的に渡す場合はそこに "Skill" を含める必要があります。

for await (const message of query({
  prompt: "Review this PR using our code review checklist",
  options: {
    settingSources: ["user", "project"],
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

スキルは .claude/skills/<name>/SKILL.md としてファイルで作る必要があり、SDK にはスキルをコードから登録する API はありません（詳しくは「Agent SDK のスキルとスラッシュコマンド」参照）。

フックは2通りで定義でき、両方が並んで動きます。

• ファイルシステムのフック: settings.json に書くフックで、該当する読み込み元が settingSources に入っていれば読まれます。対話の Claude Code で設定するフックと同じもので、"command"（シェル）・"http"（エンドポイントへ POST）・"mcp_tool"（接続済み MCP サーバーのツール）・"prompt"（LLM がプロンプトを評価）・"agent"（検証用エージェントを起動）を使えます。メインのエージェントとそこから起動したサブエージェントの両方で発火します。CLI と SDK でフックを共有したいときに向いています。
• プログラムのフック: query() に直接渡すコールバック関数で、アプリのプロセス内で動き、構造化された判断を返せます。サブエージェント内でも発火し、入力に含まれる agent_id と agent_type でどのエージェントが発火させたかを判別できます。アプリ固有のロジックに向いています。

コールバックが {} を返すとツールはそのまま実行され、止めたいときは hookSpecificOutput に permissionDecision: "deny" と permissionDecisionReason を入れて返します。理由はツールの結果として Claude に渡ります。

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher


async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Destructive command blocked",
            }
        }
    return {}  # 空の dict はツールの実行を許可


options = ClaudeAgentOptions(
    setting_sources=["project"],  # .claude/settings.json のフックも読む
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[audit_bash])]},
)

なお TypeScript SDK は Python より多くのフックイベント（SessionStart・SessionEnd・TeammateIdle・TaskCompleted など）に対応しています。コールバックの詳細は「Agent SDK のフック」を参照してください。

目的に合う機能を選ぶ

エージェントの振る舞いを広げる方法はいくつもあります。公式の対応表を日本語にすると次のとおりです。

有効にした機能はどれもコンテキストウィンドウを消費します。必要なものだけを読み込むよう settingSources と skills を絞るのが基本です。サブエージェントは「Agent SDK のサブエージェント」、MCP は「Agent SDK で MCP を使う」で扱っています。

本ページは Use Claude Code features in the SDK を中心に、Agent SDK reference - TypeScript のオプション説明（settingSources・skills・additionalDirectories）と照合した非公式の日本語解説です（確認日 2026-10-31）。最新の仕様は公式ドキュメントを確認してください。