harness

harness - Agent 团队与技能架构师

关键词：harness · build a harness · design agent team · harness engineering

元技能：harness 为领域任务设计团队和技能。

Harness 会将复杂任务拆解为由专业 Agent 组成的协作团队。它会分析你的领域，选择合适的架构模式，生成 Agent 定义文件和技能，然后端到端验证 harness。

Agent 团队需要：CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何时使用此技能

• 将复杂项目拆解为协作式多 Agent 团队
• 选择合适的架构：流水线、扇出/扇入、专家池、生产者-审阅者、监督者或分层委派
• 生成 .claude/agents/{name}.md Agent 定义文件
• 生成 .claude/skills/{name}/SKILL.md 技能文件及其打包资源
• 验证触发条件，试运行团队，并比较使用与不使用 harness 时的质量
• 为以下任务构建 harness：研究、编码、内容创作、代码审查、数据流水线、营销

说明

步骤 1：领域分析

分析任务和项目上下文：

1. 阅读代码库或用户请求，确定领域、子任务和输出
2. 判断用户的专业水平（初学者 → 提供详细脚手架；专家 → 使用精简定义）
3. 列出不同的任务类型——这些类型对应 Agent 角色
4. 决定执行模式：
   • Agent 团队（默认）：需要 2 个或更多 Agent 进行沟通或交叉验证 → 使用 TeamCreate + SendMessage
   • 子 Agent（轻量级）：任务彼此独立，结果只返回给协调器 → 使用 Agent 工具

步骤 2：团队架构设计

根据任务结构选择模式（参见 references/agent-design-patterns.md）：

模式	适用场景	示例
流水线	按顺序执行的依赖阶段	设计 → 编码 → 审查 → 部署
扇出/扇入	并行的独立工作，最后合并	4 位研究员 → 综合者
专家池	根据输入类型动态路由	路由至安全、性能或风格专家
生产者-审阅者	生成 + 验证循环	写作者 + 编辑循环
监督者	由中央协调者动态分配任务	监督者 + 迁移人员
分层委派	递归拆解（最多 2 层）	PM → 技术负责人 → 工程师

关键规则：

• Agent 团队是默认选择；只有在不需要 Agent 之间沟通时才选择子 Agent
• 所有 Agent 都必须采用基于文件的定义（.claude/agents/{name}.md）——不得将角色内嵌在 Agent 工具提示词中
• 避免团队嵌套（团队成员不能自行创建团队）
• 分层委派最多 2 层

步骤 3：生成 Agent 定义文件

为每个 Agent 创建 .claude/agents/{agent-name}.md。使用此模板：

---
name: {agent-name}
description: {role and activation conditions}
model: opus
allowed-tools: {tool list}
---

# {Agent Name}

## Core Responsibilities
- {primary responsibility 1}
- {primary responsibility 2}

## Operational Principles
1. {principle 1}
2. {principle 2}

## Input Protocol
- Receives: {what inputs this agent consumes}
- Format: {expected format}

## Output Protocol
- Produces: {what outputs this agent delivers}
- Format: {output format and location}

## Error Handling
- On failure: {recovery behavior}
- Escalation: {when to notify orchestrator}

## Team Communication
- Reports to: {orchestrator or peer}
- Communicates with: {peer agents via SendMessage}
- Completion signal: {how to signal done}

除非速度至关重要，否则默认对所有 Agent 使用 model: opus。

步骤 4：生成技能文件

对于团队需要的每项技能，按照 Agent Skills 规范创建 .claude/skills/{skill-name}/SKILL.md：

1. 编写积极主动的描述——明确列出具体触发条件和同义表达，主动引导触发
2. 解释原因（上下文），而不仅仅是要做什么（命令）
3. 将 SKILL.md 保持在 500 行以内——详细文档移至 references/
4. 在 scripts/ 中打包可复用逻辑
5. 采用渐进式披露：元数据 → 正文 → 参考资料

协调器技能模板参见 references/orchestrator-template.md。 团队架构示例参见 references/team-examples.md。

步骤 5：集成与编排

在编排器技能或 Agent 中定义完整工作流：

运行前：确保环境中已设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，以启用 Agent 团队模式。

1. 指定阶段依赖关系（哪些 Agent 必须先完成，才能开始下一阶段）
2. 定义数据传递方式：中间产物使用以 _workspace/ 为基准的绝对路径
3. 为 Agent 故障、超时和数据冲突添加错误处理
4. 保留中间产物，以便执行后验证 — 不要删除它们

步骤 6：验证与测试

运行验证，在使用前检查框架：

bash scripts/validate-harness.sh .claude/agents/ .claude/skills/

验证检查项：

• 结构：Agent 定义文件中包含必需章节
• 触发条件：20 个评估查询（10 个应触发 + 10 个不应触发）
• 试运行：模拟团队执行，不运行实际任务
• 对比：比较使用框架与不使用框架（基线）时的质量 — 目标是分数提升 +50%

有关测试方法，请参阅 references/skill-testing-guide.md。

示例

示例 1：研究框架（扇出/扇入）

Prompt: "Build a harness for deep technology research"

Generated agents:
  .claude/agents/official-researcher.md    — documentation & official sources
  .claude/agents/media-researcher.md       — investment trends & news
  .claude/agents/community-researcher.md   — social response & forums
  .claude/agents/background-researcher.md  — competitive landscape
  .claude/agents/research-orchestrator.md  — synthesizes findings

Pattern: Fan-out/Fan-in (4 parallel researchers → orchestrator)

示例 2：代码审查框架（专家池）

Prompt: "Design an agent team for thorough code review"

Generated agents:
  .claude/agents/security-reviewer.md      — OWASP, injection, secrets
  .claude/agents/performance-reviewer.md   — complexity, memory, latency
  .claude/agents/testing-reviewer.md       — coverage, assertions, mocks
  .claude/agents/review-orchestrator.md    — consolidates findings

Key feature: reviewers communicate directly (cross-domain issue detection)

示例 3：内容生产框架（流水线 + 并行）

Prompt: "Build a harness for webtoon production"

Phase 1 (parallel): worldbuilder + character-designer + plot-architect
Phase 2 (sequential): prose-stylist writes based on Phase 1
Phase 3 (parallel): science-consultant + continuity-manager review
Phase 4 (sequential): prose-stylist incorporates feedback

最佳实践

1. 始终使用基于文件的 Agent — 在 Agent 工具提示词中内嵌角色，会妨碍跨会话复用
2. 默认使用 Agent 团队 — 对任何需要协调的工作，优先使用 TeamCreate + SendMessage，而不是子 Agent
3. 描述要“积极主动” — 被动的描述会导致技能从不激活；应写出主动的邀请
4. 解释原因，而不只是说明做什么 — 相比僵化的命令，Agent 更能遵循推理过程
5. 保留中间产物 — _workspace/ 文件可用于运行后验证和调试
6. 部署前进行验证 — 在生产环境中使用框架前，运行触发评估（20 个查询）和试运行
7. 最多 2 层层级 — 更深的嵌套会增加协调开销，却无法提升质量

参考资料

• Agent 设计模式
• 编排器模板
• 团队示例
• 技能编写指南
• 技能测试指南
• harness GitHub
• Agent Skills 规范