Claude Code系统提示词只有几行，为什么反而更有效？

---

The Counter-Intuitive Design Philosophy Behind Claude Code's System Prompt 🤯

TL;DR: Anthropic's Claude Code doesn't follow traditional agent design patterns. Instead of complex prompt chains and tool definitions, it uses a surprisingly minimalist system prompt that prioritizes exploration over instruction. We'll dissect why this works and what we can learn from it.

---

Cover image: A minimalist desk setup with a single coffee cup and laptop displaying terminal output, representing the simplicity-first approach

---

Last week at a cozy café in Kreuzberg, I was debugging a particularly nasty React state issue when my colleague leaned over and said, "Have you actually read Claude Code's system prompt? It's... not what you'd expect."

I hadn't. And when I did, I nearly spilled my flat white. ☕

The prompt was short. Like, really short.

The "Wait, That's It?" Moment

Most AI agents I've built follow the same pattern: exhaustive instructions, strict tool definitions, and step-by-step workflows. We've all been there—writing 200-line system prompts thinking more detail = better results.

At least I was. Guilty as charged.

Claude Code's approach? It's almost laughably simple.

{% highlight yaml %}

Traditional Agent System Prompt (what we usually write)

You are a coding assistant with the following capabilities:

1. Read files using the read_file tool

2. Write files using the write_file tool

3. Execute commands using execute_command

4. Search codebases using grep_search

When asked to implement a feature:

• First, understand the requirement
• Second, explore relevant files
• Third, propose a plan
• Fourth, implement after user approval

{% endhighlight %}

I spent 3 hours last month debugging why my agent kept skipping step 3 and jumping straight to implementation. 3 hours I'll never get back. The prompt was too prescriptive—it confused the model when edge cases appeared. I was basically teaching it to follow a recipe when what I actually needed was a chef who could taste and adjust.

What Claude Code Does Differently 💡

Instead of rigid instructions, Claude Code's system prompt essentially says: "You have tools. Figure out what you need. Ask if you're unsure."

Here's the philosophical shift that blew my mind:

1. Exploration-First, Not Instruction-First

Traditional agents wait for explicit commands. Claude Code proactively explores.

{% highlight javascript %}

// What we expect from traditional agents

User: "Fix the login bug"

Agent: "Which file should I look at?"

// 🤦‍♂️

// What Claude Code does

User: "Fix the login bug"

Agent: *reads package.json, finds auth middleware,

checks recent git changes, identifies the issue*

Agent: "Found it in auth.ts line 42. The JWT expiry

isn't being handled. Want me to fix it?"

{% endhighlight %}

The system prompt doesn't tell it to do this—it just gives it permission to be curious. That's the whole secret. Permission.

2. Tool Definitions Are Hints, Not Contracts

This is where I really messed up in my early projects. I defined tools like legal documents:

{% highlight python %}

My over-engineered tool definition (don't do this)

tools = [{

"name": "search_codebase",

"description": "Search the codebase using ripgrep.

Use this ONLY when you need to find

specific patterns. Do NOT use for

reading full files. Prefer grep over

file reads for initial exploration.",

"parameters": {

"pattern": "The regex pattern to search for",

"directory": "MUST be an absolute path",

"file_types": "Optional comma-separated extensions"

}

}]

{% endhighlight %}

I cringe looking at this now. Why did I think the model needed me to explain when grep is appropriate? It knows what grep does.

Claude Code's tool descriptions are more like: "Search for text in files. Returns matching lines."

That's it. The model figures out when to use it. 🔥

Actually, wait—I should clarify that this only works if the underlying model is genuinely capable. I tried this minimalist approach with an older open-source model back in January and it completely fell apart. The model just... didn't explore anything. It froze. So there's definitely a capability threshold here.

3. Error Recovery Through Humility

Here's my favorite part: the system prompt explicitly acknowledges uncertainty. It's okay with saying "I don't know" or "Let me check that."

{% highlight bash %}

Real interaction I had with Claude Code

$ claude "Is this deployment script safe to run?"

Let me check the script first...

*reads deploy.sh*

I notice this script doesn't have a rollback mechanism

and it directly modifies the production database.

This could be risky. Want me to add safety checks first?

{% endhighlight %}

Most agents would just execute and pray. Claude Code's prompt encourages verification before action. This one design choice probably prevents more incidents than all my carefully crafted safety instructions combined. And I've written some truly paranoid safety instructions, believe me.

The Berlin Startup Lesson 🚀

At a meetup last month—this was at the AI Tinkerers event in Mitte, if you're local—someone asked me: "So should we all just write shorter prompts?"

Not exactly. I think... well, it's more nuanced than that.

The lesson isn't about length—it's about trust.

We tend to micromanage our AI agents because we don't trust them. But over-specifying creates brittle systems that break when reality doesn't match our instructions. I've seen this happen at least a dozen times across different projects.

The counter-intuitive truth: less instruction leads to more robust behavior when the model is capable enough.

I was skeptical until I tried it. Now I'm a convert.

Practical Takeaways for Your Own Agents

After studying this approach (and rewriting my own agents), here's what I've changed:

• **Replace step-by-step instructions with principles** - Instead of "first do X, then Y," say "prefer understanding before acting"
• **Simplify tool descriptions** - Focus on *what* the tool does, not *when* to use it
• **Allow uncertainty** - Add phrases like "If you're unsure, ask or investigate"
• **Test with ambiguity** - Throw vague requests at your agent and see if it explores or freezes

{% highlight markdown %}

Before: Micromanagement Style

When the user reports a bug:

1. Ask for the file name

2. Read the file

3. Identify the issue

4. Propose a fix

5. Wait for confirmation

6. Implement the fix

After: Principle-Based Style

When investigating issues, explore the codebase proactively.

Use available tools to understand context before proposing

solutions. Ask clarifying questions when needed, but don't

wait for permission to investigate.

{% endhighlight %}

The difference in real-world performance? Night and day. My agents went from confused to competent just by removing constraints. Last Tuesday I threw a deliberately vague bug report at my refactored agent—"the payments thing is broken again"—and it actually found the issue in Stripe webhook handling within 30 seconds. The old version would've asked me five clarifying questions first.

Well... that's complicated. Sometimes it still fails spectacularly. But the failure modes are weirder and more interesting now, if that makes sense. Before, failures were predictable and boring. Now they're... creative.

The Coffee-Fueled Conclusion ☕

Sometimes the best engineering decisions are about what we remove, not what we add. Claude Code's system prompt philosophy reminds me of that famous quote: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."

I think that was Antoine de Saint-Exupéry. Probably butchered the spelling. Whatever.

I'm still learning this lesson. Just yesterday I caught myself writing a 150-line prompt for a simple file organizer agent. Old habits die hard. I deleted about 130 of those lines.

But now I ask myself: Am I writing instructions, or am I building trust?

Curious to hear from others who've tried both approaches. The dev.to community always has strong opinions on prompt engineering, and honestly, I learn more from the comment sections here than from most papers these days.

Also, if you're in Berlin and want to chat about AI agents over a proper espresso, hit me up. The tech scene here is buzzing with these conversations. 🇩🇪

---

#ai #programming #webdev #beginners #tutorial