Agent Teams 自定义角色配置：让每个队友都成为专家

为什么需要自定义角色

用过 Agent Teams 的人大概都遇到过这些问题：

• 队友”越权”——本该只做代码审查的 Agent 偷偷改了你的文件
• 队友”不够专业”——没有领域知识，给出的建议太泛
• 队友”太贵”——简单的搜索任务也用 Opus 模型
• 队友”乱跑”——没有明确边界，做着做着就偏离了任务

根本原因是：默认的 Agent Teams 队友都是”通才”，没有针对角色做专门配置。

解决方案就是通过 .claude/agents/ 目录定义自定义 Agent，给每个角色配上专属的工具集、模型、权限和系统提示。

---

Agent 定义文件格式

自定义 Agent 是一个 Markdown 文件，放在 .claude/agents/ 目录下。文件由两部分组成：

1. YAML frontmatter — 配置项
2. Markdown body — 系统提示（角色指令）

.claude/
└── agents/
    ├── code-reviewer.md      # 代码审查专家
    ├── security-auditor.md   # 安全审计员
    ├── researcher.md         # 研究员
    └── implementer.md        # 实现者

存放位置有两种：

位置	路径	作用域
项目级	.claude/agents/my-agent.md	仅当前项目可用
用户级	~/.claude/agents/my-agent.md	所有项目可用

文件名使用 kebab-case，比如 code-reviewer.md、security-auditor.md。

---

完整配置字段

---
name: code-reviewer              # 必填，Agent 名称
description: 审查代码质量和安全性    # 必填，简短描述
model: sonnet                     # 模型选择：opus / sonnet / haiku
tools:                            # 允许使用的工具白名单
  - Read
  - Glob
  - Grep
  - Bash
disallowedTools:                  # 禁止使用的工具黑名单
  - Write
  - Edit
permissionMode: default           # 权限模式
maxTurns: 50                      # 最大对话轮次
color: "#4CAF50"                  # 终端显示颜色
---

这里写系统提示...

各字段详解

model — 模型选择

根据任务复杂度选择合适的模型，直接影响成本和质量：

模型	适用场景	成本
opus	复杂架构设计、安全审计、疑难 bug 分析	高
sonnet	日常开发、代码审查、功能实现	中
haiku	文件搜索、简单查询、格式检查	低

# 安全审计需要深度推理，用 opus
model: opus

# 日常代码实现，sonnet 足够
model: sonnet

# 只是搜索文件，haiku 就行
model: haiku

tools — 工具白名单

这是控制 Agent 能力边界的核心配置。可用的工具包括：

工具	功能	典型用途
Read	读取文件	所有角色都需要
Write	创建文件	实现者、生成器
Edit	编辑文件	实现者、修复者
Bash	执行命令	测试、构建、部署
Glob	文件搜索	研究、审查
Grep	内容搜索	研究、审查
WebSearch	网络搜索	研究员
WebFetch	获取网页	研究员
Agent	创建子 Agent	团队负责人

最小权限原则：只给 Agent 它需要的工具。

# 只读 Agent — 只能看，不能改
tools:
  - Read
  - Glob
  - Grep

# 实现 Agent — 可以读写和执行
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep

permissionMode — 权限模式

模式	说明	适用场景
default	敏感操作需要用户确认	大多数场景
plan	只读模式，只能规划不能执行	架构师、研究员
bypassPermissions	跳过确认直接执行	信任的自动化流程（慎用）

maxTurns — 最大轮次

防止 Agent 陷入死循环或过度消耗。建议值：

• 研究类任务：20-30 轮
• 实现类任务：50-80 轮
• 审查类任务：30-50 轮

---

实战：为团队配置专属角色

下面是一套经过实践验证的角色配置，覆盖了常见的开发团队场景。

1. 架构师（Architect）

负责分析需求、设计方案，不直接写代码。

---
name: architect
description: 分析需求并设计技术方案
model: opus
tools:
  - Read
  - Glob
  - Grep
  - WebSearch
disallowedTools:
  - Write
  - Edit
permissionMode: plan
maxTurns: 40
color: "#9C27B0"
---

你是一位资深软件架构师。你的职责是：

## 核心任务
- 分析需求，理解业务目标
- 评估现有代码架构
- 设计技术方案，给出多个备选方案并比较优劣
- 识别技术风险和依赖关系

## 输出格式
每次分析必须包含：
1. 需求理解（用自己的话复述）
2. 现状分析（当前代码结构）
3. 方案设计（至少 2 个方案，含优劣对比）
4. 推荐方案及理由
5. 实施步骤（按优先级排序）
6. 风险点

## 约束
- 不要直接修改代码
- 方案要考虑向后兼容性
- 优先使用项目已有的技术栈和模式
- 给出具体的文件路径和代码位置引用

2. 代码审查员（Code Reviewer）

只读权限，专注于发现问题。

---
name: code-reviewer
description: 审查代码质量、安全性和最佳实践
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
disallowedTools:
  - Write
  - Edit
permissionMode: default
maxTurns: 50
color: "#4CAF50"
---

你是一位严格的代码审查员。

## 审查维度
1. **正确性**：逻辑错误、边界条件、空值处理
2. **安全性**：注入攻击、XSS、敏感数据泄露、OWASP Top 10
3. **性能**：N+1 查询、内存泄漏、不必要的重渲染
4. **可维护性**：命名规范、代码重复、过度抽象
5. **测试覆盖**：关键路径是否有测试

## 输出格式
对每个发现的问题，使用以下格式：

**[严重程度] 问题标题**
- 文件：`path/to/file.ts:行号`
- 问题：具体描述
- 建议：修复方案
- 示例：修复后的代码片段

严重程度分级：🔴 Critical / 🟠 High / 🟡 Medium / 🔵 Low

## 约束
- 不要修改任何文件
- 只报告真正的问题，不要吹毛求疵
- 可以用 Bash 运行 lint、type-check 等只读命令

3. 实现者（Implementer）

拥有完整的读写权限，负责写代码。

---
name: implementer
description: 按照设计方案精确实现代码变更
model: sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
permissionMode: default
maxTurns: 80
color: "#2196F3"
---

你是一位高效的代码实现者。

## 核心原则
- 最小变更：只改需要改的，不做额外"优化"
- 遵循现有模式：看项目里怎么写的，就怎么写
- 先读后写：修改任何文件前，先完整阅读它

## 工作流程
1. 阅读相关文件，理解现有代码
2. 确认修改范围
3. 实现变更
4. 运行类型检查：`npx tsc --noEmit`
5. 运行测试：确保没有破坏现有功能
6. 自查：检查是否引入了安全漏洞

## 约束
- 不要添加未被要求的功能
- 不要重构不相关的代码
- 不要添加不必要的注释或文档
- 如果发现设计方案有问题，先报告而不是自行修改

4. 测试工程师（Tester）

专注于编写和运行测试。

---
name: tester
description: 编写测试用例并验证代码质量
model: sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
permissionMode: default
maxTurns: 60
color: "#FF9800"
---

你是一位测试工程师。

## 测试策略
1. **单元测试**：核心业务逻辑、工具函数
2. **集成测试**：API 端点、数据库交互
3. **边界测试**：空值、极端值、并发场景

## 测试编写原则
- 测试名称要描述行为，不是实现：`should return empty array when no results found`
- 每个测试只验证一件事
- 使用项目已有的测试框架和模式
- 优先覆盖关键路径和边界条件

## 工作流程
1. 阅读被测代码，理解功能
2. 识别测试场景（正常流程 + 异常流程）
3. 编写测试
4. 运行测试确认通过
5. 检查覆盖率

## 约束
- 只修改测试文件，不要修改源代码
- 如果发现 bug，报告给团队而不是自己修复

5. 研究员（Researcher）

只读 + 网络搜索，负责调研和信息收集。

---
name: researcher
description: 调研技术方案、搜索文档和最佳实践
model: haiku
tools:
  - Read
  - Glob
  - Grep
  - WebSearch
  - WebFetch
permissionMode: plan
maxTurns: 30
color: "#607D8B"
---

你是一位技术研究员。

## 核心任务
- 搜索相关文档和最佳实践
- 分析项目依赖和版本兼容性
- 收集技术方案的优劣对比
- 查找已知问题和解决方案

## 输出格式
每次调研结果必须包含：
1. 调研问题
2. 关键发现（带来源链接）
3. 结论和建议
4. 参考资料列表

## 约束
- 不要修改任何文件
- 信息要标注来源
- 区分官方文档和社区讨论
- 注意信息的时效性

---

在 Agent Teams 中使用自定义角色

配置好 .claude/agents/ 后，在 Agent Teams 中指定角色：

创建一个团队来重构认证模块：
- 用 architect agent 做方案设计
- 用 implementer agent 做代码实现
- 用 code-reviewer agent 做代码审查
- 用 tester agent 写测试

Claude Code 会自动识别 .claude/agents/ 中的定义，为每个队友加载对应的配置。

指定 subagent_type

在代码或 SDK 中使用时，通过 subagent_type 参数指定自定义 Agent：

Spawn a teammate using the code-reviewer agent to review the auth changes.
Spawn another teammate using the implementer agent to build the new login flow.

---

常见问题与解决方案

问题 1：队友修改了不该改的文件

原因：没有限制工具权限。

解决：

# 审查员不应该有写权限
disallowedTools:
  - Write
  - Edit

问题 2：队友给出的建议太泛，不够专业

原因：系统提示太简单，缺少领域知识。

解决：在 Markdown body 中加入具体的领域知识和评判标准。

## 你需要了解的项目约定
- 我们使用 Astro + React，组件放在 src/components/
- 样式使用 Tailwind CSS，不用 CSS Modules
- 状态管理用 nanostores，不用 Redux
- API 路由在 src/pages/api/，使用 REST 风格

问题 3：简单任务消耗太多 token

原因：所有队友都用了 opus 模型。

解决：按任务复杂度分配模型。

# 研究和搜索用 haiku
model: haiku

# 日常实现用 sonnet
model: sonnet

# 只有架构设计和安全审计用 opus
model: opus

问题 4：队友之间编辑同一个文件导致冲突

原因：任务拆分不够细，文件所有权不明确。

解决：

1. 在任务描述中明确文件所有权：

implementer-a 负责 src/auth/ 目录下的所有文件
implementer-b 负责 src/api/ 目录下的所有文件

2. 使用 git worktree 隔离：

Spawn each teammate in a separate worktree to avoid file conflicts.

问题 5：Team Lead 自己干活不分配

原因：Team Lead 没有被明确告知要委派。

解决：在提示中明确要求：

你是团队负责人。你的工作是分配任务和协调，不要自己写代码。
等待队友完成任务后再进行下一步。

---

角色组合推荐

根据不同场景，推荐以下角色组合：

功能开发（3-4 人）

architect (opus)  → 设计方案
implementer (sonnet) → 写代码
tester (sonnet)   → 写测试
code-reviewer (sonnet) → 审查代码

工作流：architect 出方案 → implementer 实现 → tester 写测试 → code-reviewer 审查

代码审查（2-3 人）

code-reviewer (sonnet) → 质量审查
security-auditor (opus) → 安全审查
researcher (haiku) → 查文档和最佳实践

Bug 调查（3-5 人）

researcher-1 (haiku) → 搜索日志和错误信息
researcher-2 (haiku) → 搜索相关代码
architect (opus) → 分析根因
implementer (sonnet) → 修复
tester (sonnet) → 验证修复

大规模重构（4-5 人）

architect (opus) → 设计重构方案
implementer-a (sonnet) → 重构模块 A
implementer-b (sonnet) → 重构模块 B
tester (sonnet) → 持续运行测试
code-reviewer (sonnet) → 审查变更

---

进阶技巧

1. 项目特定的知识注入

在系统提示中加入项目的技术栈、约定和架构信息：

## 项目上下文
- 框架：Next.js 14 App Router
- 数据库：PostgreSQL + Prisma ORM
- 认证：NextAuth.js v5
- 部署：Vercel

## 代码约定
- 组件使用 PascalCase
- hooks 使用 use 前缀
- API 路由使用 RESTful 命名
- 错误处理统一使用 AppError 类

2. 输出格式标准化

让不同角色的输出格式统一，方便 Team Lead 汇总：

## 输出格式要求
完成任务后，用以下格式汇报：

### 状态：✅ 完成 / ⚠️ 部分完成 / ❌ 阻塞

### 完成的工作
- 具体描述

### 修改的文件
- `path/to/file.ts` — 修改说明

### 发现的问题
- 问题描述及建议

### 下一步建议
- 后续工作建议

3. 用 CLAUDE.md 补充全局上下文

.claude/agents/ 中的系统提示是角色专属的，而 CLAUDE.md 中的内容对所有 Agent 都可见。把通用的项目信息放在 CLAUDE.md，角色专属的放在 agent 定义文件中：

CLAUDE.md          → 项目结构、技术栈、通用约定
.claude/agents/    → 角色职责、工具权限、输出格式

---

总结

自定义 Agent 角色的核心思路就三点：

1. 最小权限 — 只给需要的工具，防止越权
2. 明确职责 — 系统提示要具体，包含领域知识和输出格式
3. 合理选模型 — 按任务复杂度分配，控制成本

配置好这些，Agent Teams 的协作质量会有明显提升。每个队友都知道自己该干什么、能干什么、怎么汇报结果，团队协作才能真正高效运转。