4.2 KiB
| type | subtype | title | summary | tags | scope | last_updated | date | last_reviewed | related | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| reference | pattern/framework | Claude Code system-prompt customization surface — mechanisms, risks, subtract-first finding | Every supported mechanism for shaping Claude Code's session context (append vs full replacement, exclude-dynamic-sections, tool restriction, setting sources, output styles, per-session plugin enablement), the risk profile of each, and the measured finding that self-added layers (CLAUDE.md, plugins, hooks) usually dwarf Anthropic's built-in prompt as the bloat source. |
|
global | 2026-07-08 | 2026-07-08 | 2026-07-08 |
|
Claude Code system-prompt customization surface
Verified 2026-07-08 against claude --help and
https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md
Mechanisms (CLI + Agent SDK)
| Mechanism | Effect | Risk |
|---|---|---|
--append-system-prompt[-file] |
Adds after the full default prompt; nothing removed | None |
--system-prompt[-file] |
Full replacement for the session (works interactively, not just -p) |
High: loses tool guidance, safety rules, env context; re-broken by every CC update |
--exclude-dynamic-system-prompt-sections (SDK: excludeDynamicSections) |
Moves per-machine sections (cwd, git status, OS, memory paths) into the first user message so identical configs share a prompt-cache entry across machines/users | Low; env context carries marginally less weight from the user message |
--tools <list> / --disallowedTools |
Restricts built-in toolset → removes tool schemas from context | Low |
--settings <file> / --setting-sources user,project,local |
Controls which settings layers load — and therefore which CLAUDE.md files, enabled plugins, and hooks apply | Low |
Output styles (~/.claude/output-styles/*.md) |
Replace the coding-instructions section of the default prompt, or extend it with keep-coding-instructions: true; persistent, reusable, officially supported partial replacement |
Medium |
Per-profile plugin enablement (settings overlay with its own enabledPlugins) |
Every enabled plugin injects its skill/agent/hook descriptions into every session; disabling irrelevant plugins is the single biggest quick win | Low |
Agent SDK systemPrompt |
{type:'preset', preset:'claude_code', append, excludeDynamicSections} or a custom string; SDK default (no option) is a minimal prompt, unlike the CLI |
— |
CLAUDE.md is injected into the conversation, not the system prompt — it works under any system-prompt configuration and doesn't affect the system-prompt cache entry.
Key facts for cost reasoning
- The built-in prompt is a static cached prefix: after turn 1 (within the 5-min cache TTL) it's re-read at ~10% of input price. Size still costs linearly every turn, and large context degrades attention ("context rot") regardless of source.
- Deferred tool loading (ToolSearch) already removed most tool-schema cost from the default prompt in current CC versions.
- Measured on a real heavy setup (cc-os, 2026-07-08): project CLAUDE.md ~11k tokens, 17 enabled plugins' skills/agents listing several k tokens, memsearch SessionStart injection ~3k tokens, plus multiple hook injections — the self-added layers dwarf the built-in prompt as the controllable bloat source.
Subtract-first pattern
For lean/profiled sessions, prefer (in order): (1) diet the always-on layers (CLAUDE.md size,
plugin enablement per profile, hook output); (2) compose profiles with
--append-system-prompt-file + --tools + settings overlays via a launcher wrapper;
(3) output styles for persona-level partial replacement; (4) full --system-prompt
replacement only as an eval-gated experiment in headless runs — it is maintaining a fork of
prompt content the model was tuned around.
Pi (pi.dev) reality check: its lean-ness comes from being a different harness (no MCP, no subagents, no permission popups, minimal prompt + TypeScript extensions), and its site makes no speed/cost/hallucination claims — it is not evidence that stripping CC's prompt in place yields those wins.