การปรับแต่ง System Prompts

เลือกระหว่าง preset claude_code และ custom system prompt และปรับแต่งพฤติกรรมด้วย CLAUDE.md, output styles, append, หรือ custom prompt แบบเต็ม

System prompts กำหนดพฤติกรรม, ความสามารถ, และรูปแบบการตอบสนองของ Claude เริ่มจาก preset claude_code สำหรับ CLI หรือ IDE-like coding tools ที่มนุษย์ดูและ steering งาน เขียน prompt ของตัวเองสำหรับ agents ที่มี surface, identity, หรือ permission model ที่แตกต่างกัน

วิธีการทำงานของ System Prompts

SDK มีจุดเริ่มต้นสามจุดสำหรับ system prompt:

Minimal default: เมื่อคุณไม่ตั้งค่า systemPrompt ใน TypeScript หรือ system_prompt ใน Python SDK จะใช้ prompt ขั้นต่ำที่ครอบคลุม tool calling แต่ละเว้น coding guidelines ของ Claude Code
Preset claude_code: system prompt เต็มรูปแบบที่ Claude Code CLI ใช้ พร้อม tool usage instructions, code style and formatting guidelines, response tone และ verbosity rules, security และ safety instructions, และ context เกี่ยวกับ working directory ตั้งค่าด้วย systemPrompt: { type: "preset", preset: "claude_code" }
Custom string: prompt ที่คุณเขียนเอง SDK ส่งเฉพาะสิ่งที่คุณระบุ

ตัดสินใจว่าจะใช้จุดเริ่มต้นไหน

คุณกำลังสร้าง...	ใช้	สิ่งที่คุณได้
CLI หรือ IDE-like coding tool ที่มนุษย์ดูและ steering และค่า default ของ Claude Code ตรงกับที่คุณต้องการ	`claude_code` preset	Claude Code prompt เต็ม: tool guidance, safety rules, terminal-friendly responses, repo-convention awareness
Tool แบบเดียวกัน บวกกับ product-specific rules	`claude_code` preset กับ `append`	ทุกอย่างข้างต้น บวกกับ instructions ของคุณที่เพิ่มหลัง preset
Agent ที่มี surface, identity, หรือ permission model ที่แตกต่างกัน หรือ non-coding agent	Custom prompt string	เฉพาะสิ่งที่คุณเขียน คุณรับผิดชอบการแทนที่ tool guidance และ safety instructions
Tool-calling loop บางๆ ที่ไม่มี agent persona	ไม่มี option `systemPrompt`	Minimal default: tool-calling support และไม่มีอะไรเพิ่มเติม

ปรับแต่งพฤติกรรม Agent

ไฟล์ CLAUDE.md สำหรับ project-level instructions

ไฟล์ CLAUDE.md ให้ project context และ instructions ที่คงทนกับ Claude SDK inject เนื้อหาของพวกมันเข้าในการสนทนา ไม่ใช่ใน system prompt ดังนั้นพวกมันทำงานกับ system prompt configuration ใดก็ได้

SDK อ่าน CLAUDE.md เมื่อ matching setting source ถูกเปิดใช้งาน: 'project' โหลด CLAUDE.md หรือ .claude/CLAUDE.md จาก working directory และ 'user' โหลด ~/.claude/CLAUDE.md

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"
    },
    settingSources: ["project"] // โหลด CLAUDE.md จาก project
  }
})) {
  messages.push(message);
}

from claude_agent_sdk import query, ClaudeAgentOptions

messages = []

async for message in query(
    prompt="Add a new React component for user profiles",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",
        },
        setting_sources=["project"],  # โหลด CLAUDE.md จาก project
    ),
):
    messages.append(message)

Output styles สำหรับ configurations ที่คงทน

Output styles คือ saved configurations ที่แก้ไข system prompt ของ Claude เก็บเป็นไฟล์ markdown และสามารถนำมาใช้ซ้ำข้าม sessions และ projects

สร้าง output style

Output style คือไฟล์ markdown ที่มี frontmatter สำหรับ metadata บันทึกไปยัง ~/.claude/output-styles/ สำหรับ user-level style หรือ .claude/output-styles/ ในที่เก็บ repository ของคุณ

---
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)

Append ไปยัง preset `claude_code`

คุณสามารถใช้ Claude Code preset กับ property append เพื่อเพิ่ม custom instructions ของคุณในขณะที่รักษา built-in functionality ทั้งหมด

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);
  }
}

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

messages = []

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)

ปรับปรุง prompt caching ข้าม users และเครื่อง

โดย default สอง sessions ที่ใช้ claude_code preset และ append text เดียวกันยังไม่สามารถแชร์ prompt cache entry ได้หากรันจาก working directories ที่แตกต่างกัน นี่เป็นเพราะ preset ฝัง per-session context ใน system prompt

เพื่อทำให้ system prompt เหมือนกันข้าม sessions ให้ตั้ง excludeDynamicSections: true ใน TypeScript หรือ "exclude_dynamic_sections": True ใน Python:

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
    }
  }
})) {
  // ...
}

note

excludeDynamicSections ต้องการ @anthropic-ai/claude-agent-sdk v0.2.98 หรือใหม่กว่า หรือ claude-agent-sdk v0.1.58 หรือใหม่กว่าสำหรับ Python

Custom system prompts

คุณสามารถระบุ custom string เป็น systemPrompt เพื่อแทนที่ default ทั้งหมดด้วย instructions ของตัวเอง

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);
  }
}

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 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)

เปรียบเทียบสี่วิธี

Feature	CLAUDE.md	Output Styles	`systemPrompt` กับ append	Custom `systemPrompt`
Persistence	Per-project file	บันทึกเป็นไฟล์	Session เท่านั้น	Session เท่านั้น
Reusability	Per-project	ข้าม projects	Code duplication	Code duplication
Management	บน filesystem	CLI + files	ใน code	ใน code
Default tools	Preserved	Preserved	Preserved	หาย (ถ้าไม่รวม)
Built-in safety	Maintained	Maintained	Maintained	ต้องเพิ่มเอง
Environment context	Automatic	Automatic	Automatic	ต้อง provide
Customization level	เพิ่มเท่านั้น	แทนที่หรือขยาย default	เพิ่มเท่านั้น	Control ทั้งหมด
Version control	กับ project	ใช่	กับ code	กับ code
Scope	Project-specific	User หรือ project	Code session	Code session

Use Cases และ Best Practices

เมื่อไหร่ควรใช้ CLAUDE.md

ใช้ CLAUDE.md สำหรับ instructions ที่ควรใช้กับทุก session ใน project ไม่ว่าจะใช้ system prompt ไหน: coding standards, common commands, architecture context, และ team conventions

เมื่อไหร่ควรใช้ output styles

Output styles เหมาะสำหรับ personas ที่ต้องการนำมาใช้ซ้ำข้าม CLI และ SDK โดยไม่ต้องเปลี่ยน application code

ดีที่สุดสำหรับ:

การเปลี่ยนแปลงพฤติกรรมที่คงทนข้าม sessions
Team-shared configurations
Specialized assistants เช่น code reviewer, data scientist, หรือ DevOps assistant

เมื่อไหร่ควรใช้ `systemPrompt` กับ append

ใช้ append เมื่อ preset claude_code ตรงกับ product ของคุณแล้วและคุณต้องการเพิ่ม instructions เพิ่มเติมเท่านั้น

ดีที่สุดสำหรับ:

การเพิ่ม coding standards หรือ preferences เฉพาะ
ปรับแต่ง output formatting
เพิ่ม domain-specific knowledge

เมื่อไหร่ควรใช้ custom `systemPrompt`

ใช้ custom prompt เมื่อ surface, identity, หรือ permission model ของ agent ของคุณแตกต่างจาก Claude Code

ดีที่สุดสำหรับ:

Control ทั้งหมดเหนือพฤติกรรมของ Claude
Specialized single-session tasks
สร้าง specialized agents ที่มีพฤติกรรมเฉพาะ

ผสมวิธีต่างๆ

วิธีเหล่านี้สามารถ compose ได้ Output style หรือ CLAUDE.md ที่คงทนตั้งพฤติกรรมระยะยาว และ append เพิ่ม session-specific instructions ไว้บน:

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

// สมมติว่า "Code Reviewer" output style ถูกใช้งาน
// เพิ่ม focus areas เฉพาะ session
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);
}

ดูเพิ่มเติม

Output styles: สร้าง, จัดการ, และแชร์ output styles สำหรับ CLI
How Claude remembers your project: สิ่งที่ควรใส่ใน CLAUDE.md และวิธีเขียน instructions ที่มีประสิทธิภาพ
TypeScript SDK reference: type Options เต็ม รวมถึง systemPrompt, settingSources, และ settings
Python SDK reference: type ClaudeAgentOptions เต็ม รวมถึง system_prompt และ setting_sources

วิธีการทำงานของ System Prompts​

ตัดสินใจว่าจะใช้จุดเริ่มต้นไหน​

ปรับแต่งพฤติกรรม Agent​

ไฟล์ CLAUDE.md สำหรับ project-level instructions​

Output styles สำหรับ configurations ที่คงทน​

สร้าง output style​

Append ไปยัง preset claude_code​

ปรับปรุง prompt caching ข้าม users และเครื่อง​

Custom system prompts​

เปรียบเทียบสี่วิธี​

Use Cases และ Best Practices​

เมื่อไหร่ควรใช้ CLAUDE.md​

เมื่อไหร่ควรใช้ output styles​

เมื่อไหร่ควรใช้ systemPrompt กับ append​

เมื่อไหร่ควรใช้ custom systemPrompt​

ผสมวิธีต่างๆ​

ดูเพิ่มเติม​

วิธีการทำงานของ System Prompts

ตัดสินใจว่าจะใช้จุดเริ่มต้นไหน

ปรับแต่งพฤติกรรม Agent

ไฟล์ CLAUDE.md สำหรับ project-level instructions

Output styles สำหรับ configurations ที่คงทน

สร้าง output style

Append ไปยัง preset `claude_code`

ปรับปรุง prompt caching ข้าม users และเครื่อง

Custom system prompts

เปรียบเทียบสี่วิธี

Use Cases และ Best Practices

เมื่อไหร่ควรใช้ CLAUDE.md

เมื่อไหร่ควรใช้ output styles

เมื่อไหร่ควรใช้ `systemPrompt` กับ append

เมื่อไหร่ควรใช้ custom `systemPrompt`

ผสมวิธีต่างๆ

ดูเพิ่มเติม