harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

harness - Agent Team & Skill Architect

harness - Agent团队与技能架构

Keyword:
harness
·
build a harness
·
design agent team
·
harness engineering
Meta-skill: harness designs the teams and skills that run your domain work.

Harness decomposes complex tasks into coordinated teams of specialized agents. It analyzes your domain, selects the right architecture pattern, generates agent definition files and skills, then validates the harness end-to-end.

Agent Teams require:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

关键词:
harness
·
build a harness
·
design agent team
·
harness engineering
元技能：harness可设计用于执行你领域工作的团队和技能。

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

Agent团队需要开启:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

When to use this skill

什么时候使用本技能

Decompose a complex project into a coordinated multi-agent team
Choose the right architecture: pipeline, fan-out/fan-in, expert pool, producer-reviewer, supervisor, or hierarchical delegation
Generate
```
.claude/agents/{name}.md
```
agent definition files
Generate
```
.claude/skills/{name}/SKILL.md
```
skill files with bundled resources
Validate trigger conditions, dry-run teams, and compare with/without harness quality
Build harnesses for: research, coding, content creation, code review, data pipelines, marketing

将复杂项目拆解为可协作的多Agent团队
选择合适的架构：流水线、扇出/扇入、专家池、生产者-评审者、监督者或者分层委派
生成
```
.claude/agents/{name}.md
```
Agent定义文件
生成附带捆绑资源的
```
.claude/skills/{name}/SKILL.md
```
技能文件
验证触发条件、对团队进行 dry-run，对比使用/不使用harness的质量差异
为以下场景搭建harness：研究、编码、内容创作、代码评审、数据流水线、营销

Instructions

使用说明

Step 1: Domain Analysis

步骤1：领域分析

Analyze the task and project context:

Read the codebase or user request to identify the domain, sub-tasks, and outputs
Detect user expertise level (beginner → detailed scaffolding; expert → lean definitions)
List the distinct task types — these map to agent roles
Decide execution mode:
- Agent Team (default): 2+ agents need to communicate or cross-validate → use
```
TeamCreate
```
  +
```
SendMessage
```
- Sub-agents (lightweight): tasks are independent and results only return to orchestrator → use
```
Agent
```
  tool

分析任务和项目上下文：

阅读代码库或用户请求，识别领域、子任务和输出内容
判断用户的专业水平（新手 → 提供详细的脚手架；专家 → 提供精简的定义）
列出不同的任务类型 —— 这些对应Agent的角色
确定执行模式：
- Agent团队（默认）：2个及以上Agent需要通信或交叉验证 → 使用
```
TeamCreate
```
  +
```
SendMessage
```
- 子Agent（轻量模式）：任务相互独立，结果仅返回给编排器 → 使用
```
Agent
```
  工具

Step 2: Team Architecture Design

步骤2：团队架构设计

Choose a pattern based on task structure (see references/agent-design-patterns.md):

Pattern	When to use	Example
Pipeline	Sequential dependent stages	Design → Code → Review → Deploy
Fan-out/Fan-in	Parallel independent work merged at the end	4 researchers → synthesizer
Expert Pool	Dynamic routing by input type	Route to security, perf, or style expert
Producer-Reviewer	Generation + validation cycle	Writer + Editor loop
Supervisor	Central coordinator with dynamic assignment	Supervisor + migrators
Hierarchical Delegation	Recursive decomposition (max 2 levels)	PM → Tech Lead → Engineers

Key rules:

Agent teams are the default; choose sub-agents only when no inter-agent communication is needed
All agents must be file-based (
```
.claude/agents/{name}.md
```
) — never embed roles inline in
```
Agent
```
tool prompts
Avoid nesting teams (team members cannot themselves create teams)
Maximum 2 levels for hierarchical delegation

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

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

核心规则：

默认使用Agent团队；仅当不需要Agent间通信时才选择子Agent模式
所有Agent必须基于文件定义（
```
.claude/agents/{name}.md
```
）—— 永远不要在
```
Agent
```
工具提示中内嵌角色定义
避免嵌套团队（团队成员不能自己再创建团队）
分层委派最多设置2层

Step 3: Generate Agent Definition Files

步骤3：生成Agent定义文件

Create

.claude/agents/{agent-name}.md

for each agent. Use this template:

markdown

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

为每个Agent创建

.claude/agents/{agent-name}.md

文件，使用以下模板：

markdown

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

{Agent Name}

Core Responsibilities

{primary responsibility 1}
{primary responsibility 2}

{primary responsibility 1}
{primary responsibility 2}

Operational Principles

{principle 1}
{principle 2}

{principle 1}
{principle 2}

Input Protocol

Receives: {what inputs this agent consumes}
Format: {expected format}

Receives: {what inputs this agent consumes}
Format: {expected format}

Output Protocol

Produces: {what outputs this agent delivers}
Format: {output format and location}

Produces: {what outputs this agent delivers}
Format: {output format and location}

Error Handling

On failure: {recovery behavior}
Escalation: {when to notify orchestrator}

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}


Use `model: opus` for all agents by default unless speed is critical.

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


默认所有Agent使用 `model: opus`，除非对速度要求极高。

Step 4: Generate Skill Files

步骤4：生成技能文件

For each skill the team needs, create

.claude/skills/{skill-name}/SKILL.md

following the Agent Skills spec:

Write a "pushy" description — actively invites triggering with specific conditions and synonyms
Explain why (context), not just what (commands)
Keep
```
SKILL.md
```
under 500 lines — move detailed docs to
```
references/
```
Bundle reusable logic in
```
scripts/
```
Apply progressive disclosure: metadata → body → references

For the orchestrator skill template, see references/orchestrator-template.md. For team architecture examples, see references/team-examples.md.

对于团队需要的每个技能，按照Agent技能规范创建

.claude/skills/{skill-name}/SKILL.md

文件：

编写**"主动式"描述** —— 明确列出触发条件和同义词，主动引导触发
解释为什么（上下文），而不仅仅是做什么（命令）
控制
```
SKILL.md
```
篇幅在500行以内 —— 把详细文档移动到
```
references/
```
目录下
把可复用逻辑封装在
```
scripts/
```
目录下
采用渐进式披露结构：元数据 → 正文 → 参考资料

编排器技能模板参考 references/orchestrator-template.md。团队架构示例参考 references/team-examples.md。

Step 5: Integration & Orchestration

步骤5：集成与编排

Define the full workflow in the orchestrator skill or agent:

Before running: ensure
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
is set in your environment for agent team mode.

Specify phase dependencies (which agents must complete before the next phase starts)
Define data passing: use absolute paths anchored to
```
_workspace/
```
for intermediate artifacts
Add error handling for agent failures, timeouts, and data conflicts
Preserve intermediate artifacts for post-execution verification — do not delete them

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

运行前: 确保你的环境中已经设置
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
以开启Agent团队模式。

明确阶段依赖关系（下一阶段开始前哪些Agent必须完成任务）
定义数据传递规则：中间产物使用基于
```
_workspace/
```
的绝对路径
针对Agent失败、超时和数据冲突添加错误处理逻辑
保留中间产物用于执行后验证 —— 不要删除它们

Step 6: Validation & Testing

步骤6：验证与测试

Run validation to verify the harness before use:

bash

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

Validation checks:

Structure: required sections present in agent definition files
Trigger conditions: 20 eval queries (10 should-trigger + 10 should-NOT-trigger)
Dry run: simulate team execution without running real tasks
Comparative: quality with harness vs without (baseline) — target +50% score improvement

For testing methodology, see references/skill-testing-guide.md.

使用前运行验证命令检查harness：

bash

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

验证检查项：

结构: Agent定义文件包含所有必填部分
触发条件: 20个评估查询（10个应该触发+10个不应该触发）
Dry run: 不运行真实任务的前提下模拟团队执行
对比验证: 使用harness和不使用harness（基线）的质量对比 —— 目标是得分提升+50%

测试方法参考 references/skill-testing-guide.md。

Examples

示例

Example 1: Research Harness (Fan-out/Fan-in)

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

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)

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)

Example 2: Code Review Harness (Expert Pool)

示例2：代码评审Harness（专家池）

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)

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)

Example 3: Content Production Harness (Pipeline + Parallel)

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

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

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

Best practices

最佳实践

File-based agents always — embedding roles inline in
```
Agent
```
tool prompts prevents reuse across sessions
Agent teams by default — prefer
```
TeamCreate
```
+
```
SendMessage
```
over sub-agents for any work requiring coordination
"Pushy" descriptions — passive descriptions mean skills never activate; write active invitations
Explain why, not just what — agents follow reasoning better than rigid commands
Preserve intermediate artifacts —
```
_workspace/
```
files enable post-run verification and debugging
Validate before deploy — run trigger eval (20 queries) and dry-run before using the harness in production
Max 2 hierarchy levels — deeper nesting creates coordination overhead without quality gains

始终使用基于文件的Agent —— 在
```
Agent
```
工具提示中内嵌角色定义会导致无法跨会话复用
默认使用Agent团队 —— 对于任何需要协作的工作，优先选择
```
TeamCreate
```
+
```
SendMessage
```
而非子Agent
使用主动式描述 —— 被动描述会导致技能永远无法被触发；编写主动的触发引导
解释原因，而不仅仅是要求 —— Agent更容易遵循有逻辑的说明，而非生硬的命令
保留中间产物 ——
```
_workspace/
```
下的文件可用于运行后验证和调试
部署前验证 —— 在生产环境使用harness前，运行触发评估（20个查询）和dry-run
最多2层层级结构 —— 更深的嵌套会带来协调开销，且不会提升质量

References

参考资料

Agent Design Patterns
Orchestrator Template
Team Examples
Skill Writing Guide
Skill Testing Guide
harness GitHub
Agent Skills Specification

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