ใช้งาน Claude Code Features ใน SDK

โหลด project instructions, skills, hooks และ Claude Code features อื่นๆ ลงใน SDK agents ของคุณ

Agent SDK ถูกสร้างบนพื้นฐานเดียวกับ Claude Code ซึ่งหมายความว่า SDK agents ของคุณสามารถเข้าถึง features เดียวกับ filesystem-based features ได้: project instructions (CLAUDE.md และ rules), skills, hooks และอื่นๆ

เมื่อคุณละเว้น settingSources, query() จะอ่าน filesystem settings เดียวกับ Claude Code CLI: user, project และ local settings, CLAUDE.md files และ .claude/ skills, agents และ commands เพื่อรันโดยไม่มีสิ่งเหล่านี้ ให้ส่ง settingSources: [] ซึ่งจะจำกัด agent ไปยังสิ่งที่คุณกำหนดค่าด้วยโปรแกรม

ควบคุม Filesystem Settings ด้วย settingSources

ตัวเลือก setting sources (setting_sources ใน Python, settingSources ใน TypeScript) ควบคุมว่า SDK จะโหลด filesystem-based settings ใด ส่งรายการชัดเจนเพื่อเลือกเข้าร่วม sources เฉพาะ หรือส่ง array ว่างเพื่อปิดใช้งาน user, project และ local settings

ตัวอย่างนี้โหลดทั้ง user-level และ project-level settings:

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

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, AssistantMessage):
        for block in message.content:
            if hasattr(block, "text"):
                print(block.text)
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(f"\nResult: {message.result}")

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

for await (const message of query({
  prompt: "Help me refactor the auth module",
  options: {
    settingSources: ["user", "project"],
    allowedTools: ["Read", "Edit", "Bash"]
  }
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") console.log(block.text);
    }
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log(`\nResult: ${message.result}`);
  }
}

แต่ละ source จะโหลด settings จากตำแหน่งเฉพาะ โดยที่ <cwd> คือ working directory ที่คุณส่งผ่านตัวเลือก cwd:

Source	สิ่งที่โหลด	ตำแหน่ง
"project"	Project CLAUDE.md, .claude/rules/*.md, project skills, project hooks, project settings.json	<cwd>/.claude/ สำหรับ settings.json และ hooks; <cwd> และทุก parent directory สำหรับ CLAUDE.md
"user"	User CLAUDE.md, ~/.claude/rules/*.md, user skills, user settings	~/.claude/
"local"	CLAUDE.local.md, .claude/settings.local.json	<cwd>/.claude/ สำหรับ settings.local.json

การละเว้น settingSources เทียบเท่ากับ ["user", "project", "local"]

สิ่งที่ settingSources ไม่ควบคุม

settingSources ครอบคลุม user, project และ local settings inputs บางส่วนจะถูกอ่านโดยไม่คำนึงถึงค่าของมัน:

Input	พฤติกรรม	วิธีปิดใช้งาน
Managed policy settings	โหลดเสมอเมื่อมีอยู่บน host	ลบไฟล์ managed settings
~/.claude.json global config	อ่านเสมอ	ย้ายด้วย CLAUDE_CONFIG_DIR ใน env
Auto memory ที่ ~/.claude/projects/<project>/memory/	โหลดเป็นค่าเริ่มต้นใน system prompt	ตั้ง autoMemoryEnabled: false ใน settings หรือ CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 ใน env

warning

อย่าพึ่งพาตัวเลือก query() เริ่มต้นสำหรับการแยกระบบ multi-tenant เนื่องจาก inputs ข้างต้นถูกอ่านโดยไม่คำนึงถึง settingSources SDK process สามารถรับ host-level configuration และ per-directory memory ได้ สำหรับการ deploy แบบ multi-tenant ให้รันแต่ละ tenant ใน filesystem ของตัวเองและตั้ง settingSources: [] บวก CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 ใน env

Project Instructions (CLAUDE.md และ Rules)

CLAUDE.md files และ .claude/rules/*.md files ให้ agent บริบทโปรเจกต์แบบถาวร: แบบแผนการเขียนโค้ด, คำสั่ง build, การตัดสินใจด้านสถาปัตยกรรม และคำแนะนำ เมื่อ settingSources มี "project" SDK จะโหลด files เหล่านี้เข้าสู่บริบทเมื่อเริ่ม session

ตำแหน่งโหลด CLAUDE.md

ระดับ	ตำแหน่ง	เมื่อโหลด
Project (root)	<cwd>/CLAUDE.md หรือ <cwd>/.claude/CLAUDE.md	settingSources มี "project"
Project rules	<cwd>/.claude/rules/*.md	settingSources มี "project"
Project (parent dirs)	CLAUDE.md files ในไดเรกทอรีด้านบน cwd	settingSources มี "project" โหลดเมื่อเริ่ม session
Project (child dirs)	CLAUDE.md files ในไดเรกทอรีย่อยของ cwd	โหลดตามต้องการเมื่อ agent อ่านไฟล์ใน subtree นั้น
Local	<cwd>/CLAUDE.local.md	settingSources มี "local"
User	~/.claude/CLAUDE.md	settingSources มี "user"

tip

คุณยังสามารถ inject บริบทโดยตรงผ่าน systemPrompt โดยไม่ใช้ CLAUDE.md files ดู Modify system prompts ใช้ CLAUDE.md เมื่อคุณต้องการบริบทเดียวกันที่แบ่งปันระหว่าง interactive Claude Code sessions และ SDK agents ของคุณ

Skills

Skills คือ markdown files ที่ให้ความรู้เฉพาะทางและ workflows ที่เรียกใช้ได้แก่ agent ของคุณ ต่างจาก CLAUDE.md (ซึ่งโหลดทุก session) skills จะโหลดตามต้องการ

เมื่อตัวเลือก skills บน query() ถูกละเว้น user และ project skills ที่ค้นพบจะถูกเปิดใช้งานและ Skill tool จะพร้อมใช้งาน

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="Review this PR using our code review checklist",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],
        skills="all",
        allowed_tools=["Read", "Grep", "Glob"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

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

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);
  }
}

note

Skills ต้องถูกสร้างเป็น filesystem artifacts (.claude/skills/<name>/SKILL.md) SDK ไม่มี programmatic API สำหรับการลงทะเบียน skills ดู Agent Skills ใน SDK สำหรับรายละเอียดเต็มรูปแบบ

Hooks

SDK รองรับสองวิธีในการกำหนด hooks และทั้งคู่รันควบคู่กัน:

• Filesystem hooks: shell commands ที่กำหนดใน settings.json โหลดเมื่อ settingSources มี source ที่เกี่ยวข้อง
• Programmatic hooks: callback functions ที่ส่งโดยตรงไปยัง query() สิ่งเหล่านี้รันใน application process ของคุณ

ตัวอย่าง programmatic hook:

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


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 {}


async for message in query(
    prompt="Refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["project"],
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[audit_bash]),
            ]
        },
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

import { query, type HookInput, type HookJSONOutput } from "@anthropic-ai/claude-agent-sdk";

const auditBash = async (input: HookInput): Promise<HookJSONOutput> => {
  if (input.hook_event_name !== "PreToolUse") return {};
  const toolInput = input.tool_input as { command?: string };
  if (toolInput.command?.includes("rm -rf")) {
    return {
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "Destructive command blocked",
      },
    };
  }
  return {};
};

for await (const message of query({
  prompt: "Refactor the auth module",
  options: {
    settingSources: ["project"],
    hooks: {
      PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }]
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

เลือก Feature ที่เหมาะสม

คุณต้องการ...	ใช้	SDK surface
ตั้งค่า project conventions ที่ agent ปฏิบัติตามเสมอ	CLAUDE.md	settingSources: ["project"] โหลดโดยอัตโนมัติ
ให้ reference material แก่ agent ที่โหลดเมื่อเกี่ยวข้อง	Skills	settingSources + ตัวเลือก skills
รัน reusable workflow (deploy, review, release)	User-invocable skills	settingSources + ตัวเลือก skills
มอบหมาย subtask แบบ isolated ให้ fresh context	Subagents	ตัวแปร agents + allowedTools: ["Agent"]
รันตรรกะที่กำหนดเองบน tool calls (audit, block, transform)	Hooks	ตัวแปร hooks พร้อม callbacks
ให้ Claude เข้าถึง tool แบบ structured ไปยัง external service	MCP	ตัวแปร mcpServers

ทรัพยากรที่เกี่ยวข้อง

• Skills ใน SDK: คู่มือเต็มรูปแบบสำหรับการใช้ skills ด้วยโปรแกรม
• Subagents: กำหนดและเรียกใช้ subagents สำหรับ isolated subtasks
• Hooks: ดักจับและควบคุมพฤติกรรม agent ที่จุดดำเนินการสำคัญ
• Permissions: ควบคุมการเข้าถึง tool ด้วย modes, rules และ callbacks
• System prompts: Inject บริบทโดยไม่ใช้ CLAUDE.md files