什么是 Claude Code？What is Claude Code?

Claude Code 是一个命令行工具command-line tool，让你可以和一个能读写、运行代码的 AI 对话。你输入消息，Claude 来完成工作。Claude Code is a 命令行工具command-line tool that lets you talk to an AI that can read, write, and run code on your computer. You type a message, and Claude does the work.

它不只是聊天机器人。它可以真正做事情 —— 打开文件、运行程序、编辑代码、搜索整个项目。把它想象成一个坐在你终端terminal里的技术助手。It is not just a chatbot. It can actually do things — open files, run programs, edit your code, and search across your entire project. Think of it as a skilled assistant sitting inside your 终端terminal.

消息的旅程The Journey of a Message

逐步了解你的消息是如何从键盘传递到最终回答的。点击"下一步"来推进。Walk through each step to see exactly how your message travels from your keyboard to the final answer. Click "Next Step" to advance.

代码解读：程序入口Code Translation: The Entry Point

这是你输入 claude 时最先运行的代码 —— 来自入口文件entry point的真实源码。左边是代码，右边是通俗解释。Here is the very first thing that runs when you type claude — real code from the 入口文件entry point file. Read the code on the left, and the plain English translation on the right.

async function main(): Promise<void> {
  const args = process.argv.slice(2);

  if (args[0] === '--version') {
    console.log(MACRO.VERSION);
    return;
  }

  // For all other paths, load the
  // startup profiler and continue...
  await launchRepl(config);
}
          

查询循环The Query Loop

应用加载完成后，一切都围绕一个核心概念运转：QueryEngineQueryEngine在一个循环中工作。它不断在 Claude 和你的电脑之间来回协调，直到任务完成。Once the app is loaded, everything revolves around one core idea: the QueryEngineQueryEngine works in a loop. It keeps going back and forth between Claude and your computer until the job is done.

检验你的理解Check Your Understanding

制作团队The Production Crew

Claude Code 不是一个庞大的单体程序。它更像一个完整的电影制片厂，每个专业部门各负责制作的不同环节。以下是五个主要角色。Claude Code is not one giant program. It is an entire movie studio with specialized departments, each handling a different part of the production. Here are the five main players.

制片厂地图The Studio Map

每个部门都有自己的办公区。这是 Claude Code 源代码source code的目录directory结构 —— 每个文件夹就是一个部门。Every department has its own wing of the building. Here is the 目录directory structure of Claude Code's 源代码source code — each folder is a department.

片场的一天A Day on Set

看看各部门在处理一个真实请求时是如何互相交流的。点击"下一条消息"来逐步推进对话。Watch the departments talk to each other as they handle a real request. Click "Next Message" to step through the conversation.

代码解读：共享剧本Code Translation: The Shared Script

还记得状态部门 —— 那个共享的信息源吗？这是它在源代码source code中的简化版。这段代码来自一个叫 AppStateStore.tsAppStateStore.ts 的文件。Remember the State department — the shared source of truth? Here is a simplified version of what it actually looks like in the 源代码source code. This is from a file called AppStateStore.tsAppStateStore.ts.

type AppState = {
  settings: SettingsJson
  verbose: boolean
  mainLoopModel: ModelSetting
  toolPermissionContext:
    ToolPermissionContext
  mcp: {
    clients: MCPServerConnection[]
    tools: Tool[]
    commands: Command[]
  }
  plugins: {
    enabled: LoadedPlugin[]
    disabled: LoadedPlugin[]
  }
  tasks: { [taskId]: TaskState }
}
          

核心思想：关注点分离The Big Idea: Separation of Concerns

什么是工具？What Are Tools?

当 Claude 说"我需要读取一个文件"或"让我来运行这条命令"时，它就是在使用工具。工具就是 Claude 从思考转向行动的桥梁。When Claude says "I need to read a file" or "Let me run this command," it is using a tool. Tools are how Claude goes from thinking to doing.

Claude Code 内置了 45 个工具，以下是主要分类：Claude Code ships with 45 tools. Here are the main categories:

工具的设计蓝图The Tool Blueprint

每个工具都遵循完全相同的模式。这是 FileReadTool 的简化版构建方式——来自源码的真实代码：Every tool follows the exact same pattern. Here is a simplified version of how the FileReadTool is built — this is real code from the source:

export const FileReadTool = buildTool({
  name: 'Read',

  async description() {
    return 'Reads a file from the filesystem'
  },

  inputSchema: () => z.object({
    file_path: z.string(),
    offset: z.number().optional(),
    limit: z.number().optional(),
  }),

  async validateInput(input, context) {
    // Check if file exists, validate path
  },

  async checkPermissions(input, context) {
    // Does the user allow reading this?
  },

  async execute(input, context) {
    // Actually read and return the file
  },
})
          

权限检查站The Permission Checkpoint

把它想象成机场安检。每一次工具使用——每一次文件读取、每一条命令、每一次网页搜索——都必须通过多步检查站才能运行。点击动画来看看具体过程：Think of this like airport security. Every single tool use — every file read, every command, every web search — must pass through a multi-step checkpoint before it can run. Walk through the animation to see what happens:

三层防护Three Layers of Protection

权限系统不只是一个简单的"是/否"门禁。它有三个独立的防护层，各自捕获不同类型的风险：The permission system is not just a single yes/no gate. It has three independent layers, each catching different kinds of risk:

检验你的理解Check Your Understanding

白板难题The Whiteboard Problem

Claude 一次只能"看到"有限的文本量。这就是上下文窗口。把它想象成会议室里的一块白板：Claude 需要知道的一切都必须写在那块白板上。Claude can only "see" a limited amount of text at once. This is the context window. Think of it as a whiteboard in a meeting room: everything Claude needs to know has to fit on that whiteboard.

四种清理策略Four Cleanup Strategies

白板写满时，Claude Code 不会直接崩溃。它有四种释放空间的策略，按从温和到激进的顺序递进使用：Claude Code does not just crash when the whiteboard fills up. It has four strategies for freeing space, used in escalating order — from gentle to aggressive:

自动压缩何时触发？When Does Autocompact Kick In?

系统会监控白板的填充程度，当你接近上限时触发自动压缩。以下是真实的逻辑：The system monitors how full the whiteboard is and triggers autocompact when you get dangerously close to the limit. Here is the real logic:

const AUTOCOMPACT_BUFFER = 13000
const WARNING_BUFFER = 20000

function getAutoCompactThreshold(model) {
  const window = getEffectiveContextWindowSize(
    model
  )
  return window - AUTOCOMPACT_BUFFER
}
          

白板上已经写了什么？What Is Already on the Whiteboard?

在你输入第一条消息之前，白板上就已经有内容了。系统提示词像一层层蛋糕一样从六个不同的来源组装而成。点击动画来看每一层：Before you even type your first message, the whiteboard is already partially filled. The system prompt is assembled like a layer cake from six different sources. Walk through to see each layer:

CLAUDE.md——你的控制面板CLAUDE.md — Your Control Panel

CLAUDE.md 文件是你定制 Claude Code 行为的方式。它们在启动时被加载到系统提示词中，所以 Claude 每次都会遵循你的规则，不需要你重复说明。CLAUDE.md files are how YOU customize Claude Code's behavior. They are loaded into the system prompt at startup, so Claude follows your rules without you repeating them every time.

Claude Code 会在三个位置搜索 CLAUDE.md 文件：全局 ~/.claude/ 目录、项目根目录以及任何父级目录。来自所有层级的规则会合并成一套完整的指令集。Claude Code searches for CLAUDE.md files in three places: the global ~/.claude/ directory, the project root, and any parent directories. Rules from all levels are combined into a single instruction set.

检验你的理解Check Your Understanding

扩展难题The Extension Problem

Claude Code 内置了 45 个工具。但如果你还需要它操作 Notion？或者 Figma？或者公司的数据库呢？你可以等 Anthropic 为每一个服务都做适配…… 或者，你可以用插件系统。Claude Code ships with 45 built-in tools. But what if you need it to work with Notion? Or Figma? Or your company database? You could wait for Anthropic to build support for every service... or you could use a plug-in system.

可以把它想象成 USB 接口。不用为每种设备都做一个不同的插头，只需要一个标准接口。任何遵循这个标准的设备都能直接接入。Think of it like USB ports. Instead of building a different connector for every device, you create one standard port. Anything that speaks the standard can plug right in.

MCP 是什么？实际运行演示What is MCP? Watching It in Action

让我们看看，当你让 Claude 做一件它独力完成不了的事情时，幕后究竟发生了什么。逐条点击查看对话过程。Let us watch what happens behind the scenes when you ask Claude to do something it cannot do alone. Click through to see the conversation unfold.

MCP 服务器如何连接How MCP Servers Connect

MCP 服务器可以通过不同的方式连接到 Claude Code，这些方式叫做传输（Transport）。每种方式适用于不同的场景。MCP servers can connect to Claude Code in different ways, called transports. Each is suited to different situations.

深入内部：连接 MCP 服务器Under the Hood: Connecting to an MCP Server

下面是 MCP 客户端代码中的真实模式。它展示了 Claude Code 是如何接入外部服务的。Here is the real pattern from the MCP client code. It shows exactly how Claude Code plugs into an external service.

// From src/services/mcp/client.ts
async function ensureConnectedClient(
  serverName, config
) {
  const transport = new StdioClientTransport({
    command: config.command,
    args: config.args,
    env: config.env,
  });
  const client = new Client();
  await client.connect(transport);
  const tools = await client.listTools();
  const resources = await client.listResources();
  return { client, tools, resources };
}
          

MCP 服务器从哪里来Where MCP Servers Come From

MCP 服务器并不是硬编码的。它们来自多个配置来源，按优先级逐级检查。这意味着你、你的团队和你的组织可以各自提供不同的服务器。MCP servers are not hardcoded. They come from multiple configuration sources, checked in order. This means you, your team, and your organization can all contribute different servers.

检验你的理解Check Your Understanding

七条恢复路径The Seven Recovery Paths

就像飞行员为每种故障都准备了应急预案 —— 引擎、电气、导航 —— Claude Code 中的查询循环有七个不同的地方可以从错误中恢复。其中大多数都是静默发生的，你甚至都不会注意到。Like a pilot who has emergency procedures for every type of failure — engine, electrical, navigation — the query loop in Claude Code has SEVEN different places where it can recover from errors. Most of these happen silently, without you ever knowing.

重试引擎运行演示The Retry Engine in Motion

withRetry() 函数就是驾驶舱里的飞行员。逐步点击动画，看看它是如何处理每种故障的。The withRetry() function is the pilot at the controls. Walk through the animation to see how it handles each type of failure.

深入内部：重试循环Under the Hood: The Retry Loop

下面是简化后的真实 withRetry() 函数。这段代码决定是重试、等待还是放弃。Here is the real withRetry() function, simplified. This is the code that decides whether to retry, wait, or give up.

// From src/services/api/withRetry.ts
async function* withRetry(
  getClient, operation, options
) {
  for (let attempt = 1;
       attempt <= maxRetries + 1;
       attempt++) {
    try {
      return await operation(client, attempt);
    } catch (error) {
      if (isTransientCapacityError(error)) {
        const delay = BASE_DELAY
          * Math.pow(2, attempt - 1);
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}
          

功能开关：构建系统的闸门Feature Flags: The Build System Gates

Claude Code 使用功能开关（Feature Flags）来控制特定版本中包含哪些能力。下面是它们在代码中的样子：Claude Code uses feature flags to control which capabilities exist in a given version. Here is what they look like in the code:

// Feature-gated code pattern
if (feature('REACTIVE_COMPACT')) {
  // This code only exists in
  // certain builds
  const mod =
    require('./reactiveCompact.js');
}
          

氛围编程者的调试技巧Debugging Tips for Vibe Coders

当 Claude Code 表现异常时，下面是最常见的问题和排查方法。不需要计算机科学学位。When Claude Code behaves unexpectedly, here are the most common issues and what to check. No computer science degree required.

检验你的理解Check Your Understanding