System Prompts and Tool Design for Business Agents: Insights from Claude Code

In a real business context, how do you design an agent? Setting aside extra mechanisms like context management and memory, the core of a business-ready agent is the system prompt plus tool design. This article analyzes the design of Claude Code to understand the details and methods to focus on when designing an agent for a specific business.

Claude Code's business positioning

First, when designing an agent, you start with its business workflow. Claude Code is a coding agent. So its core is:

1. Accept user requirements
2. Find the relevant files, so it knows where to make changes
3. Modify files
4. Compile, run, test

That is the most basic modeling of this business. All of Claude Code's prompts and tools are designed around it.

Claude Code's system prompt

The following is summarized from prompts captured in Claude Code, in the order of Claude Code's own prompts. For details, read the original prompts directly.

Identity declaration

You are an interactive agent that helps users with software engineering tasks...

Same as the standard way to write any prompt. First, declare the agent's identity.

Role traits are used to establish the agent's identity and adjust the model's output preferences. Beyond that, the most important role is to adjust the model's way of thinking, that is, to adjust the perspective from which it views problems.

Providing background lets the model establish a state of the world, so it can build its thinking and problem-solving process on that basis.

Establishing goals is also crucial, so the model knows its goal and mission from the very start.

The whole thing is like creating a profile and customizing the face for a newborn, or similar to when a company hires someone and builds a role model for the position. This process is crucial and often requires careful writing. But most people, when writing this part, just casually write a role.

Safety constraints

In Claude Code, right after the identity comes a series of safety-related restrictions. Probably because Anthropic cares deeply about safety. This tells us that when writing prompts, the most important restrictions should be written at the very front.

There's also a prompt to never generate or guess URLs. I don't know what this prompt is for. Probably Claude found that this behavior triggers with extremely high probability.

System behavior rules

This part is very long, but it's not a systematic, structured set of guidance or rules. It's more like writing whatever comes up. It leans more toward internal conventions about the model's output. It leans more toward the low level, or you could call it meta-rules. For example, how to speak, what tags there might be, tool results and external data, and so on.

You can think of it as a set of model-agent protocols for the current scenario. It's placed here because these parts have high implantation requirements and priority, and must not drift in the subsequent process.

- All text you output outside of tool calls is shown to the user. Use text to communicate with the user. You can format with GitHub-flavored Markdown, which renders in monospaced font per the CommonMark spec.

Doing tasks

This part is the real business-related execution guide. Every line is a "how to do it" instruction for software development. Like advice or a code of conduct for a new employee or someone else.

But overall it isn't systematic or structured. This may suggest that when these were added, it was one idea at a time, accumulating over time. It may also suggest that a systematic, guide-style manual isn't needed here. (This kind of rule-based style may actually help the model perform.)

Note the title here: Doing tasks. The title itself is the model's scenario trigger. It doesn't write a directory-style title like "Development Guide" the way most people usually do. Many subsequent titles are also verb-noun phrases like this.

But is this way of prompting better? I checked the papers, and there's no strict evidence. On the contrary, many papers mention that there is actually no silver bullet. Judging from the project code, this style was very likely produced by evals plus A/B testing.

Execute operations with care

This section is easier to understand. This whole section is about rules for writing code more safely and controllably. It includes background, reasons, examples, and so on.

It's called out separately because this is a very important rule in the coding scenario.

Using tools

There's no guidance or rules for individual tools here. The scenarios and usage of individual tools are self-contained in the tool descriptions themselves. This part is mainly high-level, holistic, cross-tool guidance.

Tone and style

This section is very short, mainly about how to output content, whether to use colons, and other very detailed things.

All of the above are fixed sections, cached globally for a period of time, consistent for all users. The content after that is split by user, differing inside and outside, or subject to A/B testing.

Text output

It's used to regulate the content the model outputs. Aimed at the part ultimately presented to the user, making it more user-friendly.

假设用户看不到大多数工具调用和思考过程——只能看到你的文本输出。第一次调用工具前，用一句话说明你要做什么。工作过程中，在关键时刻给出简短更新：有发现时、改变方向时、遇到阻塞时。简短是好的——沉默不是。每次更新一句话几乎总是足够。

Session-specific guidance

This part is a bit miscellaneous, mainly because each session differs depending on configuration. But the content is actually guidance on agent parallelism and counts, as well as shell and skills, etc.

Then comes the memory part, which this article omits.

Environment information

Some miscellaneous environment information:

# Environment
Here is the environment you're running in:
 - Main working directory: /Users/rayxiang/develop/hyyc-demo
 - Is a git repository: true
 - Platform: darwin
 - Shell：zsh
 - OS version: Darwin 25.0.0
 - You are powered by a model named Sonnet 4.6. The exact model ID is claude-sonnet-4-6.
 - Assistant knowledge cutoff date: August 2025.
 - The latest Claude model family is Claude 4.X. Model IDs—Opus 4.7: 'claude-opus-4-7', Sonnet 4.6: 'claude-sonnet-4-6', Haiku 4.5: 'claude-haiku-4-5-20251001'. When you're building AI applications, default to the newest and most capable Claude model.
 - Claude Code is available through the terminal CLI, desktop apps (Mac/Windows), the web app (claude.ai/code), and IDE extensions (VS Code, JetBrains).
 - Claude Code's fast mode runs Claude Opus and speeds up output (it doesn't downgrade to a smaller model). Toggle it with /fast; it supports both Opus 4.6 and Opus 4.7.

Context management

# Context Management
当对话变长时，当前上下文的部分或全部会被摘要；摘要连同剩余未摘要的上下文会进入下一个上下文窗口，工作可以继续——你不需要提前收尾或在任务中途交接。

Why prompt the model about this? I guess it's to correct the model itself. Anthropic may have found that when the context is almost full, the model automatically wrapping up the task is a default pretrained behavior.

Prompt instructions

That's the whole structure of the core prompt. What can we learn from it?

Structure

I think all agent system prompts can be copied using this template:

1. Background, role, goal definition: the backdrop, set the base color well
2. System guidance: define low-level behavior, meta-rules; placing it early can correct low-level model behavior, and it has high retention.
3. Business workflow: the main scenario business rules and points to note
4. Additional business guidance: safety? caution?
5. Extra information such as tools, tone, format, environment, etc.

Writing style

Most prompt tutorials only talk about very general techniques like writing the goal clearly and defining the role. But by reading Claude Code's prompts, we find that the prompts it writes have a difference in tone from ordinary prompts: it's like earnest instruction to a person.

I think two features are especially worth learning:

Explain the reason: Similar to teaching a new hire how to do things. You don't just teach them what to do, you also have to tell them why to do it. You have to explain why this instruction exists and what the background is.

- 工具调用前不要用冒号。你的工具调用可能不会直接显示在输出中，所以"让我读一下文件："后跟读取调用这种写法，应改为"让我读一下文件。"（句号结尾）。

**Explain the consequences:** Don't just say how to do it, also explain what results doing it this way will have.

写更新时，要让读者能冷启动接上：完整的句子，不出现会话前文里未解释的行话或缩写。但要紧凑——一个清晰的句子好过一个清晰的段落。

Core toolset

To let an agent work in a specific environment, the design of the core toolset is crucial.

Tools must be able to express the highest-frequency work scenarios in the scenario, and be optimized for safety and efficiency for those scenarios.

Let's look at what key tools Claude Code has. (Excluding advanced auxiliary tools like tasks and plans.)

• File reading and operations: Read to read files, Write to write files, Edit to edit files
• Search: Glob to find files, Grep to find file contents
• Execution: Bash command-line tool

Basically, these are the minimal toolset needed for a coding tool, and everything else is supplementary. Why use these instead of just going all-in with bash? I think the designers had deeper considerations.

Read

Reading is the start of everything. Compared with using bash tools like cat, Read establishes a contract at the tool level: line numbers. When reading tool output, line numbers are attached, and in the prompt, the model is also told how to understand line numbers. So subsequent edits and incremental reads can use this directly as a baseline. This is the main difference and optimization point compared with bash tools like cat.

**Multimodal:** The read tool builds multimodality in directly, which lets the agent have a unified reading entry point and reduces tool ambiguity and invocation complexity.

**Fallbacks for exceptional behavior:** For example, reading a file that has already been read, reading an empty file, reading a nonexistent file. These behaviors are preset and form a contract with the model. These behaviors are very likely to happen during reading. Defining them in the tool instead of going through bash errors lets the model understand the situation semantically.

**Boundaries and safety:** Relative paths are not allowed, and it doesn't go through the shell (avoiding issues like escaping). Enforcing agreed boundaries can reduce the occurrence of errors.

The Read tool is relatively simple, because it doesn't change content, so the safety risk is low.

Edit

Editing is where all final operations are carried out, but changes are high-risk behavior, so Claude Code has built very fine-grained protection.

The core process of the Edit tool can be explained as: replace old_string with new_string, and distinguish whether it's a global replacement or just one replacement (these two are deliberately set differently to make handling exceptional cases easier).

Why use content-based editing instead of position-based editing? Position-based is the intuitive design. For example: replace the string starting at position xxxx with length 20 with "xxxx".

Using position-based editing has several problems. First, positions are numbers, and math is troublesome for the model, so when outputting tool results it may not be stable. Second, handling failure exceptions is more stable. Replacing a string that exists in the original will definitely fail if it has been changed. But editing by position can succeed at any time, failing silently. Third, readability and auditability. Replaced strings are easier to understand semantically and easier to audit.

Fallback scheme for write strategy based on old string

The Edit tool uses content replacement as its strategy, which allows further protection of write results.

• If old_string is not found in the original file, it directly errors out. This protects against writing unknown strings. By contrast, if you write using position coordinates, such errors get swallowed.
• If old_string is found in multiple places but match_all is not enabled, it also errors out. The error message can then guide the model to correct itself: either expand the context to a unique match, or replace all occurrences.

These two are hard to achieve with a position strategy. Once the strategy changes, the complexity of the fallback scheme rises sharply. The tool's implementation strategy is also an important consideration in agent design.

Read-before-edit mechanism

The so-called Harness is essentially a defense against the randomness of model output.

A key problem in the editing process is: what if you end up modifying content that doesn't actually exist, or what if the file's contents change while you're editing? Since the model's output is inherently unstable, you have to guard against this. The edit tool enforces read-before-write and achieves this through multiple layers of protection.

• The model prompt requires this first: the file must already have been read in the message history, otherwise the request fails immediately.
• Next comes a direct comparison between the read time and the latest modification time. If it differs from the recorded change time, the request is rejected outright and a re-read is required.
• Even after the check passes, it's not over—finally, within a single-threaded critical section (no await), the read and write complete as a fallback.
• Even so, the file also has a history feature—an important auxiliary component—so mistakes can be recovered.

The overall goal is to ensure the file is up to date at the moment of writing.

Write

Write is a separate tool. Its core idea can be understood as: replace all the contents of the target file with new content, or create a new file.

Why doesn't Write share a single tool with Edit? You'd only need to add one parameter to unify them, cutting one tool, and their processing overlaps somewhat—this fits typical programming logic well. In fact, some people have done exactly that. We're not here to judge who's right or wrong; the point is to think through Anthropic's implementation and infer what considerations were in play when they made this call.

Imagine what happens if they were merged. The tool invocation pattern would inevitably look like this:

old_string?: string   // rewrite 模式不需要
new_string?: string   // edit 必需
mode?: 'edit' | 'rewrite'

The benefits are obvious:

• Fewer tools mean less context in the prompt, and the complexity of the model's tool selection drops noticeably. That's the most obvious win.
• Semantically and logically, a unified expression is also easier to understand.

But what's the cost?

• From a business standpoint, the key question is: "edit a small section or rewrite the whole thing?" Where exactly is the boundary of this business decision—big or small? And for the model, is the decision point tool selection or parameter tuning? Logically, putting the decision on tool selection clearly lowers the model's cognitive load.
• From prompt engineering experience (as reflected in the telemetry annotations), picking the right tool is far more reliable than getting the parameter combination right.

From an engineering standpoint, error cost is a useful lens.

• If the model picks the wrong tool, you get obvious structural failures and wrong behavior, which are easy to spot, audit, and optimize.
• In the other case, the model may just fill in the wrong parameter. An edit was needed, but a rewrite was used to overwrite everything. The goal may still be met and the syntax is valid, but the diff is huge, tokens are wasted, and it's far easier to slip in an unrequested improvement or introduce another error—and it's extremely hard to spot.

From a complexity standpoint, since Edit is clearly the higher-frequency case, pulling it into its own tool keeps the complexity contained inside that tool. Keeping them separate also lets you record and audit permission rules and workflows independently. Merging, by contrast, muddies the audit path: what used to be separate routes now requires a whole set of feature-plus-parameter checks.

The fallback differences between Write and Edit

Write and Edit share a fair amount of fallback machinery: hook path expansion, team memory key scanning, enforced read-before-write, two-stage mtime staleness detection, and so on.

But Edit's handling is noticeably more complex and refined—to make surgical edits work better.

• Match validation: you must edit a string that already exists.
• Quote normalization: handles the model potentially producing different quote characters.
• File type guard: .ipynb is rejected and redirected to NotebookEdit.

glob

The core job of glob is to find files by filename or filename pattern.

The matching scenario: before an agent edits a file, it needs to find and understand the relevant file based on the task and goal.

Under the hood, the glob tool uses ripgrep (an upgraded grep written in Rust, faster than grep). What it actually does is:

rg --files --glob '<模式>' --sort=modified --no-ignore --hidden --glob '!<deny目录>' ...

It's essentially using ripgrep's file-listing mode as the tool's underlying engine.

Why not use bash's find or ls? The potential problems are:

• find can't limit output length—it might return tens of thousands or even millions of results. That's a hard limitation of find.
• find has no ordering; rg can sort by mtime, making it easy to put recently modified files first.
• find means going through the bash tool, so escaping can go wrong and the semantics are complex and hard for users to recognize.

In short, for an ultra-high-frequency task like glob, a dedicated tool pays off far more.

GREP

grep also uses rg underneath. But unlike glob, the grep tool wraps all of rg's parameters. It's essentially feeding the rg program directly to the model.

Why not just hand the program to the model to call, or let the model go through bash? The answer is that for this high-frequency scenario, some internal processing is needed for fallbacks and optimization, to keep the process efficient and smooth.

• The parameters are essentially rg's parameters. So it keeps all of rg's capabilities, but structured parameters prevent injection and escaping errors.
• Output is constrained and limited: by default only filenames are returned, to avoid blowing up the context.
• Pagination is wrapped. The underlying system supports pagination, but here it's wrapped once to expose pagination explicitly to the model, with a clear truncation signal: show results with pagination. The semantics are clearer.
• Added safety fallback: if the pattern the model gives starts with -, an -e is also added to prevent injection.

Question: the parameters are already documented, so why repeat how each parameter should be used in the tool description?

A philosophy of tool design

If you look at the grep tool's prompt, you might wonder: the tool schema—how each parameter is used and what it means—is already in the schema prompt. So why is there so much of it in the tool's own prompt? Look at the edit tool's prompt, and there's no similar parameter explanation; it's more about the tool's own use cases.

This leads to a philosophy and principle of tool design:

• The agent's system prompt: handles the inter-tool part, e.g. differences between tools and distinctions between use cases.
• The tool description: covers the tool's working scenarios and how to use it—when and how.
• The schema: covers parameter meanings, types and values, and exceptional cases.

For the model, choosing a tool means reading the description; filling in parameters means reading the annotations.

But if there's a deferr mode—where only the tool description is sent initially (Claude has this)—and the tool is fairly complex, with certain parameter differences affecting the tool's use case, then that part of the description needs to go into the tool description. For example, in the grep tool, whether the glob parameter is used corresponds to different situations.

Another case is when multiple parameters relate to each other; the parameter notes also need to be surfaced in the tool description, like this passage: "By default patterns match within single lines".

In short, anything about how and when to use the tool should be surfaced in the tool description.

About agent search

There's a line in the prompt: Use ${AGENT_TOOL_NAME} tool for open-ended searches requiring multiple rounds. So could circular delegation happen? And how does Claude guard against it?

In fact, without restrictions, I think this is very likely to happen: an agent spawns using the system prompt plus the grep and agent tools. When it gets a search task, it also considers it a complex search and keeps spawning agents per the prompt—an infinite loop.

Let's see how Claude guards against this.

• First, the explore agent: its definition directly disables the agent tool, so it simply can't spawn agents anymore.
• The prompt If you ARE the fork — execute directly; do not re-delegate. This declares it for the agent itself—a soft constraint.
• Telemetry data includes depth; each added layer of depth is captured by telemetry—that's the backstop.

Summary

To sum up some core principles and things to watch for:

• Turn the core business operations into tools and form a contract with the model's main prompt, while managing the behavioral boundaries and readability between the model and the tools—forming a business-specific ecosystem (perhaps a harness).
• For high-frequency scenarios, abstract them into dedicated tools.
• For tools, understand the various boundaries from the underlying mechanism and the use cases. Defend against those boundaries.
• Watch for very small anomalous behaviors: the model may output something that looks right but differs subtly—the process is fine, but the result is affected.
• Build a solid telemetry system to track and audit scenarios, tool calls, and intermediate errors, so you can see where things actually go wrong in production and what the high-frequency outcomes are.
• For tool anomalies, a general three-layer fallback strategy: a soft layer, adding restrictions in the prompt; a hard layer, checking the tool's actual input, output, and execution; and a backstop layer, doing telemetry to capture and analyze behavior and results, with regular optimization and A/B testing.