Harness Agent定义文件教程：必须写全的6大区块

Harness Agent定义文件教程必须写全的6大区块【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harnessHarness 是 Claude Code 的一个元技能meta-skill能根据你描述的业务领域自动设计出一支Agent 团队并生成这些 Agent 使用的技能文件。它落地的核心产物就是Agent 定义文件.claude/agents/目录下的每一个.md文件都完整定义了一位专业 Agent 的角色、工作原则、输入输出格式与协作方式。本教程基于 Harness 官方模板和真实团队示例带你逐个拆解 Agent 定义文件必须写全的 6 大区块新手也能照着写出可复用的 Agent。为什么 Agent 必须写成定义文件Harness 有一条硬性规则每个 Agent 必须以.claude/agents/{name}.md独立文件定义禁止把角色直接写进调用 prompt 里规则原文见 SKILL.md 的 Phase 3。原因有三点原因说明可复用定义以文件存在下一个会话直接调用不用重新解释角色可协作团队通信协议必须写明Agent 之间的协作质量才有保障职责分离Agent 文件回答谁来做技能文件回答怎么做——这正是 Harness 的核心价值即使使用general-purpose、Explore这类内置类型也要生成定义文件内置类型通过subagent_type参数指定而角色、原则和协议全部写进文件里。Agent 定义文件 6 大区块速览官方定义结构模板在 agent-design-patterns.md。一个完整的 Agent 定义文件 头部 frontmatter 正文 6 个 H2 区块骨架如下--- name: agent-name description: 1-2句角色说明。触发关键词罗列。 --- # Agent 名称 — 角色一句话摘要 你是 [领域] 的 [角色] 专家。 ## 核心角色 ## 工作原则 ## 输入/输出协议 ## 团队通信协议 ## 错误处理 ## 协作本教程的区块划分frontmatter 是区块 1核心角色、工作原则、输入/输出协议、团队通信协议是区块 2~5末尾的错误处理与协作两节合并构成区块 6。下面逐个讲清楚每块写什么、怎么写。区块 1FrontmatterAgent 的营业执照文件顶部的 YAML frontmatter 只有两个字段但都必填nameAgent 唯一名称与文件名对应如worldbuilder→worldbuilder.md也是调用时subagent_type的取值description1-2 句角色说明 触发关键词回答这个人擅长什么要具体到领域和产出物frontmatter 之后紧跟两行门面# Agent 名称 — 角色一句话摘要的标题以及你是 [领域] 的 [角色] 专家的定位句。它们和 frontmatter 一起构成文件的身份头。⚠️ 常见坑description 只写负责调研这类空话。对照官方示例——构建 SF 小说世界观的专家。设计物理法则、社会结构、技术水平、历史。——具体才有用。区块 2核心角色这个 Agent 具体干什么用编号列表写 1~4 条职责关键是具体、可检验✅ 定义世界的物理法则与技术水平❌ 负责世界观相关工作每条职责都应能对应到一次实际产出模糊的职责会让 Agent 在运行时自行发挥结果不可预期。区块 3工作原则遇到模糊时的判断标准原则告诉 Agent如何做取舍。官方 SF 世界观 Agent 的三条原则就很有参考价值内部一致性优先——设定之间不能互相矛盾用如果这个技术存在的连锁提问推演世界的派生影响世界观为故事服务——避免妨碍剧情的过度设定好的原则是可执行的标准而不是追求高质量这种空话。区块 4输入/输出协议从哪拿、往哪放这一区块定义 Agent 的工作接口必须写全三要素要素说明官方示例输入从哪里、接收什么用户的世界观概念、类型要求输出写到哪里、写什么_workspace/01_worldbuilder_setting.md格式文件格式与结构Markdown按物理/社会/技术/历史/场所分节 输出路径注意 Harness 的命名约定{phase}_{agent}_{artifact}.{ext}如01_analyst_requirements.md。这是编排器推荐的文件式数据传递方式中间产物统一存_workspace/便于事后验证与审计追溯规则详见 SKILL.md 数据传递协议。区块 5团队通信协议跟谁说话、说什么Agent 团队模式Harness 的默认执行模式下这一区块必填需要写清三件事消息接收从谁那里收什么消息如从 science-consultant 接收科学错误反馈 → 修正设定消息发送发给谁、发什么如向 character-designer 发送社会结构、阶级体系信息任务请求从共享任务列表中请求哪类任务团队模式下成员之间用SendMessage直接对话、用TaskCreate共享任务列表自行协调不必事事经过负责人。通信协议写得越明确团队协作质量越高——写不出发给谁运行时就只能靠 Agent 临场发挥。区块 6错误处理与协作兜底与边界最后一块包含两节内容错误处理失败时做什么、超时时做什么。例如官方漫画审核 Agent图像加载失败 → 该格判 REDO重绘 2 次仍 REDO → 带警告强制 PASS协作与其他 Agent 的关系——向谁提供信息、采纳谁的反馈即使你认为不会出错也要写。Harness 的验证阶段会做干运行测试逐条检查每个错误场景是否都有可执行的兜底路径检查项见 SKILL.md 的 6-5 节。完整真实示例worldbuilder.mdTeam Examples 中收录了 SF 小说团队的worldbuilder.md世界观设计 Agent完整文件是 6 大区块齐全的样板--- name: worldbuilder description: 构建 SF 小说世界观的专家。设计物理法则、社会结构、技术水平、历史。 --- # Worldbuilder — SF 世界观设计专家 你是 SF 小说的世界观设计专家。 ## 核心角色 1. 定义世界的物理法则与技术水平 2. 设计社会结构、政治体系、经济系统 ... ## 团队通信协议 - 向 character-designerSendMessage 社会结构、阶级体系信息 ...同文件里还有调研团队、漫画制作团队、代码评审团队、代码迁移团队等 5 个真实团队的配置配合 orchestrator-template.md 的编排器模板可以覆盖从单 Agent 到多 Agent 团队的几乎所有场景。验收自检清单写完文件后对照官方 产出示例清单 逐项检查文件位于.claude/agents/{name}.mdname 与文件名一致frontmatter 的 name、description 齐全description 含具体触发关键词核心角色是 1~4 条具体职责工作原则是可执行的标准不是口号输入/输出协议写明路径与格式遵循_workspace/命名约定团队通信协议写清收/发对象与任务请求范围团队模式必填错误处理覆盖失败与超时两种情形协作节写明与其他 Agent 的关系总结Agent 定义文件就是 Harness 团队里的人事档案frontmatter 是名片核心角色是岗位说明书工作原则是行为准则输入/输出协议是工作接口团队通信协议是通讯录错误处理与协作是兜底和边界。6 大区块写全这位 Agent 就能在任何会话、任何团队里被直接复用——这也是用 Harness 搭建可靠多智能体系统的地基。想继续深入Agent 分离标准、6 种架构模式与复用设计agent-design-patterns.md5 分钟快速上手从一句话生成完整团队docs/quickstart.md技能编写规范skill-writing-guide.md项目入口与全部功能说明README.md【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考