66 lines
4.2 KiB
Markdown
66 lines
4.2 KiB
Markdown
|
---
|
||
|
|
type: reference
|
||
|
|
subtype: pattern/framework
|
||
|
|
title: "Claude Code system-prompt customization surface — mechanisms, risks, subtract-first finding"
|
||
|
|
summary: "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."
|
||
|
|
tags:
|
||
|
|
- type/reference
|
||
|
|
- tool/claude-code
|
||
|
|
- domain/context-engineering
|
||
|
|
- domain/orchestration
|
||
|
|
scope: global
|
||
|
|
last_updated: 2026-07-08
|
||
|
|
date: 2026-07-08
|
||
|
|
last_reviewed: 2026-07-08
|
||
|
|
related:
|
||
|
|
- "[[claude-code-subagent-transcripts-and-token-accounting]]"
|
||
|
|
- "[[orchestration-prompting-claude-5-era]]"
|
||
|
|
---
|
||
|
|
|
||
|
|
# 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.
|