What is a system prompt? Claude Code, Codex, Cursor, Grok
By Flavio
A system prompt is the instruction layer a coding agent sends ahead of your chat. How Claude Code, Codex, Cursor and Grok Build set that layer.
A system prompt is the instruction text a tool sends ahead of your conversation, on every request. It tells the model how to use tools, what to refuse, and how to format an answer. You usually do not write that text. The product does.
What I learned reading Claude’s system prompts is the post that reads Anthropic’s published prompts and shows how much of the product lives in that layer. This entry is the short definition for coding agents, and the few controls each tool documents.
The one-line version from the old AI Fundamentals glossary still holds. A system prompt is instructions set before the conversation starts. Tools set one for you. Your own files are a separate layer.
How a system prompt works
The model sees one request. The tool builds it. The system prompt is the first block, then the conversation, then whatever project instructions the tool inserts. The model does not keep that block between requests. The tool sends it again.
Your AGENTS.md or CLAUDE.md can feel like the system prompt because both shape the answer. They are loaded on a different path. Claude Code says this outright: CLAUDE.md is not part of the system prompt.
A line in that first block is still text. A permission check is code around the tool call. Codex’s agent guide splits them: instructions communicate intent, and permissions control access.
System prompts in each tool
| Claude Code | Codex | Cursor | Grok Build | |
|---|---|---|---|---|
| Who writes it | Claude Code. You can append or replace it with a flag | Built-in instructions, plus files and config keys the reference names separately | “Cursor’s built-in instructions”, a slice of the context breakdown | Grok. --system-prompt-override replaces it for one run |
| Your project file | CLAUDE.md is a user message after the system prompt |
AGENTS.md is custom instructions. The reference does not call it the system prompt |
Rules are their own slice, next to the system prompt | AGENTS.md is loaded into context. --rules appends text to the system prompt for one run |
| A file that survives compaction as itself | The system prompt still applies. Root CLAUDE.md is re-read |
Not documented on the commands page | The breakdown keeps a system prompt slice after older turns are summarized | Not documented |
Claude Code
The glossary defines the system prompt as the instructions Claude Code sends ahead of your conversation on every request: how Claude uses tools, behaves safely, and formats responses. It is the first layer of the prompt cache.
--append-system-prompt adds to it. --system-prompt replaces it. The glossary names both flags and does not show a sample command.
CLAUDE.md and output-style instructions are not in that block. Claude Code delivers them in the conversation as system reminders. A project-root CLAUDE.md is re-read from disk after compaction, which is a different mechanism from the system prompt still applying. See the glossary and CLAUDE.md.
OpenAI Codex
The configuration reference has developer_instructions, additional developer instructions injected into the session. model_instructions_file is a replacement for built-in instructions, used instead of AGENTS.md. The instructions key is reserved and tells you to prefer those two.
None of those entries uses the words “system prompt”. AGENTS.md is the documented place for project instructions. Treat it as that file, not as a rename of the system prompt.
The agent guide’s line is the one that decides where a safety rule goes. Instructions say what you want. Permissions decide what the process may do. See Working with agents and the configuration reference.
Cursor
The prompting page splits the context window into categories. “System prompt” is Cursor’s built-in instructions for the model. Rules, skills, and MCP are separate rows. The page does not show a control that replaces the built-in system prompt.
Rules are the layer you edit. They are covered in the rules entry. See Prompting agents.
Grok Build
Project rules are loaded into context for every session. That includes AGENTS.md and CLAUDE.md. They are not described as the system prompt itself.
For one run, --rules appends text to the system prompt. --system-prompt-override replaces the system prompt. The project-rules page shows the first flag with a string and names the second without a sample. grok inspect lists the rules files it found, with approximate token counts. See AGENTS.md in Grok Build.
Details checked against each vendor’s documentation in November 2026.
A real example
A one-run instruction in Grok Build, appended to the system prompt, not saved as a project file:
grok --rules "In this repo, run npm run build before you say a change is done."The durable version of that sentence belongs in AGENTS.md or CLAUDE.md, which those tools load as project instructions. Replacing Grok’s system prompt for one run is --system-prompt-override. The docs name the flag. They do not print a sample line, so this entry does not invent one.
Codex’s config key for extra developer instructions is a string in config.toml:
developer_instructions = "In this repo, run npm run build before you say a change is done."That key is injected into the session. The reference does not call it the system prompt. If you want a file instead of built-in instructions, the key is model_instructions_file, and it is a replacement for AGENTS.md, not an extra file beside it.
Claude Code’s append and replace flags are --append-system-prompt and --system-prompt. Check the glossary for the current invocation before you put them in a script.
When to use a system prompt
You write one when you are building an agent and you own the request. The product’s system prompt is already there when you use Claude Code, Codex, Cursor, or Grok Build. Adding a sentence for a single run is the --rules case, or Claude’s append flag.
For a rule the whole project should follow next week, use the instruction file. Rules and CLAUDE.md are that layer. They are re-read on the tool’s own schedule. A flag on one command is gone when the command exits.
Skip the system prompt for a boundary that has to hold. “Always ask me before you delete” in the prompt is advice. The check belongs in permission modes.
Pitfalls
People put the project rules in the system prompt slot, then wonder why CLAUDE.md and the system prompt disagree. Claude Code loads them as different messages. Edit the file if you want the project rule. Use the flag if you want to change the product’s own instructions for one run.
A long system prompt is sent on every request. It occupies the context window before your first message, and it is the first layer of Claude Code’s prompt cache. Appending a new sentence changes that prefix.
Codex model_instructions_file replaces built-in instructions instead of AGENTS.md. Pointing it at a file does not merge the two. You get the file.
The system prompt linter checks a prompt you wrote for vague rules and contradictions. It does not show you the hidden prompt inside Claude Code or Codex.
Related on flaviocopes.com
- What I learned reading Claude’s system prompts walks through Anthropic’s published prompts, which are mostly rules, facts, tools, and safety checks.
- How to make AI harnesses talk less shows output styles as extra instructions Claude Code adds on every request, next to the system prompt.
- What is an AGENTS.md file is the project file, which is the layer you can edit without replacing the product prompt.
- How to prevent AI agents from taking irreversible actions is the argument for putting a real boundary in code.
Related glossary entries
- CLAUDE.md: CLAUDE.md is the Markdown file of project instructions Claude Code loads at the start of a session. How Codex, Cursor and Grok Build treat that same filename.
- Rules: Project rules are durable instructions a coding agent loads for a repo. How they work in Cursor, Claude Code, Codex and Grok Build, and when to skip them.
- Context window: The context window is everything a coding agent can see at once. How to check it, free it and keep it small in Claude Code, Codex, Cursor and Grok Build.
- Context engineering: Context engineering is choosing what an agent sees before it edits. How Claude Code, Codex, Cursor and Grok Build load rules, files and skills.
Want me to talk about your product? You can sponsor this site.