Tuỳ chỉnh system prompt

System prompt định nghĩa hành vi, năng lực, và phong cách phản hồi của Claude. Bắt đầu từ preset claude_code cho các công cụ coding kiểu CLI hay IDE nơi có con người theo dõi và điều hướng công việc. Tự viết prompt riêng cho các agent có môi trường (surface), danh tính, hoặc mô hình quyền khác.

Trang này bao gồm:

• System prompt hoạt động thế nào, kèm bảng quyết định để chọn giữa preset, preset kèm append, và một prompt tùy chỉnh
• Tuỳ chỉnh hành vi agent bằng file CLAUDE.md, output style, append, hay một chuỗi tùy chỉnh
• So sánh bốn cách tiếp cận theo độ bền, phạm vi, và những gì được giữ lại
• Kết hợp các cách tiếp cận để chồng các phương pháp tuỳ chỉnh lên nhau

System prompt hoạt động thế nào

System prompt là tập chỉ dẫn ban đầu định hình cách Claude hành xử xuyên suốt hội thoại. Agent SDK có ba điểm khởi đầu cho nó:

• Mặc định tối giản: khi bạn không đặt systemPrompt trong TypeScript hay system_prompt trong Python, SDK dùng một prompt tối giản chỉ bao gồm việc gọi tool nhưng bỏ qua các hướng dẫn coding, phong cách phản hồi, và ngữ cảnh dự án của Claude Code. Điều này khác với claude -p, vốn dùng full Claude Code prompt theo mặc định. Nếu bạn đang chuyển từ CLI và muốn hành vi khớp nhau, hãy đặt preset claude_code.
• Preset claude_code: full system prompt mà Claude Code CLI dùng, gồm chỉ dẫn dùng tool, quy tắc style và format code, quy tắc tông giọng và độ chi tiết phản hồi, chỉ dẫn bảo mật và an toàn, và ngữ cảnh về thư mục làm việc và môi trường. Đặt systemPrompt: { type: "preset", preset: "claude_code" } trong TypeScript hoặc system_prompt={"type": "preset", "preset": "claude_code"} trong Python, tùy chọn kèm append để thêm chỉ dẫn riêng của bạn vào cuối.
• Chuỗi tùy chỉnh: một prompt bạn tự viết. SDK chỉ gửi những gì bạn cung cấp.

Chọn điểm khởi đầu

Yếu tố quyết định là agent của bạn giống Claude Code tới mức nào: một agent coding hoạt động trong một repository, với con người theo dõi output stream và điều hướng công việc. Sản phẩm của bạn càng khác điều đó, bạn càng cần tự viết prompt.

Bạn đang xây	Dùng	Bạn nhận được
Một công cụ coding kiểu CLI hay IDE nơi con người theo dõi và điều hướng, và mặc định của Claude Code là điều bạn muốn	Preset claude_code	Full Claude Code prompt: hướng dẫn dùng tool, quy tắc an toàn, phản hồi thân thiện với terminal, nhận biết convention repo
Cùng loại công cụ đó, cộng thêm quy tắc riêng của sản phẩm như coding standard, output format, hay ngữ cảnh domain	Preset claude_code kèm append	Mọi thứ ở trên, cộng chỉ dẫn của bạn thêm vào sau preset. Không gì bị loại bỏ, nên đây là cách tuỳ chỉnh ít rủi ro nhất
Một agent có môi trường, danh tính, hoặc mô hình quyền khác, hay một agent không làm coding	Chuỗi prompt tùy chỉnh	Chỉ những gì bạn viết. Bạn chịu trách nhiệm thay thế hướng dẫn dùng tool và chỉ dẫn an toàn mà agent của bạn vẫn cần
Một vòng lặp tool-calling đơn giản không có persona agent, nơi bạn cung cấp mọi hành vi trong user prompt	Không đặt tùy chọn systemPrompt	Mặc định tối giản: chỉ hỗ trợ gọi tool và không gì khác

“Khác với Claude Code” thường có nghĩa một trong những điều sau:

• Môi trường khác: output không được đọc trong terminal bởi người đã kích hoạt nó. Chat UI, các bên tiêu thụ structured output, và automation không phải coding đều cần một prompt khớp với cách output của chúng được render và review. Automation coding không giám sát, như một CI job sửa lỗi lint hay review diff, vẫn phù hợp với preset vì bản thân công việc là thứ preset được viết cho.
• Danh tính khác: agent không nên tự giới thiệu là Claude Code. Một support bot, một trợ lý phân tích dữ liệu, hay bất kỳ agent chuyên biệt domain nào cần tên, phạm vi, và persona riêng.
• Mô hình quyền khác: agent chạy tự động không có con người phê duyệt từng bước, hoặc hoạt động trên một tập tài nguyên hẹp. Prompt của Claude Code giả định có con người trong vòng lặp với quyền truy cập toàn bộ toolset.
• Tác vụ không phải coding: hầu hết prompt của Claude Code là hướng dẫn coding. Với agent nghiên cứu, nội dung, hay vận hành, hướng dẫn đó cạnh tranh với chỉ dẫn bạn thực sự cần.

Bảng so sánh cho thấy mỗi phương pháp tuỳ chỉnh giữ lại những gì.

Tuỳ chỉnh hành vi agent

Output style, append, và một chuỗi prompt tùy chỉnh đều thay đổi trực tiếp system prompt. CLAUDE.md đi theo hướng khác: SDK đọc nó và tiêm nội dung vào hội thoại như ngữ cảnh dự án, không phải vào system prompt, nên nó định hình hành vi song song với bất kỳ system prompt nào bạn chọn. Skills, hooks, và permissions cũng định hình hành vi ngoài system prompt và được nói riêng ở trang của chúng.

File CLAUDE.md cho chỉ dẫn cấp dự án

File CLAUDE.md cho Claude ngữ cảnh và chỉ dẫn bền vững về dự án. SDK tiêm nội dung của chúng vào hội thoại, không phải vào system prompt, nên chúng hoạt động với bất kỳ cấu hình system prompt nào. Để biết nên viết gì trong CLAUDE.md, đặt ở đâu, và cách viết chỉ dẫn hiệu quả, xem Cách Claude ghi nhớ dự án của bạn. Phần này nói về những gì riêng của SDK: cách CLAUDE.md được load.

SDK đọc CLAUDE.md khi setting source tương ứng được bật: 'project' load CLAUDE.md hoặc .claude/CLAUDE.md từ thư mục làm việc, và 'user' load ~/.claude/CLAUDE.md. Tùy chọn query() mặc định bật cả hai source, nên CLAUDE.md tự động được load. Nếu bạn đặt settingSources trong TypeScript hay setting_sources trong Python một cách tường minh, hãy đưa vào các source bạn cần. Việc load CLAUDE.md được kiểm soát bởi setting source, không phải bởi preset claude_code.

Load CLAUDE.md với SDK

Để load CLAUDE.md, đặt settingSources để gồm cấp mà CLAUDE.md của bạn tồn tại. Ví dụ dưới đây load một CLAUDE.md cấp dự án cùng với preset claude_code, nên Claude có cả full coding-agent prompt lẫn convention dự án của bạn:

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" // Dùng system prompt của Claude Code
    },
    settingSources: ["project"] // Load CLAUDE.md từ dự án
  }
})) {
  messages.push(message);
}

// Giờ Claude có quyền truy cập chỉ dẫn dự án của bạn từ 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",  # Dùng system prompt của Claude Code
            },
            setting_sources=["project"],  # Load CLAUDE.md từ dự án
        ),
    ):
        messages.append(message)


asyncio.run(main())

# Giờ Claude có quyền truy cập chỉ dẫn dự án của bạn từ CLAUDE.md

Khi bạn chạy một trong hai ví dụ, SDK trả về message khi Claude làm việc: một system init message, assistant message, user message mang tool result, và một result message cuối cùng với kết quả session.

CLAUDE.md bền vững qua mọi session trong một dự án, chia sẻ với team qua git, và được tự động phát hiện mà không cần sửa code. Nó không được load nếu bạn truyền một mảng settingSources rỗng.

Output style cho cấu hình bền vững

Output style là các cấu hình đã lưu, sửa system prompt của Claude. Chúng được lưu dưới dạng file markdown và có thể tái sử dụng qua các session và dự án.

Tạo một output style

Một output style là một file markdown có frontmatter cho metadata, theo sau là nội dung prompt. Lưu nó vào ~/.claude/output-styles/ cho một style cấp người dùng khả dụng ở mọi dự án, hoặc .claude/output-styles/ trong repository của bạn cho một style cấp dự án bạn có thể commit và chia sẻ với team.

Mặc định, một output style tùy chỉnh thay thế chỉ dẫn software engineering của preset claude_code bằng chỉ dẫn riêng của bạn. Để giữ chúng và chồng chỉ dẫn của bạn lên trên, đặt keep-coding-instructions: true trong frontmatter. Giữ chúng khi agent của bạn vẫn đang làm công việc software engineering. Bỏ chúng khi bạn thay thế hoàn toàn vai trò.

Ví dụ dưới đây định nghĩa một persona review code giữ lại chỉ dẫn coding, vì review code vẫn hưởng lợi từ hướng dẫn bảo mật và chất lượng code của Claude Code. Lưu nó thành ~/.claude/output-styles/code-reviewer.md để dùng được ở mọi dự án:

~/.claude/output-styles/code-reviewer.md

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

Kích hoạt một output style

Sau khi tạo, kích hoạt output style qua:

• CLI: chạy /config và chọn một output style

• Settings: đặt outputStyle trong .claude/settings.local.json

• TypeScript SDK: đặt outputStyle bên trong object settings inline truyền cho query(), hoặc trỏ settings tới một file settings đặt nó. outputStyle không phải trường cấp cao nhất của Options:

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

Python SDK không có tùy chọn để chọn output style theo cách lập trình. Với các deployment chỉ-code không thể ghi vào .claude/settings.local.json, dùng append hoặc một chuỗi prompt tùy chỉnh thay vào đó.

Lưu ý cho người dùng SDK: output style được load khi bạn đưa settingSources: ['user'] hay settingSources: ['project'] (TypeScript) / setting_sources=["user"] hay setting_sources=["project"] (Python) vào tùy chọn của bạn.

Append vào preset claude_code

Bạn có thể dùng Claude Code preset kèm một property append để thêm chỉ dẫn tùy chỉnh trong khi vẫn giữ mọi chức năng built-in.

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

Cải thiện prompt caching qua nhiều người dùng và máy

Mặc định, hai session dùng cùng preset claude_code và cùng text append vẫn không thể chia sẻ một prompt cache entry nếu chúng chạy từ working directory khác nhau. Đó là vì preset nhúng ngữ cảnh riêng của mỗi session vào system prompt trước text append của bạn: working directory, có phải git repository hay không, platform, shell đang dùng, phiên bản OS, và đường dẫn auto-memory. Bất kỳ khác biệt nào trong ngữ cảnh đó tạo ra một system prompt khác và một cache miss. Nội dung CLAUDE.md không ảnh hưởng tới system prompt cache vì SDK tiêm nó vào hội thoại, không phải system prompt.

Để làm system prompt giống hệt nhau qua các session, đặt excludeDynamicSections: true trong TypeScript hoặc "exclude_dynamic_sections": True trong Python. Ngữ cảnh riêng của mỗi session chuyển vào user message đầu tiên, để lại chỉ preset tĩnh và text append của bạn trong system prompt, cho phép các cấu hình giống hệt nhau chia sẻ một cache entry qua nhiều người dùng và máy.

Ghi chú

excludeDynamicSections yêu cầu @anthropic-ai/claude-agent-sdk v0.2.98 trở lên, hoặc claude-agent-sdk v0.1.58 trở lên cho Python. Nó chỉ áp dụng cho dạng object preset và không có tác dụng khi systemPrompt là một chuỗi.

Ví dụ sau kết hợp một khối append dùng chung với excludeDynamicSections để một đội agent chạy từ các thư mục khác nhau có thể tái sử dụng cùng system prompt đã cache:

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

Đánh đổi: working directory, cờ git-repo, platform, shell đang dùng, phiên bản OS, và đường dẫn auto-memory vẫn tới được Claude, nhưng là một phần của user message đầu tiên thay vì system prompt. Chỉ dẫn trong user message có trọng số nhẹ hơn một chút so với cùng text đó trong system prompt, nên Claude có thể dựa vào chúng ít mạnh hơn khi suy luận về thư mục hiện tại hay đường dẫn auto-memory. Bật tùy chọn này khi việc tái sử dụng cache qua các session quan trọng hơn ngữ cảnh môi trường có trọng số cao nhất.

Với flag tương đương trong chế độ CLI non-interactive, xem --exclude-dynamic-system-prompt-sections.

System prompt tùy chỉnh

Bạn có thể cung cấp một chuỗi tùy chỉnh làm systemPrompt để thay thế hoàn toàn mặc định bằng chỉ dẫn riêng của bạn.

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

Trong Python, load một custom prompt lớn từ file bằng system_prompt={"type": "file", "path": "..."} thay vì truyền dưới dạng chuỗi. Python SDK truyền một chuỗi prompt như một command-line argument duy nhất cho CLI subprocess, nên một prompt vượt giới hạn độ dài argument của OS sẽ lỗi ngay khi spawn process trước khi có bất kỳ request API nào được gửi. Trên Linux, lỗi là Argument list too long. Xem SystemPromptFile để biết ngưỡng theo từng platform và hành vi trên Windows.

So sánh bốn cách tiếp cận

Bốn phương pháp tuỳ chỉnh khác nhau ở nơi chúng tồn tại, cách chúng được chia sẻ, và những gì chúng giữ lại từ preset claude_code.

Tính năng	CLAUDE.md	Output Styles	systemPrompt kèm append	systemPrompt tùy chỉnh
Độ bền	File theo dự án	Lưu dưới dạng file	Chỉ trong session	Chỉ trong session
Tái sử dụng	Theo dự án	Qua các dự án	Trùng lặp code	Trùng lặp code
Quản lý	Trên filesystem	CLI + file	Trong code	Trong code
Tool mặc định	Được giữ lại	Được giữ lại	Được giữ lại	Mất (trừ khi thêm vào)
An toàn built-in	Được duy trì	Được duy trì	Được duy trì	Phải tự thêm
Ngữ cảnh môi trường	Tự động	Tự động	Tự động	Phải tự cung cấp
Mức tuỳ chỉnh	Chỉ thêm	Thay thế hoặc mở rộng mặc định	Chỉ thêm	Toàn quyền kiểm soát
Version control	Cùng dự án	Có	Cùng code	Cùng code
Phạm vi	Theo dự án	Người dùng hoặc dự án	Session code	Session code

“Kèm append” nghĩa là dùng systemPrompt: { type: "preset", preset: "claude_code", append: "..." } trong TypeScript hoặc system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} trong Python. CLAUDE.md không thay đổi bản thân system prompt: SDK tiêm nội dung của nó vào hội thoại như ngữ cảnh dự án.

Use case và best practice

Khi nào dùng CLAUDE.md

Dùng CLAUDE.md cho chỉ dẫn nên áp dụng cho mọi session trong một dự án, bất kể session đó dùng system prompt nào: coding standard, lệnh thường dùng, ngữ cảnh kiến trúc, và convention team. CLAUDE.md được commit vào repository của bạn, nên nó luôn đồng bộ với code nó mô tả. Xem Khi nào nên thêm vào CLAUDE.md để biết hướng dẫn đầy đủ.

File CLAUDE.md được load khi setting source project được bật, vốn được bật theo mặc định cho tùy chọn query(). Nếu bạn đặt settingSources trong TypeScript hay setting_sources trong Python một cách tường minh, hãy đưa 'project' vào để tiếp tục load CLAUDE.md cấp dự án.

Khi nào dùng output style

Output style dành cho các persona bạn muốn tái sử dụng qua CLI và SDK mà không sửa code ứng dụng. Vì chúng tồn tại dưới dạng file trong .claude/output-styles, cùng một persona khả dụng từ /config trong CLI và từ bất kỳ SDK session nào load setting source tương ứng.

Phù hợp nhất cho:

• Thay đổi hành vi bền vững qua các session
• Cấu hình chia sẻ trong team
• Trợ lý chuyên biệt như code reviewer, data scientist, hay DevOps assistant
• Sửa đổi prompt phức tạp cần versioning

Ví dụ:

• Tạo một trợ lý tối ưu SQL chuyên dụng
• Xây một code reviewer tập trung bảo mật
• Phát triển một trợ giảng với phương pháp sư phạm cụ thể

Khi nào dùng systemPrompt kèm append

Dùng append khi preset claude_code đã khớp với sản phẩm của bạn và bạn chỉ cần chồng thêm chỉ dẫn. Bạn giữ lại hướng dẫn dùng tool, quy tắc an toàn, và convention coding của preset mà không cần tự implement lại.

Phù hợp nhất cho:

• Thêm coding standard hay sở thích cụ thể
• Tuỳ chỉnh format output
• Thêm kiến thức chuyên biệt domain
• Sửa độ chi tiết phản hồi
• Nâng cao hành vi mặc định của Claude Code mà không mất chỉ dẫn tool

Khi nào dùng systemPrompt tùy chỉnh

Dùng một prompt tùy chỉnh khi môi trường, danh tính, hay mô hình quyền của agent bạn khác với Claude Code, như mô tả trong Chọn điểm khởi đầu. Bạn định nghĩa toàn bộ tập chỉ dẫn, gồm bất kỳ hướng dẫn tool hay quy tắc an toàn nào agent của bạn cần.

Phù hợp nhất cho:

• Toàn quyền kiểm soát hành vi của Claude
• Tác vụ chuyên biệt trong một session
• Thử nghiệm chiến lược prompt mới
• Tình huống không cần tool mặc định
• Xây agent chuyên biệt với hành vi riêng

Kết hợp các cách tiếp cận

Các phương pháp này có thể ghép nối. Một output style bền vững hay CLAUDE.md đặt hành vi lâu dài, và append chồng chỉ dẫn riêng cho session lên trên mà không đụng tới cấu hình đã lưu.

Kết hợp một output style với bổ sung riêng cho session

Ví dụ dưới đây giả định một output style Code Reviewer đã được kích hoạt. Khối append chồng các trọng tâm riêng cho session lên trên persona, nên một buổi review đơn lẻ có thể ưu tiên OAuth và lưu trữ token mà không cần thay đổi output style đã lưu:

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

// Giả sử output style "Code Reviewer" đã được kích hoạt (qua /config hoặc settings)
// Thêm các trọng tâm riêng cho session này
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

# Giả sử output style "Code Reviewer" đã được kích hoạt (qua /config hoặc settings)
# Thêm các trọng tâm riêng cho session này
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())

Xem thêm

• Output styles: tạo, quản lý, và chia sẻ output style cho CLI, gồm định dạng file và nơi lưu trữ
• Cách Claude ghi nhớ dự án của bạn: nên viết gì trong CLAUDE.md, đặt ở đâu, và cách viết chỉ dẫn dự án hiệu quả
• TypeScript SDK reference: kiểu Options đầy đủ, gồm systemPrompt, settingSources, và settings
• Python SDK reference: kiểu ClaudeAgentOptions đầy đủ, gồm system_prompt và setting_sources
• Settings: tài liệu tham khảo settings.json, gồm nơi lưu output style và các cấu hình khác

Nguồn

Dịch và biên soạn từ Modifying system prompts.