Gunakan fitur Claude Code di SDK

Muat instruksi proyek, skills, hooks, dan fitur Claude Code lainnya ke dalam agen SDK Anda.

Agent SDK dibangun di atas fondasi yang sama dengan Claude Code, yang berarti agen SDK Anda memiliki akses ke fitur berbasis filesystem yang sama: instruksi proyek (CLAUDE.md dan rules), skills, hooks, dan lainnya.

Ketika Anda menghilangkan settingSources, query() membaca pengaturan filesystem yang sama dengan Claude Code CLI: pengaturan pengguna, proyek, dan lokal, file CLAUDE.md, dan skills, agen, dan perintah di .claude/. Untuk menjalankan tanpa ini, teruskan settingSources: [], yang membatasi agen hanya pada apa yang Anda konfigurasi secara terprogram. Pengaturan kebijakan terkelola dan konfigurasi global ~/.claude.json dibaca terlepas dari opsi ini. Lihat Apa yang tidak dikontrol settingSources.

Kontrol pengaturan filesystem dengan settingSources

Opsi sumber pengaturan (setting_sources di Python, settingSources di TypeScript) mengontrol pengaturan berbasis filesystem mana yang dimuat SDK. Teruskan daftar eksplisit untuk memilih sumber tertentu, atau teruskan array kosong untuk menonaktifkan pengaturan pengguna, proyek, dan lokal.

Contoh ini memuat pengaturan tingkat pengguna dan tingkat proyek dengan menetapkan settingSources ke ["user", "project"]:

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
import asyncio


async def main():
async for message in query(
prompt="Help me refactor the auth module",
options=ClaudeAgentOptions(
# "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
# Together they give the agent access to CLAUDE.md, skills, hooks, and
# permissions from both locations.
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}")


asyncio.run(main())

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

for await (const message of query({
prompt: "Help me refactor the auth module",
options: {
// "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
// Together they give the agent access to CLAUDE.md, skills, hooks, and
// permissions from both locations.
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}`);
}
}

Ketika ini berjalan, respons asisten mencetak ke stdout, diikuti oleh baris hasil akhir setelah run selesai.

Setiap sumber memuat pengaturan dari lokasi tertentu, di mana <cwd> adalah direktori kerja yang Anda teruskan melalui opsi cwd, atau direktori saat ini proses jika tidak diatur. Untuk definisi tipe lengkap, lihat SettingSource (TypeScript) atau SettingSource (Python).

Menghilangkan settingSources setara dengan ["user", "project", "local"].

Opsi cwd menentukan di mana SDK mencari input tingkat proyek. settings.json proyek dan hooks dimuat hanya dari <cwd>/.claude/ tanpa fallback direktori induk.

Apa yang tidak dikontrol settingSources

settingSources mencakup pengaturan pengguna, proyek, dan lokal. Beberapa input dibaca terlepas dari nilainya:

Instruksi proyek (CLAUDE.md dan rules)

File CLAUDE.md dan file .claude/rules/*.md memberikan agen Anda konteks persisten tentang proyek Anda: konvensi pengkodean, perintah build, keputusan arsitektur, dan instruksi. Ketika settingSources mencakup "project" (seperti dalam contoh di atas), SDK memuat file ini ke dalam konteks pada awal sesi. Agen kemudian mengikuti konvensi proyek Anda tanpa Anda mengulanginya di setiap prompt.

Lokasi pemuatan CLAUDE.md

Semua level bersifat aditif: jika file CLAUDE.md proyek dan pengguna keduanya ada, agen melihat keduanya. Tidak ada aturan preseden keras antara level; jika instruksi bertentangan, hasilnya tergantung pada bagaimana Claude menafsirkannya. Tulis aturan yang tidak bertentangan, atau nyatakan preseden secara eksplisit di file yang lebih spesifik ("Instruksi proyek ini menggantikan default tingkat pengguna yang bertentangan").

Untuk cara menyusun dan mengorganisir konten CLAUDE.md, lihat Kelola memori Claude.

Skills

Skills adalah file markdown yang memberikan agen Anda pengetahuan khusus dan alur kerja yang dapat dipanggil. Tidak seperti CLAUDE.md (yang dimuat setiap sesi), skills dimuat sesuai permintaan. Agen menerima deskripsi skill pada startup dan memuat konten lengkap ketika relevan.

Skills ditemukan dari filesystem melalui settingSources. Ketika opsi skills pada query() dihilangkan, skills pengguna dan proyek yang ditemukan diaktifkan dan tool Skill tersedia, sesuai dengan perilaku CLI. Untuk mengontrol skills mana yang diaktifkan, berikan skills sebagai "all", daftar nama skill, atau [] untuk menonaktifkan semua. Ketika skills diatur, SDK secara otomatis menambahkan tool Skill ke allowedTools. Jika Anda juga meneruskan daftar tools eksplisit, sertakan "Skill" dalam daftar tersebut sehingga Claude dapat memanggil skills.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio


# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async def main():
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)


asyncio.run(main())

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

// Skills in .claude/skills/ are discovered automatically
// when settingSources includes "project"
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);
}
}

Hooks

SDK mendukung dua cara untuk mendefinisikan hooks, dan mereka berjalan beriringan:

• Filesystem hooks: perintah shell yang didefinisikan di settings.json, dimuat ketika settingSources mencakup sumber yang relevan. Ini adalah hooks yang sama yang akan Anda konfigurasi untuk sesi Claude Code interaktif.
• Programmatic hooks: fungsi callback yang diteruskan langsung ke query(). Ini berjalan dalam proses aplikasi Anda dan dapat mengembalikan keputusan terstruktur. Lihat Kontrol eksekusi dengan hooks.

Callback hook menerima input tool dan mengembalikan dict keputusan. Mengembalikan {} berarti izinkan tool untuk melanjutkan. Untuk memblokir eksekusi, kembalikan objek hookSpecificOutput dengan permissionDecision: "deny" dan permissionDecisionReason. Alasan dikirim ke Claude sebagai hasil tool. Lihat panduan hooks untuk tanda tangan callback lengkap dan tipe pengembalian.

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage
import asyncio


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, reserved for future abort-signal support
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 {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async def main():
async for message in query(
prompt="Refactor the auth module",
options=ClaudeAgentOptions(
setting_sources=["project"],  # Loads hooks from .claude/settings.json
hooks={
"PreToolUse": [
HookMatcher(matcher="Bash", hooks=[audit_bash]),
]
},
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

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

// PreToolUse hook callback. HookInput is a discriminated union on
// hook_event_name, so narrowing on it gives TypeScript the right
// tool_input shape for this event.
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 {}; // Empty object: allow the tool to proceed
};

// Filesystem hooks from .claude/settings.json run automatically
// when settingSources loads them. You can also add programmatic hooks:
for await (const message of query({
prompt: "Refactor the auth module",
options: {
settingSources: ["project"], // Loads hooks from .claude/settings.json
hooks: {
PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }]
}
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Kapan menggunakan tipe hook mana

Untuk detail lengkap tentang hooks terprogram, lihat Kontrol eksekusi dengan hooks. Untuk sintaks hook filesystem, lihat Hooks.

Pilih fitur yang tepat

Agent SDK memberi Anda akses ke beberapa cara untuk memperluas perilaku agen Anda. Jika Anda tidak yakin mana yang digunakan, tabel ini memetakan tujuan umum ke pendekatan yang tepat.

Setiap fitur yang Anda aktifkan menambah jendela konteks agen Anda. Untuk biaya per-fitur dan bagaimana fitur ini berlapis bersama, lihat Perluas Claude Code.

Sumber daya terkait

• Perluas Claude Code: Gambaran konseptual semua fitur ekstensi, dengan tabel perbandingan dan analisis biaya konteks
• Skills di SDK: Panduan lengkap menggunakan skills secara terprogram
• Subagents: Tentukan dan panggil subagents untuk subtask terisolasi
• Hooks: Intersep dan kontrol perilaku agen di titik eksekusi kunci
• Permissions: Kontrol akses tool dengan mode, rules, dan callbacks
• System prompts: Suntikkan konteks tanpa file CLAUDE.md