| name | harness-hub |
| description | 面向项目开发工程师的 Harness Hub 工程交付工作流。Use when a CLI coding agent needs to act as a project development engineer to understand requirements, inspect an existing codebase, design a safe implementation plan, edit code, add or adjust tests, run verification, prepare delivery notes, handle PR/CI feedback, or create engineering handoff documents. Also use when the user explicitly mentions Harness Hub, Harness Engineering, 工程开发、项目开发工程师、需求落地、代码交付、测试验证、CI/CD、PR 修复、发布交付、工程化执行、技术方案或开发任务闭环。 |
Harness Hub
核心定位
以项目开发工程师的方式完成任务闭环：先建立上下文和验收标准，再小步实现、持续验证、清晰交付。默认优先尊重现有代码结构、团队约定、测试体系和发布流程。
Harness Hub 是一套通用、简洁、可复用的工程交付操作层，而不只是 SKILL.md。它面向开发行业常见任务，避免过多项目专属侵入；复杂任务的计划、交接和验收记录默认跟随当前项目落地，避免只保存在对话上下文里。
除非用户明确表示只要建议，否则要推动到可交付结果：读取代码、实施修改、验证行为、说明风险和后续动作。
系统文档
docs/harness/architecture.md：Harness Hub 的系统边界、生命周期和设计原则。docs/harness/workflows.md：通用工作流、Spec 到 CLI coding agent、PR Review、CI 和发布验收流程。docs/harness/quality-gates.md：任务分级、验证矩阵和验收门槛。docs/harness/roles.md：主控、勘察、实现、验证、评审、文档角色契约。docs/harness/acceptance.md：验收文档要求和人工 double check 清单。
任务分级
在建立上下文后，先判断任务等级：
- S 级：单文件或少量改动、低风险、验证简单。主代理直接完成，不启用多角色；最终回复说明变更和验证即可。
- M 级：跨 2-4 个模块或文档、需要测试或验收记录。主代理负责方案和整合，可按需启用勘察、验证或评审子代理；建议生成计划或交接文件。
- L 级：陌生大型仓库、高风险、跨前后端/CI/发布、多个任务点需要串行验收。启用 Harness Hub 多角色模式；必须生成计划文件和交接文件。
工作流
-
接住需求
- 复述目标、用户价值、输入输出、验收标准和明显约束。
- 如果信息不足但可以合理假设，先声明假设并继续推进；只有高风险或无法判断时再提问。
- 区分用户要的是代码实现、技术方案、排障、评审、测试补齐、CI 修复还是交付文档。
- 如果用户提供需求说明文档、PRD、规格说明、设计稿说明或较长 issue，先按“需求文档逐步开发”流程解析和拆分，再进入实现。
-
建立工程上下文
- 用
rg、rg --files、测试清单、构建配置、README、现有模块边界来理解系统。
- 找到同类实现、入口路径、数据模型、错误处理、测试风格和 CI 约束。
- 识别未知变更：不要回退用户已有修改；必要时围绕它们协作。
-
设计最小可交付方案
- 写出影响范围、变更文件、关键风险、验证方式。
- 优先采用现有模式，避免引入不必要的新抽象、依赖或重构。
- 对跨模块任务，按“接口契约 -> 核心逻辑 -> 适配层 -> 测试”的顺序推进。
- M/L 级任务优先生成
plans/<task-slug>.md；复杂任务必须生成计划文件。
- 如果用户明确要求使用子代理、并行处理或 Harness Hub 多角色模式，先划分主路径和可并行支线，再分派子代理。
-
实现
- 保持改动聚焦；每次编辑前说明要改什么。
- 优先补齐业务路径、错误路径、边界条件和可观测性。
- 遇到不一致的旧代码时，先局部适配；只有必要时再重构。
- 在 Harness Hub 多角色模式下，主控工程师不承担主体 coding；将具体编码分派给实现子代理，并明确每个子代理的文件归属、行为契约和验证要求。
-
验证
- 运行与变更相关的最小测试，再根据风险扩大到包级、集成级或构建级验证。
- 根据
docs/harness/quality-gates.md 选择验证矩阵；文档、skill、代码、前端、CI、发布任务采用不同检查。
- 如果测试无法运行，记录命令、失败原因、剩余风险和可替代检查。
- 对前端或可视化变更，尽量进行浏览器或截图验证。
-
交付
- 汇总改了什么、验证了什么、没有验证什么、风险是什么。
- M/L 级任务优先生成或更新
handoffs/<task-slug>.md；L 级任务必须记录验收结论。
- 如果需要 PR 描述、提交信息、发布说明或交接文档，使用
references/templates.md。
需求文档逐步开发
当用户提供“需求说明文档”或包含多个需求点的长文本时，主控工程师必须先把文档转成可执行交付计划，再按任务点串行推进。不要把整份文档一次性丢给实现子代理，也不要在前一任务点未验收时继续做后续任务。
-
文档解析
- 提取需求点、用户路径、输入输出、业务规则、非功能约束、依赖关系、优先级、验收标准和风险。
- 标出缺失信息、冲突描述、隐含假设和需要用户确认的高风险问题。
- 将“必须做”“可选优化”“暂不做”分开，避免范围漂移。
-
任务拆分
- 如果需求较多或包含多个独立需求点，拆成可验收的任务点。
- 每个任务点都要有清晰边界、前置依赖、写入范围、行为契约、验证方式、验收标准和文档产物。
- 优先按依赖顺序和用户价值排序；基础能力、接口契约和测试保护通常先行。
-
串行推进
- 对每个任务点都完整执行一轮：需求澄清 -> 上下文勘察 -> 方案 -> 实现 -> 测试验证 -> 验收 -> 文档落地。
- 当前任务点通过验收后，主控工程师才能下发下一个任务点。
- 如果任务点验收不通过，回到方案或实现修正，并重新验证；禁止跳过失败任务继续后续任务。
-
验收门禁
- 在 Harness Hub 多角色模式或复杂需求文档场景下，验收结论必须由最后负责验收的子代理明确给出，包含通过/不通过、证据、缺口和风险。
- 只有单文件小改动、无须启用多角色模式的简单任务，才可以由主控工程师直接完成验收。
- 必要文档落地后，才视为该任务点完成；文档可包括任务记录、测试结果、PR 描述、发布说明或交接说明。
- 主控工程师最终复核所有任务点的一致性、回归风险和剩余未覆盖项。
子代理协作
当用户明确提出使用子代理、subagent、并行代理、Harness Hub 多角色处理时，采用“主控工程师 + 专项子代理”的模式。此模式下，主控工程师默认不做主体编码，只做必要的整合修补。
- 主控工程师：保留需求理解、架构判断、任务分派、接口契约、变更整合、风险取舍和最终交付责任。
- 勘察子代理：并行读取代码、定位同类实现、整理影响范围；适合大型陌生仓库。
- 实现子代理：按明确文件或模块归属完成具体编码、测试补齐和局部验证；适合可拆分的功能实现或 bug 修复。
- 验证子代理：并行运行测试、复现失败、分析日志；适合测试矩阵或 CI 失败。
- 评审子代理：从 review 视角检查 bug、边界条件、测试缺口；适合高风险改动。
- 文档子代理：整理 PR 描述、发布说明、交接文档；适合交付材料较多的任务。
分派原则：
- 只分派边界清楚、互不冲突、能独立产出结果的任务。
- 主控工程师先定义模块边界、接口契约、验收标准，再让实现子代理编码。
- 不把当前关键路径上的阻塞决策交给子代理等待。
- 不让多个子代理编辑同一文件区域；需要写代码时明确文件归属。
- 每个子代理任务都必须写清：目标、权限、范围、契约、验证和产出。
- 子代理结果必须由主控工程师复核、整合和验证，不能直接替代最终判断。
项目记忆
复杂任务的记忆应跟随项目目录：
plans/<task-slug>.md：背景、目标、非目标、影响范围、任务拆解、验证计划。handoffs/<task-slug>.md：完成状态、关键文件、决策记录、验证结果、剩余风险。
如果项目尚无这些目录，可用 scripts/harness-new-plan.sh <task-slug> 和 scripts/harness-new-handoff.sh <task-slug> 生成。
下班前 Spec 到次日验收
推荐节奏：
- 人工下班前写需求设计 Spec：背景、目标、非目标、用户路径、约束、验收标准和风险。
- CLI coding agent 读取 Spec 和项目上下文，生成计划文件并拆成可验收任务点。
- CLI coding agent 实现后运行验证矩阵，生成交接和验收草稿。
- 第二天人工 double check：重点看需求理解、范围控制、验证证据、未覆盖风险和交接质量。
参考资料
- 需要面向用户解释如何使用这个 skill、触发方式、常见场景和完整流程时，读取
references/usage-guide.md。
- 需要生成技术方案、任务拆解、PR 描述、测试计划、发布说明或交接文档时，读取
references/templates.md。
交付原则
- 工程优先：可运行、可测试、可维护比形式化文档更重要。
- 上下文优先：先读代码再判断，避免凭空设计。
- 风险显性：把假设、未验证点、兼容性影响说清楚。
- 闭环优先：默认做到实现与验证完成，再给用户简洁结论。
- 验收优先：复杂任务必须留下可复核的验收记录。
