Claude Code 源码解析丨从 6 个问题窥视 CC 的 Harness Engineering

Claude Code 源码"开源"之后，相信很多人拿着各种 AI 工具对其源码进行了一顿操作，然而，相信大部分人，都是让 CC "重新认识了一遍自己"，AI 学会了，但自己好像没学会。

笔者认为，带着问题去让 AI 进行主题性分析的话，或许会有更大的收获。

目前绝大部分 Agent 无非就是一个 ReAct 循环，只不过将这个几十行代码的 ReAct 扩展成了若干万行代码，以满足不同的场景需求。Claude Code 当然也不例外，那为什么 Claude Code 能在众多 Agent（尤其是 Coding CLI 中）脱颖而出呢？

笔者对以下几个问题其实是十分好奇的：

提示

1. Claude Code 每次 LLM API 调用的 Prompt 是怎样的？
   1. Prompt 的组成 部分是怎样的？为什么是选择这些而不是别的？
   2. Prompt 有哪些撰写原则？我们能学到什么？
   3. Prompt 过长时，压缩机制是怎样的？
2. Claude Code 的 ReAct 循环是怎样的？在 Receive-Action-Observe 这个循环中，它做了哪些不一样的东西？
3. Claude Code 内置了哪些工具，以支撑它如此灵活地完成各种各样的任务？工具体系又是如何搭建的？
4. Claude Code 在"写代码（修改文件）"的时候，究竟发生了什么？

当然还有很多很多其他的问题，比如权限系统、sub-agent 体系、UI 优化等。不过贪多嚼不烂，笔者目前对上述问题是比较感兴趣的，所以就让 Claude Code 对着它自己的源码，通过对这些问题层层展开，最后由笔者整理成本文。

注：本文尽力避免"万字长文"，怎奈为使行文连贯，有些地方难免啰嗦。好在每章自成主题，可单独阅读，按需食用即可。

1Claude Code 每一个 Prompt 是如何组织的

如上图所示，发给 Claude API 的最终请求结构其实很简单：

{
  system: string[],
  messages: Message[],
  tools: Tool[]
}

但构建这个请求的过程远不简单。整个 Prompt 的构建可以分为三个核心区域：

1.1System Prompt：Claude Code 的"灵魂"

System Prompt 是整个架构中最精心设计的部分。它分为静态部分和动态部分，两者之间由一个关键的边界标记 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 分隔。

静态部分定义在 constants/prompts.ts 中，包含 7 个 Section，如图所示不再赘述。

这部分无论固定不变的。 ← 所以可以命中 KV Cache，提高响应速度的同时，减少 token 费用。

在静态和动态部分之间，有一段至关重要的文字：

提示

"Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior."

这段话的意义深远——它告诉 Claude，接下来的动态指令（包括用户的自定义规则）优先级高于默认行为。这就是为什么我们在 CLAUDE.md 中写的规则能够生效。

动态部分由 utils/cloudend.ts 生成，包含多达 8 个组件，如图所示不再赘述。

这里值得特别展开的是 CLAUDE.md 的加载。Claude Code 会从多个位置按照优先级依次查找并合并配置。这个设计非常优雅，它允许从企业级的全局规范到个人项目的特定偏好，形成一个完整的配置层级。越靠近当前工作目录的规则，优先级越高。

1.2Messages：上下文的大拼图（附件系统）

Messages 是整个 Prompt 中最复杂的部分。一条看似简单的用户消息，在发送给 API 之前，会被附加大量的上下文信息，具体分为以下 2 个部分：

如上图所示，附件系统是 Claude Code 的核心设计之一，实现在 utils/attachments.ts 中（三层结构）。

这里要思考几个问题：

1. 为什么需要附件系统？
2. 附件为什么需要分层？
3. 这么多的附件类型是一回事，关键是，为什么是它们？
4. 这么多附件，每次注入的时候如何选择？

1.2.1 为什么需要附件系统？

先思考第 1 个问题，为什么需要附件系统？

提示

模型不知道你刚在 IDE 里手动改了一行代码，不知道 linter 自动格式化了文件，不知道长会话已经跨越了午夜。附件系统的工作，就是在每个 turn 自动注入这些模型"应该知道但没法主动获取"的信息。

1.2.2 附件为什么要分层？

根据不同的触发条件，附件被分为三类：

现在可以回答第 2 个问题：为什么要分层？

提示

子 agent 被分配了"重构 parser.ts"的子任务，它需要知道 parser.ts 是否被外部修改了（changed_files，在 allThread 层），但不需要知道用户在 IDE 里选中了哪段代码（ide_selection，在 mainThread 层）。信息按需分发，不是所有线程看到所有东西。

1.2.3 为什么是这些附件？

要解答第 3 个问题，我们可以将附件按照它们要解决的问题分类，这样能更好地理解设计意图。

1.2.4 如何选择要注入的附件？

附件不是每轮都全量注入的——那样会快速耗尽上下文窗口。每种附件都有精心设计的触发条件、去重策略和生命周期管理：

1.3Tools：强大的工具体系

请见 🫱 4. Claude Code 的工具体系

2Claude Code 的 Prompt 有哪些撰写原则

在知道了 Claude Code 每一个 Prompt 的组成部分之后，里面具体写了什么呢？有没有一些最佳实践是我们可以参考（抄）的呢？当然是有的，经对源码进行分析后，笔者（借助 AI）提取出了 Claude Code 在 Prompt Engineering 的 8 个最佳实践，可供参考。

提示

一句话总结： Claude Code 的 prompt 哲学是：不教模型"怎么做好"，而是堵住模型"会做错"的所有口子；不用抽象规则，而用具体场景；不靠文字约束，而靠系统设计让错误行为无法发生。

2.1行为塑造靠"反面清单"，不靠"正面宣言"

传统做法是告诉 AI "你是一个优秀的程序员"。Claude Code 几乎不做正面描述，而是用大量具体的禁止行为来约束：

"Don't add features, refactor code, or make 'improvements' beyond what was asked."
"Don't add docstrings, comments, or type annotations to code you didn't change."
"Don't add error handling, fallbacks, or validation for scenarios that can't happen."
"Don't create helpers, utilities, or abstractions for one-time operations."
"Three similar lines of code is better than a premature abstraction."

LLM 天然倾向"过度工程化"和"讨好用户"。不写反面清单，模型会不断添加不必要的代码。这些禁令是从大量真实用户反馈中提炼出来的,每一条背后都是一个"模型做过头了"的真实场景。

提示

写 prompt 时，先想"AI 最容易犯什么错"，然后写对应的禁令。

2.2用具体场景代替抽象规则

Claude Code 从不写"请谨慎操作"这样的空话，而是给出具体例子和边界条件：

"Examples of the kind of risky actions that warrant user confirmation:
 - Destructive operations: deleting files/branches, dropping database tables,
   killing processes, rm -rf, overwriting uncommitted changes
 - Hard-to-reverse operations: force-pushing, git reset --hard, amending
   published commits, removing or downgrading packages/dependencies
 - Actions visible to others: pushing code, creating/closing/commenting on
   PRs or issues, sending messages (Slack, email, GitHub)"

又比如对 git 的操作：

"A user approving an action (like a git push) once does NOT mean that they
 approve it in all contexts"

"If you discover unexpected state like unfamiliar files, branches, or
 configuration, investigate before deleting or overwriting, as it may
 represent the user's in-progress work."

提示

每条规则都用"例如..."或具体场景补充。让模型能类比推理到新场景。

2.3面向失败模式设计，每条规则对治一个真实 BUG

读 prompts.ts 的注释能看到很多 @[MODEL LAUNCH] 标记，说明这些指令是针对特定模型版本的行为问题定制的：

// @[MODEL LAUNCH]: capy v8 thoroughness counterweight (PR #24302)
"Before reporting a task complete, verify it actually works: run the test,
 execute the script, check the output."

// @[MODEL LAUNCH]: False-claims mitigation for Capybara v8 (29-30% FC rate)
"Never claim 'all tests pass' when output shows failures, never suppress or
 simplify failing checks to manufacture a green result"

// @[MODEL LAUNCH]: Remove or soften once the model stops over-commenting
"Default to writing no comments. Only add one when the WHY is non-obvious"

提示

Prompt 不是一次性写好的。应该持续监控模型行为，发现问题后添加对应的矫正指令。这是一个持续迭代的工程过程。

2.4面向人类用户体验的输出控制

Claude Code 对输出格式的控制极其细致：

"Lead with the answer or action, not the reasoning."
"Use inverted pyramid when appropriate (leading with the action), and if
 something about your reasoning is so important that it absolutely must be
 in user-facing text, save it for the end."

“先给出答案或行动方案，而非先阐述理由。”
“在适当的情况下采用倒金字塔结构（先讲行动方案），如果您的理由中有某些内容非常重要，必须出现在面向用户的文本中，那么就将其放在最后。”

"Match responses to the task: a simple question gets a direct answer in prose,
 not headers and numbered sections."
"Only use tables when appropriate; for example to hold short enumerable facts.
 Don't pack explanatory reasoning into table cells."

“将回答与任务内容相匹配：简单的问题应给出明确的散文式回答，而非使用标题和编号列表形式。”
“仅在适当的情况下使用表格；例如用于展示简短的可列举事实。切勿将解释性推理内容塞进表格单元格中。”

"Focus text output on:
 - Decisions that need the user's input
 - High-level status updates at natural milestones
 - Errors or blockers that change the plan"

"If you can say it in one sentence, don't use three."

“将文本输出的重点放在以下方面：
- 需要用户参与的决策事项
- 在自然的阶段性节点上呈现的高级状态更新
- 会改变计划的错误或阻碍因素”
“如果能用一句话表达清楚就不要用三句话。”

"Avoid semantic backtracking: structure each sentence so a person can read it
 linearly, building up meaning without having to re-parse what came before."

 “避免语义回溯：将每个句子进行结构设计，以便读者能够按线性顺序阅读，从而逐步构建出意义，而无需反复解析之前的内容。”

提示

不只管"模型说什么"，还管"模型怎么说"。输出质量 = 信息量 / 认知负荷。

2.5用隐式约束

最巧妙的是通过工具系统设计而非 prompt 文字来约束行为：

工具描述中（getEditToolDescription）：

"You MUST use your Read tool at least once before editing."
→ 不是建议，是工具层面的强制（validateInput 会检查 readFileState）

"The edit will FAIL if old_string is not unique in the file."
→ 不是提醒，是实际的校验逻辑

工具可用性控制：

- Glob/Grep 存在 → prompt 告诉模型 "Use Glob instead of find"
- Glob/Grep 不存在（embedded 模式）→ 这段 prompt 自动消失
→ 工具集和 prompt 始终一致

提示

最好的 prompt 是让错误行为根本无法执行，而不是"请不要这样做"。

2.6预设用户的"走开"场景

Claude Code 假设用户不会一直盯着屏幕：

"When making updates, assume the person has stepped away and lost the thread.
 They don't know codenames, abbreviations, or shorthand you created along the
 way, and didn't track your process. Write so they can pick back up cold:
 use complete, grammatically correct sentences without unexplained jargon."

"Before your first tool call, briefly state what you're about to do.
 While working, give short updates at key moments."

提示

Agent 的输出应该是自包含的进度报告，不是需要"回看上文"才能理解的日志。

2.7精确的权限边界语言

安全相关的 prompt 使用了极其精确的法律式语言：

"Authorization stands for the scope specified, not beyond."

"Match the scope of your actions to what was actually requested."

"Follow both the spirit and letter of these instructions — measure twice, cut once."

安全领域：

"Assist with authorized security testing, defensive security, CTF challenges,
 and educational contexts. Refuse requests for destructive techniques, DoS
 attacks, mass targeting, supply chain compromise, or detection evasion for
 malicious purposes."
→ 不是简单的"不要做坏事"，而是穷举了允许和禁止的边界

提示

安全指令要像法律条文——穷举允许项和禁止项，不留模糊地带。

2.8优秀的工程管理

3Claude Code 的 ReAct 循环剖析

如上图所示，这是一个经典的 ReAct 循环，事实上绝大部分的 Agent 都是一个 ReAct 循环。关键在于，Claude Code 是如何把一个几十行代码的 ReAct 循环硬生生整出超过 51w 行代码的？或者说，为啥要这样？这可能就是最近比较火的 Harness Engineering 了吧。

接下来让我们从上图这 5 个阶段来一一拆解。

3.1消息预处理阶段

这里 Claude Code 在压缩（compact）Prompt 的处理，是值的我们学习的。谈到压缩，我们一般能想到的就是滑动窗口，丢失掉旧的数据，这个时候我们会怕关键信息丢失，所以自然就想到了调另外一个 LLM 来做 summarize，一般也就到此为止了。

而 Claude Code 的压缩并不是一个简单的"满了就摘要"的操作，而是一套从轻到重的五级渐进式降级策略。这五级从轻到重依次执行，每一级解决一个特定的膨胀来源，设计思想是能不动就不动，能少压就少压。

每一级都只在前一级不够用时才启动。大部分对话只会触发前三级，只有真正的超长会话才会走到 Autocompact。这既节省了 LLM 调用成本，也最大限度地保留了对话上下文的完整性。

当然，其中最具挑战、最容易造成信息损失的，还是 Autocompact。在让 LLM 进行 summarize 的时候，我们需要思考以下几个问题：

1. 什么时候触发 Autocompact？
2. 提示词是怎样的？（要留哪些东西？舍弃哪些东西？）
3. summarize 后仍然超长怎么办？

3.1.1 什么时候触发压缩？

3.1.2 压缩的提示词是什么？

获取压缩 prompt 的代码如下：

export function getCompactPrompt(customInstructions?: string): string {
  let prompt = NO_TOOLS_PREAMBLE + BASE_COMPACT_PROMPT;
  if (customInstructions && customInstructions.trim() !== "") {
    prompt += `\n\nAdditional Instructions:\n${customInstructions}`;
  }
  prompt += NO_TOOLS_TRAILER;
  return prompt;
}

说白了，就是三个部分：

const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.

`;

const BASE_COMPACT_PROMPT = `Your task is to create a detailed summary of the conversation so far, paying close attention to the user's explicit requests and your previous actions.
This summary should be thorough in capturing technical details, code patterns, and architectural decisions that would be essential for continuing development work without losing context.

${DETAILED_ANALYSIS_INSTRUCTION_BASE}

Your summary should include the following sections:

1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Pay special attention to the most recent messages and include full code snippets where applicable and include a summary of why this file read or edit is important.
4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users' feedback and changing intent.
7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
8. Current Work: Describe in detail precisely what was being worked on immediately before this summary request, paying special attention to the most recent messages from both user and assistant. Include file names and code snippets where applicable.
9. Optional Next Step: List the next step that you will take that is related to the most recent work you were doing. IMPORTANT: ensure that this step is DIRECTLY in line with the user's most recent explicit requests, and the task you were working on immediately before this summary request. If your last task was concluded, then only list next steps if they are explicitly in line with the users request. Do not start on tangential requests or really old requests that were already completed without confirming with the user first.
                       If there is a next step, include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off. This should be verbatim to ensure there's no drift in task interpretation.

Here's an example of how your output should be structured:

<example>
<analysis>
[Your thought process, ensuring all points are covered thoroughly and accurately]
</analysis>

<summary>
1. Primary Request and Intent:
   [Detailed description]

2. Key Technical Concepts:
   - [Concept 1]
   - [Concept 2]
   - [...]

3. Files and Code Sections:
   - [File Name 1]
      - [Summary of why this file is important]
      - [Summary of the changes made to this file, if any]
      - [Important Code Snippet]
   - [File Name 2]
      - [Important Code Snippet]
   - [...]

4. Errors and fixes:
    - [Detailed description of error 1]:
      - [How you fixed the error]
      - [User feedback on the error if any]
    - [...]

5. Problem Solving:
   [Description of solved problems and ongoing troubleshooting]

6. All user messages: 
    - [Detailed non tool use user message]
    - [...]

7. Pending Tasks:
   - [Task 1]
   - [Task 2]
   - [...]

8. Current Work:
   [Precise description of current work]

9. Optional Next Step:
   [Optional Next step to take]

</summary>
</example>

Please provide your summary based on the conversation so far, following this structure and ensuring precision and thoroughness in your response. 

There may be additional summarization instructions provided in the included context. If so, remember to follow these instructions when creating the above summary. Examples of instructions include:
<example>
## Compact Instructions
When summarizing the conversation focus on typescript code changes and also remember the mistakes you made and how you fixed them.
</example>

<example>
# Summary instructions
When you are using compact - please focus on test output and code changes. Include file reads verbatim.
</example>
`;

const NO_TOOLS_TRAILER =
  "\n\nREMINDER: Do NOT call any tools. Respond with plain text only — " +
  "an <analysis> block followed by a <summary> block. " +
  "Tool calls will be rejected and you will fail the task.";

3.1.3 压缩后还超长怎么办？

摘要不够短就砍掉更多历史再摘要，直到低于阈值。渐进式截断而非一次性丢弃，尽可能多保留信息。

export async function compactConversation(...) ... {
      ...
    let ptlAttempts = 0
    for (;;) {
      ...
      ptlAttempts++
      const truncated =
        ptlAttempts <= MAX_PTL_RETRIES
          ? truncateHeadForPTLRetry(messagesToSummarize, summaryResponse)
          : null
      if (!truncated) {
        throw new Error(ERROR_MESSAGE_PROMPT_TOO_LONG)
      }
    ...
    }
        ...
}

3.1.4 Autocompact 总结

3.2Thinking 阶段：调用 LLM 生成下一轮思考/行动

3.3Act 阶段：执行 LLM 请求的工具调用，获取结果

3.4Observe 阶段：收集工具结果和外部输入，准备下一轮

3.5状态更新 & 继续判断：决定是继续循环还是退出

3.6我们能学到什么？

了解了上述 5 个阶段后，我们能学习什么？这里笔者像转变一下视角：

提示

不是 Claude Code 设计了什么，而是工业级 Agent 必须具备什么？Claude Code 又是怎么满足的？

笔者认为可以考虑以下几个硬性需求：

4Claude Code 的工具体系

4.1架构全景

4.2工具总览

4.3工具接口

type Tool<Input, Output, P> = {
  // ═══ 身份 ═══
  name: string                    // 唯一名称，如 "Glob", "Bash"
  aliases?: string[]              // 别名（重命名兼容）
  searchHint?: string             // ToolSearch 的关键词提示

  // ═══ Schema ═══
  inputSchema: ZodObject          // Zod schema，定义输入参数
  inputJSONSchema?: JSONSchema    // MCP 工具用 JSON Schema 替代
  outputSchema?: ZodType          // 输出 schema

  // ═══ 核心执行 ═══
  call(input, context, canUseTool, parentMsg, onProgress?)
    : Promise<ToolResult<Output>>         // 执行工具！

  // ═══ 权限 ═══
  validateInput?(input, context)          // 语义校验（路径存在？参数合法？）
    : Promise<ValidationResult>
  checkPermissions(input, context)        // 工具特有权限检查
    : Promise<PermissionResult>
  preparePermissionMatcher?(input)        // Hook if 条件匹配器
    : Promise<(pattern) => boolean>

  // ═══ 属性查询 ═══
  isEnabled(): boolean                    // 当前环境是否启用
  isConcurrencySafe(input): boolean       // 可否与其他工具并行执行
  isReadOnly(input): boolean              // 是否只读
  isDestructive?(input): boolean          // 是否破坏性操作
  interruptBehavior?(): 'cancel' | 'block' // 用户中断时的行为

  // ═══ 结果处理 ═══
  mapToolResultToToolResultBlockParam(output, toolUseID)
    : ToolResultBlockParam                // 转成 API tool_result 格式
  maxResultSizeChars: number              // 超此大小持久化到磁盘

  // ═══ UI 展示 ═══
  description(input, options): Promise<string>  // 发给模型的工具描述
  prompt(options): Promise<string>              // system prompt 中的描述
  userFacingName(input): string                 // 终端显示名
  renderToolUseMessage?(...)                    // 渲染工具调用
  renderToolResultMessage?(...)                 // 渲染工具结果
  getActivityDescription?(input): string        // spinner 显示的活动描述

  // ═══ 高级特性 ═══
  shouldDefer?: boolean           // 延迟加载（ToolSearch 触发后才可用）
  alwaysLoad?: boolean            // 强制始终加载（不延迟）
  isMcp?: boolean                 // 是否 MCP 工具
  backfillObservableInput?(input) // 向观察者填充派生字段
}

提供安全的默认值（fail-closed 原则）：

4.4工具工厂

buildTool() —— 工具工厂 (Tool.ts:783)

export function buildTool(def) {
  return { ...TOOL_DEFAULTS, userFacingName: () => def.name, ...def }
}

4.5GlobTool 为例

src/tools/GlobTool/
  ├── GlobTool.ts   ← 工具定义（核心逻辑）
  ├── prompt.ts     ← 工具描述文本（发给模型）
  └── UI.tsx        ← 终端渲染组件

完整实现如下：

export const GlobTool = buildTool({
  // ── 身份 ──
  name: 'Glob',
  searchHint: 'find files by name pattern or wildcard',
  maxResultSizeChars: 100_000,

  // ── Schema ──
  inputSchema: z.strictObject({
    pattern: z.string(),
    path: z.string().optional(),
  }),

  // ── 属性 ──
  isConcurrencySafe: () => true,     // ← 文件搜索可以并行
  isReadOnly: () => true,            // ← 只读操作

  // ── 校验 ──
  validateInput({ path }) {           // ← path 存在且为目录？
    if (path) {
      const stats = await fs.stat(expandPath(path))
      if (!stats.isDirectory()) return { result: false, ... }
    }
    return { result: true }
  },

  // ── 权限 ──
  checkPermissions(input, context) {  // ← 读权限检查
    return checkReadPermissionForTool(GlobTool, input, ...)
  },

  // ── 核心执行 ──
  call(input, { abortController, getAppState, globLimits }) {
    const { files, truncated } = await glob(
      input.pattern,
      GlobTool.getPath(input),
      { limit: globLimits?.maxResults ?? 100 },
      abortController.signal,
    )
    return {
      data: { filenames: files.map(toRelativePath), durationMs, numFiles, truncated }
    }
  },

  // ── 结果转 API 格式 ──
  mapToolResultToToolResultBlockParam(output, toolUseID) {
    return {
      type: 'tool_result',
      tool_use_id: toolUseID,
      content: output.filenames.join('\n'),
    }
  },
})

4.6工具注册

💡 关键设计原则

• feature() 门控在编译时做死代码消除（DCE），不同构建版本有不同工具集。
• 工具排序保证 prompt cache 命中率——内置工具始终是 contiguous prefix。
• uniqBy('name') 确保内置工具与 MCP 同名工具不冲突。

4.7MCP 集成

MCP 工具的特殊之处：

4.8工具执行

4.9权限控制

5Claude Code 是如何修改代码的

在对 Claude Code 的上下文管理、ReAct 循环、Harness Engineering 和工具体系有了一个基本的了解之后，笔者身为程序员，自然最关心的就是"修改代码"这件事情了，所以本节我们就落到这个具体的需求点上，来探讨一下 Claude Code 在做修改代码这件事情的时候，到底做了什么。

当面对这个问题的时候，笔者心中又衍生了几个小问题：

1. 修改代码这个行为是怎么完成的？
2. 如何确保修改的精确性？
3. 如何确保修改的全面性？
4. 如何确保修改的安全性？（并发冲突...）
5. 如何确保修改的语法正确性？
6. 如何确保修改的功能正确性？
7. 修改后整个上下文管理发生了什么？

好的，让我们一一解答。（废了，我不想要"万字长文"的 🤷🏻‍♀️🤡😷）

5.1修改代码这个行为是怎么完成的？

Claude Code 修改文件有两个工具：

System prompt 引导模型优先使用 Edit——修改 500 行文件中的 1 行，Edit 只需发送 ~10 行 token，Write 则需发送全部 500 行。

"ALWAYS prefer editing existing files. NEVER write new files unless explicitly required."

举个例子：

输入:
  file_path:  "/project/src/auth.ts"
  old_string: "function login(user) {\n  return false\n}"
  new_string: "function login(user) {\n  return authenticate(user)\n}"

执行:
  fileContent.replace(old_string, new_string)

 function login(user) {−  return false（删除）+  return authenticate(user)（新增） }

为什么选这个方案？ —— 因为它匹配 LLM 的能力特征：

5.2如何确保修改的精确性？

提示

核心问题：模型给出的 old_string，能不能准确定位到文件中的正确位置？

5.2.1 唯一性校验 - 不允许歧义

默认 replace_all = false，要求 old_string 在文件中只出现一次：

// 匹配 3 次 → 拒绝

"Found 3 matches, but replace_all is false. Provide more context to uniquely identify the instance."

这个设计迫使模型提供足够的上下文行来唯一定位修改点。模型不能只写 return false（可能出现多次），必须包含上下行直到唯一。

5.2.2 先读后写 - 禁止盲改

const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
if (!readTimestamp) {
  → 拒绝: "File has not been read yet. Read it first."
}

模型必须先用 FileReadTool 读过文件。这确保 old_string 是基于当前真实内容构造的，而不是基于训练数据中的"记忆"。

5.2.3 编码和换行符保留 - 不引入格式噪音

读取时: 检测编码(UTF-8/UTF-16LE) + 换行符(LF/CRLF) → 记录
替换时: 在标准化的 \n 文本上操作
写入时: 用原始编码 + 原始换行符写回

不保留的后果：Windows 项目 CRLF 文件被转成 LF → git diff 爆炸，每行都显示被修改。

5.3如何确保修改的全面性？

提示

核心问题：如果需要改多处，怎么保证不遗漏？

5.3.1 replace_all 模式

一个 Edit 调用 + replace_all: true 可以一次替换文件中所有匹配——适用于变量重命名等场景。

5.3.2 对话循环驱动多文件修改

Claude Code 的修改不是一次性的，而是对话循环驱动的多轮工具调用：

模型: "我需要修改 3 个文件"
  → tool_use: Edit(file_a, ...)
  → tool_use: Edit(file_b, ...)
  → tool_use: Edit(file_c, ...)
  → "修改完成"

模型可以在一轮中发出多个 Edit 调用，并行执行（Glob/Grep/Read 是 concurrency_safe，可并行；Edit 是非 safe，串行执行）。

5.3.3 Agent 并行修改

主线程可以 spawn 子 Agent 并行处理不同文件/模块：

主 Agent: "重构 auth 模块"
  ├── spawn Explore Agent → 搜索所有相关文件
  ├── 基于搜索结果，spawn 多个 General Agent → 各自修改不同文件
  └── 汇总结果

5.3.4 附件系统的"变更感知"

每轮工具执行完成后，changed_files 附件会检测哪些文件被外部修改（linter、format-on-save 等），注入 diff snippet 告知模型：

"Note: auth.ts was modified, either by the user or by a linter.
 Here are the relevant changes: ..."

模型看到这些变更后可以决定是否需要追加修改——确保不遗漏 linter 引入的变化。

5.4如何确保修改的安全性？

提示

核心问题：并发冲突、外部修改、误操作如何防范？

5.5如何确保修改的语法正确性？

提示

核心问题：替换完成后，文件的语法是否仍然合法？

5.5.1 Claude Code 当前策略：事后检测而非事前校验

FileEditTool 本身不做任何语法检查——它是语言无关的纯文本替换。语法正确性由两个机制保障：

5.5.2 工程建议：借鉴强类型语言的编译时保障

当前的"事后检测"模式存在缺陷：先写入错误代码 → LSP 报错 → 模型再修 → 又一轮 API 调用。每次修复循环至少浪费一轮 token。更好的思路是写入前校验。

这个时候，静态强类型语言的编译器（如 TypeScript 和 Rust），就可以发挥巨大的作用。

5.6如何确保修改的功能正确性？

提示

核心问题：语法对了，但逻辑是否正确？功能是否如预期？

这不是单个工具能解决的问题。我们可以通过三道防线构建功能正确性保障：

1. Prompt 引导自验证

2. TDD 驱动的验证循环

3. 独立于执行者的外部校验

5.6.1 第一道防线：Prompt 引导自验证

Claude Code 的 System prompt 中存在以下关键指令:

"Before reporting a task complete, verify it actually works:
 run the test, execute the script, check the output."

"If you can't verify (no test exists, can't run the code),
 say so explicitly rather than claiming success."

"Never claim 'all tests pass' when output shows failures."

这些不是建议，而是行为纠偏指令——专门针对模型"虚报成功"的倾向。

5.6.2 第二道防线：TDD 驱动的验证循环

Claude Code 的对话循环天然支持 红-绿-重构 的 TDD 工作流：

理想流程（TDD 先行）:

用户: "给 authenticate 函数添加 token 过期检查"

模型: Read(auth.test.ts)                → 了解现有测试
模型: Edit(auth.test.ts, ...)           → 先写测试（红）
模型: Bash("npm test")                  → 确认测试失败（红 ✓）
模型: Read(auth.ts)                     → 了解实现
模型: Edit(auth.ts, ...)                → 修改实现（绿）
模型: Bash("npm test")                  → 确认测试通过（绿 ✓）
模型: "修改完成，新增了 token 过期测试，所有测试通过。"

实际常见流程:

模型: Edit(auth.ts, ...)                → 修改代码
模型: Bash("npm test")                  → 运行已有测试
      ← 失败: "TypeError: authenticate is not a function"
模型: Read(auth.ts)                     → 重读文件
模型: Edit(auth.ts, ...)                → 修复问题
模型: Bash("npm test")                  → 再次运行
      ← 所有测试通过

即使模型不主动做 TDD，现有测试也充当安全网。

TDD 思维对 AI Coding 的特殊价值：

当没有测试时——这是最危险的场景。Claude Code 的 prompt 要求模型明确说 "I can't verify" 而不是假装成功。但更好的做法是：模型主动为修改的代码补充测试。这可以通过 CLAUDE.md 中的项目级指令强化：

# CLAUDE.md

修改任何函数时，如果该函数没有测试，先补充测试再修改实现。

5.6.3 第三道防线：独立于执行者的外部校验

5.7修改后整个上下文管理发生了什么？

提示

核心目标：让模型在每一轮都拥有与真实世界一致的认知。

整体状态（state）的迁移图如下：

一次 Edit 不只是"改了一个文件"——它更新了系统的文件认知（readFileState）、触发了语言服务器重分析（LSP）、通知了用户的 IDE（VSCode）、创建了可撤销的备份（fileHistory），并在下一轮对话中通过附件系统将所有变化反馈给模型。整个上下文管理的目标是：让模型在每一轮都拥有与真实世界一致的认知。

5.8串一下整个流程

一个完整的代码修改流程如下所示：

Step 1: 基础校验
├── old_string === new_string? → 拒绝（无变化）
├── deny 规则检查 → 路径是否被禁止编辑
├── UNC 路径安全检查（防 NTLM 泄露）
└── 文件大小 > 1GiB? → 拒绝（防 OOM）

Step 2: 读取文件
├── 检测编码（UTF-8 / UTF-16LE）
├── CRLF → LF 标准化
├── 文件不存在 + old_string 为空 → 创建新文件
└── .ipynb 文件 → 引导用 NotebookEditTool

Step 4: 查找 old_string
├── 精确匹配 → 使用
├── 不匹配 → 尝试 curly quote 标准化匹配
│ (文件中 'hello' → 模型输出 'hello' → 自动匹配)
└── 仍不匹配 → 拒绝: "String to replace not found"

Step 5: 唯一性检查
├── 匹配 1 次 → OK
├── 匹配 > 1 次 且 replace_all=false
│ → 拒绝: "Found N matches, set replace_all=true or provide more context"
└── 匹配 > 1 次 且 replace_all=true → OK（替换全部）

Step 6: 写权限检查
└── checkWritePermissionForTool() → allow/ask/deny

Step 7: 执行替换
├── 7a. 发现技能目录（非阻塞）
├── 7b. 诊断追踪器 beforeFileEdited()
├── 7c. 确保父目录存在 mkdir()
├── 7d. 文件历史备份（若启用）
├── 7e. 同步读取文件（原子性临界区开始）
│ readFileSyncWithMetadata() ← 保留编码和换行符
├── 7f. 再次检查文件未被修改（staleness check）
│ mtime > lastRead.timestamp? → throw Error
├── 7g. findActualString() → 处理 curly quote
├── 7h. preserveQuoteStyle() → 保留文件原有引号风格
├── 7i. getPatchForEdit() → 生成 patch + 新文件内容
│ replace_all ? file.replaceAll(old, new) : file.replace(old, new)
├── 7j. writeTextContent() ← 写入磁盘 ★★★
│ 保留原始编码（UTF-8/UTF-16LE）
│ 保留原始换行符（LF/CRLF）

Step 8: 后置处理
├── 8a. 通知 LSP 服务器 didChange + didSave
├── 8b. 通知 VSCode 更新 diff 视图
├── 8c. 更新 readFileState（更新 timestamp 和 content）
├── 8d. 记录遥测事件
└── 8e. 返回 { filePath, oldString, newString, originalFile, structuredPatch }

6写在最后

Claude Code 的"开源"，给了我们一个难得的机会，去理解一个工业级 AI Agent 的真实复杂度。它不是一个"更大的 demo"，而是一个充分考虑了边界情况、失败模式、用户体验的工程系统。

但更重要的是，这些设计原则是可迁移的。无论你在构建 Coding Agent、数据分析 Agent，还是任何其他领域的 Agent：

希望本文的分析能帮助读者不只是"知道 Claude Code 做了什么"，而是理解为什么这样做，并将这些思想应用到自己的实践中。

重要

毕竟，AI 学会了没用——你学会了才有用。