Skip to main content
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.

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 sisa konten preset claude_code, termasuk instruksi keamanan dan keselamatannya. Ini berbeda dari claude -p, yang menggunakan system prompt Claude Code secara default. Jika Anda bermigrasi dari CLI dan menginginkan perilaku yang cocok, atur preset claude_code.
  • Preset claude_code: system prompt yang digunakan CLI Claude Code, dengan instruksi penggunaan tool dan instruksi keamanan dan keselamatan. 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

append dan string prompt khusus masing-masing mengubah system prompt secara langsung, dan output style mengubah instruksi yang Claude Code berikan kepada Claude untuk setiap respons. CLAUDE.md mengambil jalur yang berbeda: SDK membacanya dan menyuntikkan kontennya ke dalam percakapan sebagai konteks proyek, 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 dan membiarkan system prompt tidak berubah, 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 Kapan menambahkan ke CLAUDE.md dan sisanya dari 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 Anda menyimpan CLAUDE.md Anda. Contoh di bawah memuat CLAUDE.md tingkat proyek bersama dengan preset claude_code, sehingga Claude memiliki prompt agen coding lengkap dan konvensi proyek Anda:
Ketika Anda menjalankan salah satu contoh, SDK melakukan streaming pesan saat Claude bekerja: pesan inisialisasi sistem, pesan asisten, pesan pengguna yang membawa hasil alat, dan pesan hasil akhir dengan hasil sesi. 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 dari instruksi yang mengubah peran, nada, dan format output 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. Output style khusus meninggalkan instruksi rekayasa perangkat lunak dari preset claude_code dan menggunakan instruksi Anda sendiri. Untuk mempertahankannya dan melapisi instruksi Anda di atasnya, atur keep-coding-instructions: true di frontmatter. Instruksi tersebut hanya ada dalam system prompt lengkap Claude Code, jadi pengaturan ini tidak berpengaruh dalam sesi pada system prompt yang lebih pendek; atur CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT ke 0 untuk memilih prompt lengkap pada model apa pun. Pertahankan mereka ketika agent 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 /output-style <style>, misalnya /output-style concise, atau jalankan /config dan pilih satu. Perintah /output-style memerlukan Claude Code v2.1.269 atau lebih baru.
  • 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:
Dalam Python SDK, atur outputStyle melalui opsi settings, yang mengambil string JSON seperti '{"outputStyle": "Explanatory"}' atau jalur ke file pengaturan yang menetapkannya. 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 ketika lokasi auto memory mereka berbeda. Preset menyematkan lokasi itu dalam system prompt sebelum teks append Anda. Lokasi default adalah jalur absolut di bawah ~/.claude/projects/ yang dinamai untuk jalur repositori di disk, sehingga berbeda di berbagai pengguna, mesin, dan checkout. Konten CLAUDE.md dan detail lingkungan seperti direktori kerja, platform, shell, dan versi OS tidak mempengaruhi cache system prompt, karena Claude Code menyampaikannya 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-pengguna 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. Atur pada bentuk objek preset saja. SDK mengabaikannya ketika Anda melewatkan prompt khusus alih-alih preset; untuk menjaga instruksi prompt khusus yang di-cache dalam TypeScript SDK, lihat Cache bagian statis dari prompt khusus.
Contoh berikut memasangkan blok append bersama dengan excludeDynamicSections sehingga armada agen dapat menggunakan kembali system prompt yang di-cache sama:
Tradeoffs: teks yang berpindah keluar dari system prompt masih mencapai Claude, tetapi dalam pesan pengguna. Teks itu setidaknya adalah lokasi direktori auto memory, dan sering kali seluruh bagian auto memory. Instruksi dalam pesan pengguna memiliki bobot sedikit lebih rendah daripada teks yang sama dalam system prompt, sehingga Claude mungkin mengikuti panduan auto memory-nya dengan kurang konsisten. Aktifkan opsi ini ketika penggunaan kembali cache lintas-sesi lebih penting daripada itu. 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.
Di Python, muat prompt khusus besar dari file dengan system_prompt={"type": "file", "path": "..."} alih-alih meneruskannya sebagai string. Python SDK melewatkan prompt string sebagai satu argumen baris perintah ke subprocess CLI, sehingga prompt yang melebihi batas panjang argumen OS gagal saat pemijahan proses sebelum permintaan API apa pun dikirim. Di Linux kesalahannya adalah Argument list too long. Lihat SystemPromptFile untuk ambang batas platform dan perilaku Windows.

Cache bagian statis dari prompt khusus

Dalam TypeScript SDK, Anda dapat melewatkan prompt khusus sebagai array string alih-alih satu string, dengan penanda SYSTEM_PROMPT_DYNAMIC_BOUNDARY antara bagian statis dan sisanya. Gunakan ini ketika prompt Anda menggabungkan instruksi yang sama pada setiap permintaan dengan konteks yang berubah per permintaan, seperti pelanggan atau tiket yang ditangani agen. Ketika Anda melewatkan kedua bagian sebagai satu string, perubahan pada bagian per-permintaan mengubah seluruh system prompt, sehingga instruksi statis melewatkan cache juga. Bentuk array tidak tersedia dalam Python SDK; ClaudeAgentOptions mencantumkan bentuk yang system_prompt terima.
SDK membagi prompt hanya ketika memanggil Claude API secara langsung atau berjalan di Claude Platform on AWS. Dalam setiap konfigurasi lain, seperti Amazon Bedrock, Agent Platform Google Cloud, Microsoft Foundry, atau LLM gateway, dan kapan pun Anda menetapkan CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, SDK mengirim seluruh prompt sebagai satu blok, sama seperti melewatkan satu string.
Untuk membagi prompt, impor SYSTEM_PROMPT_DYNAMIC_BOUNDARY dari @anthropic-ai/claude-agent-sdk dan lewatkan sebagai elemen array terpisahnya antara dua bagian. SDK mengirim string sebelum penanda sebagai satu blok teks dan string setelahnya sebagai blok kedua, masing-masing dengan titik henti cache-nya sendiri. Dalam contoh di bawah, agen dukungan memuat instruksi triase dari file dan menerima detail tentang satu tiket pada setiap permintaan, sehingga instruksi tetap di-cache sementara detail tiket berubah:
TypeScript
Track cache tokens menjelaskan field cache_creation_input_tokens dan cache_read_input_tokens pada setiap pesan hasil. SDK merakit blok dari array sebagai berikut:
  • SDK menggabungkan string di setiap sisi penanda dengan baris kosong di antara mereka dan menghapus penanda itu sendiri, sehingga teks penanda tidak mencapai Claude.
  • Jika Anda menyertakan penanda lebih dari sekali, yang pertama adalah pemisahan dan SDK menghapus yang lain.
  • Jika Anda meninggalkan penanda, SDK menggabungkan semua string menjadi satu blok, sama seperti melewatkan satu string.
Dengan flag --system-prompt atau --system-prompt-file CLI, prompt adalah satu string, sehingga tidak ada array untuk membawa penanda. Sertakan baris yang hanya berisi __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ antara bagian statis dan per-permintaan sebagai gantinya. Claude Code membagi prompt pada baris pertama seperti itu menjadi dua blok yang sama dan menghapus baris itu. Memerlukan Claude Code v2.1.275 atau lebih baru. Dalam SDK, lebih suka bentuk array, yang membawa batas tanpa baris penanda.

Ubah prompt dari sesi yang ada

Secara default, jika Anda melewatkan append atau prompt khusus yang berbeda ketika Anda kembali ke sesi dengan resume atau continue, Claude tidak melihatnya pada giliran berikutnya. Claude Code mencatat system prompt pada permintaan pertama sesi dan menggunakan kembali catatan itu sampai sesi dikompakkan. Teks baru berlaku setelah pemadatan itu, atau dalam sesi baru.

Perbarui instruksi Claude di tengah-sesi

Jika instruksi yang Anda masukkan dalam system prompt perlu berubah saat sesi berjalan, misalnya karena pengguna Anda beralih agen ke mode read-only atau mengedit konfigurasinya di aplikasi Anda, kirim instruksi baru dalam percakapan alih-alih mengubah systemPrompt:
  • Dalam pesan Anda berikutnya: sertakan instruksi baru dalam pesan pengguna berikutnya yang Anda kirim.
  • Dari hook: kembalikan additionalContext dari callback hook UserPromptSubmit atau PostToolUse hook callback, ditulis sebagai pernyataan faktual seperti “Workspace sekarang read-only”. SDK menyisipkan teks ke dalam percakapan pada titik di mana hook dipecat, sehingga prompt yang dicatat tetap tidak berubah.

Matikan pencatatan saat Anda mengulangi redaksi

Saat Anda mengulangi redaksi prompt dan ingin setiap edit mencapai sesi yang Anda lanjutkan, atur snapshot ke false pada bentuk objek system prompt. Claude Code kemudian membangun kembali prompt pada setiap permintaan. Field tersedia pada bentuk preset dan custom dari systemPrompt di TypeScript dan dari system_prompt di Python, dan memerlukan @anthropic-ai/claude-agent-sdk v0.3.257 atau lebih baru, atau claude-agent-sdk v0.2.153 atau lebih baru. Pertahankan pencatatan aktif dalam produksi. Dengan pencatatan mati, append atau prompt khusus yang berbeda pada sesi yang dilanjutkan mencapai Claude pada giliran berikutnya, dan permintaan itu tidak dapat menggunakan kembali prompt cache sesi. Di mana API memberlakukan preserved thinking, Claude juga kehilangan pemikirannya dari giliran sebelumnya. Di luar cloud sessions, jika Anda memulai Claude Code dalam bare mode dengan melewatkan --bare melalui extraArgs atau menetapkan CLAUDE_CODE_SIMPLE=1, pencatatan tetap mati kecuali Anda menetapkan snapshot: true. Pencatatan append atau prompt khusus secara default memerlukan Claude Code v2.1.265 atau lebih baru, yang TypeScript Agent SDK bundel dari v0.3.265 dan Python Agent SDK dari v0.2.153. Sebelum Claude Code v2.1.268, sesi yang tidak mengambil feature flags, termasuk sesi di Amazon Bedrock, Agent Platform Google Cloud, dan Microsoft Foundry, membangun kembali prompt pada setiap permintaan dan snapshot tidak berpengaruh.

Konteks yang Claude Code tambahkan di luar system prompt

System reminders adalah pesan yang Claude Code tambahkan ke percakapan selama sesi untuk memberikan Claude konteks, seperti isi file CLAUDE.md Anda atau catatan bahwa file berubah di disk. Claude Code mengirimnya dalam percakapan, bukan dalam system prompt, sehingga sebagian besar di antaranya mencapai Claude apakah Anda menggunakan preset claude_code atau meneruskan string Anda sendiri sebagai systemPrompt. Bagian ini mencakup reminders yang paling mungkin mengubah perilaku agen Anda, cara mematikan yang diganti agen Anda, dan cara melihat apa yang Claude terima dalam permintaan tertentu.

Reminders Claude Code adds to the conversation

System reminders adalah teks yang Claude Code tambahkan ke percakapan bersama dengan prompt yang kode Anda kirim. Reminders berikut adalah yang paling mungkin mengubah perilaku agen Anda:
  • Project instructions: file CLAUDE.md yang opsi settingSources Anda muat
  • Output style instructions: instruksi dari output style aktif, dalam percakapan utama
  • Commit and pull request attribution: trailer Co-Authored-By dan footer pull request dari pengaturan attribution
  • Hook output: teks yang hooks Anda kembalikan sebagai additionalContext
  • Available skills: nama dan deskripsi skills yang dapat dipanggil Claude
  • Available subagents: nama dan deskripsi subagents yang dapat dimulai Claude
  • Task list nudges: dalam sesi yang memiliki task-tracking tools, prompt untuk memperbarui daftar tugas ketika Claude belum menyentuhnya selama beberapa putaran
  • File-changed notes: catatan bahwa file yang dibaca Claude sebelumnya telah berubah di disk
Claude Code memperkenalkan file CLAUDE.md Anda dengan baris yang memberi tahu Claude bahwa instruksi menggantikan perilaku default. Jika Anda meneruskan string Anda sendiri sebagai systemPrompt, tambahkan kalimat ke dalamnya yang mengatakan apa itu system reminder. Preset claude_code memiliki satu, dan string Anda menggantikan seluruh preset. Tanpa itu, tidak ada dalam prompt Anda yang memberi tahu Claude bahwa reminders seperti konten CLAUDE.md dan hook output berasal dari aplikasi daripada dari pengguna. Sebagai contoh:

Turn off the context your agent replaces

Matikan bagian konteks bawaan ketika agen Anda menyediakan versi panduan yang sama. Misalnya, jika prompt Anda memberi tahu Claude untuk menulis pesan commit sebagai PROJ-142: fix login redirect tanpa trailer, Claude Code masih memberi tahu Claude untuk mengakhiri setiap pesan commit dengan trailer Co-Authored-By, sehingga Claude menerima dua instruksi yang bertentangan untuk commit yang sama. Teruskan kunci pengaturan melalui opsi settings di TypeScript atau settings di Python, dan variabel lingkungan melalui opsi env. Di TypeScript, env menggantikan lingkungan yang diwariskan, jadi sebarkan process.env ke dalamnya. Atur includeGitInstructions ke false untuk menyingkirkan instruksi commit dan pull request bawaan, yang merupakan bagian dari deskripsi tool Bash dan tetap mencapai Claude bahkan dengan systemPrompt kustom. Namun, dengan default minimal, systemPrompt kustom, atau agent thread utama kustom yang memiliki prompt sendiri, sesi dimulai tanpa snapshot status git. Jika Anda mengatur CLAUDE_CODE_DISABLE_ATTACHMENTS, Claude Code juga mengirim penyebutan file @ sebagai teks biasa daripada memperluas mereka ke konten file. Daftar subagent yang tersedia dan notifikasi tugas latar belakang masih tiba. Untuk menghentikan hanya perluasan penyebutan file @, atur CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 sebagai gantinya, pada Claude Code v2.1.299 atau yang lebih baru. Claude kemudian mendapatkan path yang disebutkan beserta catatan untuk membacanya dengan tool file-nya. Contoh berikut adalah untuk agen yang membawa aturan commit sendiri dalam append. Ini mengatur kedua kunci attribution ke string kosong untuk menghapus trailer dan footer, dan mematikan includeGitInstructions sehingga instruksi alur kerja commit Claude Code sendiri tidak bersaing dengan milik Anda:
Untuk mengonfirmasi perubahan, jalankan contoh dalam repositori dengan perubahan yang dipentaskan dan periksa commit baru dengan git log -1. Pesan berakhir tanpa trailer Co-Authored-By.

See what Claude received

Aliran pesan SDK tidak menyertakan system reminders, jadi membaca pesan yang kode Anda terima tidak akan menunjukkan kepada Anda apa yang Claude lihat. Untuk melihatnya, catat permintaan yang Claude Code kirim:
  • Raw request logging: atur OTEL_LOG_RAW_API_BODIES ke file:<dir>. Claude Code menulis setiap badan permintaan ke direktori itu.
  • A gateway you control: arahkan ANTHROPIC_BASE_URL ke proxy yang mencatat badan permintaan.
Dalam permintaan yang dicatat, lihat di array messages. Reminder muncul di dalam pesan pengguna yang dibungkus dalam tag <system-reminder> atau, pada beberapa model, sebagai pesan terpisah dengan peran system.

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.

Menggabungkan pendekatan

Pendekatan-pendekatan ini dapat digabungkan. 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