Agent Teams 完全配置手册：终端、记忆与工作流

一句话核心：掌握终端配置、记忆系统与工作流设计，让 Agent Teams 从“能用”到“好用”。

为什么需要这份手册？

Claude Code 的 Agent Teams 功能强大，但官方文档分散在多个页面，关键配置细节容易被忽略。更重要的是，很多“奇怪的行为”其实是有意的设计——如果不理解背后的逻辑，你会浪费大量时间在错误的方向上。

这份手册聚焦三个核心问题：

终端配置：如何在不同终端中获得最佳体验？
记忆系统：如何让 Agent 持续学习而非每次从零开始？
工作流设计：如何在当前限制下设计高效的协作流程？

第一部分：终端配置的技术真相

Split-pane 只支持 tmux 和 iTerm2 的真正原因

很多人以为这是技术限制或开发进度问题，实际上是架构选择：Claude Code 需要程序化创建和管理窗格（spawn、resize、send text、detect closure），只有 tmux 和 iTerm2 暴露了这些能力。

tmux：通过 tmux split-window、tmux send-keys 等命令提供完整的窗格管理 API
iTerm2：通过 Python API 和 it2 CLI 提供原生 macOS 窗格控制

其他终端（Ghostty、VS Code Terminal、Windows Terminal）缺少这层抽象，无法被外部程序控制窗格生命周期。这不是 Bug，而是这些终端的设计哲学——它们优先考虑简洁性而非可编程性。

配置方案对比：三种路径的权衡

方案 1：iTerm2 Native（macOS 本地开发首选）

配置步骤：

安装 it2

https://github.com/mkusaka/it2

启用 iTerm2 Python API

iTerm2 → Settings → General → Magic → 勾选 “Enable Python API”

启动 Claude Code

claude --teammate-mode tmux

体验优势：

✅ 原生 macOS 集成：Cmd+点击文件路径直接打开、触控板双指滚动、原生文本选择
✅ iTerm2 功能全开：Cmd+F 搜索、拖拽调整窗格大小、分离窗格到独立窗口
✅ 配置文件生效：每个窗格继承你的 iTerm2 配色、字体、透明度设置

适用场景：

本地 macOS 开发
需要频繁查看日志和文件路径
重度依赖触控板操作

限制：

❌ macOS 专属，无法跨平台
❌ 无会话持久化（iTerm2 关闭后会话丢失）

方案 2：tmux in Any Terminal（跨平台/远程开发首选）

配置步骤：

# 1. 安装 tmux
brew install tmux  # macOS
sudo apt install tmux  # Linux

# 2. 启动 tmux 会话
tmux

# 3. 在 tmux 内启动 Claude Code
claude --teammate-mode tmux

体验优势：

✅ 跨平台：macOS、Linux、Windows（WSL）、远程 SSH 全支持
✅ 会话持久化：SSH 断线后 tmux attach 恢复，Teammates 完好无损
✅ 强大的脚本能力：可编写 tmux 脚本自动化窗格布局

适用场景：

远程服务器开发
需要会话持久化（长时间运行的任务）
跨平台工作流

限制：

❌ 学习曲线陡峭：prefix key（默认 Ctrl+B）、copy mode、配置语法
❌ 无原生手势：需要进入 copy mode 才能滚动，无 Cmd+点击

快速上手 tmux 的最小知识：

# 基础操作（prefix = Ctrl+B）
prefix + %        # 垂直分割窗格
prefix + "        # 水平分割窗格
prefix + 方向键   # 切换窗格
prefix + d        # 分离会话（后台运行）
tmux attach       # 重新连接会话

# 滚动查看历史
prefix + [        # 进入 copy mode
q                 # 退出 copy mode

方案 3：tmux -CC in iTerm2（最佳体验，设置复杂）

配置步骤：

# 1. 确保 tmux 已安装
brew install tmux

# 2. 在 iTerm2 中启动 tmux -CC
tmux -CC

# 3. 启动 Claude Code
claude --teammate-mode tmux

体验优势：

✅ tmux 后端 + iTerm2 前端：兼得会话持久化和原生 macOS 体验
✅ 网络断线恢复：SSH 断开后重连，tmux -CC attach 恢复所有窗格
✅ 无需学习 tmux 快捷键：窗格管理完全通过 iTerm2 原生界面

适用场景：

远程开发但希望保持本地体验
需要会话持久化 + 原生手势
愿意投入时间配置以获得最佳体验

限制：

❌ 设置复杂度最高
❌ 仅限 iTerm2 + macOS

决策树：选择适合你的方案

你在 macOS 上工作吗？
├─ 否 → 使用 tmux（方案 2）
└─ 是 → 你需要远程开发或会话持久化吗？
    ├─ 否 → 使用 iTerm2 Native（方案 1）
    └─ 是 → 使用 tmux -CC in iTerm2（方案 3）

验证配置是否成功：
运行 claude --teammate-mode tmux 后创建一个团队，如果看到多个独立窗格出现且可以独立交互，说明配置成功。

第二部分：窗格生命周期的反直觉设计

为什么 Teammate 关闭后窗格不消失？

这是我测试时最困惑的地方，也是很多人尝试“修复”的问题。真相是：这是特性，不是 Bug。

当 Teammate 关闭时，Claude Code 进程退出，但窗格保持打开状态并显示：

# 窗格内容示例
[Teammate 完成的最后输出]
...
$ claude --resume abc123-session-id

设计意图：

审计优先：每个窗格是该 Teammate 的“工作日志”，保留完整输出供事后审查
会话恢复：显示 --resume 命令，可以重新进入该 Teammate 的对话
架构约束：Claude Code 缓存窗格 ID 用于后续团队创建，删除窗格会导致 “Session not found” 错误

不要尝试自动关闭窗格

我花了很长时间尝试编写脚本自动关闭窗格，最终发现这是与设计对抗：

问题链：

手动关闭窗格 → Claude Code 缓存的窗格 ID 失效
尝试创建第二个团队 → “Session not found” 错误
必须重启 Claude Code 并重新 --teammate-mode tmux

正确的工作流：

启动 Claude Code
→ 创建团队并完成任务
→ 团队关闭（窗格保持打开）
→ 审查每个窗格的输出和会话 ID
→ 关闭所有窗格和 Claude Code
→ 下次需要新团队时，重新启动 Claude Code

核心原则：一个 Claude Code 会话 = 一个团队生命周期

窗格永不复用的现状

即使旧窗格还开着，Claude Code 也会创建全新窗格。这意味着如果你强行在一个会话中创建多个团队（即使成功），旧窗格会不断累积。

当前最佳实践：

接受“一次性团队”的设计
利用窗格保留的特性做事后分析
需要新团队时干净地重启

未来可能的改进（实验性阶段未确定）：

窗格复用机制
多团队会话支持
更智能的窗格生命周期管理

第三部分：记忆系统的双轨设计

Claude Code 有两套看似相似但本质不同的记忆机制，混淆它们会导致信息放错位置、Agent 表现不佳。

CLAUDE.md：静态规则手册

本质：你写给 Agent 的“公司制度”，明确的、不变的指令。

文件位置：

/Library/Application Support/ClaudeCode/CLAUDE.md  # 组织级（macOS）
~/.claude/CLAUDE.md                                 # 用户级
.claude/CLAUDE.md                                   # 项目级
.claude/rules/*.md                                  # 模块化规则
.claude/CLAUDE.local.md                             # 项目本地（不提交 git）

典型内容：

# 编码规范
- 使用 TypeScript strict mode
- 所有函数必须有 JSDoc 注释
- 使用 Prettier 格式化代码

# 项目架构
- API 路由在 /src/api
- 组件在 /src/components
- 测试文件与源文件同目录，命名为 *.test.ts

# 常用命令
- 运行测试：npm test
- 启动开发服务器：npm run dev

特点：

✅ 你完全控制内容
✅ 可以通过 git 共享给团队
✅ 支持 @path/to/import 语法递归导入（最多 5 层）
❌ 静态，不会自动更新

Memory Frontmatter：动态学习日志

本质：Agent 自己积累的“工作经验”，动态的、涌现的知识。

启用方式：
在 Subagent 的 markdown 文件中添加 YAML frontmatter:

---
name: security-reviewer
memory: user  # 或 project / local
---

你是安全审查专家。在审查过程中，将发现的漏洞模式、
修复方案、常见误区记录到你的 memory 中。

Memory Scopes：


Scope	存储路径	适用场景
user	`~/.claude/agent-memory/<agent>/`	跨项目通用知识（推荐默认）
project	`.claude/agent-memory/<agent>/`	项目特定知识，可提交 git
local	`.claude/agent-memory-local/<agent>/`	项目特定但不应提交（敏感信息）

工作机制：

Agent 启动时，自动加载 MEMORY.md 前 200 行到系统提示
Agent 获得 Read/Write/Edit 工具管理记忆文件
超过 200 行时，Agent 被指示自动整理和精简
可以创建额外的主题文件并从 MEMORY.md 链接

主动触发学习：

# 任务前
"查看你的记忆，这个项目有哪些已知的安全问题？"

# 任务后
"将本次发现的新模式保存到你的记忆中"

# 嵌入 Agent 定义
"在每次审查后，自动更新你的记忆：
- 发现的新漏洞模式
- 有效的修复方案
- 团队常犯的错误"

决策矩阵：什么放在哪里？


问题	CLAUDE.md	Memory Frontmatter
这是明确的、不变的规则吗？	✅	❌
这需要 Agent 自己发现和积累吗？	❌	✅
团队所有人都应该知道吗？	✅	❌
这是 Agent 特定的专业知识吗？	❌	✅
内容会随着任务执行而变化吗？	❌	✅

典型分配示例：

CLAUDE.md：

编码规范（ESLint 配置、命名约定）
项目架构（目录结构、模块职责）
技术栈约束（使用 React 18、禁用 class 组件）
常用命令（测试、构建、部署）

Memory Frontmatter：

“发现 lodash 的 _.get() 在深层嵌套时性能差，改用可选链“
“团队常在 useEffect 中忘记清理定时器，导致内存泄漏”
“auth 模块的文档在 /docs/internal/auth-flow.md "
“上次 PR 中发现 SQL 注入风险在用户输入未转义时”

最佳实践：让 Agent 持续进化

1. 为专业化任务创建带记忆的 Subagents

<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
memory: user
---

你是安全审查专家，重点关注：
- SQL 注入、XSS、CSRF
- 认证和授权漏洞
- 敏感数据泄露

**记忆指令**：
每次审查后，更新你的记忆：
1. 新发现的漏洞模式
2. 有效的修复方案
3. 本项目特有的风险点

2. 建立“首次运行”和“持续改进”的双阶段流程

# 第一次使用
"审查这个 PR 的安全问题，并将发现的模式记录到记忆中"

# 第 5 次使用
"根据你的记忆，这个 PR 是否重复了之前发现的问题？"

3. 定期审查 Agent 的记忆质量

# 查看记忆内容
cat ~/.claude/agent-memory/security-reviewer/MEMORY.md

# 如果发现记忆过时或错误
"你的记忆中关于 X 的部分已过时，请更新为：[新信息]"

验证记忆是否有效：

第 5 次调用同一 Agent 时，是否比第 1 次更精准、更快？
Agent 是否主动引用记忆中的先前发现？
记忆文件是否随着任务增长而有意义地扩充？

第四部分：在限制中设计高效工作流

Agent Teams 仍处于实验阶段，了解当前限制并围绕它们设计工作流，比试图绕过限制更高效。

当前核心限制（2026 年 2 月）


限制	影响	应对策略
一个会话一个团队	无法在同一 Claude Code 会话中连续创建多个团队	接受“一次性团队”设计，任务完成后重启
Teammate 不可恢复	`/resume` 和 `/rewind` 不恢复 Teammates	任务前充分规划，避免依赖恢复
无嵌套团队	Teammates 不能创建子团队	扁平化任务分解，避免递归结构
任务状态可能滞后	Teammates 有时不标记任务完成	使用 Split-pane 模式手动监控
关闭可能延迟	Teammates 完成后延迟关闭	预留缓冲时间，不要立即关闭窗格

高效工作流模板

模板 1：研究探索型任务

场景：调研一个新技术方案，需要从多个角度评估

团队结构：

Team Lead（协调）
├─ Teammate 1：技术可行性分析
├─ Teammate 2：性能和成本评估
└─ Teammate 3：竞品方案对比

工作流：

# 1. 启动 Claude Code（Split-pane 模式）
claude --teammate-mode tmux

# 2. 创建团队
"创建一个 3 人团队调研 [技术方案]：
- Teammate 1 负责技术可行性，重点关注集成难度和依赖
- Teammate 2 负责性能和成本，给出量化评估
- Teammate 3 负责竞品对比，列出优劣势
完成后互相挑战对方的结论，给出综合建议"

# 3. 监控执行（Split-pane 优势）
# 实时查看三个窗格的输出，发现偏离方向时及时介入

# 4. 团队关闭后审查
# 逐个窗格查看完整输出，提取关键洞见

# 5. 关闭 Claude Code
# 下次新任务时重新启动

关键点：

✅ 任务边界清晰，Teammates 可独立工作
✅ 需要互相挑战，体现 Agent Teams 价值
✅ Split-pane 模式便于实时监控研究方向

模板 2：并行代码审查

场景：PR 审查，需要从安全、性能、测试三个维度评估

团队结构：

Team Lead（综合结论）
├─ Security Reviewer（带记忆）
├─ Performance Reviewer（带记忆）
└─ Test Coverage Reviewer（带记忆）

工作流：

# 1. 确保 Reviewers 已配置记忆
# .claude/agents/security-reviewer.md（memory: user）
# .claude/agents/performance-reviewer.md（memory: user）
# .claude/agents/test-reviewer.md（memory: user）

# 2. 启动 Claude Code（In-process 模式即可）
claude

# 3. 创建团队
"使用 security-reviewer、performance-reviewer、test-reviewer 
三个 agent 审查这个 PR。每个 reviewer 先查看自己的记忆，
然后给出审查意见。完成后对比发现，给出优先级排序"

# 4. 等待结果（In-process 模式）
# 不需要实时监控，完成后查看综合报告即可

# 5. 审查后更新记忆
"每个 reviewer 将本次发现的新问题模式保存到记忆中"

关键点：

✅ 利用 Memory Frontmatter 让 Reviewers 持续改进
✅ In-process 模式减少干扰，只关心最终结果
✅ 任务完全独立，无需频繁通信

模板 3：跨层功能开发

场景：开发一个新功能，涉及前端、后端、测试

团队结构：

Team Lead（Delegate Mode）
├─ Frontend Dev
├─ Backend Dev
└─ Test Engineer

工作流：

# 1. 启动 Claude Code（Split-pane 模式）
claude --teammate-mode tmux

# 2. 创建团队并启用 Delegate Mode
"创建团队开发 [功能]：
- Frontend：实现 UI 组件和状态管理
- Backend：实现 API 端点和数据验证
- Test：编写端到端测试
API 契约已在任务描述中定义"

# 创建团队后按 Shift+Tab 启用 Delegate Mode

# 3. 监控协调（Split-pane + Delegate Mode）
# Lead 只做任务分配和消息传递，不参与实现
# 实时查看三个窗格，发现接口不一致时协调

# 4. 验证集成
# 团队完成后，手动运行测试验证集成

# 5. 审查代码质量
# 逐个窗格查看实现细节

关键点：

✅ Delegate Mode 保持 Lead 专注协调
✅ 明确 API 契约减少 Teammates 间依赖
✅ Split-pane 模式便于发现集成问题

避免的反模式

❌ 反模式 1：在一个会话中创建多个团队

# 错误做法
创建团队 A → 完成 → 尝试创建团队 B → "Session not found"

# 正确做法
创建团队 A → 完成 → 关闭 Claude Code → 重启 → 创建团队 B

❌ 反模式 2：期望 Teammates 恢复状态

# 错误做法
创建团队 → 中途退出 → /resume → Lead 恢复但 Teammates 丢失

# 正确做法
任务前充分规划，一次性完成；或接受从头开始

❌ 反模式 3：创建复杂的任务依赖

# 错误做法
"Teammate 1 完成后，Teammate 2 基于其结果工作，
然后 Teammate 3 综合两者..."

# 正确做法
尽量让任务并行且独立，最后由 Lead 综合

第五部分：配置检查清单

终端配置验证

iTerm2 Native：

已安装 it2 CLI：which it2 有输出
已启用 Python API:iTerm2 → Settings → General → Magic
能创建窗格：claude --teammate-mode tmux 后创建团队，看到多个窗格
触控板滚动有效：在窗格中双指滚动可查看历史
Cmd+点击有效：点击文件路径能打开文件

tmux：

已安装 tmux：tmux -V 显示版本
能创建会话：tmux 启动成功
能创建窗格：在 tmux 内运行 claude --teammate-mode tmux
能分离和重连：Ctrl+B d 分离，tmux attach 重连
能滚动历史：Ctrl+B [ 进入 copy mode

tmux -CC in iTerm2：

tmux 和 iTerm2 都已配置
tmux -CC 启动后窗格显示为原生 iTerm2 分割
分离后 tmux -CC attach 能恢复

记忆系统验证

CLAUDE.md：

项目级文件存在：.claude/CLAUDE.md
用户级文件存在：~/.claude/CLAUDE.md（可选）
内容是静态规则：编码规范、架构说明、常用命令
Claude 启动时自动加载：启动后询问 Claude 是否知道项目规范

Memory Frontmatter：

Subagent 文件包含 memory: user/project/local
记忆目录已创建：~/.claude/agent-memory/<agent>/ 或 .claude/agent-memory/<agent>/
MEMORY.md 文件存在且有内容
内容是动态学习：发现的模式、经验、项目特定知识
Agent 能引用记忆：询问“你的记忆中有什么？”

工作流验证

一个会话一个团队：

理解窗格不消失是特性
不尝试自动关闭窗格
团队完成后重启 Claude Code 再创建新团队

任务设计：

任务边界清晰，Teammates 可独立工作
避免复杂的任务依赖链
预留 Teammates 讨论和综合的时间

模式选择：

需要实时监控时用 Split-pane
只关心结果时用 In-process
3+ Teammates 且需要协调时启用 Delegate Mode

缺口清单：需要你补充的真实案例

以下部分需要你根据实际使用经验补充：

1. 终端配置的实际截图

iTerm2 Native 的窗格布局截图
tmux 的窗格布局截图
tmux -CC 的窗格布局截图

2. 记忆系统的真实演进

某个 Subagent 的 MEMORY.md 从第 1 次到第 10 次的变化
具体的记忆内容示例（脱敏后）
记忆带来的实际改进数据（如审查时间缩短、发现问题增多）

3. 工作流的真实案例

一次完整的研究探索任务记录（任务描述、团队配置、最终产出）
一次并行代码审查的完整日志
一次跨层功能开发的协调过程

4. 踩坑与解决

遇到 “Session not found” 错误的具体场景和解决过程
Teammates 任务状态滞后的实际影响和应对
其他未在文档中提及的问题

5. 成本数据

同一任务用单 Agent vs Agent Teams 的 Token 消耗对比
不同 Teammate 数量（2/3/5）的成本差异
时间节省 vs 成本增加的量化分析

总结：从“能用”到“好用”的三个关键

终端配置不是可选项：Split-pane 模式在复杂任务中的价值远超设置成本，选择适合你工作流的方案并正确配置。
记忆系统是复利引擎：CLAUDE.md 定义规则，Memory Frontmatter 积累经验，两者配合让 Agent 从“临时工”变成“老员工”。
接受限制而非对抗：当前的“一个会话一个团队”、“窗格不消失”等设计有其合理性，围绕限制设计工作流比试图绕过更高效。

Agent Teams 仍在快速迭代，这份手册基于 2026 年 2 月的实测和官方文档。随着功能成熟，部分限制可能解除，但核心配置逻辑和记忆系统的设计哲学应该会保持稳定。

参考资源：

更新日期：2026 年 2 月 7 日
适用版本：Claude Code with Opus 4.6+