System-Prompt Layers: Assembly, Cache Boundaries, and Runtime OverridesSystem Prompt 分层：组装、缓存边界与运行时覆盖

JollySammy is a squirrel who loves to plan, but this time his imagination has run dry — he simply can’t think of a good analogy, so he goes straight to the point. If we liken the system prompt to a notebook, its bound pages correspond to stable instructions, its loose leaves to session context, and a separator marker divides the cacheable prefix from the volatile suffix. An actual harness works with typed modules that carry ordering and cache metadata; instruction authority is determined by the model API and the host application, and does not rise automatically just because a passage sits earlier in the “notebook.” The first half of this post covers the assembly pipeline; the second half analyzes the runtime-override mechanisms of Claude Code and Codex.

1. The pieces change at different rates

On any given turn, the prompt the model sees reads like one continuous document:

You are an interactive agent that helps users with coding tasks.
# System rules
...
# Tool usage policy
...                                        <- (A) never changes in a session
__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__         <- (B) an internal boundary marker
# Environment
- Primary working directory: /home/sammy/burrow
- Platform: linux                          <- (C) session-level, may change
# MCP Server Instructions
...
Project house rules apply.                 <- (D) appended assembly tail
gitStatus: Current branch: main ...        <- (E) changes every turn

The pieces it’s made of come from entirely different places, on entirely different clocks:

identity text      -> hardcoded, never changes
tool usage rules   -> hardcoded, never changes
env info           -> needs a subprocess: git rev-parse ...
MCP instructions   -> depends on the currently connected servers
CLAUDE.md          -> the user may edit it mid-session
git status         -> changes after every commit / file edit
current date       -> changes at midnight

The transport ultimately needs one byte-stable serialized value, while the harness starts with components that change at different rates. Assembly is the step between them. A naive implementation concatenates every component on each turn:

# WRONG: naive per-turn concatenation
system_prompt = (
    identity + rules + tool_policy
    + env_info + git_status + claude_md + today
)

This creates two problems. First, when git status changes in the middle of the serialized prompt, content from that point onward no longer shares an identical prefix with the previous request. Depending on the provider’s cache semantics and breakpoint placement, the reusable prefix becomes shorter or the intended cache entry is missed entirely; it is therefore inaccurate to assume that all prompt tokens remain cacheable. (The same prefix-stability constraint appeared earlier in this series when deciding whether parallel results should be reordered before they are written to history.) Second, an opaque string has poor provenance: when output changes, the harness cannot readily identify which module contributed a sentence or which component changed between requests. A more reliable design classifies components by change frequency, applies deterministic assembly rules, and places volatile content after stable content.

2. System-prompt assembly: grouping and criteria

The assembly unit in JollySammy’s favorite harness is a PromptModule: a small dataclass that either carries finished text, or a compute callback — lazy evaluation, meaning the value isn’t produced until assembly actually needs it. Every module declares one of three groups:

• STATIC — identity, system rules, task rules, tool usage, tone. Byte-for-byte constant for the whole session; this is the future cacheable prefix.
• DYNAMIC — session-level but changeable: environment info (cwd, platform, model id), language preference, output style, MCP server instructions.
• APPENDED — content assigned to the assembly tail: values passed through --append-system-prompt, memory usage hints, and similar extensions.

These groups describe change frequency and placement. They do not, by themselves, define instruction authority.

3. Four stages from module list to final text

Three modules can walk the whole pipeline: intro (static, finished text), env_info (dynamic, compute callback), append_prompt (appended, finished text).

resolve runs the callbacks. env_info shells out to git rev-parse, reads the platform, and only now becomes a # Environment block. After this stage every module holds concrete text:

[intro          | STATIC   | order=100 | "You are an interactive..."]
[env_info       | DYNAMIC  | order=200 | "# Environment\n- Primary..."]
[append_prompt  | APPENDED | order=100 | "Project house rules apply."]

sort orders them by a three-part key and filters out the empty ones:

# jollysammy/context/assembler.py
def assemble_prompt_modules(modules: list[PromptModule]) -> list[PromptModule]:
    ordered = sorted(
        modules,
        key=lambda module: (
            _GROUP_ORDER[module.group],   # STATIC:0 < DYNAMIC:1 < APPENDED:2
            module.order,                 # intra-group slot, e.g. intro=100
            module.key,                   # deterministic tiebreaker
        ),
    )
    return [module for module in ordered if module.has_text]

Group is the primary key and the intra-group slot is secondary. An appended module with order=100 therefore remains behind a dynamic module with order=500. This precedence is encoded in the sort key rather than left as a convention for callers to preserve.

blockify merges the sorted modules into per-group blocks and inserts a boundary between the static block and the first volatile block:

block[0] static   | cache_scope=GLOBAL | "You are an interactive..."
block[1] boundary | cache_scope=NONE   | "__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__"
block[2] dynamic  | cache_scope=NONE   | "# Environment ..."
block[3] appended | cache_scope=NONE   | "Project house rules apply."

serialize joins the blocks with blank lines.

4. The system prompt’s boundary marker

__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ is an internal value: it carries no instruction semantics and exists only to preserve a structural boundary through serialization. In this harness, content before the marker is eligible for the cacheable prefix and content after it is treated as volatile. The marker is emitted only when both regions exist. The API adapter consumes it when placing the provider-specific cache breakpoint; it should not be presented to the model unless the transport requires the literal text.

The assembly result deliberately exposes three views: structured blocks, flattened full_text, and an isolated cacheable_prefix. Flattening too early forces downstream code to parse text in order to recover structure the assembler already knew. Preserving structure until the transport boundary keeps cache policy explicit and testable.

5. Not everything enters the system prompt: three injection paths

The model should see this on every turn does not imply this belongs in the system prompt. The harness uses three paths, selected according to the content’s semantics, authority, and change frequency.

Path one, the prompt body — the static + dynamic + appended assembly above, built once per user submission.

Path two, the per-turn tail. Facts that may change on every API request, such as git status, bypass module assembly and are appended to the serialized prompt as key: value lines. The harness extracts the cacheable prefix before appending this tail, so volatile state cannot enter that prefix.

Path three, the message channel. In this harness, project conventions and the current date are collected from their source for each request, wrapped in <system-reminder> tags, and placed in a synthetic context message flagged is_meta=True. The message is not persisted to session history, so the next request can use updated content without accumulating stale copies. The tag is metadata understood by the host; its name does not create a system-role message.

Claude Code exposes a similar distinction at the product level: its default system prompt carries persistent coding-agent guidance, while CLAUDE.md, hook output, environment state, and other runtime context are loaded through separate mechanisms. The exact internal serialization is an implementation detail and should not be inferred from visible <system-reminder> markup. For a harness design, placement should consider both change frequency and semantics: stable behavioral constraints belong in the highest supported instruction surface; current world state belongs in refreshable context. Treating a volatile fact as a permanent rule increases the risk that the model will continue to rely on it after it expires.

6. Position is not priority

This brings us to the second part of the discussion: keeping a specific instruction persistently in place and promoting it. Assume such an instruction — a memory-loading instruction, say, which we take as the running example from here on — may live in the APPENDED group. Even so, STATIC / DYNAMIC / APPENDED describe assembly position and cache policy, not permission tiers. Where the API exposes these roles, the authority order is generally understood as:

system > developer > user > assistant

This ordering is a useful model, not a guarantee of compliance, and not every provider exposes the same role set. Moving text earlier or adding IMPORTANT can affect salience, but it does not change the message role. In Claude Code, --append-system-prompt appends to the default system prompt for that invocation. CLAUDE.md and auto memory are product-level context surfaces; stronger wording within those files does not turn them into a higher API role.

We separate three concrete requirements: should the instruction be reloaded on every turn, should it be supplied through a higher-authority instruction surface, or should it be enforced independently of model compliance? Each calls for a different mechanism.

7. Claude Code mid-session: repeatable context injection

For the first requirement — reload the instruction on every turn — Claude Code provides UserPromptSubmit hooks. A small file can act as a runtime context slot, with the hook reading and returning its current contents before each submitted prompt:

.claude/runtime-context.md
        ↓
UserPromptSubmit hook
        ↓
added to Claude context on every submitted prompt

UserPromptSubmit runs after the user submits input and before Claude processes it. According to the hook contract, additionalContext is wrapped in a system reminder and inserted alongside the submitted prompt. It is hidden from the chat interface, but the documentation describes it as context injection, not as a new system-role instruction. The distinction matters: repeated injection improves freshness and salience; it does not independently establish a higher authority tier.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/inject_runtime_context.py\""
          }
        ]
      }
    ]
  }
}

# .claude/hooks/inject_runtime_context.py (abridged)
context_file = project_dir / ".claude" / "runtime-context.md"

if context_file.exists():
    content = context_file.read_text(encoding="utf-8").strip()
    if content:
        content = content[:9000]   # hook context output is capped at 10k chars
        print(json.dumps({
            "hookSpecificOutput": {
                "hookEventName": "UserPromptSubmit",
                "additionalContext": (
                    "<runtime_context>\n"
                    "The following workflow context is active for this turn. "
                    "Apply it unless it conflicts with higher-priority "
                    "instructions.\n\n"
                    f"{content}\n</runtime_context>"
                ),
            }
        }, ensure_ascii=False))

The file contains the workflow context that is currently active:

# .claude/runtime-context.md

## Current workflow context

Before planning or modifying files:

1. Read `.memory/MEMORY.md`.
2. Resolve the relevant topic memory files.
3. Summarize which memories were loaded.

Once the hook is configured, editing the file changes the context added to the next submitted prompt; emptying it stops the injection. This avoids placing a temporary policy in long-lived CLAUDE.md and ensures the policy is reintroduced after long histories or compaction. The trade-off is repeated token cost, so the file should contain concise workflow instructions rather than the memory corpus itself.

8. Guidance and enforcement are different layers

The third requirement — the workflow must run every time — cannot be guaranteed by prompt wording alone. Model compliance remains probabilistic, whereas a lifecycle hook can block a concrete action. A robust design separates context from enforcement:

UserPromptSubmit
    └── injects the memory summary and the active policy
PreToolUse / Stop hook
    └── checks whether memory retrieval actually ran;
        blocks the critical tool call, or blocks stopping, otherwise

CLAUDE.md, memory, and additionalContext guide the model. PreToolUse and Stop hooks can enforce observable lifecycle conditions by blocking a tool call or preventing the turn from ending. The stronger architecture is therefore for the harness or hook to perform retrieval, inject the result, record completion state, and reject only the actions that require that state. This turns a vague behavioral instruction into a testable invariant.

9. If the instruction is known before launch

Use the invocation-level system-prompt option directly:

claude --append-system-prompt-file .claude/high-priority-system.md

--append-system-prompt-file appends to Claude Code’s default system prompt for the current invocation, preserving its default tool guidance, safety instructions, and coding conventions. By contrast, --system-prompt-file replaces the default prompt, so the caller becomes responsible for any guidance that still needs to be present. Both flags are invocation-scoped. For a session already in progress, a preconfigured hook is the mechanism that can refresh context without restarting.

10. Codex CLI: startup instructions and per-turn hooks

Codex provides both durable startup configuration and lifecycle hooks; they solve different problems.

developer_instructions can be placed in a named profile:

# ~/.codex/memory-policy.config.toml
developer_instructions = """
Before beginning any task, load the repository memory index and retrieve
the relevant topic memories.
"""

Launch it with codex --profile memory-policy, or set a one-off config override with -c key=value. Despite the key name, the current configuration reference describes this value as additional user instructions injected before AGENTS.md; it should not be presented as proof of a distinct developer-role message. It is resolved when the run starts.

AGENTS.override.md has a narrower precedence rule than “nearest file wins.” In each directory, Codex checks AGENTS.override.md before AGENTS.md and includes at most one of them. It then concatenates guidance from the project root toward the working directory, so guidance in a deeper directory appears later and can override earlier guidance. Discovery runs once per run, so edits generally require a new run or resume before they are reloaded.

Current Codex versions also support UserPromptSubmit, PreToolUse, and Stop hooks in hooks.json or config.toml. A UserPromptSubmit hook can implement the same file-backed, per-turn context pattern shown above; PreToolUse and Stop cover mechanical checks. Hook availability and output semantics are versioned, so production integrations should validate them against the installed Codex manual or generated schema.

Finally, model_instructions_file replaces Codex’s built-in base instructions. AGENTS.md discovery is a separate instruction path; replacing the base prompt should not be described as automatically disabling AGENTS.md. Because this option changes foundational behavior, it is unsuitable as a temporary runtime override.

11. If you control a Codex App Server

A custom App Server client has finer-grained controls than a standalone prompt file. In the current experimental protocol:

• thread/settings/update changes supported thread settings for subsequent turns; an experimental collaborationMode can carry mode-specific developer instructions;
• turn/start can select a collaborationMode for the turn being started;
• thread/inject_items appends raw Responses API items to the thread’s model-visible history;
• turn/steer appends user input to an active, steerable turn.

These methods are not equivalent forms of promotion. Settings can change the instruction mode; injected items and steering add content at their defined history or user-input positions. A runtime-policy wrapper can use the settings path as follows:

runtime_policy.md changed
        ↓
thread/settings/update(collaborationMode=...)
        ↓
subsequent turns use the selected mode's
developer instructions and policy version

The protocol is explicitly experimental and versioned. Clients should generate the schema from the Codex version they deploy rather than treating method names or field shapes as permanent.

12. Match the mechanism to the requirement

long-lived reference facts   -> MEMORY.md / topic memories
long-lived project norms     -> CLAUDE.md / AGENTS.md
refreshable session context  -> runtime-context.md via UserPromptSubmit
high-authority launch policy -> append-system-prompt / configured instruction surface
mechanical constraints       -> hooks / harness state machine

The categories should remain separate. Memory stores information, instruction files express durable conventions, per-turn hooks refresh context, and blocking hooks or harness state enforce observable invariants. Combining them under the word “priority” obscures which guarantee the system actually provides.