术语表 — 从 Agent 到 Worktree

在 Claude Code 的语境下，Agent 并不是某个框架或库，而是模型本身。当我们说「Claude 是一个 Agent」，意思是它可以自主地观察环境、做出决策、调用工具、根据反馈调整行动，直到完成目标。

Agent 的核心能力在于 Tool Loop：模型不断地接收工具调用的结果，判断下一步该做什么，直到它认为任务完成（返回 end_turn）。这个循环不需要外部编排框架来驱动——模型自身就是决策者。

理解这一点很重要：很多「Agent 框架」实际上是给模型加上了一层编排逻辑，但 Claude Code 的哲学是让模型直接做 Agent，harness 只负责提供工具和约束。

类比：Agent 就像一个有经验的开发者，你给他一台配好环境的电脑（harness），他自己决定怎么完成任务。

Harness 是围绕模型的一切基础设施：工具集合、知识注入、权限系统、上下文管理。它不做决策，只提供能力和约束。Claude Code 本身就是一个 harness——它把 Bash、文件读写、搜索等工具暴露给模型，同时通过权限系统控制模型能做什么。

Harness 和 Agent 的关系类似于操作系统和用户的关系：操作系统提供文件系统、网络、进程管理等能力，用户决定如何使用这些能力。

一个好的 harness 应该是「透明的」——它不应该过多干预模型的决策，而是确保模型有足够的工具和信息来完成任务。Claude Code 的设计哲学就是如此：尽量少的编排，尽量多的工具。

组成要素：Tool Dispatch Map（工具映射）、System Prompt（系统提示）、Permission Mode（权限模式）、Context Management（上下文管理）。

Tool Loop 是 Claude Code 的心脏。它的伪代码本质上是一个 while True 循环：不断调用模型，检查 stop_reason，如果是 tool_use 就执行工具并把结果追加到消息数组，然后再次调用模型；如果是 end_turn 就结束。

这个循环没有硬编码的步骤上限（虽然实际上有 token 预算限制）。模型可以连续调用数十个工具来完成一个复杂任务——读取文件、搜索代码、编辑文件、运行测试，全部在一个循环中完成。

Tool Loop 的优雅之处在于它的简单：不需要状态机、不需要 DAG 编排、不需要预定义的工作流。模型自己决定调用什么工具、以什么顺序、什么时候停止。

关键：整个 Agent 行为的「智能」来自模型本身，而不是循环的逻辑。循环只是机械地执行「调用 → 检查 → 执行工具 → 再调用」。

stop_reason 是 Claude API 返回的一个字段，告诉 harness 模型为什么停止了输出。它是 Tool Loop 的「交通信号灯」，决定循环是继续还是结束。

三种主要的 stop_reason：tool_use 表示模型想调用一个工具，harness 应该执行该工具并把结果返回给模型；end_turn 表示模型认为任务完成了，可以把最终回复展示给用户；max_tokens 表示模型输出达到了 token 上限，被强制截断。

max_tokens 是一个需要特殊处理的情况——它意味着模型的回复不完整。Claude Code 会在这种情况下自动重试或提示用户。

调试提示：如果你发现 Claude Code 似乎「卡住了」或者回复被截断，检查 stop_reason 是排查问题的第一步。

Tool Dispatch Map 本质上是一个 {name: handler} 的字典。当模型返回一个工具调用请求（包含工具名称和参数），harness 在这个映射中查找对应的处理函数并执行。

在 Claude Code 中，这个映射包含了所有内置工具（Bash、Read、Write、Edit、Grep、Glob 等）以及通过 MCP 动态注册的外部工具。每个工具的 handler 负责执行实际操作并返回结果。

这种设计使得工具的添加和移除非常灵活——只需要在映射中增删条目即可。MCP 工具的注册就是在运行时动态向这个映射添加新条目。

示例：当模型说「我要调用 Bash 工具，参数是 ls -la」，harness 在映射中找到 "Bash" 对应的 handler，执行命令，把 stdout/stderr 包装成工具结果返回。

Messages Array 是 Claude Code 中整个对话状态的核心数据结构。每次 API 调用都会把完整的消息数组发送给模型，模型的回复和工具调用结果都会追加到这个数组中。

数组中的每条消息有一个角色（user、assistant）和内容。工具调用请求作为 assistant 消息的一部分，工具调用结果作为 user 消息的一部分。这种「追加式」的结构意味着上下文会不断增长。

当消息数组增长到接近上下文窗口上限时，就需要进行 Context Compact（上下文压缩）——用一段摘要替换大部分历史消息，释放空间。

重要：模型没有「记忆」——它只能看到消息数组中的内容。如果某个信息不在数组中，模型就不知道它的存在。这就是为什么 System Prompt 和 CLAUDE.md 的内容需要在每次调用时都注入。

Context Window 是模型单次 API 调用能处理的最大 token 数量。对于 Claude，这个数字通常是 200K token。所有的输入（System Prompt、消息历史、工具定义）加上输出，都必须装进这个窗口里。

在 Claude Code 中，上下文窗口的管理是一个核心挑战。随着对话进行，消息数组不断增长，工具调用的结果（比如大文件的内容）会快速消耗空间。当剩余空间不足约 13000 token 时，系统会自动触发压缩。

理解上下文窗口对于高效使用 Claude Code 至关重要：如果你一次性让它读取太多大文件，可能会很快耗尽上下文，导致频繁压缩和信息丢失。

实践建议：使用 /cost 命令查看当前 token 使用量。当接近上限时，考虑手动 /compact 或 /clear 来释放空间。

System Prompt 是每次 API 调用时都会发送给模型的持久指令。它告诉模型「你是谁、你能做什么、你应该遵守什么规则」。在 Claude Code 中，System Prompt 包含了工具使用说明、安全规则、行为准则等内容。

System Prompt 不是对话的一部分——用户看不到它，但它深刻影响模型的行为。Claude Code 的 System Prompt 相当长，包含了对每个工具的详细使用指南、文件操作的安全规则、git 操作的最佳实践等。

每次调用都发送完整的 System Prompt 意味着它会消耗上下文窗口的一部分空间。这也是为什么 System Prompt 不能无限长——它需要在「提供足够指导」和「留出对话空间」之间取得平衡。

与 CLAUDE.md 的关系：CLAUDE.md 的内容会被合并到 System Prompt 中一起发送。两者共同构成了模型在每次调用时看到的「基础指令」。

CLAUDE.md 是一个特殊的 Markdown 文件，放在项目根目录或 ~/.claude/ 下，让用户为 Claude Code 定义项目级或全局级的行为规则。它的内容会在每次 API 调用时作为系统指令的一部分注入。

典型的 CLAUDE.md 内容包括：项目的技术栈说明、代码风格偏好、常用命令、特殊的工作流程要求、需要避免的操作等。模型会严格遵守这些指令。

CLAUDE.md 支持多层叠加：全局的 ~/.claude/CLAUDE.md、项目根目录的 CLAUDE.md、子目录中的 CLAUDE.md，它们会按层级合并。越具体的规则优先级越高。

最佳实践：保持 CLAUDE.md 简洁精炼。每一行都会消耗上下文窗口的空间，所以只放真正重要的规则，避免冗余描述。

Auto Memory 是 Claude Code 自动从对话中提取并保存重要信息的机制。当 Claude 发现用户反复强调某个偏好、纠正某个行为、或者提到某个项目约定时，它会将这些信息保存为「记忆」。

这些记忆存储在 ~/.claude/ 目录下，格式类似于 CLAUDE.md 的条目。在后续会话中，这些记忆会被自动注入到上下文中，使 Claude 能够「记住」之前的约定。

Auto Memory 的触发是隐式的——你不需要主动说「记住这个」。Claude 会自己判断哪些信息值得记忆。当然，你也可以通过 /memory 命令手动管理这些记忆条目。

注意：Auto Memory 和消息数组是独立的。即使你 /clear 了对话，记忆仍然保留。它是一种跨会话的持久化知识机制。

Skills 是 Claude Code 的「按需知识包」机制。与 System Prompt 和 CLAUDE.md 不同，Skills 不会在每次调用时都注入——只有当用户触发特定的 Slash Command 或匹配特定条件时，对应的 Skill 内容才会被加载到上下文中。

这种设计解决了一个关键问题：如果把所有知识都放在 System Prompt 中，上下文窗口会被迅速耗尽。Skills 采用「延迟加载」策略，只在需要时才注入相关知识。

每个 Skill 本质上是一段结构化的 Markdown 文档，包含特定领域的详细指导。比如 commit Skill 包含了 git commit 的最佳实践，review-pr Skill 包含了 PR 审查的步骤和标准。

与 MCP 的关系：Skills 提供知识，MCP 提供工具。两者互补——Skill 告诉模型「怎么做」，MCP 工具让模型「能做」。

Context Compact 是 Claude Code 在上下文窗口即将耗尽时自动执行的压缩机制。它不是简单地截断历史消息，而是采用分层策略来最大限度地保留有用信息。

三层压缩策略：第一层是摘要生成——让模型对历史对话生成一段结构化摘要（最多约 2000 token），保留关键决策、文件修改记录和重要上下文。第二层是工具结果截断——大型工具输出（如完整文件内容）会被大幅压缩或移除。第三层是身份重注入——确保压缩后的上下文仍然包含必要的系统指令和项目规则。

压缩会在上下文使用量达到约 contextWindow - 13000 token 时自动触发。你也可以通过 /compact 命令或传入自定义提示来手动触发。

风险：压缩不可避免地会丢失一些细节。如果你正在进行需要大量上下文的复杂任务，频繁的压缩可能导致模型「忘记」重要的中间步骤。这时候可以考虑拆分任务或使用 Subagent。

Token 是大语言模型处理文本的最小单位。它不等于字、词或字符——一个英文单词可能是 1-3 个 token，一个中文字通常是 1-2 个 token，一段代码中的符号和关键字各占不同数量的 token。

在 Claude Code 的使用中，token 直接关系到两个核心资源：上下文窗口的容量（决定了你能放多少信息）和 API 调用的费用（按 token 计费）。每次工具调用的输入和输出都会消耗 token。

Claude 使用的 tokenizer 与 GPT 不同。粗略估算，1000 个 token 约等于 750 个英文单词，或约 500 个中文字。你可以用 /cost 命令查看当前会话已经消耗了多少 token。

优化技巧：减少不必要的大文件读取、使用精确的搜索而非全文件扫描、及时 /compact，都能有效控制 token 消耗。

MCP 是 Anthropic 推出的一个标准化协议，用于让 LLM 连接外部工具和数据源。它定义了一种统一的方式让外部服务把自己的功能「暴露」给模型，模型可以像使用内置工具一样调用它们。

在 Claude Code 中，MCP 的主要作用是扩展工具集。通过配置 MCP server，你可以让 Claude 访问数据库、调用第三方 API、操作特定的开发工具等。每个 MCP server 提供一组工具定义（包括名称、参数 schema、描述），Claude Code 在启动时或运行时动态加载这些定义到 Tool Dispatch Map 中。

MCP 的设计理念是「标准化」——不同的工具提供者只需要实现同一个协议，就能被任何支持 MCP 的 LLM 客户端使用。这避免了每个工具都要写一个定制的集成插件。

配置方式：在 .claude/settings.json 或通过 /mcp 命令管理 MCP server 的连接。支持 stdio 和 SSE 两种传输方式。

LSP 是微软提出的一个协议，用于标准化编辑器/IDE 与语言分析工具之间的通信。它提供代码补全、跳转定义、查找引用、诊断错误等功能。

在 Claude Code 的 IDE 集成场景中（如 VS Code 扩展），LSP 扮演了重要角色。通过 LSP，Claude Code 可以获取当前文件的语法错误、符号定义、类型信息等丰富的代码上下文，从而做出更精确的代码分析和修改。

LSP 和 MCP 有相似的设计哲学——都是通过标准化协议解耦工具提供者和消费者。但 LSP 专注于代码导航和分析，MCP 则是更通用的工具连接协议。

实际影响：当你在 IDE 中使用 Claude Code 时，它能获得比纯 CLI 模式更丰富的代码上下文，因为 IDE 的 LSP 服务提供了深层的代码理解能力。

OAuth 2.0 是一个行业标准的授权协议，允许用户在不暴露密码的情况下，授权第三方应用访问其资源。在 Claude Code 中，OAuth 2.0 用于认证和授权流程，特别是在连接需要身份验证的外部服务时。

典型的使用场景包括：登录 Claude.ai 账户获取 API 访问权限、连接 GitHub 等第三方服务、授权 MCP server 访问受保护的资源。OAuth 流程通常涉及浏览器重定向——Claude Code 会打开一个本地端口监听回调，用户在浏览器中完成授权后，token 自动传回。

Claude Code 使用 OAuth 2.0 的 Authorization Code 流程，配合 PKCE（Proof Key for Code Exchange）扩展来增强安全性，防止授权码被拦截。

注意：如果你使用 API Key 直接认证，就不需要走 OAuth 流程。OAuth 主要用于 claude.ai 账号登录和第三方服务集成。

JWT 是一种紧凑的、URL 安全的令牌格式，用于在各方之间安全地传递声明（claims）。它由三部分组成：Header（算法声明）、Payload（数据载荷）、Signature（签名校验）。

在 Claude Code 的 IDE Bridge 架构中，JWT 用于 CLI 进程和 IDE 扩展之间的安全通信。当 VS Code 扩展启动 Claude Code CLI 时，会生成一个 JWT 来标识这次会话，确保只有合法的 IDE 实例能与 CLI 进程通信。

JWT 的优势在于它是「自包含」的——接收方可以直接验证令牌的有效性而不需要查询数据库或认证服务器。这使得它非常适合轻量级的本地进程间通信。

安全要点：JWT 本身不加密数据（除非使用 JWE），它只保证数据未被篡改。不要在 JWT 的 Payload 中放置敏感信息。

JSONL 是一种文件格式，每一行是一个独立的 JSON 对象，行与行之间用换行符分隔。它非常适合追加式写入（append-only）的场景，因为添加新数据只需要在文件末尾追加一行，不需要解析和重写整个文件。

在 Claude Code 的多 Agent 通信架构（MessageBus）中，JSONL 被用作异步消息传递的文件格式。每个 Agent 有自己的消息文件，新消息以 JSONL 格式追加。这种设计避免了复杂的进程间通信机制，利用文件系统作为天然的消息队列。

JSONL 的另一个优势是流式处理友好——可以逐行读取和处理，不需要将整个文件加载到内存中。这对于可能增长到很大的日志文件和消息队列非常重要。

对比 JSON：标准 JSON 文件需要完整解析才能使用，JSONL 可以逐行处理。在并发写入场景下，JSONL 也更安全——两个进程同时追加一行不会破坏文件结构。

SSE 是一种 HTTP 协议扩展，允许服务器通过长连接持续向客户端推送数据。与 WebSocket 不同，SSE 是单向的（服务器到客户端），基于标准 HTTP，天然支持重连和事件 ID。

在 Claude Code 中，SSE 主要用于两个场景：一是 Claude API 的流式响应——模型生成的每个 token 通过 SSE 事件实时推送到客户端，用户可以看到文字逐步出现而不需要等待完整回复。二是 MCP server 的一种传输方式——MCP 支持 SSE 作为服务端向客户端推送工具调用结果的通道。

SSE 的优势在于简单和兼容性好——它使用标准 HTTP 连接，不需要协议升级，能穿透大多数防火墙和代理。对于「服务端主动推送、客户端被动接收」的场景，SSE 比 WebSocket 更合适。

格式：每个 SSE 事件以 data: 前缀开头，事件之间用空行分隔。Claude API 的流式响应就是一系列 data: {...} 事件。

WebSocket 是一种在单个 TCP 连接上提供全双工（双向）通信的协议。与 HTTP 的请求-响应模式不同，WebSocket 连接建立后，双方可以随时向对方发送数据，没有严格的请求-响应对应关系。

在 Claude Code 生态中，WebSocket 主要出现在需要实时双向通信的场景：IDE 扩展与后端服务的实时交互、某些 MCP server 的传输层、以及浏览器客户端与服务的连接。

WebSocket 和 SSE 的选择取决于通信模式：如果只需要服务端推送，SSE 更简单；如果需要双向通信（客户端也要主动发送），WebSocket 是更好的选择。

连接过程：WebSocket 通过 HTTP Upgrade 机制建立——客户端发送一个特殊的 HTTP 请求，服务端同意升级后，连接从 HTTP 切换到 WebSocket 协议。

gRPC 是 Google 开发的一个高性能远程过程调用（RPC）框架，使用 Protocol Buffers 作为接口定义语言和序列化格式，基于 HTTP/2 传输。它支持四种通信模式：一元调用、服务端流、客户端流、双向流。

在 LLM 应用架构中，gRPC 通常出现在后端微服务之间的通信中——比如认证服务、计费服务、模型推理服务之间的调用。它的优势是高效的二进制序列化（比 JSON 小得多、快得多）和强类型的接口定义。

虽然 Claude Code 的主要外部通信使用 HTTP/JSON（Claude API）和 stdio/SSE（MCP），但了解 gRPC 有助于理解更大的系统架构——模型推理的后端服务很可能使用 gRPC 进行内部通信。

与 REST 的对比：REST 基于 HTTP + JSON，人类可读性好，适合公开 API；gRPC 基于 HTTP/2 + Protobuf，性能更高，适合内部微服务通信。

Bun 是一个用 Zig 编写的 JavaScript/TypeScript 运行时，同时集成了包管理器、打包器和测试运行器。它的启动速度和执行性能显著优于 Node.js，这对 CLI 工具来说非常重要——用户不想等好几秒才能开始交互。

Claude Code 选择 Bun 作为运行时，主要是因为它的快速启动特性和对 TypeScript 的原生支持（不需要额外的编译步骤）。在构建过程中，Bun 也承担打包角色，将整个项目编译为一个高效的可执行文件。

Bun 还提供了一些 Node.js 不具备的内置功能，如原生的 SQLite 绑定、高性能的文件 I/O，这些在 Claude Code 的本地数据存储和文件操作中都有用武之地。

兼容性：Bun 高度兼容 Node.js API 和 npm 生态。大部分 Node.js 包可以直接在 Bun 上运行而无需修改。

TypeScript 是 JavaScript 的超集，添加了静态类型系统。Claude Code 的整个代码库都使用 TypeScript 编写，这为一个复杂的大型项目提供了类型安全和更好的代码可维护性。

在 Claude Code 的上下文中，TypeScript 的类型系统特别重要：工具定义的参数类型、API 响应的结构、消息数组的格式——这些都通过 TypeScript 类型得到严格约束，减少了运行时错误的可能性。

搭配 Zod 这样的运行时类型验证库，TypeScript 在 Claude Code 中实现了「编译时 + 运行时」的双重类型安全。编译时捕获开发者的类型错误，运行时验证外部输入（API 响应、用户输入、MCP 工具结果）的格式正确性。

在 Claude Code 源码中：你会看到大量的 interface、type 和 enum 定义，它们是理解系统架构的重要入口。

Ink 是一个让你用 React 组件编写终端 UI 的框架。Claude Code 使用 React + Ink 来构建它的交互式终端界面——你看到的那些带颜色的输出、实时更新的状态栏、交互式选择器，都是用 React 组件渲染出来的。

这种选择看起来很不寻常（React 不是用来做网页的吗？），但它带来了巨大的工程优势：组件化的 UI 架构、声明式的状态管理、成熟的生态系统。开发者可以像写网页一样写终端 UI，而 Ink 负责将 React 组件树渲染为终端控制序列。

在 Claude Code 中，local-jsx 类型的 Slash Command 就是用 React + Ink 渲染的交互式面板。比如 /config 命令打开的配置界面、/mcp 命令打开的 MCP 管理界面，都是完整的 React 应用。

渲染机制：Ink 使用自定义的 React reconciler，将组件树映射到终端的行和列。它支持 Flexbox 布局、文字样式、边框等常见 UI 元素。

Zod 是一个 TypeScript-first 的运行时类型验证库。它允许你定义数据的「schema」，然后在运行时验证实际数据是否符合这个 schema。在 Claude Code 中，Zod 扮演着「守门员」的角色。

典型使用场景包括：验证 Claude API 返回的响应格式是否正确、验证 MCP 工具的参数和返回值、验证用户配置文件（settings.json）的结构、验证 Slash Command 的参数。任何来自外部的数据都不应该被信任——Zod 确保这些数据在进入系统之前被严格校验。

Zod 的一个强大特性是它的 schema 可以自动生成 TypeScript 类型（通过 z.infer），这意味着你不需要同时维护 TypeScript 类型和验证逻辑——它们总是同步的。

在工具定义中的角色：每个内置工具的参数 schema 都是用 Zod 定义的。这些 schema 被转换为 JSON Schema 发送给模型，同时在执行工具时用于验证模型传入的参数。

Zustand 是一个极简的 React 状态管理库，比 Redux 轻量得多，API 简洁直观。在 Claude Code 中，Zustand 用于管理应用的全局状态——当前对话状态、权限设置、工具配置、UI 显示状态等。

Zustand 的核心是一个 store：你定义初始状态和更新函数，组件通过 hook 订阅所需的状态片段。当状态更新时，只有订阅了变化部分的组件会重新渲染，这对终端 UI 的性能很重要。

在 Claude Code 的架构中，Zustand store 是连接各个模块的「中枢」——Tool Loop 更新对话状态到 store，UI 组件从 store 读取状态并渲染，权限系统从 store 读取当前模式来决策。

为什么不用 Redux：Claude Code 是一个 CLI 工具，不需要 Redux 那样的时间旅行调试和中间件生态。Zustand 的极简 API 更适合这种场景。

Commander.js 是 Node.js 生态中最流行的命令行参数解析库。它负责解析用户在终端输入的命令行参数和选项，将它们转换为结构化的配置对象供程序使用。

在 Claude Code 中，Commander.js 处理启动时的所有参数：--model、--permission-mode、--output-format、-p（直接传入 prompt）等。它还负责生成 --help 输出和参数校验。

Commander.js 的一个重要特性是支持子命令——Claude Code 的一些非交互式模式（如 claude mcp 子命令）就是通过 Commander.js 的子命令机制实现的。

与 Slash Commands 的区别：Commander.js 处理的是启动时的 CLI 参数（shell 命令行），Slash Commands 是运行时在 Claude Code 交互界面中输入的命令，两者是完全不同的系统。

ripgrep 是一个用 Rust 编写的极速文件内容搜索工具，比传统的 grep 快很多倍。Claude Code 内置了 ripgrep 作为代码搜索的核心引擎——当你让 Claude 搜索代码时，底层就是通过 ripgrep 执行的。

Claude Code 的 Grep 工具本质上是对 ripgrep 的封装，提供了更友好的接口（文件过滤、输出模式、上下文行数等参数）。ripgrep 的速度对于 Agent Loop 至关重要——搜索是最频繁的工具调用之一，毫秒级的搜索速度意味着 Claude 可以快速探索代码库。

ripgrep 默认尊重 .gitignore 规则，自动跳过二进制文件和隐藏目录，这意味着搜索结果通常非常「干净」——不会被 node_modules 或 .git 目录中的内容污染。

性能秘密：ripgrep 使用 Rust 的正则引擎、内存映射文件 I/O、并行搜索，在大型代码库上的搜索速度可以比 GNU grep 快 10-100 倍。

Feature Flag 是一种通过配置开关来控制功能是否启用的技术。在 Claude Code 中，Feature Flag 有两层含义：编译时的条件编译（决定哪些代码被包含在构建产物中）和运行时的功能开关（根据用户身份、配置等动态启用/禁用功能）。

编译时 Feature Flag 的典型用法是区分发布环境：某些功能只在内部测试版本中启用，不会出现在公开发布的版本中。这通过构建脚本中的条件逻辑实现——对应的代码在打包时被物理移除（Dead Code Elimination）。

运行时 Feature Flag 更灵活，通常通过远程配置服务（如 GrowthBook）管理。Claude Code 启动时会获取当前用户的 Feature Flag 配置，决定哪些命令可用、哪些功能启用。这也是为什么不同用户可能看到不同数量的 Slash Commands。

调试价值：如果你发现某个文档中提到的功能在你的 Claude Code 中不存在，很可能是该功能被 Feature Flag 关闭了——可能是还未正式发布，或者不面向你的用户群开放。

Dead Code Elimination（DCE）是一种编译/打包优化技术，自动检测并移除不会被执行到的代码。在 Claude Code 的构建过程中，打包工具（Bun 或其他 bundler）会分析代码的依赖图，移除未被引用的模块和函数。

DCE 与 Feature Flag 配合使用时特别强大：当某个功能被编译时 Feature Flag 关闭后，相关的代码分支变成了「死代码」，打包器会自动将其移除。这意味着最终产物不包含任何未启用功能的代码——既减小了文件体积，也防止了未发布功能的代码泄露。

在 JavaScript/TypeScript 生态中，DCE 通常依赖于 ES Module 的静态分析能力。打包器能够确定哪些 export 被使用了、哪些没有（即 Tree Shaking），从而安全地移除未使用的部分。

常见陷阱：动态的 require() 或 import() 会阻止 DCE，因为打包器无法静态分析动态导入的路径。这也是为什么现代项目倾向使用静态的 ES Module import。

GrowthBook 是一个开源的 Feature Flag 和 A/B 测试平台。Claude Code 使用 GrowthBook 来管理运行时的功能开关——哪些功能对哪些用户群体启用、新功能的灰度发布比例等。

在 Claude Code 启动时，它会从 GrowthBook 服务获取当前用户的功能配置。这些配置决定了：哪些 Slash Commands 可用、哪些实验性功能启用、某些行为的参数值（比如上下文窗口的预留空间大小）等。

GrowthBook 支持基于多种维度的定向投放：用户 ID、订阅等级、地理位置、客户端版本等。这使得 Claude Code 团队可以渐进式地发布新功能，先让小部分用户测试，确认没有问题后再全面开放。

A/B 测试作用：除了功能开关，GrowthBook 还支持真正的 A/B 测试——比如测试不同的 System Prompt 措辞、不同的默认参数值对用户体验的影响。

Subagent 是 Claude Code 中用于处理隔离子任务的机制。当主 Agent 遇到一个可以独立完成的子任务时，它可以启动一个 Subagent——这个 Subagent 有自己独立的上下文窗口和消息数组，不会污染主 Agent 的上下文。

Subagent 的核心价值在于「上下文隔离」：主 Agent 的上下文窗口是有限的，如果所有子任务都在同一个上下文中执行，窗口会很快耗尽。通过启动 Subagent，子任务在独立的上下文中完成，只有最终结果返回给主 Agent。

每个 Subagent 都继承主 Agent 的权限设置和工具集，但拥有独立的消息历史。它像一个「分身」——能力相同，但记忆独立。完成任务后，Subagent 返回一段简洁的结果摘要给主 Agent。

典型场景：「帮我在 10 个文件中分别查找并修复同一类 bug」——主 Agent 可以为每个文件启动一个 Subagent 并行处理，而不是把所有文件的内容都加载到自己的上下文中。

Agent Teams（也称 Swarms）是多个 Agent 持久协作完成复杂任务的模式。与 Subagent 的「主从关系」不同，Agent Teams 中的成员可以是对等的，各自负责不同的职责领域，通过消息总线进行异步通信。

典型的 Agent Team 配置可能包括：一个负责代码编写的 Agent、一个负责代码审查的 Agent、一个负责测试编写的 Agent。它们各自在独立的 Git Worktree 中工作，通过文件系统中的消息文件进行协调。

Agent Teams 的关键挑战是协调和一致性：如何避免两个 Agent 修改同一个文件导致冲突？如何确保团队的整体行动朝着同一个目标推进？这些问题通过 MessageBus、Correlation ID 和 FSM 等机制来解决。

与单 Agent 的权衡：Agent Teams 能处理更复杂的任务，但引入了通信开销和协调复杂性。对于大多数日常任务，单 Agent + Subagent 的模式已经足够。

MessageBus 是 Claude Code 多 Agent 架构中的异步通信机制。它不是一个独立的消息队列服务，而是基于文件系统实现的——每个 Agent 有一个 JSONL 格式的消息文件，其他 Agent 通过向该文件追加行来发送消息。

这种设计的优雅之处在于完全不依赖外部服务：不需要 Redis、不需要 RabbitMQ、不需要任何后台进程。文件系统就是消息基础设施。每个 Agent 定期轮询自己的消息文件（Idle Poll），检查是否有新消息到达。

MessageBus 的消息格式通常包含：发送者 ID、接收者 ID、Correlation ID（用于请求-响应配对）、消息类型、消息内容和时间戳。这些信息足以支持复杂的多方异步通信。

可靠性保证：由于使用 append-only 的 JSONL 格式，消息不会丢失或被覆盖。但这也意味着消息文件会不断增长，需要定期清理或归档。

Correlation ID 是一个唯一标识符，用于将异步通信中的请求和响应配对。在 Claude Code 的 MessageBus 中，当 Agent A 向 Agent B 发送一个请求时，会附带一个 Correlation ID；Agent B 的回复会携带同一个 ID，这样 Agent A 就能知道这个回复对应的是哪个请求。

在异步通信中，消息的到达顺序不确定——Agent A 可能同时向多个 Agent 发送了请求，回复会以任意顺序到达。没有 Correlation ID，就无法将回复和请求正确关联。

Correlation ID 通常是 UUID 格式的字符串，在请求创建时生成。它贯穿整个请求-响应链路，在日志和调试中也非常有用——你可以通过一个 ID 追踪一个请求从发起到完成的完整生命周期。

更广泛的应用：Correlation ID 不只在多 Agent 场景中使用。在分布式系统中，它是追踪跨服务调用链的标准手段（类似于分布式追踪中的 Trace ID）。

有限状态机是一种数学模型，系统在任一时刻只能处于有限个状态中的一个，并根据输入事件从一个状态转移到另一个状态。在 Claude Code 的多 Agent 协作中，FSM 用于管理每个 Agent 和任务的生命周期状态。

典型的 Agent 状态机可能包括：idle（空闲，等待任务）→ working（执行任务中）→ waiting（等待其他 Agent 的响应）→ done（任务完成）。每个状态转移都有明确的触发条件和副作用。

FSM 的价值在于它使系统行为可预测、可调试。你可以清楚地知道一个 Agent 当前处于什么状态、什么事件会导致它进入下一个状态、状态转移时会执行什么操作。

在任务管理中的应用：任务也有自己的状态机——pending → in_progress → completed / failed。状态转移由 Agent 的操作触发，并通过 MessageBus 通知相关方。

Idle Poll 是 Agent 在空闲状态下定期检查是否有新任务或新消息的机制。在 Claude Code 的多 Agent 架构中，Agent 不使用事件驱动（如 WebSocket 推送），而是采用简单的轮询方式检查消息文件是否有更新。

轮询间隔通常是几秒到几十秒。Agent 在每次轮询时读取自己的 MessageBus 文件，检查是否有新的行（通过记录上次读取的文件偏移量来实现增量读取）。如果有新消息，就根据消息类型进行处理。

虽然轮询比事件驱动效率低一些，但它的优势在于实现简单、不依赖额外的基础设施。对于本地多 Agent 场景，轮询的开销完全可以接受——几秒的延迟对于开发任务来说不是问题。

优化：可以结合文件系统的 watch 机制（如 fs.watch）来减少不必要的轮询。但在实践中，简单的定时轮询往往是最可靠的方案。

Identity Re-injection 是 Context Compact（上下文压缩）过程中的一个关键步骤。当对话历史被压缩为摘要时，模型的「身份信息」（我是谁、我在做什么、我应该遵守什么规则）可能会被稀释或丢失。Identity Re-injection 确保压缩后的上下文仍然包含完整的身份信息。

具体做法是：在压缩完成后，将 System Prompt 中的核心指令、CLAUDE.md 的关键规则、以及当前任务的上下文重新注入到压缩后的消息数组中。这样模型在下一次调用时仍然「记得」自己是谁。

如果没有 Identity Re-injection，压缩后的模型可能会出现「人格漂移」——忘记自己应该遵守的规则，或者偏离原来的任务目标。这在长时间运行的 Agent 任务中尤为重要。

在多 Agent 场景中：每个 Agent 都有自己的身份（角色定义、职责范围）。压缩后重注入身份信息确保 Agent 不会「忘记」自己的角色，避免在团队协作中产生混乱。

Git Worktree 是 Git 的一个原生功能，允许你在同一个仓库中创建多个工作目录，每个工作目录对应不同的分支。在 Claude Code 的多 Agent 架构中，Worktree 是实现文件级隔离的关键机制。

当多个 Agent 需要同时修改代码时，如果它们共享同一个工作目录，就会产生冲突。通过为每个 Agent 分配独立的 Worktree，它们可以在各自的分支上自由工作，互不干扰。最终通过 Git merge 来合并各自的修改。

Worktree 的优势在于它比完整 clone 轻量得多——所有 Worktree 共享同一个 .git 目录（对象数据库、引用等），只是各自有独立的工作目录和索引文件。创建和销毁 Worktree 几乎是瞬间完成的。

使用方式：git worktree add ../agent-1-workspace feature-branch-1 创建一个新的 Worktree。Claude Code 会自动管理 Worktree 的创建和清理。

DAG 是一种图结构，其中节点之间有方向性的边，且不存在环路。在 Claude Code 的多 Agent 任务管理中，DAG 用于表示任务之间的依赖关系——某些任务必须在其前置任务完成后才能开始。

例如，一个「重构模块 X」的任务可能被分解为：「理解当前代码结构」→「编写新接口」→「迁移调用方」→「删除旧代码」→「运行测试」。这些子任务形成一个 DAG，其中有些可以并行（比如迁移不同的调用方），有些必须顺序执行（先写新接口，再迁移调用方）。

DAG 的「无环」约束确保了任务的执行不会陷入死循环。调度器可以通过拓扑排序确定任务的执行顺序，最大化并行度。

在 Git 中的体现：Git 的 commit 历史本身就是一个 DAG——每个 commit 指向一个或多个父 commit，但不存在环路。理解 DAG 有助于理解 Git 的分支和合并机制。

Transcript 是 Claude Code 将完整的对话历史保存到磁盘的机制。每次会话的所有消息（包括用户输入、模型回复、工具调用和结果）都会被记录到本地文件中。

Transcript 的主要用途包括：通过 /resume 恢复之前的会话、在 Context Compact 前保存完整历史（压缩会丢失细节，但 Transcript 保留了一切）、事后审计和调试（查看模型做了什么决策、调用了什么工具）。

Transcript 文件存储在 ~/.claude/ 目录下，以 JSON 格式保存。每个会话有一个唯一的 ID，对应一个 Transcript 文件。随着使用时间增长，这些文件会积累占用磁盘空间。

隐私提示：Transcript 包含了你与 Claude 的完整对话内容，包括你发送的代码和文件内容。如果你处理敏感信息，注意定期清理或管理这些文件。

Checkpoint 是 Claude Code 在关键时刻自动保存的「快照」，包含当前的对话状态和代码状态（通过 Git 实现）。当你需要回退到之前的某个时间点时，可以通过 Checkpoint 恢复。

Claude Code 会在每次工具调用后自动创建 Checkpoint。这意味着如果一个代码修改出了问题，你可以通过 /rewind 命令回退到修改之前的状态——不仅回退代码（通过 Git），还回退对话历史。

Checkpoint 的实现依赖于 Git——每次创建 Checkpoint 时，当前的工作目录状态会被 Git 记录。这比自己做文件备份高效得多，因为 Git 只存储差异部分。

与 Git commit 的区别：Checkpoint 是自动的、临时的、频繁的，不会出现在 Git 的正式提交历史中。它更像是一个「撤销栈」，让你可以在 Agent 操作的任意时间点回退。

Permission Mode 是 Claude Code 控制模型操作权限的核心机制。不同的模式提供不同程度的自主权，从完全需要用户确认到完全自动执行。主要模式包括：

default：标准模式，危险操作（如写入文件、运行命令）需要用户确认。acceptEdits：自动接受文件编辑，但命令执行仍需确认。plan：只规划不执行，模型只输出计划。auto：完全自动，所有操作无需确认（但会经过 Classifier 安全检查）。bypassPermissions：跳过所有权限检查（仅限特殊场景）。

Permission Mode 通过启动参数 --permission-mode 或配置文件设置。选择合适的模式是安全性和效率的平衡——auto 模式让 Claude 可以连续执行大量操作而不被打断，但也意味着你需要更多地信任模型的判断。

安全建议：日常使用推荐 default 模式。只有在充分理解风险且任务确实需要连续自动执行时，才考虑 auto 模式。

Classifier 是 Claude Code 在 auto 权限模式下使用的安全检查机制。当模型请求执行一个操作时，Classifier 会评估这个操作的风险等级，决定是否允许自动执行或需要回退到用户确认。

Classifier 基于机器学习模型，能够分析命令的语义和潜在影响。例如，ls -la 是低风险的只读操作，可以自动执行；rm -rf / 是极高风险的破坏性操作，即使在 auto 模式下也会被拦截。

Classifier 的判断不是简单的关键词匹配——它理解命令的上下文和意图。同一个命令在不同的上下文中可能有不同的风险评估。这比静态的黑白名单更灵活、更准确。

局限性：Classifier 不是万无一失的。对于非常新颖或罕见的操作模式，它可能做出不准确的判断。这也是为什么 auto 模式仍然需要谨慎使用。

Sandbox 是一种将程序执行限制在安全边界内的技术。在 Claude Code 中，Sandbox 用于限制 Bash 工具执行的命令——确保命令只能在指定的目录内操作、不能访问敏感的系统资源、不能进行网络连接（如果配置了限制）。

Sandbox 的实现方式因平台而异：在 macOS 上可以使用 sandbox-exec，在 Linux 上可以使用容器技术或 seccomp 过滤器。Claude Code 的沙箱配置确保即使模型生成了意外的命令，也不会对系统造成实质性损害。

Sandbox 是纵深防御策略的一层——即使 Permission Mode 和 Classifier 都被绕过，Sandbox 仍然提供最后一道保护。它限制的是操作系统层面的能力，而不仅仅是应用层面的判断。

调试影响：如果你发现某些合法命令在 Claude Code 中无法执行（比如网络访问被拒绝），可能是 Sandbox 规则导致的。检查权限配置和沙箱设置来排查问题。

Allow/Deny Rules 是预配置的权限模式匹配规则，让你可以精确控制哪些工具调用自动允许、哪些自动拒绝、哪些需要确认。它们定义在 .claude/settings.json 中，支持 glob 模式匹配。

例如，你可以配置「自动允许在 src/ 目录下创建文件」但「拒绝在项目根目录下创建文件」，或者「自动允许运行 npm test」但「所有 rm 命令需要确认」。这种细粒度的控制比简单的 Permission Mode 更灵活。

规则按顺序评估，第一个匹配的规则生效。如果没有规则匹配，则回退到当前 Permission Mode 的默认行为。这种「规则 + 默认」的机制让你可以只为特殊情况定义规则，其余情况使用默认行为。

最佳实践：从严格开始，逐步放开。先在默认模式下使用，观察哪些操作是你经常确认的，然后为这些操作添加 Allow 规则来提高效率。

Hooks 是在特定工具事件发生前后自动执行的 Shell 命令。在 Claude Code 中，你可以配置 Hooks 来在工具调用前进行额外检查、在工具调用后执行清理操作、或者在特定事件发生时触发自定义工作流。

Hooks 定义在 .claude/settings.json 中，每个 Hook 指定了触发的事件类型（如 pre-tool-use、post-tool-use）、匹配条件（哪个工具、什么参数）、以及要执行的命令。

典型的 Hook 用例包括：在每次文件编辑后自动运行 linter、在 Bash 命令执行前检查命令是否在允许列表中、在对话结束后自动保存摘要到指定位置。Hooks 是实现「自动化行为」的正确方式——比在 CLAUDE.md 中写「每次编辑后都要运行 linter」更可靠。

重要：Hooks 由 harness 执行，不是由模型执行。这意味着它们是确定性的、可靠的——不会因为模型的「理解」偏差而被跳过。这也是 Hooks 和 CLAUDE.md 指令的根本区别。