System prompt

A system prompt is the block of instructions sent ahead of the conversation in every request to a model, setting the role the model plays and the rules it follows.

In the Claude API it is the system parameter, kept separate from the list of messages. In a coding agent it is written by the agent's makers rather than by you: it covers how the agent behaves, how it uses its tools and how it formats answers, and it is in place before you type anything. Claude Code lets you replace it with --system-prompt or extend it with --append-system-prompt.

Other layers sit around it. Anthropic's API adds a system prompt of its own when tools are defined and another when thinking is active; the request includes whichever tool definitions the client makes available. CLAUDE.md is not part of it: Claude Code loads that file as a user message after the system prompt.

Because it is identical from one request to the next, it is the part prompt caching handles best, read from the cache at a fraction of the input price after the first request. The corollary is that changing it is expensive. Anthropic caches in the order tools, system prompt, messages, so an edited system prompt invalidates everything after it and the next request processes the whole conversation again.

Instructions meant for a single task therefore belong in the conversation rather than in the system prompt. Claude Code's plan mode and skills append their instructions as conversation messages, which leaves the cached prefix intact.

← All terms