claude-code-best · claude-code-best · Apr 1, 2026 · Apr 1, 2026
diff --git a/docs/agent/coordinator-and-swarm.mdx b/docs/agent/coordinator-and-swarm.mdx
@@ -0,0 +1,58 @@
+---
+title: "协调者与蜂群"
+description: "从单兵作战到团队协作——多 Agent 的高级编排模式"
+---
+
+{/* 本章目标：介绍 Coordinator Mode 和 Agent Swarms */}
+
+## 两种协作模式
+
+子 Agent 是"临时帮手"——主 Agent 派出去做一件事就回来。对于更复杂的协作需求，Claude Code 提供了两种高级模式：
+
+## Coordinator Mode：一个指挥，多个执行
+
+就像一个团队 leader 带着几个开发者：
+
+- **Coordinator**（协调者）：负责理解需求、拆解任务、分配工作、汇总结果
+- **Workers**（执行者）：各自领取任务独立执行，通过邮箱向 Coordinator 汇报
+
+```
+        ┌─── Worker A (重构 API)
+        │
+Coordinator ──┼─── Worker B (更新测试)
+        │
+        └─── Worker C (更新文档)
+```
+
+Coordinator 不自己写代码，它的职责是**编排**——确保所有 Worker 的工作能拼合在一起。
+
+## Agent Swarms：蜂群式协作
+
+比 Coordinator 更松散的协作模式：
+
+- 多个 Agent 以对等身份同时工作
+- 没有中心化的指挥者
+- 通过消息邮箱互相通信和协调
+- 适合"各自负责一块、偶尔需要沟通"的场景
+
+## Teammate 机制
+
+进程内的"队友"——一种更轻量的协作方式：
+
+- 在同一个进程内运行，共享部分基础设施状态
+- 有独立的对话上下文和工具权限
+- 适合"我需要一个搭档帮忙看看这段代码"的场景
+
+## 任务类型
+
+支撑多 Agent 协作的是丰富的任务类型：
+
+| 任务类型 | 用途 |
+|----------|------|
+| **LocalAgentTask** | 本地子 Agent 任务 |
+| **LocalShellTask** | 后台 shell 命令 |
+| **InProcessTeammateTask** | 进程内队友 |
+| **RemoteAgentTask** | 远程 Agent |
+| **DreamTask** | 后台自主任务 |
+
+每种任务类型都有自己的生命周期管理、状态追踪和通信方式。
diff --git a/docs/agent/sub-agents.mdx b/docs/agent/sub-agents.mdx
@@ -0,0 +1,69 @@
+---
+title: "子 Agent：分身术"
+description: "当一个 AI 不够用时，它会召唤更多的自己"
+---
+
+{/* 本章目标：解释子 Agent 机制的设计和应用场景 */}
+
+## 为什么需要子 Agent
+
+有些任务太大，一个 AI 实例忙不过来：
+
+- "在 5 个不同的文件中分别找到并修复同类 bug"
+- "一边重构后端 API，一边更新前端调用"
+- "研究这个库的用法，同时修改我们的代码"
+
+## 分身术的运作方式
+
+Claude Code 中的 Agent 工具让 AI 能够**启动另一个 AI 实例**来处理子任务：
+
+<Steps>
+  <Step title="主 Agent 分析任务">
+    主 Agent 判断任务可以被拆解为独立的子任务
+  </Step>
+  <Step title="启动子 Agent">
+    通过 Agent 工具创建一个或多个子 Agent，每个子 Agent 收到一个清晰的子任务描述
+  </Step>
+  <Step title="并行执行">
+    多个子 Agent 可以同时工作，互不干扰
+  </Step>
+  <Step title="结果汇总">
+    子 Agent 完成后，结果返回给主 Agent，主 Agent 汇总并呈现给用户
+  </Step>
+</Steps>
+
+## 子 Agent 的边界
+
+子 Agent 不是和主 Agent 完全一样的——它有明确的能力边界：
+
+| 特性 | 主 Agent | 子 Agent |
+|------|---------|---------|
+| 可用工具 | 全部工具 | 受限子集（不能再启动子 Agent 等） |
+| 上下文 | 完整的会话历史 | 只有主 Agent 给的任务描述 |
+| 权限 | 用户设定 | 继承主 Agent 的权限，或更严格 |
+| 状态 | 可修改全局状态 | 隔离的状态空间 |
+
+## 通信方式
+
+主 Agent 和子 Agent 之间通过**消息邮箱**通信：
+
+- 主 Agent 通过 `Agent` 工具启动子 Agent
+- 子 Agent 通过 `SendMessage` 工具向主 Agent 报告进度
+- 这种松耦合的通信方式让 Agent 可以异步协作
+
+## 适用场景
+
+<CardGroup cols={2}>
+  <Card title="并行研究" icon="magnifying-glass">
+    多个子 Agent 同时搜索不同方向的信息
+  </Card>
+  <Card title="分治修改" icon="code-branch">
+    把大规模修改拆分到多个子 Agent 并行执行
+  </Card>
+  <Card title="前后台配合" icon="layer-group">
+    一个子 Agent 在后台运行测试，主 Agent 继续写代码
+  </Card>
+  <Card title="隔离实验" icon="flask">
+    在 worktree 中启动子 Agent 尝试一个方案，不影响主分支
+  </Card>
+</CardGroup>
diff --git a/docs/agent/worktree-isolation.mdx b/docs/agent/worktree-isolation.mdx
@@ -0,0 +1,55 @@
+---
+title: "Worktree 隔离"
+description: "给子 Agent 一个独立的工作空间，互不污染"
+---
+
+{/* 本章目标：解释 git worktree 在多 Agent 协作中的作用 */}
+
+## 问题：多个 Agent 改同一份代码
+
+当多个 Agent 同时修改项目文件时，冲突在所难免：
+
+- Agent A 修改了 `config.ts`，Agent B 也在改同一个文件
+- Agent A 的测试需要某个状态，Agent B 的修改破坏了它
+- 半完成的修改混在一起，无法分辨哪些是哪个 Agent 做的
+
+## 解决方案：Git Worktree
+
+Git 原生支持 **worktree**（工作树）——在同一个仓库中创建多个独立的工作目录，每个目录在自己的分支上独立工作。
+
+Claude Code 利用这个特性为子 Agent 提供隔离的工作空间：
+
+| | 共享工作目录 | Worktree 隔离 |
+|---|---|---|
+| 文件冲突 | 多个 Agent 可能互相覆盖 | 每个 Agent 在自己的目录中工作 |
+| 分支 | 都在同一个分支上 | 每个 Agent 有自己的分支 |
+| 测试 | 互相干扰 | 完全独立 |
+| 合并 | 需要手动处理冲突 | 通过 git merge 有序合并 |
+
+## 工作流程
+
+<Steps>
+  <Step title="创建 Worktree">
+    AI 启动带隔离模式的子 Agent，系统自动在 `.claude/worktrees/` 下创建新的工作目录
+  </Step>
+  <Step title="独立工作">
+    子 Agent 在自己的 worktree 中自由修改文件、执行命令
+  </Step>
+  <Step title="完成任务">
+    子 Agent 完成后，变更留在 worktree 的分支上
+  </Step>
+  <Step title="合并或丢弃">
+    主 Agent（或用户）决定：合并这些变更到主分支，还是丢弃
+  </Step>
+  <Step title="清理">
+    不再需要的 worktree 会被自动清理
+  </Step>
+</Steps>
+
+## 安全网
+
+Worktree 还充当了一个安全网：
+
+- 子 Agent 的实验性修改不会影响主分支
+- 如果方案不可行，整个 worktree 可以直接丢弃
+- 多个方案可以在不同 worktree 中并行尝试，最后选最好的
diff --git a/docs/context/compaction.mdx b/docs/context/compaction.mdx
@@ -0,0 +1,63 @@
+---
+title: "上下文压缩"
+description: "对话太长怎么办——优雅地'遗忘'不重要的信息"
+---
+
+{/* 本章目标：解释 Compaction 机制的设计和策略 */}
+
+## 为什么需要压缩
+
+每次 API 调用的 token 有上限（通常 200K）。一场长时间的编程对话可能产生：
+
+- 大量的文件内容（AI 读了几十个文件）
+- 长篇的命令输出（构建日志、测试结果）
+- 往返的对话历史
+
+不压缩的话，很快就会撞到 token 上限，对话被迫终止。
+
+## 压缩的策略
+
+Claude Code 提供了多层压缩机制：
+
+<AccordionGroup>
+  <Accordion title="自动压缩">
+    当 token 接近上限时，系统自动触发压缩。AI 生成一份当前对话的**摘要**，替换掉早期的详细消息。效果就像人类的"记忆"——记住要点，忘记细节。
+  </Accordion>
+  <Accordion title="手动压缩">
+    用户可以随时通过 `/compact` 命令主动触发压缩。可以附带提示语（如 `/compact 聚焦在认证模块的修改上`），引导 AI 保留特定信息。
+  </Accordion>
+  <Accordion title="Micro Compact">
+    更细粒度的局部压缩——不是压缩整个对话，而是压缩某些特别长的工具输出（比如一个 5000 行的测试日志）。
+  </Accordion>
+</AccordionGroup>
+
+## 压缩边界
+
+压缩后，系统在消息历史中插入一个"边界标记"。后续的 API 调用只发送边界之后的消息：
+
+```
+[早期的 50 条消息] ← 被压缩
+[压缩摘要边界] ← 一段浓缩的摘要
+[后续的 10 条消息] ← 正常发送
+```
+
+这个设计保证了：
+- 压缩后的摘要为 AI 提供了历史上下文
+- 新的对话不受旧消息的 token 负担
+- 用户无感知——对话继续自然进行
+
+## 压缩前后的 Hooks
+
+压缩是一个可能丢失信息的操作，因此系统允许用户在压缩前后执行自定义脚本：
+
+- **Pre-compact Hook**：压缩前执行，可以标记"这些信息不能丢"
+- **Post-compact Hook**：压缩后执行，可以验证关键信息是否保留
+
+## 什么信息会被保留
+
+压缩不是简单的截断，AI 会智能地决定保留什么：
+
+- 用户的核心需求和目标
+- 重要的决策和原因
+- 当前工作的状态（改了哪些文件、做到哪一步）
+- 之前犯过的错误（避免重蹈覆辙）
diff --git a/docs/context/project-memory.mdx b/docs/context/project-memory.mdx
@@ -0,0 +1,58 @@
+---
+title: "项目记忆"
+description: "让 AI 跨对话记住你的偏好和项目上下文"
+---
+
+{/* 本章目标：解释记忆系统如何让 AI 变得'有记忆' */}
+
+## AI 的记忆困境
+
+大语言模型没有真正的记忆。每次新对话，它都是一张白纸。用户不得不反复解释"我的项目用 Bun 不用 Node"、"commit 消息用中文"。
+
+## 记忆系统的解决方案
+
+Claude Code 通过一个基于文件的持久化记忆系统来模拟"跨会话记忆"：
+
+<CardGroup cols={2}>
+  <Card title="用户记忆" icon="user">
+    关于用户的信息：角色、偏好、技术背景
+  </Card>
+  <Card title="反馈记忆" icon="message">
+    用户对 AI 行为的纠正和肯定
+  </Card>
+  <Card title="项目记忆" icon="folder">
+    项目中的非代码信息：谁负责什么、截止日期
+  </Card>
+  <Card title="参考记忆" icon="link">
+    外部资源的位置：Issue tracker、Dashboard URL
+  </Card>
+</CardGroup>
+
+## 记忆的读写时机
+
+| 时机 | 动作 |
+|------|------|
+| 每次对话开始 | 加载记忆索引（MEMORY.md），相关记忆注入 System Prompt |
+| 用户纠正 AI | AI 自动判断是否值得记住，写入反馈记忆 |
+| 用户说"记住这个" | 立即保存到对应类型的记忆文件 |
+| 用户说"忘掉这个" | 找到并删除对应的记忆条目 |
+| 记忆可能过期时 | 使用前先验证（文件还在？函数还存在？），过期则更新或删除 |
+
+## 记忆 vs 代码注释 vs CLAUDE.md
+
+| | 记忆 | 代码注释 | CLAUDE.md |
+|---|---|---|---|
+| 存储位置 | `~/.claude/` 目录 | 代码文件中 | 项目目录中 |
+| 谁能看到 | 只有当前用户 | 所有开发者 | 所有使用 Claude Code 的人 |
+| 适合存什么 | 个人偏好、非公开的上下文 | 代码逻辑解释 | 项目约定、开发指南 |
+| 跨项目 | 是 | 否 | 否 |
+
+## 不该存什么
+
+记忆系统明确规定了不应存储的内容：
+
+- 代码结构和架构（读代码就知道）
+- git 历史（`git log` 就能查）
+- 调试方案（修复已在代码中）
+- CLAUDE.md 里已有的内容（避免重复）
+- 临时性任务状态（用任务系统）
diff --git a/docs/context/system-prompt.mdx b/docs/context/system-prompt.mdx
@@ -0,0 +1,53 @@
+---
+title: "System Prompt 的动态组装"
+description: "AI 的'工作记忆'是如何在每次对话前被精心拼装的"
+---
+
+{/* 本章目标：解释 System Prompt 的组装过程和设计思想 */}
+
+## 什么是 System Prompt
+
+每次调用 AI API 时，都需要发送一个 System Prompt——它是 AI 的"人设说明书"，告诉 AI：
+
+- 你是谁（Claude Code，一个编程助手）
+- 你能做什么（可用工具列表）
+- 你在什么环境（操作系统、当前目录、git 状态）
+- 你需要遵守什么规则（安全规范、输出格式）
+
+## 不是静态模板，而是动态组装
+
+Claude Code 的 System Prompt 不是一段写死的文本，而是根据当前环境**实时组装**的：
+
+| 组成部分 | 内容 | 来源 |
+|----------|------|------|
+| 基础人设 | 角色定义、行为准则 | 内置模板 |
+| 环境信息 | 操作系统、shell 类型、当前日期 | 运行时检测 |
+| Git 状态 | 当前分支、最近提交、工作区状态 | `git` 命令输出 |
+| 项目知识 | CLAUDE.md 文件内容 | 项目目录层级扫描 |
+| 记忆文件 | 用户偏好、项目约定 | 持久化记忆系统 |
+| 工具说明 | 每个可用工具的描述和参数 | 工具注册表 |
+
+## CLAUDE.md：项目级知识注入
+
+这是 Claude Code 最巧妙的设计之一。在项目根目录放一个 `CLAUDE.md` 文件，就能让 AI "理解" 你的项目：
+
+- **项目概述**：这个项目做什么、用了什么技术栈
+- **开发约定**：代码风格、命名规范、分支策略
+- **常用命令**：怎么构建、怎么测试、怎么部署
+- **注意事项**：已知的坑、特殊的配置
+
+系统会自动发现并合并多级 CLAUDE.md：
+
+```
+~/.claude/CLAUDE.md              ← 用户全局（个人偏好）
+  └── /project/CLAUDE.md         ← 项目根目录（团队共享）
+        └── /project/src/CLAUDE.md  ← 子目录（模块特定）
+```
+
+## 缓存策略
+
+System Prompt 的 token 消耗不小（可能占总量的 30%+）。为了降低成本，系统使用了缓存机制：
+
+- 不变的部分（基础人设、工具说明）可以跨请求复用
+- 变化的部分（git 状态、记忆文件）每次重新生成
+- 缓存节点的位置经过精心设计，最大化缓存命中率