The System Prompt Architecture for Coding Agents: What Claude Code and Cursor Get Right

Two coding agents built billion-dollar businesses. One uses a 642-token system prompt. The other assembles 24,000+ tokens dynamically. Both ship working code. The difference tells you everything about where prompt engineering actually matters for agentic systems.

642 Tokens vs. 24,000: The Same Problem, Two Answers

When TensorZero reverse-engineered Cursor's LLM client by proxying all its requests, they found something surprising. The entire agent runs on a system prompt you could fit in a long tweet thread. Their assessment: current-generation LLMs have internalized enough software engineering through post-training that you don't need to teach them much.

Cursor hit $1B in annual recurring revenue by November 2025 with this minimal approach.

Claude Code takes the opposite path. It doesn't use a single static prompt at all. The system assembles dozens of prompt fragments based on what you're doing: a main prompt, tool descriptions for 18+ built-in tools, mode-specific reminders, sub-agent instructions, and utility prompts. The full payload exceeds 24,000 tokens before your first message.

Neither approach is wrong. They reflect different bets about the same question: how much does the model already know, and what do you still need to tell it?

The Three Patterns Every Coding Agent Uses

Strip away the branding and every production coding agent shares three architectural patterns in their system prompts. Understanding these patterns lets you build your own.

Pattern 1: Environment Declaration

The prompt tells the model what it can touch and what's off limits. This isn't about the model's knowledge -- it's about the specific runtime it's operating in.

Here's what this looks like in practice. Say you're building a coding agent that works inside a Docker container with access to a project directory and a set of CLI tools:

You are a coding assistant operating inside a sandboxed environment.

Working directory: /workspace/project
Available tools: read_file, write_file, run_command, search_code
Shell: bash (commands timeout after 30 seconds)
Language runtimes: Python 3.12, Node 22

You cannot access the internet. You cannot install new packages.
You cannot modify files outside /workspace/project.

This prompt works because it front-loads constraints before the model starts planning. Without the "no internet" line, the model will suggest pip install for missing packages. Without the timeout, it might propose long-running test suites. Every constraint you omit becomes a failure mode you'll hit in production.

Expected output behavior: The model plans solutions using only available tools and installed packages, never suggesting network calls or system-level changes outside the declared boundaries.

Pattern 2: Tool Schema as Instruction

The biggest chunk of most agent system prompts isn't prose -- it's tool definitions. Claude Code's 18+ tool descriptions aren't just API docs. They're behavioral instructions disguised as schemas.

Look at the difference between a lazy tool description and one that actually shapes behavior:

# Weak tool description
search_code: Searches code in the repository.

# Strong tool description  
search_code: Searches file contents using regex patterns.
- Use this instead of running grep via the shell
- Supports glob filtering (e.g., "*.py", "src/**/*.ts")  
- Returns matching file paths sorted by modification time
- For open-ended searches requiring multiple rounds, 
  use the agent tool instead
- Pattern syntax uses ripgrep, not grep -- literal braces 
  need escaping

The strong version does three things the weak one doesn't. It redirects away from bad habits (don't shell out to grep). It sets expectations about output format. And it routes complex cases to a different tool entirely.

When you write tool descriptions for your own agents, treat each one as a mini system prompt. The model reads them with the same weight it gives your top-level instructions.

Pattern 3: Error Recovery as Product Design

This is where Bolt.new's story gets interesting. StackBlitz was doing $80K a year in late 2023. After launching Bolt.new in October 2024 with a carefully engineered system prompt, they crossed $40M ARR in five months.

The secret wasn't clever role definitions or creative temperature settings. It was error handling.

Bolt's system prompt includes an <artifact_instructions> section with specific recovery instructions for every common failure they hit during testing. Not "handle errors gracefully." Specific patterns like: if the Vite dev server fails to start because of a missing dependency, check package.json against the import statements before suggesting a fix.

The feedback loop: encounter a failure in production, add the exact recovery instruction to the prompt, ship. Every user who hit that error before becomes a user who doesn't hit it again.

You can apply this same pattern to any agent you're building:

When a Python import fails with ModuleNotFoundError:
1. Check if the module is in requirements.txt / pyproject.toml
2. If present but not installed, run the install command
3. If absent, check whether it's a stdlib module that was 
   renamed (e.g., ABCs imported from collections instead of
   collections.abc, removed in Python 3.10)
4. If the module genuinely doesn't exist in the environment, 
   suggest an alternative that IS available

Do NOT suggest pip install for packages not in the 
project's dependency file without asking first.

Expected output behavior: Instead of immediately suggesting pip install mystery-package, the agent traces the import chain, checks existing dependency files, and proposes a fix that respects the project's dependency management.

The Hidden Architecture: What the Prompt Doesn't Show

Here's the part most prompt engineering discussions miss. Cursor's real advantage isn't its 642-token prompt. It's the four-layer local storage system that preserves every conversation, checkpoint, and code attribution score. Plus a summarization pipeline that compresses history when the context window fills up.

The model is stateless. Everything it "knows" about your codebase comes from what the harness constructs and sends alongside your message. The system prompt is just the outermost layer.

A March 2026 paper (arXiv 2603.05344) formalizes this as two phases: Scaffolding (assemble prompts, build tool schemas, register sub-agents before the first message) and Harness (runtime orchestration of tool calls, context management, safety checks, session persistence).

The scaffolding is your prompt architecture. The harness is your context pipeline. Production agents need both.

Sub-Agent Specialization: One Orchestrator, Many Specialists

Claude Code doesn't run everything through one prompt. It spawns specialized sub-agents -- a planner, an explorer, a security reviewer, a task executor -- each with their own system prompt tuned for that job.

The pattern is straightforward. Your orchestrator prompt decides what kind of work needs doing. Then it delegates to a specialist prompt that's been written specifically for that task type.

You are a code review specialist. You receive diffs 
and evaluate them for:

1. Correctness: Does the change do what was intended?
2. Security: Does it introduce injection, auth bypass, 
   or data exposure risks?
3. Style: Does it match the existing codebase patterns?

Report issues by severity. If you find no issues, say so 
in one sentence. Do not add praise or filler.

You do NOT make changes. You only review.

That last line matters. Telling a sub-agent what it can't do is as important as telling it what it can. Without that constraint, a review agent will start suggesting rewrites, which steps on the implementation agent's job and creates conflicts.

What This Means for Your Own Agents

If you're building AI tooling for your team or your product, here's what the production agents teach you:

Start with the shortest prompt that works. Cursor proves that current models know how to write code. You don't need to teach them Python syntax. You need to tell them about your specific environment, your specific tools, and your specific constraints.

Add instructions only when you hit real failures. The Bolt pattern. Don't pre-engineer every edge case. Ship, watch what breaks, add the fix to the prompt. Your prompt becomes a living document of solved problems.

Invest more in what you feed the model than how you instruct it. Context engineering -- what files, what history, what state gets assembled into each request -- determines output quality more than prompt wording. A perfect system prompt with bad context produces bad results. A minimal system prompt with excellent context produces good results.

Separate your specialists. One giant prompt trying to handle planning, coding, reviewing, and debugging will underperform four focused prompts that each do one job well. The orchestrator pattern scales; the monolith prompt doesn't.

The system prompt is the part of your agent that's easiest to see and change. That makes it tempting to over-invest there. The agents making real money invested just enough in the prompt and put the rest of the work into the infrastructure around it.

Prompt architecture for coding agents is one piece of a much larger skill set. If your team is building AI-powered development tools or trying to get more out of existing ones, Kief Studio runs hands-on training sessions that go from prompt fundamentals through full agent design. Join us on Discord or book a session.