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.
Untuk gambaran konseptual tentang apa yang dilakukan setiap fitur dan kapan menggunakannya, lihat Perluas Claude Code.
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"]:
<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).
| Sumber | Apa yang dimuat | Lokasi |
|---|---|---|
"project" | CLAUDE.md proyek, .claude/rules/*.md, skills proyek, hooks proyek, settings.json proyek | <cwd>/.claude/ untuk settings.json dan hooks; <cwd> dan setiap direktori induk untuk CLAUDE.md dan rules; <cwd> dan setiap direktori induk hingga akar repositori untuk skills |
"user" | CLAUDE.md pengguna, ~/.claude/rules/*.md, skills pengguna, pengaturan pengguna | ~/.claude/ |
"local" | CLAUDE.local.md, .claude/settings.local.json | <cwd>/.claude/ untuk settings.local.json; <cwd> dan setiap direktori induk untuk CLAUDE.local.md |
settingSources setara dengan ["user", "project", "local"].
Opsi cwd menentukan di mana SDK mencari input tingkat proyek. CLAUDE.md dan rules dimuat dari <cwd> dan dari setiap direktori induk. Skills dimuat dari <cwd> dan dari setiap direktori induk hingga akar repositori. 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:
| Input | Perilaku | Untuk menonaktifkan |
|---|---|---|
| Pengaturan kebijakan terkelola | Selalu dimuat ketika ada di host | Hapus file pengaturan terkelola |
Konfigurasi global ~/.claude.json | Selalu dibaca | Pindahkan dengan CLAUDE_CONFIG_DIR di env |
Memori otomatis di ~/.claude/projects/<project>/memory/ | Dimuat secara default ke dalam system prompt | Atur autoMemoryEnabled: false di pengaturan, atau CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 di env |
| Konektor MCP dari claude.ai | Dimuat ketika metode autentikasi aktif adalah langganan claude.ai. Melewatkan mcpServers: {} tidak menekannya | Atur strictMcpConfig: true, atau ENABLE_CLAUDEAI_MCP_SERVERS=false di env |
Instruksi proyek (CLAUDE.md dan rules)
FileCLAUDE.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
| Level | Lokasi | Kapan dimuat |
|---|---|---|
| Proyek (root) | <cwd>/CLAUDE.md atau <cwd>/.claude/CLAUDE.md | settingSources mencakup "project" |
| Rules proyek | <cwd>/.claude/rules/*.md dan .claude/rules/*.md di setiap direktori induk | settingSources mencakup "project" |
| Proyek (direktori induk) | File CLAUDE.md di direktori di atas cwd | settingSources mencakup "project", dimuat pada awal sesi |
| Proyek (direktori anak) | File CLAUDE.md di subdirektori cwd | settingSources mencakup "project", dimuat sesuai permintaan ketika agen membaca file di subtree itu |
| Lokal | <cwd>/CLAUDE.local.md dan CLAUDE.local.md di setiap direktori induk | settingSources mencakup "local" |
| Pengguna | ~/.claude/CLAUDE.md | settingSources mencakup "user" |
| Rules pengguna | ~/.claude/rules/*.md | settingSources mencakup "user" |
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 sepertiCLAUDE.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.
Skills harus dibuat sebagai artifact filesystem (
.claude/skills/<name>/SKILL.md). SDK tidak memiliki API terprogram untuk mendaftarkan skills. Lihat Agent Skills di SDK untuk detail lengkap.Hooks
SDK mendukung dua cara untuk mendefinisikan hooks, dan mereka berjalan beriringan:- Filesystem hooks: perintah shell yang didefinisikan di
settings.json, dimuat ketikasettingSourcesmencakup 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.
.claude/settings.json proyek Anda dan Anda menetapkan settingSources: ["project"], hooks tersebut berjalan secara otomatis di SDK tanpa konfigurasi tambahan.
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. Bidang tingkat atas decision dan reason sudah usang untuk PreToolUse. Lihat panduan hooks untuk tanda tangan callback lengkap dan tipe pengembalian.
Kapan menggunakan tipe hook mana
| Tipe hook | Terbaik untuk |
|---|---|
Filesystem (settings.json) | Berbagi hooks antara sesi CLI dan SDK. Mendukung "command" (skrip shell), "http" (POST ke endpoint), "mcp_tool" (panggil tool server MCP yang terhubung), "prompt" (LLM mengevaluasi prompt), dan "agent" (menghasilkan agen verifier). Ini dijalankan di agen utama dan subagen apa pun yang dihasilkannya. |
Programmatic (callbacks di query()) | Logika khusus aplikasi, keputusan terstruktur, dan integrasi dalam proses. Ini juga dijalankan di dalam subagen. Callback menerima agent_id dan agent_type untuk membedakan. |
SDK TypeScript mendukung event hook tambahan di luar Python, termasuk
SessionStart, SessionEnd, TeammateIdle, dan TaskCompleted. Lihat panduan hooks untuk tabel kompatibilitas event lengkap.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.| Anda ingin… | Gunakan | Permukaan SDK |
|---|---|---|
| Atur konvensi proyek yang selalu diikuti agen Anda | CLAUDE.md | settingSources: ["project"] memuat secara otomatis |
| Berikan agen materi referensi yang dimuat ketika relevan | Skills | settingSources + skills option |
| Jalankan alur kerja yang dapat digunakan kembali (deploy, review, release) | User-invocable skills | settingSources + skills option |
| Delegasikan subtask terisolasi ke konteks segar (research, review) | Subagents | Parameter agents + allowedTools: ["Agent"] |
| Koordinasikan beberapa instans Claude Code dengan daftar tugas bersama dan pesan inter-agen langsung | Agent teams | Tidak dikonfigurasi langsung melalui opsi SDK. Agent teams adalah fitur CLI di mana satu sesi bertindak sebagai pemimpin tim, mengoordinasikan pekerjaan di seluruh rekan kerja independen |
| Jalankan logika deterministik pada tool calls (audit, block, transform) | Hooks | Parameter hooks dengan callbacks, atau skrip shell dimuat melalui settingSources |
| Berikan Claude akses tool terstruktur ke layanan eksternal | MCP | Parameter mcpServers |
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