Subagents的配置与Team管理 - 学习笔记-subagents

前置知识：Subagents是Claude Code中由主代理（Parent Agent）创建的辅助子代理，Team是管理多个子代理协同工作的组织形式。理解Team的配置和管理是充分发挥子代理能力的关键。

一、TeamCreate创建团队

TeamCreate是创建子代理团队的核心工具，它允许主代理建立一个有组织的子代理群体，并为团队设定明确的目标和角色分工。使用TeamCreate工具时，主代理需提供以下关键参数：

team_name：团队唯一名称，用于标识和索引团队。命名应具有描述性，便于在多个团队中快速识别。名称会直接影响配置文件在文件系统中的路径。
description：团队描述，说明团队的创建目的、预期完成的工作范围以及团队的整体目标。这个描述会被写入config.json，供所有子代理读取。
agent_type：团队领导角色的类型（如"leader"、"researcher"、"writer"等），决定了该子代理在团队中的职责和行为模式。

创建成功后，TeamCreate会在文件系统中生成对应的配置文件和目录结构，为后续的团队协作提供基础。所有配置信息都持久化存储在本地，跨会话保持可用。

关键点：TeamCreate只需调用一次即可完成团队创建。创建后的团队配置会持久保存在 ~/.claude/teams/ 目录下，后续会话可以直接使用，无需重复创建。

二、Team配置文件结构

每个Team创建后，会在 ~/.claude/teams/{team-name}/config.json 位置生成一个JSON配置文件。这个文件是整个团队的核心信息载体，团队成员通过读取该文件来了解团队构成和各自职责。

典型的config.json文件结构如下：

{
  "team_name": "documentation-team",
  "description": "负责文档编写和审核的团队",
  "members": [
    {
      "name": "lead-writer",
      "agentId": "sub_agent_abc123",
      "agentType": "writer"
    },
    {
      "name": "lead-reviewer",
      "agentId": "sub_agent_def456",
      "agentType": "reviewer"
    }
  ]
}

team_name：与创建时指定的名称一致，用于标识团队。
description：团队目标和职责描述。
members数组：团队成员列表，每个成员包含：
- name：成员名称，用于在子代理之间互相引用和发送消息。
- agentId：代理ID，系统生成的唯一标识符。
- agentType：代理类型，定义该成员的职能角色。

注意：虽然config.json是普通的JSON文件，可以手动编辑，但不建议在运行时手动修改。手动修改可能导致配置文件与实际运行的子代理状态不一致。如需调整，应通过TeamCreate重新配置或通过TeamDelete清理后重新创建。

三、Task目录管理

与Team配置相对应的另一重要目录是 ~/.claude/tasks/{team-name}/，用于存储该团队相关的任务文件。Task目录与TeamCreate创建的团队一一对应，提供了任务持久化存储的能力。

Task目录的关键特性：

任务持久化：任务文件存储在本地文件系统中，跨会话保持可用。即使主代理会话结束，任务信息也不会丢失。
TaskCreate/TaskList对应：使用TaskCreate创建的任务会在tasks目录中生成对应的文件，通过TaskList可以读取目录中所有任务的定义和状态。
文件系统访问：子代理可以通过文件系统直接读取Task目录中的内容，无需通过网络或API调用，大幅降低延迟。

架构要点：Task目录本质上是文件系统级别的共享存储。所有属于同一Team的子代理都可以通过访问 ~/.claude/tasks/{team-name}/ 来获取任务信息，这种设计使得任务管理轻量且高效。

四、团队成员发现

子代理之间的协调依赖于团队成员发现机制。当子代理被创建后，它们可以通过读取config.json文件来发现其他团队成员，从而实现协作。

团队成员发现的核心流程：

读取config.json：子代理使用Read工具读取 ~/.claude/teams/{team-name}/config.json，获取完整的成员列表。
获取成员信息：从config.json的members数组中获取每个成员的name、agentId和agentType，了解团队分工。
跨代理通信：子代理通过config.json中的name属性向其他子代理发送消息，实现任务分配、进度同步和结果汇总。
角色识别：根据agentType字段识别每个成员的职能角色（如writer负责编写，reviewer负责审核），实现专业分工。

这种基于文件系统的发现机制使得团队配置高度透明。任何子代理都可以随时查阅最新的团队配置，确保协作信息的一致性和准确性。

关键点：团队成员发现完全基于本地文件系统，不依赖外部服务。子代理通过读取config.json中的name和agentId信息，即可实现精准的跨代理消息路由。

五、TeamDelete清理资源

当团队的工作完成后，应及时清理团队资源以释放磁盘空间并保持文件系统整洁。TeamDelete工具用于完成这一清理工作。

资源清理的标准流程：

确认子代理状态：在删除团队之前，确保所有子代理已关闭或已完成其任务。强制删除正在运行的子代理可能导致数据丢失。
删除team目录：TeamDelete会清理 ~/.claude/teams/{team-name}/ 目录，包括config.json配置文件。
删除tasks目录：同时清理 ~/.claude/tasks/{team-name}/ 目录，移除所有关联的任务文件。
验证清理结果：确认目录已被完全删除，避免残留文件影响后续的团队创建。

最佳实践：

始终在团队工作完全结束后再执行TeamDelete。
如果团队工作尚未完成但需要临时关闭，保留其目录结构，下次启动时可继续使用。
定期清理不再使用的Team目录，避免大量废弃配置占用磁盘空间。
执行TeamDelete前确认没有其他会话在使用该团队。

六、整体工作流程

理解Subagents团队配置与管理的完整生命周期，有助于合理规划多代理协作任务。以下是推荐的标准化工作流程：

┌─────────────────────────────────────────────────────┐ │ Subagents Team 生命周期管理 │ ├─────────────────────────────────────────────────────┤ │ │ │ 1. TeamCreate │ │ ├─ 指定 team_name（唯一标识） │ │ ├─ 描述 description（团队目标） │ │ └─ 配置 agent_type（角色分配） │ │ ↓ │ │ 2. 自动生成配置文件 │ │ ├─ ~/.claude/teams/{team-name}/config.json │ │ └─ ~/.claude/tasks/{team-name}/ │ │ ↓ │ │ 3. 团队协作运行 │ │ ├─ 子代理通过config.json发现队友 │ │ ├─ 通过TaskCreate/TaskList管理任务 │ │ └─ 跨代理消息传递与协调 │ │ ↓ │ │ 4. TeamDelete │ │ ├─ 确认所有子代理已关闭 │ │ ├─ 删除 teams 目录 │ │ └─ 删除 tasks 目录 │ │ │ └─────────────────────────────────────────────────────┘

七、常见问题与排错

问题1：TeamCreate后无法找到配置文件

检查 ~/.claude/teams/ 目录是否存在，确认team_name拼写是否正确。如果目录不存在，可能是创建过程被中断，重新执行TeamCreate即可。

问题2：子代理无法发现其他团队成员

确认子代理有权限读取config.json文件。检查文件权限设置，确保读取路径正确。最常见的原因是使用了错误的team_name导致路径不匹配。

问题3：Task文件丢失

Task文件存储在本地文件系统中，如果意外丢失，检查 ~/.claude/tasks/{team-name}/ 目录是否存在。若目录被误删，需重新创建任务。建议定期备份重要的Task配置文件。

问题4：TeamDelete删除失败

确认没有其他进程正在使用该团队目录。某些系统（如Windows）可能会锁定正在被使用的文件。关闭所有相关会话后重试。

八、核心要点总结

1. 团队生命周期：TeamCreate（创建）→ 配置文件生成 → 团队协作运行 → TeamDelete（清理），形成完整的管理闭环。

2. 配置持久化：所有配置存储在 ~/.claude/teams/ 目录，支持跨会话持久化，无需重复创建。

3. 文件系统协作：团队成员发现和任务管理均基于本地文件系统，配置透明、访问高效。

4. 资源管理：及时清理不再使用的Team目录是良好的实践，有助于保持开发环境的整洁。

5. config.json为核心：既是团队配置的存储文件，也是子代理互相发现和通信的桥梁。

九、进一步思考

Subagents的Team机制为复杂任务的多代理协作提供了基础架构支撑。在掌握了基本的创建、配置、运行和清理流程之后，可以考虑以下进阶方向：

多团队协作模式：如何设计多个Team之间的协作关系？是否可以将一个Team的输出作为另一个Team的输入，形成流水线式处理？
团队角色优化：针对不同类型的任务，如何设计最优的角色组合？例如"研究+编写+审核"的三角色模型。
任务优先级管理：当Team中有多个任务同时进行时，如何有效管理任务优先级和资源分配？
错误恢复机制：当一个子代理发生故障时，如何实现自动恢复或任务重新分配？