Memodifikasi system prompts

Pilih antara preset claude_code dan system prompt kustom, serta sesuaikan perilaku dengan CLAUDE.md, output styles, append, atau prompt yang sepenuhnya kustom.

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 serta konteksnya tentang direktori kerja dan lingkungan. 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, instruksi keamanan dan keselamatan, dan 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

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:

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

const messages = [];

for await (const message of query({
prompt: "Add a new React component for user profiles",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code" // Use Claude Code's system prompt
},
settingSources: ["project"] // Loads CLAUDE.md from project
}
})) {
messages.push(message);
}

// Now Claude has access to your project guidelines from CLAUDE.md

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

messages = []


async def main():
async for message in query(
prompt="Add a new React component for user profiles",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",  # Use Claude Code's system prompt
},
setting_sources=["project"],  # Loads CLAUDE.md from project
),
):
messages.append(message)


asyncio.run(main())

# Now Claude has access to your project guidelines from CLAUDE.md

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, yang Anda pin aktif atau nonaktif dengan CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT. 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:

---
name: Code Reviewer
description: Thorough code review assistant
keep-coding-instructions: true
---

You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)

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:

  const options = { settings: { outputStyle: "Explanatory" } };
  

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.

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

const messages = [];

for await (const message of query({
prompt: "Help me write a Python function to calculate fibonacci numbers",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "Always include detailed docstrings and type hints in Python code."
}
}
})) {
messages.push(message);
if (message.type === "assistant") {
console.log(message.message.content);
}
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

messages = []


async def main():
async for message in query(
prompt="Help me write a Python function to calculate fibonacci numbers",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "Always include detailed docstrings and type hints in Python code.",
}
),
):
messages.append(message)
if isinstance(message, AssistantMessage):
print(message.content)


asyncio.run(main())

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.

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:

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

for await (const message of query({
prompt: "Triage the open issues in this repo",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "You operate Acme's internal triage workflow. Label issues by component and severity.",
excludeDynamicSections: true
}
}
})) {
// ...
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
async for message in query(
prompt="Triage the open issues in this repo",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "You operate Acme's internal triage workflow. Label issues by component and severity.",
"exclude_dynamic_sections": True,
},
),
):
...


asyncio.run(main())

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.

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

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
prompt: "Create a data processing pipeline",
options: {
systemPrompt: customPrompt
}
})) {
messages.push(message);
if (message.type === "assistant") {
console.log(message.message.content);
}
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

custom_prompt = """You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices"""

messages = []


async def main():
async for message in query(
prompt="Create a data processing pipeline",
options=ClaudeAgentOptions(system_prompt=custom_prompt),
):
messages.append(message)
if isinstance(message, AssistantMessage):
print(message.content)


asyncio.run(main())

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.

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:

import { readFile } from "node:fs/promises";
import { query, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from "@anthropic-ai/claude-agent-sdk";

// Identical on every request
const instructions = await readFile("triage-instructions.md", "utf8");
// Different on every request
const ticketContext = "Customer plan: Enterprise. Other open tickets from this customer: 3.";

for await (const message of query({
  prompt: "Triage ticket 4821",
  options: {
    systemPrompt: [instructions, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, ticketContext]
  }
})) {
  // ...
}

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.

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:

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

// Assuming "Code Reviewer" output style is active (via /config or settings)
// Add session-specific focus areas
const messages = [];

for await (const message of query({
prompt: "Review this authentication module",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: `
For this review, prioritize:
- OAuth 2.0 compliance
- Token storage security
- Session management
`
}
}
})) {
messages.push(message);
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

# Assuming "Code Reviewer" output style is active (via /config or settings)
# Add session-specific focus areas
messages = []


async def main():
async for message in query(
prompt="Review this authentication module",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": """
For this review, prioritize:
- OAuth 2.0 compliance
- Token storage security
- Session management
""",
}
),
):
messages.append(message)


asyncio.run(main())

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