使用 HiFox 推进产品研发

这篇文档介绍如何把一个产品想法、需求或 Bug，逐步转成可追踪、可指派、可验证的研发工作。它关注的是完整协作流程，而不是首次安装和配置。

如果团队还没有准备好电脑、Runtime、Agent 和代码库，请先完成快速上手。实际执行能力取决于 Agent 的指令和 Skill、所选 Runtime、电脑环境、仓库权限以及任务中提供的上下文。

一条推荐的产品研发链路如下：

记录需求
  → Agent 调研并补全上下文
  → 人工确认范围和验收标准
  → 拆分任务并标明依赖
  → 选择 Agent 或小队
  → 在隔离工作目录中执行
  → 跟踪进展、阻塞和人工请求
  → 执行约定检查并人工验收
  → 用项目、迭代和视图持续管理
  → 按需接入 Jira、禅道、GitHub 和自动化

这是一套推荐实践，不代表每个环节都会默认自动发生。任务范围、产品取舍、权限授权、最终验收、代码合并和发布仍应由团队明确决定。

开始前的准备

在记录第一个需求前，先确认基础环境可以支持后续执行：

  • 已创建合适的空间，并准备好团队需要的任务类型和任务状态；
  • 至少有一个职责明确的 Agent；
  • Agent 选择的电脑在线，并且对应 Runtime 处于可用状态；
  • 代码任务已经配置代码库，电脑也具备访问仓库所需的凭据和工具；
  • 团队反复使用的研发规范、检查清单和交付格式已经按需整理成 Skill。

电脑在线只表示本地服务仍在连接。只有 Agent 所选 Runtime 可用，并且代码、目录、凭据和命令都能访问，任务才具备真正执行的条件。

GitHub 集成和代码库访问也是两件不同的事。GitHub 集成可以关联 PR 和 Issue，但真正执行 clone、读取代码和运行命令的仍是 Agent 所在的电脑。

1. 把原始需求记录成任务

产品研发流程应该从一个团队都能查看的任务开始。可以根据工作性质选择“需求”“Bug”“任务”或团队自定义类型。

任务不必一开始就是完整 PRD，但至少要让后续人员或 Agent 知道：为什么要做、这次做什么、怎样判断完成。

可以使用以下模板：

背景：目标：本次范围：不在本次范围：验收标准：已知限制或待确认问题：相关资料：

记录任务时建议：

  • 标题写明具体目标，避免只写“优化一下”或“处理问题”；
  • 把稳定的背景、范围和验收标准放在任务描述中；
  • 把设计稿、截图、日志、历史任务和外部资料作为附件或链接补充；
  • 把后续讨论、问题和决策过程放在评论中；
  • 如果需求还没有准备好执行，先放在待处理类别，不要因为已经指派 Agent 就立即进入执行阶段。

Agent 不会默认获得团队所有文档、全部历史讨论或任意外部系统的访问权限。需要参考的资料应进入它能够访问的任务上下文；外部链接还要求电脑和 Runtime 具备相应网络和权限。

2. 先让 Agent 调研，不要急着修改

当目标仍然模糊时，先让 Agent 调研现状，再决定实现范围，通常比直接要求修改代码更稳妥。

  • 还没有形成任务时，可以先通过与 Agent 对话整理思路；
  • 已经有任务时，优先在任务中通过评论要求 Agent 调研，让结论与后续执行保留在同一个上下文中。

例如，可以发送：

先不要修改代码。请读取任务描述、相关评论和代码库，说明当前实现、涉及模块、可选方案、风险和依赖、仍需人工确认的问题，并建议可验证的验收标准。每项结论请注明依据。

一次有用的调研结果通常包括：

  1. 当前产品或代码是怎样工作的；
  2. 可能涉及哪些模块、接口和数据；
  3. 有哪些可选方案和主要取舍；
  4. 存在哪些权限、环境、兼容性或依赖风险；
  5. 哪些问题必须由产品、研发或其他成员确认；
  6. 如何拆分工作，以及怎样验证最终结果。

独立 Agent 对话不会自动转成任务，任务内的对话和任务评论也不是同一套记录。需要团队长期共享的结论，应由人员确认后写回任务描述或评论。完整区别见与 Agent 对话。

3. 人工确认范围和执行条件

调研完成后，先设置一个人工确认点。团队需要确认的不只是技术方案，还包括产品取舍、权限要求、依赖和完成条件。

开始执行前，可以检查任务是否已经具备：

  • 明确的用户或业务目标；
  • 本次范围和明确的非目标；
  • 可以判断通过或不通过的验收标准；
  • Agent 能访问的代码、资料和运行环境；
  • 合适的执行者；
  • 已解决或已记录的依赖和风险。

把确认后的稳定结论更新到任务描述，避免关键决策只留在某次私有对话里。仍需讨论的内容可以继续通过评论记录，Agent 提出的问题也可以在原评论话题中回复。

如果任务还没有准备好，保持在待处理类别。确认后再移到待办、进行中或团队配置的其他可执行状态。任务被指派给 Agent 并不代表一定会立即运行；任务状态、Runtime、电脑连接、并发和工作目录都会影响启动。

4. 拆分任务并标明依赖

一个大型需求通常不适合直接交给单个执行者完成。拆分时，优先让每个子任务都能独立指派、独立验证，并产生清晰的交付结果。

常见拆分维度包括：

  • 产品或交互确认；
  • 前端界面和状态处理；
  • 后端接口和数据变更；
  • 数据迁移或兼容处理；
  • 测试、文档和人工验收；
  • 发布前检查或后续观察。

不要只为追求并行而机械切碎工作。如果两个改动必须频繁修改同一组文件、共享尚未确定的接口，或只能一起验证，先处理共同依赖通常更合适。

可以请 Agent 提供拆解建议、子任务草稿和依赖分析，但正式任务结构应由人员确认。父任务用于表达总体目标，子任务用于承载具体执行步骤；两个独立任务之间的阻塞、重复或上下文关系可以通过任务关联表达。

任务关联只保留关系和上下文，不会自动把任务切换到阻塞或完成状态，也不会在前置任务完成后自动启动后续任务。重要依赖还应配合任务状态和评论说明。

如果这些任务共同服务于一个较大的交付目标，可以加入同一个项目；如果需要在固定时间窗口内推进，可以安排进迭代。

5. 选择单个 Agent 或小队

根据工作范围选择执行者：

执行方式适合场景需要注意
单个 Agent范围清楚、职责单一、可以独立完成和验证的任务。Agent 的长期职责写在 Agent 指令中，本次要求仍要写进任务。
小队需要调研、实现、测试、review 和汇总等多个角色协作的工作。小队先启动 Leader，由 Leader 判断是否指派成员，不会默认同时启动所有成员。

无论选择哪一种方式，都应先确认：

  • Agent 或小队的职责与任务匹配；
  • 所需 Skill 和代码库已经配置；
  • 电脑、Runtime 和凭据可用；
  • 验收标准和最终汇报格式已经写清楚；
  • 涉及高风险或不可逆操作时，保留明确的人工确认点。

长期稳定的职责和边界放在 Agent 指令中；只属于本次需求的内容放在任务里；多个 Agent 会复用的流程放进 Skill。完整配置方法见 Agent和小队。

6. 指派任务并使用隔离工作目录

把任务的处理人设置为合适的 Agent 或小队，并将任务移入可执行状态后，HiFox 会尝试启动运行。完整触发条件和状态变化见 Agent 如何执行任务。

对于代码任务，一般建议使用独立临时目录：

任务 A → 独立目录 / Git worktree A → Runtime 执行
任务 B → 独立目录 / Git worktree B → Runtime 执行
任务 C → 独立目录 / Git worktree C → Runtime 执行

这样可以减少多个任务直接写入同一工作区、互相覆盖文件或污染本地状态的情况。但隔离目录不能消除最终集成时的业务冲突、接口冲突、依赖冲突或 Git 合并冲突，团队仍需 review 和整合结果。

如果 Agent 配置为指定已有目录：

  • 任务会复用电脑上的现有代码和工具；
  • 同一个目录通常一次只能运行一个任务；
  • 多个任务需要等待空闲目录，或使用不同的已配置目录；
  • 多个小队成员共用同一目录时，应由 Leader 控制指派顺序，避免同时修改相同文件。

实际并行数量还会受到电脑并发、Agent 最大并发、Runtime provider、网络、磁盘和目录可用性的限制。并行能力应逐步提高，而不是把所有任务一次性启动。

7. 跟踪进展、阻塞和人工请求

执行开始后，从任务详情查看评论、进展、执行记录和必要时的执行转录。团队不需要只依赖某台电脑上的本地终端判断结果。

需要区分两套状态：

  • 任务状态：表示任务生命周期，例如待处理、待办、进行中、待验收、已完成；
  • Agent 工作状态：表示当前运行情况，例如排队、工作中、等待人工回复、等待人工审阅、受阻或失败。

因此，任务可以仍处于进行中，同时 Agent 正在等待人员补充信息。需要人工处理的提醒会进入收件箱，成员应从通知回到原任务补充上下文、回答问题或检查结果。

Agent 可以在任务中汇报修改内容、检查结果、阻塞和建议下一步，但信息完整程度取决于 Runtime 和 Agent 指令。建议明确要求它在遇到问题时写清：

  • 当前缺少什么；
  • 谁或哪种权限可以解决；
  • 是否需要产品或技术决策；
  • 已完成到哪一步；
  • 获得答复后应如何继续。

不要仅用文件数、代码行数或一个百分比代替对实际完成情况的判断。是否接近完成，应结合验收标准、运行结果、未解决风险和人工 review 判断。

8. 执行约定检查并完成人工验收

HiFox 不会固定为每个项目运行同一组检查。团队应该根据任务类型，把需要执行的测试、lint、typecheck、构建、手动页面验证或其他命令写入：

  • 当前任务的验收标准；
  • Agent 的长期指令；
  • 团队复用的 Skill。

要求 Agent 在交付时如实汇报：

  1. 修改了什么，影响范围是什么；
  2. 实际运行了哪些命令；
  3. 哪些检查成功，哪些失败；
  4. 哪些部分没有验证以及原因；
  5. 仍然存在的限制、风险和建议下一步。

人员再根据任务目标 review 代码、测试结果和可见效果。如果结果不符合预期，在原任务评论中补充具体反馈，让 Agent 基于同一个任务上下文继续处理。

完成 Agent 验证不等于自动合并或发布。是否 commit、push、创建或合并 PR、更新任务状态、发布上线以及清理工作目录，应由人员明确决定，或通过团队已经确认的流程显式授权。

如果使用 GitHub，PR 合并也不会自动把 HiFox 任务改为完成状态。需要团队根据实际验收结果更新任务，或另行配置合适的自动化。

9. 用项目、迭代和视图管理持续交付

单个任务解决“这件事怎样执行”，项目、迭代和视图帮助团队管理更长周期的交付。

  • 项目：表示一组任务共同服务的目标，例如一个产品功能、版本或改版计划；
  • 迭代：表示一个固定时间窗口内准备推进的任务范围；
  • 视图：保存任务列表的筛选、分组、排序和显示方式，不会复制任务。

团队可以保存一些常用视图：

  • 待人工确认的需求；
  • Agent 正在执行的任务；
  • Agent 受阻或运行失败的任务；
  • 本迭代等待验收的任务；
  • 当前项目中仍未完成的任务。

任务可以同时属于项目和迭代，再通过不同视图从目标、时间窗口、执行者或状态等角度查看。

项目和迭代中的进度来自关联任务的状态或估算数据，因此团队需要及时更新任务状态。这些指标适合观察范围和流转情况，不应被理解为真实研发完成度的精确测量。

10. 按需接入 Jira、禅道、GitHub 和自动化

当团队已经有外部系统或重复流程时，可以把它们接入这条研发链路，但不要把集成能力与 Agent 的代码访问或默认自动执行混为一谈。

Jira

Jira 集成可以把 Jira issue、epic、状态、评论、附件和关联关系导入或同步到 HiFox。其中：

  • Jira issue 可以成为 HiFox 任务；
  • Jira epic 可以成为 HiFox 项目；
  • 一次性导入和持续同步是不同能力；
  • 双向同步需要显式配置；
  • 并非所有高度自定义的 Jira 字段都会一比一同步。

导入或同步后，仍应为准备执行的任务补充清楚本次目标、范围和验收标准，不要只依赖历史 Jira 上下文。

禅道

禅道集成适用于国内版 HiFox，可将禅道产品线或项目中的工作导入到 HiFox Space，并按需配置后续同步。其中：

  • 导入与后续同步是不同能力；
  • 开启后续同步前，需要完成连接、同步链接和回调配置；
  • 状态和成员映射应在首次导入前确认；
  • 个别禅道对象或字段无法写回时，任务详情会说明限制，不应将其作为可通过重试解决的同步失败。

先以小范围来源验证导入结果和同步边界，再扩大到更多产品线或项目。

GitHub

GitHub 集成适合关联 PR、同步 Issue 和建立任务回链。它不负责让 Agent 所在电脑获得仓库 clone 权限；代码访问仍依赖连接代码库和电脑上的 Git 凭据。

可以按团队约定在 PR 标题、描述或分支中包含任务编号来建立关联。合并 PR 不会自动完成 HiFox 任务，仍需根据验收情况更新任务状态或显式配置自动化。

自动化

HiFox 提供两类不同的自动化能力：

  • 自动化助理：根据时间、任务状态、评论关键词或 Webhook 等触发条件，调用 Agent 或小队处理工作；
  • 自动化工作流：在画布中编排多步流程，并可以使用 Run Agent 等节点。

自动化需要团队配置触发器、执行对象、指令和后续动作，不代表系统默认会自动建任务、拆解、指派或并行执行。自动化工作流中的 Run Agent 当前也不会自动创建任务。

初次启用时，建议从只读总结、分诊、提醒或状态检查等低风险流程开始。对于代码修改、发布或其他高风险操作，优先创建或补充可追踪的任务，让 Agent 在明确上下文中执行，并保留人工确认。

推荐工作流检查清单

在一次需求进入验收前，可以使用下面的清单复核：

  1. 已记录背景、目标、范围、非目标和验收标准；
  2. 已让 Agent 调研，并将稳定结论写回任务；
  3. 产品取舍、权限和待确认问题已经人工确认；
  4. 大任务已经拆成可独立验收的任务，并标明依赖；
  5. 已选择合适的 Agent 或小队；
  6. 代码库、凭据、电脑和 Runtime 可用；
  7. 已选择独立临时目录，或明确接受已有目录的顺序执行限制；
  8. 已写明本任务真正需要运行的检查；
  9. 已查看执行记录、阻塞、失败和未验证部分；
  10. 已完成人工验收，再决定合并、发布和任务状态；
  11. 已把任务归入适当的项目、迭代和视图；
  12. Jira、GitHub 或自动化只在团队明确需要时配置。

完成这条流程后，HiFox 中保留的不只是一次 Agent 输出，而是一条可以被团队共同理解、继续推进和复用的产品研发记录。