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