Claude Code不是命令行工具，而是一个"活"的系统

你有没有想过一个问题：为什么同样是命令行工具，Claude Code和ls、grep、git这些传统命令给人的感觉完全不一样？

用ls列目录，你输入什么，它就返回什么，百分之百确定。但Claude Code呢？同样是让它"看看这个文件"，有时候它会用FileReadTool，有时候会用BashTool的cat，有时候甚至会先grep搜索再决定读哪部分。

图：传统CLI像自动售货机，投币必出货；Claude Code像厨师，会根据情况决定怎么做菜

这背后的差别，不是功能多少的问题，而是本质上的不同。传统CLI工具是"死"的——它们在开发时就被写死了所有行为，分发出去之后就是那样了。Claude Code是"活"的——它在被你使用的时候，仍然能自己决定怎么做事，甚至能自己编写工具来解决问题。

今天咱们就解剖一下这个"活系统"的内脏，看看它到底怎么运转的。

三层架构：Claude Code的骨架

如果把Claude Code比作一个人，它有三层结构：

**应用层（TypeScript）**是大脑和神经系统，负责思考、决策、协调。这一层有1884个TypeScript文件，Agent Loop在这里运转，工具系统在这里注册，系统提示词在这里组装。

**运行时层（Bun/JSC）**是血液循环和肌肉系统，提供动力和执行能力。Bun负责快速启动，JavaScriptCore（Safari的JS引擎）负责执行代码，bun:bundle负责在构建时优化。

外部依赖层是感官和外部接口——Anthropic API提供大脑（模型），MCP Servers提供可扩展的工具，GrowthBook提供动态配置。

图：Claude Code的三层架构，信息在层间流动

这三层之间的信息流是双向的。应用层向下发送请求，外部依赖层向上返回结果。关键是：模型（Anthropic API）返回的结果会直接影响应用层的行为——模型决定调用什么工具、怎么调用、要不要继续。这就是为什么叫它"活"的系统：它的行为不是完全由代码预设的，而是由代码+模型+提示词共同塑造的。

“On Distribution”：分发了还能自己长本事

传统软件的开发流程是这样的：开发→测试→打包→分发→用户安装→固定行为。一旦分发出去，软件的能力就定死了，除非发新版本。

Claude Code打破了这种模式。它的核心设计理念叫"on distribution"——在分发状态下运行。什么意思呢？

想象一下，你买了台咖啡机。传统咖啡机出厂时只能做美式、拿铁、卡布奇诺，菜单是固定的。但Claude Code这台"咖啡机"不一样：它不仅能做咖啡，还能自己学会做新的饮品。你告诉它"我想喝生椰拿铁"，它可能先去学什么是生椰拿铁（通过工具搜索），然后自己调配出来（通过组合工具）。

具体体现在三个层面：

模型选择工具。每次Agent Loop迭代，模型自己决定调用哪个工具、传什么参数。工具的描述（description）和参数结构（inputSchema）不是给人看的文档，而是发给模型的指令。

模型编写自己的工具。通过BashTool，模型可以执行任意shell命令；通过FileWriteTool，模型可以创建新文件；通过SkillTool，模型可以加载和执行用户定义的提示词模板。模型在使用工具的过程中，实际上在创造新的"能力"。

模型作用于自己的上下文。通过压缩（Compaction）、微压缩（Microcompact）和上下文折叠（Context Collapse），模型参与管理自己的上下文窗口。它决定什么该记住、什么可以忘掉。

这就是为什么测试AI Agent特别难——同一个输入可能产生不同的工具调用序列。传统软件可以靠单元测试覆盖所有代码路径，但Claude Code的"代码路径"有一部分是在模型脑子里实时决定的。

启动优化：并行预取的秘密

作为CLI工具，启动速度直接影响用户体验。没人愿意输入claude之后等三秒才看到界面。

Claude Code的入口文件main.tsx前20行代码，展示了一种精心设计的启动优化策略。它把I/O密集型操作提前到模块加载的"死时间"中并行执行：

// main.tsx的启动预取
import { profileCheckpoint } from './utils/startupProfiler.js';
profileCheckpoint('main_tsx_entry');

import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';
startMdmRawRead();  // 启动MDM子进程（macOS的plutil/Windows的reg query）

import { startKeychainPrefetch } from './utils/secureStorage/keychainPrefetch.js';
startKeychainPrefetch();  // 并行读取Keychain（OAuth令牌和API密钥）

这三个操作遵循同一个模式：

• profileCheckpoint：标记入口时间点，用于性能分析
• startMdmRawRead：启动MDM（移动设备管理）子进程，与后续约135ms的模块加载并行执行
• startKeychainPrefetch：并行启动两个macOS Keychain读取操作。如果不预取，后续会通过同步spawn顺序读取，每次启动多花约65ms

图：main.tsx的启动流程，I/O操作与模块加载并行

这种设计有个特点：失败是安全的。如果Keychain访问被拒绝，ensureKeychainPrefetchCompleted()返回空值，应用回退到交互式凭证提示。如果MDM子进程超时，后续的plutil调用会以同步方式重新尝试。这叫"乐观并行+悲观回退"。

ESLint注释// eslint-disable-next-line custom-rules/no-top-level-side-effects透露了一个信息：团队有规则禁止顶层副作用，这里是经过审慎考虑后的豁免。性能优化不是随便做的，而是有原则、有回退方案的。

Feature Flag：两套并行的控制机制

Claude Code有89个构建时Feature Flag，这是它作为"快速迭代实验平台"的证据。但很多人不知道的是，它其实有两套Flag机制：

构建时feature()——来自bun:bundle，在打包时求值。这是编译时常量，不是运行时的if判断。当Bun打包器遇到feature(‘X’)时，会把它替换成true或false字面量，然后JavaScript引擎的死代码消除（DCE）会移除不可达的分支。

const WebBrowserTool = feature('WEB_BROWSER_TOOL')
  ? require('./tools/WebBrowserTool/WebBrowserTool.js').WebBrowserTool
  : null;

如果WEB_BROWSER_TOOL为false，这段代码会变成const WebBrowserTool = null;，而WebBrowserTool.js及其整个依赖树都不会出现在最终的bundle中。这不是运行时隐藏，是编译时消除——模型根本不知道这个工具存在。

运行时GrowthBook——从服务端拉取的动态配置，用于A/B测试和灰度发布。比如tengu_ultrathink_enabled控制是否启用深度思考模式。

两者是互补关系：feature()决定"这个功能是否存在"，GrowthBook决定"这个功能对哪些用户开放"。一个功能通常先由feature()守卫其模块加载，再由GrowthBook控制其运行时行为。

工具注册的四重策略

在tools.ts的getAllBaseTools()函数中，可以看到工具注册的四种策略：

策略一：无条件注册。核心工具始终可用，如AgentTool、BashTool、FileReadTool等。

策略二：构建时Feature Flag守卫。如WebBrowserTool，Flag为false时代码根本不打包。

策略三：运行时环境变量守卫。如ConfigTool和TungstenTool，通过process.env.USER_TYPE === 'ant'控制，只给Anthropic内部员工使用。这是A/B测试的"暂存区"模式。

策略四：运行时函数守卫。如GlobTool和GrepTool的条件：

...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),

当Bun单文件可执行中内嵌了搜索工具（bfs/ugrep）时，独立的GlobTool和GrepTool反而被移除——因为模型可以通过BashTool访问这些内嵌工具。这确保了不同构建版本中模型的搜索能力等价。

失败关闭的默认值哲学

在Tool.ts中，buildTool()工厂函数提供了默认值。这些默认值遵循一个安全原则：在不确定时假设最危险的情况。

const TOOL_DEFAULTS = {
  isConcurrencySafe: () => false,  // 默认不安全，禁止并发
  isReadOnly: () => false,         // 默认非只读，需要权限
  isDestructive: () => false,      // 默认非破坏性
  // ...
};

这意味着：一个新工具如果忘记声明isConcurrencySafe和isReadOnly，系统会自动将其视为"可能修改文件系统且不能并发执行"。这是最保守、最安全的假设。只有当工具开发者主动声明安全时，系统才会放宽限制。

GrepTool明确覆盖这两个默认值：

isConcurrencySafe() { return true },
isReadOnly() { return true },

而BashTool的并发安全性是有条件的——只有只读命令才允许并发：

isConcurrencySafe(input) {
  return this.isReadOnly?.(input) ?? false;
},

一个git status可以并发执行，但git push不行。这种输入感知的属性控制，实现了精确的权限管理。

这对开发者意味着什么

理解了Claude Code的"活系统"本质，对你日常使用有什么帮助？

第一，优化你的期望。不要把它当传统CLI工具用——输入A必然得到B。它是协作伙伴，同一个请求可能有不同的解决路径。有时候它会选择更稳妥但慢的方式，有时候它会冒险尝试捷径。

第二，理解响应延迟。启动时的并行预取、工具调用的权限检查、模型API的响应时间——这些都不是"bug"，而是架构设计的一部分。如果启动慢，检查Keychain访问是否正常；如果响应慢，可能是上下文窗口触发了压缩。

第三，利用Feature Flag的思维。如果你有实验性功能想加到自己的AI Agent中，考虑区分"功能是否存在"（构建时控制）和"功能对谁开放"（运行时控制）。这让你能在内部测试新功能，而不影响外部用户。

第四，设计模型友好的工具。如果你在使用MCP扩展Claude Code的能力，记住工具描述是给模型看的指令，不是给人看的文档。描述要说明"这个工具做什么"，更要说明"模型应该在什么情况下使用这个工具"。

总结一下

Claude Code不是传统意义上的命令行工具。它是一个在分发状态下运行的智能系统，模型不仅是使用者，还是决策者和创造者。

它的三层架构（应用层/运行时层/外部依赖层）支撑了这种灵活性。构建时Feature Flag和运行时Flag的双层机制，让它既能保持代码精简，又能灵活控制功能 rollout。失败关闭的默认值哲学，让安全成为默认选项而非可选配置。

理解这些，不只是满足好奇心——它能帮你更好地与这个工具协作，理解它的行为模式，甚至在你构建自己的AI Agent时借鉴这些设计。

毕竟，Claude Code可能是目前最先进的AI编码工具，而它的源码就摆在那里，等着被学习和超越。

文章写到这儿，希望对你理解Claude Code的本质有所帮助。如果觉得有收获，欢迎点赞转发。想深入了解更多AI编码工具的底层原理，关注梦兽编程，咱们下篇继续解剖。