Harness 实战一条提示词生成 Claude Code 多智能体团队的六阶段流水线与验证方法【免费下载链接】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 定义生成、Skill 生成、编排集成与验证测试输出一套完整的多智能体协作体系.claude/agents/.claude/skills/。本文以该项目的发布内容文档为主体结合仓库内 skills/harness/SKILL.md 及 6 份参考指南的源码级细节完整讲解其六阶段流水线、六种架构模式、数据传递与错误处理协议、触发验证与 A/B 对比测试方法以及可复制的安装与使用步骤——读完你既能理解其设计原理也能在自己的项目中直接落地一套可验证的 Agent 团队。一、为什么需要结构化预配置多智能体团队搭建的摩擦原文档指出了 LLM 代码 Agent 的核心痛点能力很强但方向缺失。同一个模型、同一个任务产出质量可能在 40/100 与 80/100 之间剧烈波动缺少的是结构而非智能。而当使用 Claude Code 的 Agent Teams 功能时手动搭建多智能体工作流往往比任务本身更耗时需要反复完成判断需要哪些 Agent编写带角色与协议的 Agent 定义文件为每个 Agent 创建 Skill 文件选择协作模式协调模式打通数据传递与错误处理测试触发器是否正确生效。Harness 将上述过程自动化Build a harness for this project一句提示词即可触发一个六阶段流水线自动产出完整的 Agent 团队及其技能。仓库 README.md 将 Harness 定位为 Claude Code 生态 L3 层的Team-Architecture Factory团队架构工厂与生成确定性运行时配置的同类工具Runtime-Configuration Factory处于同一层的相邻子层。二、六阶段流水线总览Harness 的核心是一次结构化流水线README 与 skills/harness/SKILL.md 均给出如下流程Phase 1: Domain Analysis领域分析 ↓ Phase 2: Team Architecture Design团队架构设计Agent Teams vs Subagents 6 种模式 ↓ Phase 3: Agent Definition GenerationAgent 定义生成.claude/agents/ ↓ Phase 4: Skill GenerationSkill 生成.claude/skills/ ↓ Phase 5: Integration Orchestration编排集成数据传递 错误处理 ↓ Phase 6: Validation Testing验证测试触发验证 有/无技能 A/B 对比在此基础上skills/harness/SKILL.md 还加入了Phase 0现状审计与Phase 7Harness 演化使其能够区分全新构建 / 存量扩展 / 运维维护三种运行模式并支持基于反馈的持续演进详见下文第七节。三、Phase 0/1现状审计与领域分析在真正生成任何文件之前Harness 先审计现状对应 SKILL.md 的 Phase 0读取项目/.claude/agents/、项目/.claude/skills/与项目/CLAUDE.md依据目录是否存在及内容分支到不同执行路径目录为空→全新构建从 Phase 1 全量执行已有 Harness→按变更类型 × Phase矩阵只执行必要的阶段审计/同步请求→进入运维维护工作流对比现有 Agent/Skill 列表与 CLAUDE.md 记录检测漂移drift。进入 Phase 1 领域分析后Harness 会识别用户所处的领域与项目类型核心任务类型生成、验证、编辑、分析等与现有 Agent/Skill 的冲突与重叠避免重复建设项目的技术栈、数据模型与主要模块通过探索代码库用户熟练度——通过对话中的术语与提问水平推断并据此调整沟通语气例如对经验较少的用户避免无解释地使用 assertion、JSON schema 等术语。四、Phase 2团队架构设计4.1 执行模式选择Agent Teams / Subagents / Hybridskills/harness/references/agent-design-patterns.md 明确Agent Teams 是最高优先级默认值。三种模式的区别如下模式适用场景核心机制Agent Teams默认2 人以上协作、需要实时协调与反馈、中间产物互相引用TeamCreate建队 SendMessage成员直连 TaskCreate共享任务列表成员自主协调Subagents替代单 Agent 任务、只需把结果返回主线程、团队通信开销过大直接调用Agent工具run_in_background: true并行Hybrid各 Phase 特性差异大如并行采集→共识整合按 Phase 混用团队/子代理决策顺序SKILL.md先尝试按 Agent Teams 设计2 人以上即默认→ 仅当团队通信在结构上不必要且开销大于收益时才选 Subagents → 若各阶段特性差异明显则考虑 Hybrid并在编排器中逐 Phase 标注执行模式。4.2 六种架构模式流水线的关键步骤是从 6 种架构模式中为领域挑选最合适的模式两种模式可组合为复合模式模式适用场景典型示例Pipeline流水线顺序依赖的任务链代码生成 → 审查 → 测试 → 部署Fan-out/Fan-in扇出/扇入可并行的独立任务后合并多视角代码审计汇总为单一报告Expert Pool专家池根据上下文动态挑选合适专家路由安全/性能/架构专家处理对应区域Producer-Reviewer生成-审查生成后做质量复核一方产出一方 QA必要时回炉Supervisor监督者中央 Agent 动态分配任务按工作进展实时派发任务Hierarchical Delegation层级委派自顶向下递归分解复杂问题逐层拆解到执行者参考指南还给出了各模式与执行模式的匹配建议例如 Fan-out/Fan-in 是 Agent Teams 最自然的模式成员可实时分享发现、互相挑战Expert Pool 则更适合 Subagents按需调用专家无需常驻团队Producer-Reviewer 建议用 Agent Teams 实现生成者与审查者的实时反馈同时设置 2~3 次最大重试上限以防死循环。复合模式如扇出 生成-审查流水线 扇出监督者 专家池在实战中更为常见。4.3 Agent 拆分与类型选择判断是否拆分 Agent 的四维标准为专业性领域不同则拆、并行性可独立执行则拆、上下文上下文负担大则拆、复用性其他团队也用则拆。Claude Code 的 Agent 类型分为内置general-purpose全工具访问、Explore只读探索、Plan只读规划与自定义.claude/agents/{name}.md全工具访问。无论是否使用内置类型Harness 都强制生成独立的 Agent 定义文件以保证跨会话复用与团队通信协议的显式化。五、Phase 3/4Agent 定义与 Skill 生成5.1 Agent 定义文件结构每个 Agent 以.claude/agents/{name}.md定义包含核心角色与职责、工作原则、输入/输出协议、错误处理策略、协作关系Agent Teams 模式下追加## 团队通信协议消息收/发对象与任务请求范围。模板详见 skills/harness/references/agent-design-patterns.md完整实例如worldbuilder.md、webtoon-reviewer.md见 skills/harness/references/team-examples.md。所有 Agent 统一使用model: opus且在Agent工具调用中必须显式声明——Harness 认为团队质量直接取决于 Agent 的推理能力上限。5.2 Skill 结构与积极型触发描述Skill 生成于.claude/skills/{name}/SKILL.mdskill-name/ ├── SKILL.md # 必需YAML frontmatter(name, description) Markdown 正文 └── Bundled Resources # 可选 ├── scripts/ # 重复/确定性任务的执行代码 ├── references/ # 按需条件加载的参考文档 └── assets/ # 输出用文件模板、图片等关键设计是description 是 Skill 唯一的触发机制。Claude 倾向于保守地触发技能因此 description 必须写得积极pushy——既描述技能能力又明确具体触发场景还要写清不该触发的边界。原文档给出的对照坏例子PDF 处理技能——几乎不会触发好例子PDF 文件读取、文本/表格提取、合并、分割、旋转、水印、加密、OCR 等所有 PDF 操作。只要提及 .pdf 文件或要求 PDF 产出就必须使用本技能。5.3 Progressive Disclosure三层上下文加载为控制上下文窗口占用Skill 采用三层渐进披露Progressive Disclosure层级加载时机规模目标Metadataname description始终在上下文中约 100 词SKILL.md 正文技能被触发时 500 行references/按需读取不限脚本可免加载直接执行配套规则skills/harness/references/skill-writing-guide.mdSKILL.md 接近 500 行时将细节拆入 references/ 并在正文留何时读取该文件的指针超过 300 行的 reference 文件顶部加目录ToC按领域拆分如 AWS/GCP/Azure 各一文件只加载相关文件。正文写作遵循Why-First讲明原因而非机械命令、一般化避免对单一样例过拟合、命令式语气、重复脚本预打包到scripts/等原则。六、Phase 5集成与编排编排器Orchestrator是团队级的特殊 Skill负责把各 Agent 与 Skill 编织成工作流——Individual Skill 定义每个 Agent 怎么做编排器定义谁在何时以何顺序协作。三种编排模板Agent Teams / Subagents / Hybrid完整代码见 skills/harness/references/orchestrator-template.md。6.1 数据传递协议策略方式适用模式适用场景消息驱动SendMessage成员直连团队实时协调、反馈交换、轻量状态传递任务驱动TaskCreate/TaskUpdate共享任务状态团队进度跟踪、依赖管理、任务请求文件驱动约定路径读写文件团队 子代理大数据量、结构化产物、审计追溯返回值驱动Agent工具返回消息子代理主线程直接收集子代理结果推荐组合团队模式 任务驱动协调 文件驱动产物 消息驱动实时沟通子代理模式 返回值驱动收结果 文件驱动大产物。文件驱动约定中间产物统一存于_workspace/命名规范为{phase}_{agent}_{artifact}.{ext}如01_analyst_requirements.md中间文件保留用于事后验证与审计最终产物才输出到用户指定路径。6.2 错误处理与团队规模错误处理的核心原则重试一次仍失败则标注缺失继续推进冲突数据不删除保留来源并列。编排器模板覆盖了单成员失败、过半成员失败、超时、数据冲突、任务状态停滞五类场景的处置策略。团队规模也有明确指导小任务5~10 项2~3 人、中任务10~20 项3~5 人、大任务20 项以上5~7 人且3 名专注成员优于 5 名散漫成员——成员越多协调开销越大。6.3 CLAUDE.md 指针与后续任务支持Harness 完成后会在项目CLAUDE.md中登记一个最小指针领域目标 触发规则 变更历史表因为 CLAUDE.md 每个新会话都会加载Agent/Skill 明细交给编排器与.claude/目录管理避免重复。同时编排器 description 必须包含后续任务关键词重新执行、更新、修改、补充、仅重跑某部分、基于上次结果改进等并在工作流开头检查_workspace/存在性以区分初始执行 / 部分重跑 / 全新执行否则首次运行后 Harness 会变成死代码。七、Phase 6验证与测试——质量真正的所在原文档强调生成文件只是入场券触发测试、A/B 对比与迭代改进循环才是产出达到生产级而非演示级的关键。完整方法论见 skills/harness/references/skill-testing-guide.md。结构校验Agent 文件位置正确、Skill frontmattername/description合法、跨 Agent 引用一致、未生成命令文件.claude/commands/保持为空。触发验证为每个 Skill 编写 should-trigger 与 should-NOT-trigger 查询各 8~10 条重点不是明显无关的查询而是**边界模糊near-miss**的查询如 xlsx 技能 vs 图片转换。还可对 20 条查询做 Train/Test 切分、自动优化 description最多 5 轮。With-skill vs Without-skill A/B 对比同一提示词同时派发两个子代理——一个加载 Skill、一个不加载baseline比较产出质量。Dry-run 测试检查编排器各 Phase 顺序逻辑、数据传递路径无断点dead link、每个 Agent 输入与上一 Phase 输出匹配、错误场景的兜底路径可行。迭代改进循环将反馈一般化为原则级修改避免窄修补、删除不增值内容、把重复出现的辅助脚本打包进scripts/直至用户满意或不再有有意义改进。定量评估采用 assertion 自动评分并产出结构化 JSONeval_metadata.json记录用例元数据、grading.json记录逐条断言通过/失败与通过率、timing.json记录 token 与耗时——注意total_tokens/duration_ms只能在子代理完成通知时立即保存之后无法恢复。评估中还可引入三个专家角色Grader断言评分、Comparator盲评 A/B 优劣、Analyzer分析无区分度断言与高方差用例。目录结构上每次迭代保留独立目录如iteration-N/禁止覆盖历史结果_workspace/不得删除。Harness 自身的进化闭环Phase 7还包括执行后主动征求反馈按反馈类型分别修改 Skill、Agent 定义、编排器或 description在 CLAUDE.md 变更历史表登记每次变更并在同类反馈出现两次、Agent 反复失败、用户绕开编排器手动操作时主动提出演进建议。八、实证数据A/B 实验结果原文档记录了作者在15 个软件工程任务、3 个难度等级上进行的受控 A/B 实验有 Harness 预配置 vs 无预配置指标无 Harness有 Harness提升平均质量分49.579.360%胜率——15/15100%输出方差——-32%最关键的发现是效果随任务复杂度放大基础任务 23.8、进阶任务 29.6、专家级任务 36.2。这符合搜索空间越大、跨子任务保持一致性越难结构化分解越重要的假设——就像盖房子需要图纸、拍电影需要分镜脚本产出越复杂流程越需要结构。需要如实说明数据边界据 README.md 的明确表述上述结果为n15 的作者自测 A/B 数据第三方复现尚待进行采用前建议在 2~4 周内开展内部试点并测量自己的数据。九、100 个现成 Harness跨领域泛化验证为证明该方法可以泛化作者用本插件批量生成了100 套生产级 Harness 配置覆盖 10 个领域内容创作、软件开发、数据/AI、商业战略、教育、营销、法律、健康等每套含 4~5 个专家 Agent 1 个编排器技能 领域专属技能共1,808 个 Markdown 文件并以英语与韩语双语发布合计 200 包。这既是开箱即用的配置库也构成对生成流水线可扩展性的实证。十、快速上手安装与使用10.1 安装两种方式在 Claude Code 中通过插件市场安装对应原文档与 docs/quickstart.md/plugin marketplace add revfactory/harness /plugin install harnessharnessCLI 等价形式claude plugin marketplace add revfactory/harness claude plugin install harnessharness或将本仓库的skills/harness目录直接复制为全局技能README 提供的方式cp -r skills/harness ~/.claude/skills/harness10.2 环境要求Harness 依赖 Claude Code 的Agent Teams能力必须启用实验性开关docs/experimental-dependency.md 解释了原因export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1该标志门控TeamCreate、SendMessage、TaskCreate三个原语未设置时生成的团队会静默回退为单 Agent 执行导致 Pipeline、Fan-out/Fan-in、Supervisor、Hierarchical Delegation 等模式失效。建议将 export 写入 shell 配置文件~/.bashrc/~/.zshrc以跨会话持久化并确认 Claude Code 版本不低于 v2.x。10.3 使用提示词在 Claude Code 中直接输入Build a harness for this project Design an agent team for deep research Set up a harness for code review Build a harness for full-stack website development中文/韩文提示同样可用SKILL.md 的韩文触发词为하네스 구성해줘等quickstart 提到韩文偶发 tokenizer 路由问题时可改用英文底层技能相同。更完整的领域示例深度研究、Web 全栈开发、网漫制作、YouTube 内容策划、代码审查、API 文档、数据管道、营销活动等 8 组可复制提示词见 README.md 的 Use Cases 章节。10.4 生成产物your-project/ ├── .claude/ │ ├── agents/ # Agent 定义角色、协议、通信契约 │ │ ├── analyst.md │ │ ├── builder.md │ │ └── qa.md │ └── skills/ # 各 Agent 的能力技能 │ ├── analyze/ │ │ └── SKILL.md │ └── build/ │ ├── SKILL.md │ └── references/快速验证ls -la .claude/agents/与ls -la .claude/skills/应出现 3~5 个与领域对应的文件随后可把一条真实任务如 Jira 工单式提示交给新团队执行。十一、五条实战经验教训原文档总结了构建这一元技能过程中的核心认知与仓库参考指南互相印证触发描述要激进Claude 对技能激活偏保守description 必须过度明确触发条件skills/harness/references/skill-writing-guide.md 有完整正反例。Progressive Disclosure 是上下文管理的关键全量预载会浪费上下文窗口元数据常驻 → 正文触发时加载 → 参考按需读取的三层机制保持精简。谁与怎么做必须分离成不同文件Agent 定义角色与职责与 Skill执行方法与工具是不同的关注点耦合会摧毁复用性分离后可以自由混搭。价值真正存在于验证环节生成文件只是基础触发测试、A/B 对比与迭代改进循环才让产出从演示级变为生产级。效果随复杂度放大简单任务不需要太多结构复杂任务非常需要Harness 恰好在你最需要它的地方创造最大价值。十二、继续深入阅读skills/harness/SKILL.md——六阶段含 Phase 0/7完整工作流、Phase 选择矩阵与产出清单skills/harness/references/agent-design-patterns.md——执行模式决策树、六种架构模式、Agent 类型与拆分/复用标准skills/harness/references/skill-writing-guide.md——description 写法、Why-First、Progressive Disclosure、数据 Schemaskills/harness/references/skill-testing-guide.md——A/B 对比、assertion 评分、触发验证、迭代改进方法论skills/harness/references/orchestrator-template.md——三种模式编排器模板、错误处理表、测试场景skills/harness/references/team-examples.md——5 个真实团队配置与 Agent 定义文件全文skills/harness/references/qa-agent-guide.md——QA Agent 集成与边界交叉比对式验证方法docs/quickstart.md——5 分钟快速入门与常见故障排查FAQ #1~#5docs/experimental-dependency.md——实验性标志依赖与三种演进场景Harness 以 Apache 2.0 协议开源。其核心主张可以概括为给 LLM Agent 团队一份图纸——谁做什么、如何协调、怎样算完成——输出质量即可获得可测量的提升。这份图纸的生成、编排与验证正是 Harness 六阶段流水线所提供的完整答案。【免费下载链接】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），仅供参考