Claude Code 2026 自訂系統提示詞指南：覆蓋預設、追加指令及不可更改項目

Claude Code Custom System Prompts in 2026: Overriding Defaults, Appending Instructions, and What You Cannot Change

This article was written with the assistance of AI, under human supervision and review.

Developers add custom instructions to Claude Code, restart the session, and watch Claude ignore them. The instructions sit in a CLAUDE.md file, or a settings.json key, or an --append-system-prompt flag, but Claude still responds with the default behavior. This confusion stems from a misunderstanding of where each layer applies and what the system prompt actually controls.

Claude Code provides three distinct mechanisms for shaping behavior: replacing or appending to the system prompt with CLI flags, defining persistent project context in CLAUDE.md files, and configuring output styles that transform how Claude formats responses. Each mechanism operates at a different layer of the request cycle, and mixing them without understanding their boundaries produces configuration that appears broken but is working exactly as designed.

The system prompt itself is not a single editable file. Claude Code builds it from multiple sources at request time, and certain parts remain locked regardless of configuration. Understanding which parts you can change, which require a different mechanism, and which remain fixed is the difference between instructions that work and instructions that vanish.

This post examines the three ways to customize Claude Code behavior, explains what each mechanism controls, and clarifies which built-in behaviors cannot be changed no matter which layer you modify.

Key Takeaways

• Claude Code builds the system prompt from multiple sources; replacing or appending text with CLI flags changes the core identity and tool guidance, while CLAUDE.md injects project context into the conversation separately.
• The --system-prompt flag replaces the entire default prompt including tool descriptions and safety instructions, while --append-system-prompt preserves the default and adds extra rules on top.
• CLAUDE.md files do not modify the system prompt; they inject content into the conversation as project context that Claude reads alongside the system prompt.
• Output styles, skills, and permission rules shape behavior through separate mechanisms that remain active regardless of system prompt customization.
• Built-in safety instructions, tool definitions, and API-level constraints cannot be overridden through any system prompt flag or configuration file.

Understanding System Prompt Presets: claude_code vs Custom Strings

Claude Code does not expose the full default system prompt as an editable file. The official documentation confirms this: "Claude Code's system prompt isn't published. To give Claude standing instructions, use CLAUDE.md files or the --append-system-prompt flag." Developers who expect a single text file controlling Claude's identity will not find one, because the prompt assembles from multiple internal sources at runtime.

The default prompt includes the following components:

• Core identity and role definition
• Tool descriptions and usage guidance for each available capability
• Safety and security instructions
• Coding conventions and best practices
• Output formatting rules

When developers pass --system-prompt or --system-prompt-file, they replace all of these components with their own text. Claude Code discards the default identity, tool guidance, and safety instructions, leaving the developer responsible for defining everything from scratch.

This replacement makes sense for non-coding agents where Claude Code's default identity does not fit the task, but it creates problems when developers simply want to add domain-specific rules without rebuilding the entire prompt. For that use case, --append-system-prompt preserves the default and adds extra instructions after it.

The choice between replacement and append determines whether developers inherit Claude Code's built-in tool guidance. A replaced prompt loses descriptions of how the Bash tool works, when to use Read versus Write, and which permission checks apply before tool execution. An appended prompt keeps those descriptions and layers new instructions on top.

Appending Instructions: Extending the Default Without Starting From Scratch

The --append-system-prompt and --append-system-prompt-file flags let developers extend the default prompt without replacing it. This preserves Claude Code's identity as a coding assistant while adding project-specific conventions, output requirements, or domain context.

A typical use case: enforcing a consistent code review format. Developers want Claude to check for specific patterns in every review without changing how Claude uses tools or responds to questions. Appending instructions achieves this:

// Start Claude Code with custom review rules appended
// Shell command:
// claude --append-system-prompt-file ./review-rules.txt

// Contents of review-rules.txt:
When reviewing code, always check for:
1. Missing error handling in async functions
2. Hardcoded configuration values that should be environment variables
3. Console.log statements that should be removed before production
4. Tests that need updating after implementation changes

Format your review as:
- Summary (2-3 sentences)
- Findings (bulleted list with file:line references)
- Risk level (low/medium/high)

Claude receives the default system prompt followed by a blank line and then the appended text. The blank line separates the default instructions from the custom rules, making the boundary clear when debugging what Claude sees.

Developers can combine both inline text and file contents by passing both --append-system-prompt and --append-system-prompt-file in the same command (requires Claude Code v2.1.283 or later). The file contents appear first, followed by a blank line, then the inline text:

// Combine file and inline instructions
// Shell command:
// claude --append-system-prompt-file ./style.md --append-system-prompt "Always reply in French"

// Claude receives:
// 1. Default system prompt
// 2. Blank line
// 3. Contents of style.md
// 4. Blank line
// 5. "Always reply in French"

This ordering ensures that persistent style rules from the file remain stable across runs while allowing per-invocation overrides through the inline flag.

Claude Code system prompt layers

The appended text applies to a single session. Starting a new session without the flags returns to the default prompt. Developers who need persistent instructions that apply across all sessions should use CLAUDE.md files instead, which inject content at a different layer.

CLAUDE.md vs System Prompts: What Actually Goes Where

CLAUDE.md files do not modify the system prompt. This distinction trips up developers who expect CLAUDE.md to work like a persistent --append-system-prompt, but CLAUDE.md operates through a separate mechanism that injects content into the conversation as project context.

The Agent SDK documentation states: "CLAUDE.md takes a different path: the SDK reads it and injects its content into the conversation as project context, so it shapes behavior alongside whichever system prompt you choose." This injection happens after the system prompt is built, meaning CLAUDE.md cannot override tool guidance or safety instructions that live in the system prompt layer.

CLAUDE.md excels at defining what the project is, what conventions it follows, and what context Claude needs to understand it. System prompt flags excel at defining who Claude is and how Claude should respond. When developers put project conventions in the system prompt or try to redefine Claude's identity in CLAUDE.md, the configuration fights against the mechanism's design.

A well-structured setup uses CLAUDE.md for project facts:

// .claude/CLAUDE.md contents:
# Project: TypeScript API Server

This project uses:
- Express 4.18 with TypeScript 5.3
- Jest for testing with 80%+ coverage requirement
- Zod for runtime validation
- Prisma 5.x for database access

Conventions:
- All API routes live in src/routes/
- Database models use singular names (User, not Users)
- Environment variables are required at startup (fail fast)
- Error responses follow RFC 7807 Problem Details format

And system prompt flags for response requirements:

// Pass this flag when starting Claude Code:
// --append-system-prompt "When suggesting code changes, always include the full file path and a brief explanation of why the change is needed"

This separation lets developers change project facts without touching how Claude formats responses, and change response formatting without modifying project documentation.

What You Cannot Override: Built-In Safety, Tool Definitions, and Hard Limits

Certain parts of Claude Code behavior remain fixed regardless of system prompt configuration. These restrictions protect against unsafe operations, ensure consistent tool behavior, and enforce API-level constraints that no client-side configuration can bypass.

Three categories of behavior cannot be overridden:

Safety and security instructions. Claude Code includes built-in rules that prevent certain operations even when the system prompt requests them. These rules operate at a layer below the system prompt, meaning a custom --system-prompt text cannot remove them. Examples include refusal to generate malware, restrictions on processing sensitive data without explicit permission, and guardrails against executing commands that could compromise the system.

Tool definitions and behavior. The tools Claude Code exposes (Bash, Read, Write, Edit, and others) have fixed definitions that describe their parameters, when to use them, and what they return. A custom system prompt can provide additional guidance on tool usage, but it cannot change the tool's signature or disable built-in tool restrictions. For instance, developers cannot use --system-prompt to make the Read tool bypass permission checks or force the Bash tool to run commands without approval when project settings require it.

API and model constraints. Token limits, rate limits, and model capabilities are set by the Anthropic API and cannot be increased through configuration. A system prompt that requests "unlimited context window" has no effect because the constraint exists at the API layer, not in Claude Code's client logic.

Developers who attempt to override these restrictions through creative prompt engineering will find that Claude Code silently ignores the instructions or Claude refuses the request. The official documentation warns: "Replacing drops all of the default prompt, including tool guidance and safety instructions, so you take responsibility for whatever your task still needs." This warning applies to guidance developers can provide, not to safety checks they cannot remove.

The distinction matters when debugging why certain instructions fail. If a custom system prompt asks Claude to "always read .env files without asking," the request fails not because the prompt is malformed but because permission checks happen after the prompt is processed. The solution is not better prompt engineering but configuring permissions through the separate permissions mechanism.

Real-World Patterns: Output Styles, Skills, and Hooks That Shape Behavior Outside the System Prompt

Claude Code provides three additional mechanisms for shaping behavior that operate independently of the system prompt: output styles, skills, and hooks. Each mechanism targets a different aspect of Claude's responses, and understanding when to use each prevents configuration conflicts.

Output styles transform how Claude formats responses without changing the underlying reasoning or tool usage. An output style might enforce markdown structure, add specific headers to code blocks, or require responses to follow a template. Output styles apply after Claude generates a response, meaning they cannot change which tools Claude chooses or what logic Claude follows. The official documentation states: "an output style changes the instructions Claude Code gives Claude for every response."

Skills add specific capabilities that Claude loads on demand. A skill defines when to run (through YAML frontmatter), what dynamic context to inject (through command substitution), and what instructions to follow when active. Skills operate through the conversation context layer, not the system prompt layer, which means they remain available even when developers replace the system prompt entirely.

Hooks execute code at specific points in the request lifecycle: before a request is sent, after Claude responds, or when specific events occur. Hooks can modify the request, transform the response, or trigger external actions. They run in the Claude Code runtime, not as instructions to Claude, which gives them capabilities that system prompts cannot replicate.

A practical example demonstrates the difference. Developers building a documentation generator want Claude to:

1. Read TypeScript source files
2. Extract JSDoc comments and type definitions
3. Format the output as markdown with specific section headers
4. Inject the result into a template
5. Write the final documentation to a file

This workflow spans multiple mechanisms:

// 1. CLAUDE.md defines project conventions
// .claude/CLAUDE.md:
# Documentation Standards
All exported functions must have JSDoc comments with @param and @returns tags.
Type definitions use TypeScript 5.3 syntax.

// 2. Skill provides dynamic context
// .claude/skills/doc-gen/SKILL.md:
---
description: Generate documentation from TypeScript source files
---
## Current files
!`find src -name "*.ts" -not -path "*/test/*"`

## Instructions
Extract JSDoc comments and type definitions from the files above.

// 3. Output style enforces format
// .claude/output-styles/docs/style.md:
Format documentation as:
## Function Name
Description from JSDoc

**Parameters:**
- param: type - description

**Returns:** return type - description

// 4. Hook writes to file
// .claude/hooks/after-response.ts:
export default async function(response, context) {
  if (context.skill === 'doc-gen') {
    await writeFile('./docs/api.md', response.text);
  }
}

Attempting to implement this workflow through a single --system-prompt flag would fail because the system prompt cannot read files dynamically (skill functionality), format output conditionally (output style functionality), or write files after Claude responds (hook functionality). Each mechanism exists because it solves a problem the system prompt cannot address alone.

Claude Code configuration mechanisms

The documentation's guidance remains relevant: "For persistent personas you can switch between and share across a project, use output styles. For project conventions Claude should always follow, use CLAUDE.md." System prompt flags are for identity and per-invocation instructions, not for persistent behavior that should survive across sessions.

Common Mistakes: Why Your System Prompt Feels Ignored

Developers report that Claude ignores custom system prompts, but the problem usually sits in one of three areas: recording behavior, layer mismatches, or permission conflicts. Understanding these failure modes prevents hours of debugging configuration that is working correctly but not in the way developers expect.

Recording behavior in resumed conversations. By default, Claude Code builds the system prompt once on the first request of a conversation and records it. Later requests in the same conversation reuse that recorded prompt, even if developers pass different --system-prompt flags when resuming with --continue. The official documentation explains: "Until the conversation is compacted, every later request uses that recorded prompt, including after you return to the conversation with --resume or --continue."

This design optimizes for consistent behavior across a multi-turn conversation, but it surprises developers who expect system prompt changes to apply immediately. The solution is passing --system-prompt-snapshot off, which rebuilds the prompt on every request. This flag is essential during development when iterating on prompt wording:

// Iterate on system prompt wording without starting new sessions
// Shell command:
// claude --append-system-prompt "Draft rules v3" --system-prompt-snapshot off --continue

// Each run rebuilds the prompt with the new text
// Perfect for testing different phrasings

Layer mismatches. Developers put instructions in CLAUDE.md expecting them to override tool behavior, or they put project facts in --system-prompt expecting persistence across sessions. Both configurations fail because the instructions sit in the wrong layer. CLAUDE.md cannot override tool guidance that lives in the system prompt, and system prompt flags do not persist across sessions without being passed on every launch.

The fix is moving instructions to the correct layer: tool behavior overrides go in --system-prompt (which replaces the default including tool guidance), project conventions go in CLAUDE.md, and per-session response formatting goes in --append-system-prompt or output styles.

Permission conflicts. A system prompt can request specific tool behavior, but permission checks run separately and take precedence. If a system prompt says "always read package.json without asking" but project permissions require approval for Read operations, the permission check blocks the read regardless of what the system prompt requests. The official documentation confirms: "an allowed-tools grant goes through the normal permission flow."

Developers who encounter this conflict must configure permissions through the separate permissions mechanism (allow/ask/deny rules in settings.json or through permission prompts) rather than attempting to bypass permissions through prompt engineering. The permissions documentation describes the full syntax, and our production guide covers common permission patterns.

A fourth category of confusion stems from character restrictions in skill names and frontmatter. If a skill appears to load but its command does not work, the official documentation lists characters that Claude Code refuses: "Claude Code refuses a command name or a frontmatter name that contains characters such as: zero-width space or control character, private-use or unassigned character, character that changes text direction, blank other than one plain space, < or >." Renaming the skill folder or editing the name field in frontmatter resolves the issue, and the debug log (claude --debug) shows which names were refused.

Frequently Asked Questions

How do I make my custom system prompt persist across all sessions?

You cannot make a --system-prompt or --append-system-prompt flag persist automatically. These flags apply to the session you start them with. For instructions that should apply to all sessions in a project, put them in a CLAUDE.md file in the project's .claude/ directory. For cross-project conventions, create a script or alias that starts Claude Code with your preferred flags.

Why does Claude ignore my CLAUDE.md file?

CLAUDE.md does not modify the system prompt and cannot override built-in tool behavior or safety instructions. It injects content into the conversation as project context, which means it works best for defining what the project is and what conventions it follows, not for changing how Claude uses tools or formats responses. If your CLAUDE.md contains instructions about tool usage or response formatting, move them to an --append-system-prompt flag or an output style.

Can I disable Claude Code's safety instructions through a custom system prompt?

No. Safety and security checks operate at a layer below the system prompt. Even when you replace the entire default prompt with --system-prompt, the API-level safety checks remain active. This restriction exists to prevent accidental or intentional misuse and cannot be bypassed through any client-side configuration.

What happens when I pass both --system-prompt and --append-system-prompt?

Claude Code uses both. The --system-prompt flag replaces the default prompt, and then --append-system-prompt adds your extra text after that replacement. This combination is useful when you need a non-coding identity (through replacement) but still want to add per-invocation instructions (through append). With Claude Code v2.1.283 or later, you can also combine the inline and file forms of the same flag.

How do I debug which system prompt Claude is actually receiving?

Claude Code does not publish the full system prompt text, but you can confirm which sources loaded by running /status inside a session and checking the "Setting sources" line. For more details, run claude --debug from your shell and search the debug log for prompt-related entries. The log shows which settings files loaded and which system prompt flags applied, though it does not dump the full prompt text.

Conclusion: Choosing the Right Layer for Your Custom Instructions

System prompt customization in Claude Code requires understanding three distinct layers: the prompt itself (controlled through CLI flags), project context (injected through CLAUDE.md), and behavior modifications (implemented through output styles, skills, and hooks). Developers who put every instruction in the system prompt discover that some work, some vanish, and some conflict with other mechanisms. The configuration is not broken but is fighting against the layer where each mechanism operates.

Replace the system prompt when the default identity does not fit the task. Append to it when you need per-invocation instructions that preserve tool guidance. Use CLAUDE.md for project facts that should persist across sessions. Configure output styles for response formatting, skills for on-demand capabilities, and hooks for request lifecycle modifications. The official documentation at code.claude.com/docs covers each mechanism in detail, and the memory strategies guide explores how these layers interact with Claude's context handling.