Langsung ke konten utama
System prompts mendefinisikan perilaku Claude, kemampuan, dan gaya respons. Mulai dari preset claude_code untuk alat coding seperti CLI atau IDE di mana manusia mengawasi dan mengarahkan pekerjaan. Tulis prompt Anda sendiri untuk agen dengan permukaan, identitas, atau model izin yang berbeda. Halaman ini mencakup:

Cara kerja system prompts

Sebuah system prompt adalah set instruksi awal yang membentuk bagaimana Claude berperilaku sepanjang percakapan. Agent SDK memiliki tiga titik awal untuk itu:
  • Default minimal: ketika Anda tidak menetapkan systemPrompt di TypeScript atau system_prompt di Python, SDK menggunakan prompt minimal yang mencakup tool calling tetapi menghilangkan panduan coding Claude Code, gaya respons, dan konteks proyek. Ini berbeda dari claude -p, yang menggunakan prompt Claude Code lengkap secara default. Jika Anda bermigrasi dari CLI dan menginginkan perilaku yang cocok, atur preset claude_code.
  • Preset claude_code: system prompt lengkap yang digunakan CLI Claude Code, dengan instruksi penggunaan tool, panduan gaya dan pemformatan kode, aturan nada dan verbositas respons, instruksi keamanan dan keselamatan, serta konteks tentang direktori kerja dan lingkungan. Atur systemPrompt: { type: "preset", preset: "claude_code" } di TypeScript atau system_prompt={"type": "preset", "preset": "claude_code"} di Python, secara opsional dengan append untuk menambahkan instruksi Anda sendiri di akhir.
  • String kustom: prompt yang Anda tulis sendiri. SDK hanya mengirimkan apa yang Anda berikan.

Tentukan titik awal

Faktor penentu adalah seberapa dekat agen Anda menyerupai Claude Code: agen coding yang beroperasi di repositori, dengan manusia mengamati output streaming dan mengarahkan pekerjaan. Semakin jauh produk Anda dari itu, semakin banyak Anda akan ingin menulis prompt Anda sendiri. “Berbeda dari Claude Code” biasanya berarti salah satu dari berikut:
  • Permukaan berbeda: output tidak dibaca di terminal oleh orang yang memicunya. Chat UI, konsumen output terstruktur, dan otomasi non-coding masing-masing memerlukan prompt yang sesuai dengan cara output mereka dirender dan ditinjau. Otomasi coding tanpa pengawasan, seperti pekerjaan CI yang memperbaiki kesalahan lint atau meninjau diff, masih sesuai dengan preset karena pekerjaan itu sendiri adalah apa yang preset ditulis untuk.
  • Identitas berbeda: agen tidak boleh menyajikan dirinya sebagai Claude Code. Bot dukungan, asisten analisis data, atau agen khusus domain apa pun memerlukan nama, cakupan, dan persona mereka sendiri.
  • Model izin berbeda: agen berjalan secara otonom tanpa manusia menyetujui setiap langkah, atau beroperasi pada set sumber daya yang sempit. Prompt Claude Code mengasumsikan manusia berada dalam loop dengan akses ke set tool lengkap.
  • Tugas non-coding: sebagian besar prompt Claude Code adalah panduan coding. Untuk penelitian, konten, atau agen operasi, panduan itu bersaing dengan instruksi yang benar-benar Anda butuhkan.
Tabel perbandingan menunjukkan apa yang dipertahankan oleh setiap metode kustomisasi.

Sesuaikan perilaku agen

Output styles, append, dan string prompt khusus masing-masing mengubah system prompt secara langsung. CLAUDE.md mengambil jalur yang berbeda: SDK membacanya dan menyuntikkan kontennya ke dalam percakapan sebagai konteks proyek, bukan ke dalam system prompt, sehingga membentuk perilaku bersama dengan system prompt apa pun yang Anda pilih. Skills, hooks, dan permissions juga membentuk perilaku di luar system prompt dan tercakup di halaman terpisahnya.

File CLAUDE.md untuk instruksi tingkat proyek

File CLAUDE.md memberikan Claude konteks proyek dan instruksi yang persisten. SDK menyuntikkan kontennya ke dalam percakapan, bukan ke dalam system prompt, sehingga mereka bekerja dengan konfigurasi system prompt apa pun. Untuk apa yang harus dimasukkan dalam CLAUDE.md, di mana menempatkannya, dan cara menulis instruksi yang efektif, lihat Bagaimana Claude mengingat proyek Anda. Bagian ini mencakup apa yang spesifik untuk SDK: bagaimana CLAUDE.md dimuat. SDK membaca CLAUDE.md ketika sumber pengaturan yang sesuai diaktifkan: 'project' memuat CLAUDE.md atau .claude/CLAUDE.md dari direktori kerja, dan 'user' memuat ~/.claude/CLAUDE.md. Opsi query() default mengaktifkan kedua sumber, sehingga CLAUDE.md dimuat secara otomatis. Jika Anda menetapkan settingSources di TypeScript atau setting_sources di Python secara eksplisit, sertakan sumber yang Anda butuhkan. Pemuatan CLAUDE.md dikendalikan oleh sumber pengaturan, bukan oleh preset claude_code.

Muat CLAUDE.md dengan SDK

Untuk memuat CLAUDE.md, atur settingSources untuk menyertakan level tempat CLAUDE.md Anda berada. Contoh di bawah memuat CLAUDE.md tingkat proyek bersama dengan preset claude_code, sehingga Claude memiliki prompt agen coding lengkap dan konvensi proyek Anda:
CLAUDE.md persisten di semua sesi dalam proyek, dibagikan dengan tim Anda melalui git, dan ditemukan secara otomatis tanpa perubahan kode. Tidak dimuat jika Anda melewatkan array settingSources kosong.

Output styles untuk konfigurasi persisten

Output styles adalah konfigurasi yang disimpan yang memodifikasi system prompt Claude. Mereka disimpan sebagai file markdown dan dapat digunakan kembali di berbagai sesi dan proyek.

Buat output style

Output style adalah file markdown dengan frontmatter untuk metadata, diikuti oleh konten prompt. Simpan ke ~/.claude/output-styles/ untuk style tingkat pengguna yang tersedia di setiap proyek, atau .claude/output-styles/ di repositori Anda untuk style tingkat proyek yang dapat Anda commit dan bagikan dengan tim Anda. Secara default, output style khusus menggantikan instruksi rekayasa perangkat lunak dari preset claude_code dengan instruksi Anda sendiri. Untuk mempertahankannya dan melapisi instruksi Anda di atasnya, atur keep-coding-instructions: true di frontmatter. Pertahankan mereka ketika agen Anda masih melakukan pekerjaan rekayasa perangkat lunak. Tinggalkan mereka ketika Anda mengganti peran sepenuhnya. Contoh di bawah mendefinisikan persona code-review yang mempertahankan instruksi coding, karena meninjau kode masih mendapat manfaat dari panduan keamanan dan kualitas kode Claude Code. Simpan sebagai ~/.claude/output-styles/code-reviewer.md untuk membuatnya tersedia di berbagai proyek:
~/.claude/output-styles/code-reviewer.md

Aktifkan output style

Setelah dibuat, aktifkan output styles melalui:
  • CLI: jalankan /config dan pilih output style
  • Settings: atur outputStyle di .claude/settings.local.json
  • TypeScript SDK: atur outputStyle di dalam objek settings inline yang dilewatkan ke query(), atau arahkan settings ke file pengaturan yang menetapkannya. outputStyle bukan field Options tingkat atas:
Python SDK tidak memiliki opsi untuk memilih output style secara terprogram. Untuk deployment hanya kode di mana Anda tidak dapat menulis ke .claude/settings.local.json, gunakan append atau string prompt khusus sebagai gantinya. Catatan untuk pengguna SDK: Output styles dimuat ketika Anda menyertakan settingSources: ['user'] atau settingSources: ['project'] (TypeScript) / setting_sources=["user"] atau setting_sources=["project"] (Python) dalam opsi Anda.

Tambahkan ke preset claude_code

Anda dapat menggunakan preset Claude Code dengan properti append untuk menambahkan instruksi khusus Anda sambil mempertahankan semua fungsionalitas bawaan.

Tingkatkan prompt caching di berbagai pengguna dan mesin

Secara default, dua sesi yang menggunakan preset claude_code dan teks append yang sama masih tidak dapat berbagi entri cache prompt jika berjalan dari direktori kerja yang berbeda. Ini karena preset menyematkan konteks per-sesi dalam system prompt sebelum teks append Anda: direktori kerja, apakah itu repositori git, platform, shell aktif, versi OS, dan jalur auto-memory. Perbedaan apa pun dalam konteks itu menghasilkan system prompt yang berbeda dan cache miss. Konten CLAUDE.md tidak mempengaruhi cache system prompt karena SDK menyuntikkannya ke dalam percakapan, bukan system prompt. Untuk membuat system prompt identik di berbagai sesi, atur excludeDynamicSections: true di TypeScript atau "exclude_dynamic_sections": True di Python. Konteks per-sesi berpindah ke pesan pengguna pertama, meninggalkan hanya preset statis dan teks append Anda dalam system prompt sehingga konfigurasi identik berbagi entri cache di berbagai pengguna dan mesin.
excludeDynamicSections memerlukan @anthropic-ai/claude-agent-sdk v0.2.98 atau lebih baru, atau claude-agent-sdk v0.1.58 atau lebih baru untuk Python. Ini hanya berlaku untuk bentuk objek preset dan tidak berpengaruh ketika systemPrompt adalah string.
Contoh berikut memasangkan blok append bersama dengan excludeDynamicSections sehingga armada agen yang berjalan dari direktori berbeda dapat menggunakan kembali system prompt yang di-cache sama:
Tradeoffs: direktori kerja, flag git-repo, platform, shell aktif, versi OS, dan jalur auto-memory masih mencapai Claude, tetapi sebagai bagian dari pesan pengguna pertama daripada system prompt. Instruksi dalam pesan pengguna memiliki bobot sedikit lebih rendah daripada teks yang sama dalam system prompt, sehingga Claude mungkin mengandalkannya lebih sedikit saat bernalar tentang direktori saat ini atau jalur auto-memory. Aktifkan opsi ini ketika penggunaan kembali cache lintas-sesi lebih penting daripada konteks lingkungan yang paling otoritatif. Untuk flag yang setara dalam mode CLI non-interaktif, lihat --exclude-dynamic-system-prompt-sections.

Custom system prompts

Anda dapat menyediakan string khusus sebagai systemPrompt untuk mengganti default sepenuhnya dengan instruksi Anda sendiri.

Perbandingan keempat pendekatan

Keempat metode kustomisasi berbeda dalam hal di mana mereka berada, bagaimana mereka dibagikan, dan apa yang mereka pertahankan dari preset claude_code. “Dengan append” berarti menggunakan systemPrompt: { type: "preset", preset: "claude_code", append: "..." } di TypeScript atau system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} di Python. CLAUDE.md tidak mengubah prompt sistem itu sendiri: SDK menyuntikkan kontennya ke dalam percakapan sebagai konteks proyek.

Use cases dan best practices

Kapan menggunakan CLAUDE.md

Gunakan CLAUDE.md untuk instruksi yang harus berlaku untuk setiap sesi dalam proyek, terlepas dari system prompt mana yang digunakan sesi tersebut: standar coding, perintah umum, konteks arsitektur, dan konvensi tim. CLAUDE.md berkomitmen pada repositori Anda, sehingga tetap sinkron dengan kode yang dijelaskannya. Lihat When to add to CLAUDE.md untuk panduan lengkap. File CLAUDE.md dimuat ketika sumber pengaturan project diaktifkan, yang merupakan default untuk opsi query(). Jika Anda menetapkan settingSources dalam TypeScript atau setting_sources dalam Python secara eksplisit, sertakan 'project' untuk terus memuat CLAUDE.md tingkat proyek.

Kapan menggunakan output styles

Output styles adalah untuk persona yang ingin Anda gunakan kembali di seluruh CLI dan SDK tanpa mengubah kode aplikasi. Karena mereka berada sebagai file di .claude/output-styles, persona yang sama tersedia dari /config di CLI dan dari sesi SDK apa pun yang memuat sumber pengaturan yang sesuai. Terbaik untuk:
  • Perubahan perilaku persisten di berbagai sesi
  • Konfigurasi bersama tim
  • Asisten khusus seperti code reviewer, data scientist, atau asisten DevOps
  • Modifikasi prompt kompleks yang memerlukan versioning
Contoh:
  • Membuat asisten optimasi SQL khusus
  • Membangun code reviewer yang berfokus pada keamanan
  • Mengembangkan asisten pengajaran dengan pedagogi spesifik

Kapan menggunakan systemPrompt dengan append

Gunakan append ketika preset claude_code sudah sesuai dengan produk Anda dan Anda hanya perlu menambahkan instruksi tambahan. Anda mempertahankan panduan tool preset, aturan keamanan, dan konvensi coding tanpa mengimplementasikannya kembali. Terbaik untuk:
  • Menambahkan standar coding atau preferensi spesifik
  • Menyesuaikan pemformatan output
  • Menambahkan pengetahuan domain-spesifik
  • Memodifikasi verbositas respons
  • Meningkatkan perilaku default Claude Code tanpa kehilangan instruksi tool

Kapan menggunakan custom systemPrompt

Gunakan prompt kustom ketika permukaan agen, identitas, atau model izin Anda berbeda dari Claude Code, seperti yang dijelaskan dalam Decide on a starting point. Anda menentukan set instruksi lengkap, termasuk panduan tool dan aturan keamanan apa pun yang dibutuhkan agen Anda. Terbaik untuk:
  • Kontrol penuh atas perilaku Claude
  • Tugas khusus sesi tunggal
  • Menguji strategi prompt baru
  • Situasi di mana tool default tidak diperlukan
  • Membangun agen khusus dengan perilaku unik

Menggabungkan pendekatan

Metode-metode ini dapat dikomposisi. Gaya output yang persisten atau CLAUDE.md menetapkan perilaku jangka panjang, dan append menambahkan instruksi spesifik sesi di atasnya tanpa menyentuh konfigurasi yang disimpan.

Menggabungkan gaya output dengan penambahan spesifik sesi

Contoh di bawah ini mengasumsikan gaya output Code Reviewer sudah aktif. Blok append menambahkan area fokus spesifik sesi di atas persona, sehingga sesi review tunggal dapat memprioritaskan OAuth dan penyimpanan token tanpa mengubah gaya output yang disimpan:

Lihat juga

  • Output styles: buat, kelola, dan bagikan output styles untuk CLI, termasuk format file dan lokasi penyimpanan
  • Bagaimana Claude mengingat proyek Anda: apa yang harus dimasukkan dalam CLAUDE.md, di mana menempatkannya, dan cara menulis instruksi proyek yang efektif
  • Referensi TypeScript SDK: tipe Options lengkap, termasuk systemPrompt, settingSources, dan settings
  • Referensi Python SDK: tipe ClaudeAgentOptions lengkap, termasuk system_prompt dan setting_sources
  • Settings: referensi settings.json, termasuk di mana output styles dan konfigurasi lainnya disimpan