From 092f175b7e366e61594304c0f46746057f41bbc7 Mon Sep 17 00:00:00 2001 From: jared Date: Wed, 8 Jul 2026 10:22:14 -0400 Subject: [PATCH] vault: session notes 2026-07-08 --- journal/2026-07-08.md | 7 ++ ...ode-system-prompt-customization-surface.md | 65 +++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 reference/claude-code-system-prompt-customization-surface.md diff --git a/journal/2026-07-08.md b/journal/2026-07-08.md index 1219974..9906fa4 100644 --- a/journal/2026-07-08.md +++ b/journal/2026-07-08.md @@ -165,3 +165,10 @@ tags: [scope/global, type/log] **Reason:** other **Vault notes touched:** (none) + +## Session — 2026-07-08T14:01:51Z + +**Project:** /tmp/orch-eval-ws4-grid/E1P-pipeline-review-fable/E1P-pipeline-review-fable-r2 +**Reason:** other +**Vault notes touched:** +(none) diff --git a/reference/claude-code-system-prompt-customization-surface.md b/reference/claude-code-system-prompt-customization-surface.md new file mode 100644 index 0000000..2831b79 --- /dev/null +++ b/reference/claude-code-system-prompt-customization-surface.md @@ -0,0 +1,65 @@ +--- +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 ` / `--disallowedTools` | Restricts built-in toolset → removes tool schemas from context | Low | +| `--settings ` / `--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.