System Prompts & CLAUDE.md

There are three ways to give Claude instructions beyond the prompt itself: --append-system-prompt adds rules on top of the defaults, --system-prompt replaces the defaults entirely, and CLAUDE.md files provide persistent project-level configuration that survives compaction. Choosing the right one determines whether Claude keeps its safety guidelines, how much you pay per call, and whether your rules stick around across sessions.

—append-system-prompt

This is the safe, additive approach. Your text is appended to the end of the default system prompt, so Claude keeps all of its built-in safety guidelines, tool instructions, and coding conventions. Your rules are layered on top.

The appended text becomes part of the system prompt that Claude sees, but nothing is removed. This is the right choice for most use cases: forcing plan mode for complex requests, adding code review criteria, injecting domain-specific rules like “always use TypeScript strict mode,” or setting output format constraints.

# Force plan-first behavior for complex tasks
claude -p "Refactor the auth module" \
  --append-system-prompt "When the user brings a list of changes, \
immediately call EnterPlanMode and research the codebase before presenting a plan."

# Security review with structured output rules
claude -p "Review auth.py" \
  --append-system-prompt "Focus exclusively on SQL injection and XSS vulnerabilities. \
Rate each finding as Critical, High, Medium, or Low."

—system-prompt

This flag replaces the entire default Claude Code system prompt. Everything built in — safety guidelines, tool usage instructions, coding conventions, permission handling rules, git safety protocols, tone and style directives — is gone. Claude becomes a blank slate that follows only what you provide.

Full override is the right tool when you want Claude to be a completely different persona — a Gandalf chatbot, a language tutor, a pure JSON transformer. Pair it with --tools "" to disable file system access and create a sandboxed persona:

# Pure persona with no tool access
claude -p "Tell me about yourself" \
  --system-prompt "You are Gandalf the Grey. Speak in character." \
  --tools ""

CLAUDE.md

Both --system-prompt and --append-system-prompt are ephemeral. They apply only to the current claude -p invocation and are not preserved when you --resume a session. For persistent, project-level instructions, use CLAUDE.md.

A CLAUDE.md file is loaded from disk at session start and re-read after compaction. This means your rules survive the /compact command and long sessions that trigger auto-compaction. Place the file in your project root, and every session launched from that directory inherits the instructions.

## Coding Standards
- Use TypeScript strict mode for all new files
- Prefer named exports over default exports
- All functions must have JSDoc comments

## Git Rules
- Never commit directly to main
- Prefix commit messages with feat:, fix:, or chore:

When to Use Which

Token Cost: Override vs Append

The system prompt mechanism you choose has a direct impact on token counts and cost. A full override with a short prompt uses fewer cached tokens than the ~14K default. Appending creates new cache entries for the combined prompt.

The override call costs $0.015 with 8,811 cached read tokens. The append call costs $0.061 with 9,124 cache creation tokens because the combined default-plus-appended prompt had to be cached fresh. On subsequent calls with the same appended text, the creation cost drops as the cache is reused.

All Three Layers Compose

A common misconception: --system-prompt replaces CLAUDE.md. It does not. All three context layers are active simultaneously:

Testing with --system-prompt "pirate speak" + --append-system-prompt "end with ARRR" + a CLAUDE.md containing “mention TEST_PROJECT”, all three instructions were followed in every response. The effective context stack is: [--system-prompt OR default] + [CLAUDE.md hierarchy] + [--append-system-prompt].

Gotchas