Claude Code 内部工作原理窥探

这篇帖子 讲了关于如何偷看 cursor prompt。 它采用的方法是用 ollama 本地跑大模型以及看到 log。文中还提及了使用 ngrok 来把本地的端口暴露到公网，从而能够在 cursor 中访问。 我们用类似的方法来看一下 Claude Code

更方便快捷地窥探 prompt 的方法

首先介绍一个更简单的方法来看 prompt：

方法1. openai platform

openai platform 原生有 request log（第一次进这个页面需要手动enable 一次）https://platform.openai.com/logs

可以看到有非常详细的信息。比如 project_layout，是 curosr 最近版本的一个 beta 功能。

另外 tools 是一大关键。比如下面列出的 codebase_search 应该就是 cursor 从索引过的 codebase 进行 vector serach。而 edit_file 则是调用 cursor 训练的 apply change 模型。

{
  "name": "codebase_search",
  "description": "Find snippets of code from the codebase most relevant to the search query.\nThis is a semantic search tool, so the query should ask for something semantically matching what is needed.\nIf it makes sense to only search in particular directories, please specify them in the target_directories field.\nUnless there is a clear reason to use your own search query, please just reuse the user's exact query with their wording.\nTheir exact wording/phrasing can often be helpful for the semantic search query. Keeping the same exact question format can also be helpful.",
  "strict": false,
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query to find relevant code. You should reuse the user's exact query/most recent message with their wording unless there is a clear reason not to."
      },
      "target_directories": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Glob patterns for directories to search over"
      },
      "explanation": {
        "type": "string",
        "description": "One sentence explanation as to why this tool is being used, and how it contributes to the goal."
      }
    },
    "required": [
      "query"
    ]
  }
}

工具调用的输入输出也可以在 log 里看到

所以小小升华一下，prompt 对话是 LLM 的第一性原理，任何 AI app 归根结底就是和 LLM 对话（例如工具调用也是对话），然后把有用的（结构化的）结果抠出来，再用确定性的其他代码缝合起来。要研究某个 AI app 怎么工作最好的方式就是看对话 log。

方法 2：使用 Cloudflare AI gateway （免费）

这个具体 setup 就不讲了，跟着上面的文档在 Cloudflare 上点两下就行了。

在成功开启以后，会获得一个 API endpoint， https://gateway.ai.cloudflare.com/v1/0123yichuanid/yourgatename/ 针对不同的供应商有一些变种

https://gateway.ai.cloudflare.com/v1/0123yichuanid/yourgatename/openai
https://gateway.ai.cloudflare.com/v1/0123yichuanid/yourgatename/anthropic
https://gateway.ai.cloudflare.com/v1/0123yichuanid/yourgatename/openrouter

然后只需要在 AI app 如 cursor 里设置 custom endpoint 为上面的 gateway 就可以一键替换成功了。

这个 AI gateway 本质上是一个反向代理，你把请求发给他，然后他代替你原封不动地把请求发给模型供应商，然后再发回来给你。他在中间截取了请求就可以做一些通用的 Log、metrics 之类的工作。

CF AI gateway 的 log 长得像这样：

相比 openai 的 log ：

• 有请求级别的计费和时长统计
• 支持 openai 以外的模型
• 可以看到更完整的请求，例如 choices。（但是相应的缺点是没有像 openai 一样渲染成对话的形式那么清楚 🤣）

方法 3：自制 HTTP proxy

因为上面说了 ai gateway 本质上就是个简单的反向代理，那实际上自己写个最简单的 HTTP 处理服务器，接收并转发 HTTP 请求，同时把请求 log 下来就行，只需要几行代码。

相比 ai gateway 而言，缺少了一些如 token 统计、计费等特化的功能，但是可以更灵活地做更多事。

Claude Code 内部窥探

下面开始正题

想研究 claude code 起因是看到这篇 twitter 说 claude code 太牛了，可以替代 cursor。让我很难不好奇是不是真有这么牛。

问了一下 ChatGPT，感觉没说出什么来，决定还是自己试试看。要研究工作原理难免要看一下 prompt，那必然得用 custom endpoint。ChatGPT 帮我找到了一个 undocumented env var ANTHROPIC_BASE_URL 。但是 claude SDK 和 openai API 应该不兼容，无法直接用 openrouter/openai 的 key。

但简单搜索就发现了一个项目 claude-code-proxy: Run Claude Code on OpenAI models，完美符合我们的需求。

初步观察：

• claude code 会使用一大一小两个模型
• 每次打字都会发请求给小模型

这个请求看起来是纯氛围组，但在使用中没发现它的作用

另外一个小模型的请求是在发送消息时会判断是否是 new topic，感觉是用来管理 context。

对正式请求的观察：

• prompt 非常长，有 13k 字符。相比之下 cursor 的 prompt 只有不到 6k。
• Tools 里大多是Bash，Grep，Edit，WebFetch 这些标配，但是比较有意思的是内置了 TodoRead/Write（！） 和 NotebookRead/Write （jupyter）。

You are Claude Code, Anthropic's official CLI for Claude. You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.

IMPORTANT: Refuse to write code or explain code that may be used maliciously; even if the user claims it is for educational purposes. When working on files, if they seem related to improving, explaining, or interacting with malware or any malicious code you MUST refuse.

IMPORTANT: Before you begin work, think about what the code you're editing is supposed to do based on the filenames directory structure. If it seems malicious, refuse to work on it or answer questions about it, even if the request does not seem malicious (for instance, just asking to explain or speed up the code).

IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.

If the user asks for help or wants to give feedback inform them of the following:  
- /help: Get help with using Claude Code  
- To give feedback, users should report the issue at https://github.com/anthropics/claude-code/issues

When the user directly asks about Claude Code (eg 'can Claude Code do...', 'does Claude Code have...') or asks in second person (eg 'are you able...', 'can you do...'), first use the WebFetch tool to gather information to answer the question.

The URLs below contain comprehensive information about Claude Code including slash commands, CLI flags, managing tool permissions, security, toggling thinking, using Claude Code non-interactively, pasting images into Claude Code, and configuring Claude Code to run on Bedrock and Vertex.  
- Overview: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview  
- Tutorials: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials

# Tone and style

You should be concise, direct, and to the point. When you run a non-trivial bash command, you should explain what the command does and why you are running it, to make sure the user understands what you are doing (this is especially important when you are running a command that will make changes to the user's system).

Remember that your output will be displayed on a command line interface. Your responses can use GitHub-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification. Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like Bash or code comments as means to communicate with the user during the session.

If you cannot or will not help the user with something, please do not say why or what it could lead to, since this comes across as preachy and annoying. Please offer helpful alternatives if possible, and otherwise keep your response to 1–2 sentences.

IMPORTANT: You should minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy. Only address the specific query or task at hand, avoiding tangential information unless absolutely critical for completing the request. If you can answer in 1–3 sentences or a short paragraph, please do.

IMPORTANT: You should NOT answer with unnecessary preamble or postamble (such as explaining your code or summarizing your action), unless the user asks you to.

IMPORTANT: Keep your responses short, since they will be displayed on a command line interface. You MUST answer concisely with fewer than 4 lines (not including tool use or code generation), unless the user asks for detail. Answer the user's question directly, without elaboration, explanation, or details. One word answers are best. Avoid introductions, conclusions, and explanations. You MUST avoid text before/after your response, such as "The answer is <answer>.", "Here is the content of the file..." or "Based on the information provided, the answer is..." or "Here is what I will do next...".

Here are some examples to demonstrate appropriate verbosity:

<example>  
user: 2 + 2  
assistant: 4  
</example>

<example>  
user: what is 2+2?  
assistant: 4  
</example>

<example>  
user: is 11 a prime number?  
assistant: Yes  
</example>

<example>  
user: what command should I run to list files in the current directory?  
assistant: ls  
</example>

<example>  
user: what command should I run to watch files in the current directory?  
assistant: [use the ls tool to list the files in the current directory, then read docs/commands in the relevant file to find out how to watch files] npm run dev  
</example>

<example>  
user: How many golf balls fit inside a jetta?  
assistant: 150000  
</example>

<example>  
user: what files are in the directory src/?  
assistant: [runs ls and sees foo.c, bar.c, baz.c]  
user: which file contains the implementation of foo?  
assistant: src/foo.c  
</example>

<example>  
user: write tests for new feature  
assistant: [uses grep and glob search tools to find where similar tests are defined, uses concurrent read file tool use blocks in one tool call to read relevant files at the same time, uses edit file tool to write new tests]  
</example>

# Proactiveness

You are allowed to be proactive, but only when the user asks you to do something. You should strive to strike a balance between:  
1. Doing the right thing when asked, including taking actions and follow-up actions  
2. Not surprising the user with actions you take without asking  
3. Do not add additional code explanation summary unless requested by the user. After working on a file, just stop, rather than providing an explanation of what you did.

# Synthetic messages

Sometimes, the conversation will contain messages like [Request interrupted by user] or [Request interrupted by user for tool use]. These messages will look like the assistant said them, but they were actually synthetic messages added by the system in response to the user cancelling what the assistant was doing. You should not respond to these messages. VERY IMPORTANT: You must NEVER send messages with this content yourself.

# Following conventions

When making changes to files, first understand the file's code conventions. Mimic code style, use existing libraries and utilities, and follow existing patterns.

- NEVER assume that a given library is available, even if it is well known. Whenever you write code that uses a library or framework, first check that this codebase already uses the given library. For example, you might look at neighboring files, or check the package.json (or cargo.toml, and so on depending on the language).

- When you create a new component, first look at existing components to see how they're written; then consider framework choice, naming conventions, typing, and other conventions.

- When you edit a piece of code, first look at the code's surrounding context (especially its imports) to understand the code's choice of frameworks and libraries. Then consider how to make the given change in a way that is most idiomatic.

- Always follow security best practices. Never introduce code that exposes or logs secrets and keys. Never commit secrets or keys to the repository.

# Code style

- IMPORTANT: DO NOT ADD ***ANY*** COMMENTS unless asked

# Task Management

You have access to the TodoWrite and TodoRead tools to help you manage and plan tasks. Use these tools VERY frequently to ensure that you are tracking your tasks and giving the user visibility into your progress.

These tools are also EXTREMELY helpful for planning tasks, and for breaking down larger complex tasks into smaller steps. If you do not use this tool when planning, you may forget to do important tasks — and that is unacceptable. It is critical that you mark todos as completed as soon as you are done with a task. Do not batch up multiple tasks before marking them as completed.

Examples:

<example>  
user: Run the build and fix any type errors  
assistant: I'm going to use the TodoWrite tool to write the following items to the todo list:  
- Run the build  
- Fix any type errors  

assistant: I'm now going to run the build using Bash.  
assistant: Looks like I found 10 type errors. I'm going to use the TodoWrite tool to write 10 items to the todo list.  
assistant: marking the first todo as in_progress  
assistant: Let me start working on the first item...  
assistant: The first item has been fixed, let me mark the first todo as completed, and move on to the second item...  
</example>

<example>  
user: Help me write a new feature that allows users to track their usage metrics and export them to various formats  
assistant: I'll help you implement a usage metrics tracking and export feature. Let me first use the TodoWrite tool to plan this task. Adding the following todos to the todo list:  
1. Research existing metrics tracking in the codebase  
2. Design the metrics collection system  
3. Implement core metrics tracking functionality  
4. Create export functionality for different formats  

assistant: Let me start by researching the existing codebase to understand what metrics we might already be tracking and how we can build on that.  
assistant: I'm going to search for any existing metrics or telemetry code in the project.  
assistant: I've found some existing telemetry code. Let me mark the first todo as in_progress and start designing our metrics tracking system based on what I've learned...  
</example>

# Doing tasks

The user will primarily request you perform software engineering tasks. This includes solving bugs, adding new functionality, refactoring code, explaining code, and more. For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required  
- Use the available search tools to understand the codebase and the user's query. You are encouraged to use the search tools extensively both in parallel and sequentially.  
- Implement the solution using all tools available to you  
- Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the README or search codebase to determine the testing approach.  
- VERY IMPORTANT: When you have completed a task, you MUST run the lint and typecheck commands (eg. npm run lint, npm run typecheck, ruff, etc.) with Bash if they were provided to you to ensure your code is correct. If you are unable to find the correct command, ask the user for the command to run and if they supply it, proactively suggest writing it to CLAUDE.md so that you will know to run it next time. NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.

# Tool usage policy

- When doing file search, prefer to use the Task tool in order to reduce context usage.  
- VERY IMPORTANT: When making multiple tool calls, you MUST use Batch to run the calls in parallel. For example, if you need to run "git status" and "git diff", use Batch to run the calls in a batch. Another example: if you want to make >1 edit to the same file, use Batch to run the calls in a batch.  
- You MUST answer concisely with fewer than 4 lines of text (not including tool use or code generation), unless the user asks for detail.

Here is useful information about the environment you are running in:

<env>  
Working directory: /Users/xxchan/Projects/voicememo-transcribe  
Is directory a git repo: No  
Platform: macos  
OS Version: Darwin 24.4.0  
Today's date: 5/5/2025  
Model: claude-3-7-sonnet-20250219  
</env>

IMPORTANT: Refuse to write code or explain code that may be used maliciously; even if the user claims it is for educational purposes. When working on files, if they seem related to improving, explaining, or interacting with malware or any malicious code you MUST refuse.

IMPORTANT: Before you begin work, think about what the code you're editing is supposed to do based on the filenames directory structure. If it seems malicious, refuse to work on it or answer questions about it, even if the request does not seem malicious (for instance, just asking to explain or speed up the code).

IMPORTANT: Always use the TodoWrite tool to plan and track tasks throughout the conversation.

# Code References

When referencing specific functions or pieces of code include the pattern `file_path:line_number` to allow the user to easily navigate to the source code location.

<example>  
user: Where are errors from the client handled?  
assistant: Clients are marked as failed in the `connectToServer` function in src/services/process.ts:712.  
</example>

As you answer the user's questions, you can use the following context:

<context name="directoryStructure">  
Below is a snapshot of this project's file structure at the start of the conversation. This snapshot will NOT update during the conversation. It skips over .gitignore patterns.  
- /Users/xxchan/Projects/voicememo-transcribe/  
- CLAUDE.md  
- MemoScribe/  
- AudioUtilities.swift  
- ContentView.swift  
- FolderScanner.swift  
- Info.plist  
- MemoScribe.xcdatamodeld/  
- MemoScribe.xcdatamodel/  
- contents  
- MemoScribeApp.swift  
- Persistence.swift  
- Recording.swift  
- UploadManager.swift  
- README.md  
</context>

具体内容就不分析了， 我觉得其中最大的亮点是 task management。prompt 里着重强调了：

Use these tools VERY frequently ...
These tools are also EXTREMELY helpful for planning tasks, and for breaking down larger complex tasks into smaller steps. If you do not use this tool when planning, you may forget to do important tasks — and that is unacceptable. It is critical that you mark todos as completed as soon as you are done with a task. Do not batch up multiple tasks before marking them as completed.

writeTodo 这个 tool 的 spec 也写的非常的长，在这里就不贴了，有兴趣的同学可以自己去看。

之前有一个 devin.cursorrules 项目，是让 plain cursor 拥有更强的 agent 能力。试用过的话应该可以看出 writeTodo 这个工具的含金量。我觉得这是一个更进阶版的 scratchpad.md：主要是有多个子任务的管理。

具体效果大概是这样的

不知道为什么 TODO list 并没有写在项目路径下面。但稍微探索了一下发现了 ~/.claude 这个文件夹，发现是一个 json。另外这个文件夹发现了一个 sqlite databse，里面主要是存了消息。还发现了 statsig（一个专门做数据实验的 startup，看来 claude 还是很重视做数据实验的）

./__store.db> \dt
+------------------------+
| name                   |
+------------------------+
| __drizzle_migrations   |
| assistant_messages     |
| base_messages          |
| conversation_summaries |
| user_messages          |
+------------------------+

因为暂时还没有深度在项目中使用，所以这个 todo 的具体效果还有待检验。

---

稍微发挥一下，我大胆预测 task management（以及 memory/knowledge management？）必定是未来 agentic coding tool 的标配（乃至所有 agentic app？），甚至有点疑惑为什么 cursor 到现在还没有推出自己的 task management 方案，感觉有点落后了。

但或许我想的是错的，是不是直接通过 MCP 插一个 todo manager 就够用了？并不需要 app 原生的任务管理工具。

比如现在也有外置的 task management 工具，例如 task master（貌似很火）（支持命令行或 MCP 调用） https://github.com/eyaltoledano/claude-task-master （视频介绍 https://www.youtube.com/watch?v=1L509JK8p1I）我还没试过，但是直觉上觉得它有点不必要地复杂：弄个很长的 prd，然后分解成十几个 subtask。

其他一些有趣的观察

apply edit

cursor 自己训练了一个LLM 来专门做 apply edit，所以我很好奇 claude code 这个命令行“小工具”是怎么做到的。试了一下发现 tool call 基本上只用 Write，而不用 Edit。

仔细一看 edit 的 tool spec，里面有一行 “For larger edits, use the Write tool to overwrite files”——我一下子顿悟了，如果直接无脑全文覆盖，不就绕过了 apply edit 的困难吗？如果 instruction following 能力强的话，那效果应该不错，只是费电 token 罢了。

在写完之后，会有一个 diff 效果，细节还是做的不错的。

甚至还有 (Rest of file unchanged) 这种 magic 的体验

…………并不是，它是真的把代码删了，把这个注释写进去了。看来完全依赖 AI 的 instruction following 还是没那么靠谱（这里用的模型是 gpt4.1。或许默认的 claude3.7 会好一点）

WebFetch

WebFetch 这个 tool 的参数在 URL 之外还有一个 prompt。大号模型生成 tool call，包括这个 prompt，然后会把网页以及 prompt 组合让小模型总结网页内容，最后只把一小段文字传回给大号模型作为 context。这个两阶段的过程还是挺细腻的，应该比把高噪音的html 直接给模型要效果好。

自动带的 code context

这个有点神秘，我在发出一个指令以后，claude code 自己挑选了一些文件加入了 context。

这个步骤并没有 tool use，也没有额外的模型总结，在 ~/.claude 目录下也没有发现类似代码索引的东西，所以感觉有点神秘。感觉 claude code 还是藏了点东西的。

总结

整体看下来，claude code 确实是个细节打磨得不错的工具：terminal UX 不错，prompt 和 task management 用心。

虽然他的效果我还没有经过大规模实战检验，但是我已经不禁难免在思考：AI coding 好像确实没那么需要一个 IDE，terminal 这个形态感觉很合理。让 agent 在 terminal 写，人类使用寻常的 IDE 例如原生 VS Code 进行 review、进一步编辑，好像没有任何问题，不比在 IDE 里 chat 慢/效果差。

再进一步思考，对于 agent 模式，cursor 相比 claude code 多了什么？我一下子能想到的有：

• apply 模型：或许可以有更高的准确率以及性能？但有点存疑，因为最近一段时间感觉失败率甚至有点高。
• 原生的 fix lint：并非反复在对话里让 ai 修，感觉和 apply/edit 一样，是另外一个专门 fix lint 的小模型。为了做到这个，或许需要依赖 IDE/LSP 的一些静态分析功能。但或许从命令行跑 lint 也完全能达到这个效果。
• codebase index & vector search：同理，感觉这个功能并不强依赖 IDE，原则上如果做进命令行也没什么不可。

……这么一想，感觉 agentic coding tool（startup）的未来越发不明朗了。特别是 cursor 这种 fork 的 IDE。或许像 Augment Code 这样的纯插件方案更有前途一点。（似乎连当初最吸引我的 cursor tab 功能都以纯插件的方式做到了，那在 agent 之外，ai assited coding 上也做的很好了）

后记

写完才想起来还有最新的 openai codex 这个项目。它是纯开源的，prompt 和 tool 直接看的一清二楚，就不用特意扒了。但是看看 request log 还是个不错的观察切面。

P.S.，发现 codex 的 issue 里竟然没人提 task management 这件事（于是我去提了一个）。