Claude System Prompts: What Belongs There

TL;DR: "Claude system prompt" means three different things depending on where you're working: the API's system parameter, a claude.ai Project's custom instructions, or Claude Code's CLAUDE.md. Each has a different owner, a different loading mechanism, and a different lifetime. Conflating them is the actual mistake; this piece keeps them apart and says what belongs in each.

What Do People Actually Mean by "Claude System Prompt"?

Ask three Claude users what a system prompt is and you'll get three correct, incompatible answers, because Anthropic ships something functionally like it across three separate products. A developer calling the API means the top-level system parameter on a Messages request. Someone using claude.ai means the custom instructions field on a Project. A Claude Code user means CLAUDE.md, a markdown file that isn't technically a system prompt at all, more on that below. All three shape Claude's behavior before you type anything, and all three get called "the system prompt" in casual conversation. None of them share a size limit, an update mechanism, or a lifetime.

Only the first row is, mechanically, a system prompt in the API sense. The other two get the name informally because they do a similar job: setting up context Claude reads before you say anything.

What Belongs in the API's system Parameter?

Of the three, this is the only one that's a system prompt by Anthropic's own naming. The Messages API reference defines it once: system: optional string or array of TextBlockParam. "System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role." That's the whole spec. No required structure, no minimum, and, worth stating because people invent one, no published character limit anywhere on that page or on Anthropic's separate prompting best-practices page.

What belongs there, per Anthropic's own guidance, is deliberately narrow: role and tone. The "Give Claude a role" section of the prompting best-practices page states that "Setting a role in the system prompt focuses Claude's behavior and tone for your use case." It adds that "Even a single sentence makes a difference". A one-line system prompt, "You are a helpful coding assistant specializing in Python.", is a documented, sufficient pattern, not a placeholder waiting for more.

One structural fact trips up people arriving from OpenAI's developer-message convention: there is no system role for individual messages in the array you send Claude. The same reference states it directly: "Note that if you want to include a system prompt, you can use the top-level system parameter — there is no "system" role for input messages in the Messages API." (Confusingly, the same schema still lists "system" among the accepted values for a message's role field elsewhere on the page, which is the reference disagreeing with its own prose, not a feature you can actually use.)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "system": "You are a support agent for Acme Cloud. Answer only from the provided ticket context. If the answer is not in the context, say so explicitly.",
    "messages": [
      {"role": "user", "content": "Why is my deploy stuck in queued?"}
    ]
  }'

Because this parameter travels with every single request, it's the only surface of the three built for content that has to be true every time: identity, safety constraints, and output-format contracts your calling code parses. It's the wrong place for a slow-changing team convention, since re-sending the same paragraph on every call is expensive relative to the two surfaces below and buys you nothing they don't already give you.

What Belongs in a claude.ai Project's Custom Instructions?

claude.ai's Projects have their own layered system, and it's easy to point instructions at the wrong layer. Profile instructions apply to every conversation on your account, project or not. Project instructions, per Anthropic's own personalization article, "only apply to chats within that project." That same article gives the rule for choosing between them: "Use profile instructions for account-wide settings that affect all your interactions with Claude." It follows immediately with the other half: "Use project instructions when you need specific guidance or context for a particular project". Point a research brief at the wrong one and it either follows you into unrelated chats or never shows up in the project it was meant for.

Access is where Anthropic's own documentation disagrees with itself, twice, and we're reporting both rather than picking a side. That same personalization article states "Projects are available to all users, including those with free Claude accounts. Free users can create a maximum of five projects." Several lines later it summarizes project instructions as available "(paid plans only)." A second, separate contradiction sits in the RAG documentation: the projects overview article states "Enhanced project knowledge with RAG is only available to users with paid Claude plans (Pro, Max, Team, or Enterprise)." The dedicated RAG article opens with "RAG for projects is available for all Claude plans (free, Pro, Max, Team, and Enterprise)." Both pages were live and unedited when we checked on September 3, 2026. Our Claude project instructions guide covers this contradiction and the full instructions template library in more depth; the short version here is: check your own account before you plan around either claim.

Two more mechanisms belong in this section because they get lumped in with "the system prompt" and shouldn't be. First, project knowledge, files you upload, is separate from instructions; an older support article states plainly: "Context is not shared across chats within a project unless the information is added into the project knowledge base." Second, and newer: project memory. Anthropic describes an auto-generated per-project summary that updates as you work: "Each project has its own separate memory space and dedicated project summary, so the context within each of your projects is focused, relevant, and separate from other projects or non-project chats." That summary is a different mechanism again from the instructions field and from the uploaded-file knowledge base — three systems doing three jobs, two of which get called "memory" in casual conversation.

If your organization is on Team or Enterprise, there's a fourth layer above all of this: org-level instructions. Anthropic's admin documentation caps them plainly: "The maximum length is 3,000 characters." They're set by an admin and take precedence over anything an individual sets: "When both are set, organization instructions take precedence." Changes there can take, per the same page, "up to an hour to take effect across Claude products."

What Belongs in Claude Code's CLAUDE.md?

This is where a wrong claim has actually circulated, worth naming precisely so it doesn't repeat: CLAUDE.md is not prepended to context on every request. Anthropic's own Claude Code documentation describes a different mechanism: "Each Claude Code session begins with a fresh context window." Separately: "CLAUDE.md files are loaded into the context window at the start of every session," not at the start of every message inside that session.

CLAUDE.md is also not, technically, part of the system prompt. Anthropic states the delivery mechanism directly, in its own troubleshooting section: "CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself." If you actually want something at the true system-prompt level inside Claude Code, the documented path is a flag, not a file: --append-system-prompt, which "must be passed every invocation," which is why Anthropic says it is better suited to "scripts and automation" than interactive use.

What belongs in the file, per the same documentation, is narrow by design: build commands, conventions, project layout, and what Anthropic itself calls "always do X" rules, the things you'd otherwise retype into chat every session. The size guidance is concrete: "target under 200 lines per CLAUDE.md file." The reasoning follows right after it: "Longer files consume more context and reduce adherence." A multi-step procedure, or an instruction relevant to only part of a codebase, belongs in a skill or a path-scoped rule instead.

# Project name

## Commands
- `npm run build:check` — typecheck + build. Run before saying "done."

## Conventions
- Server actions live in `actions/`, one file per domain.
- Never touch `.env` secrets in chat output.

CLAUDE.md also isn't the only memory mechanism here, and it's the third system in this piece that risks getting lumped in with the other two under the same word. Auto memory is a separate, Claude-written layer: notes Claude saves on its own, indexed in a MEMORY.md file. Anthropic's docs state the cap directly: "The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first," are loaded at session start the same way CLAUDE.md is. The two are complementary, not redundant, per Anthropic's own comparison: "Who writes it" is you for CLAUDE.md, Claude for auto memory.

Precedence across scopes follows a fixed order, broadest to narrowest: a managed, IT-deployed CLAUDE.md loads first, then your personal ~/.claude/CLAUDE.md, then the project's own ./CLAUDE.md, then a personal, gitignored CLAUDE.local.md. Anthropic is explicit that these are concatenated, not overridden: "All discovered files are concatenated into context rather than overriding each other." They're ordered so "instructions closer to where you launched Claude are read last." Our CLAUDE.md best-practices guide goes deeper on what to keep, cut, and audit inside the file itself.

Which One Actually Behaves Like a System Prompt?

The other structural difference is enforcement, not just naming. The API parameter is enforced by definition, it's part of every request the model sees. Project instructions and CLAUDE.md are not: Anthropic's own Claude Code documentation says outright that Claude "treats them as context, not enforced configuration." To block an action regardless of what Claude decides, you need a PreToolUse hook instead. Writing something into CLAUDE.md or a Project's instructions is a strong request, not a guarantee, however concise you write it.

A team that builds against Claude in production usually ends up using all three at once, and that's fine as long as each carries only what belongs to it. The API system parameter holds the constant identity and output contract for whatever they're shipping, since it's the only surface guaranteed to reach every request. A shared claude.ai Project holds the context specific to whichever initiative a few people on that team are chasing this quarter: a migration, a client, a launch. CLAUDE.md holds what anyone opening the repository in Claude Code needs to know regardless of which initiative brought them there. None of the three substitutes for the other two. Dropping a build command into the API's system parameter means it travels with every request whether or not the model is even touching code that session, and dropping identity or safety language into CLAUDE.md does nothing for the API traffic the same product also sends.

Picking the Right Surface

If you're building an application on the API, the system parameter isn't optional infrastructure, it's the only one of the three that travels with every call, which makes it the right place for anything that must be true every time: identity, refusal behavior, output contracts your code parses. If you're working inside claude.ai on a specific piece of work, a Project's instructions plus its files are the right layer, since they're shared with collaborators and don't leak into unrelated chats. If you're writing code with Claude Code, CLAUDE.md is for what a new teammate would need to know on day one, not a system prompt by any technical definition, whatever people call it out loud. Getting the surface right matters more than getting the wording inside it right; the same sentence in the wrong place either never loads, or loads and gets ignored the moment the conversation drifts.

For the ChatGPT side of this same question, our system prompt vs user prompt guide covers OpenAI's version, and system, developer and user roles: who wins compares precedence across OpenAI, Anthropic and Google directly. If you're deciding whether to move a prompt from ChatGPT to Claude in the first place, ChatGPT vs Claude: which writes better prompts is the starting point.

Prompt Architects treats the underlying problem the same way, one layer down: a context you write once travels with you across ChatGPT, Claude and Gemini, in whichever of these surfaces each product calls its own system prompt, instead of living in just one project's instructions field or one repo's CLAUDE.md.