第一次使用 Hypo-Workflow：从空项目到跑完一个 Cycle

如果你第一次看到 Hypo-Workflow，最容易误会的一点是：它不是一个帮你后台跑任务的自动化 runner。

真正写代码、跑测试、改文档、做审查的，仍然是你正在使用的 AI Agent，比如 Codex、Claude Code、OpenCode、Cursor。Hypo-Workflow 做的是另一件事：把一个长任务拆成可以规划、可以暂停、可以审查、可以恢复的本地 workflow。它把状态、规则、提示词、报告和日志放进项目里的 .pipeline/，让这些信息不要只活在聊天窗口里。

这篇文章就按第一次使用的节奏来。我们不从概念图开始，也不先讲完整命令表。先带你跑完一轮最小流程：安装入口、选一个低风险任务、初始化、规划、执行、验收。如果中间断了，也知道怎么接回来。

先选你在哪个平台用

Hypo-Workflow 支持多个宿主平台。Codex、Claude Code、OpenCode、Cursor、GitHub Copilot、Trae 都有各自的入口，但它们共享同一套 .pipeline/ 协议。

如果你用 Codex，最直接的方式是把 Hypo-Workflow 安装成 Codex Skill。普通使用可以 clone 到 Codex 的 skills 目录：

git clone https://github.com/HypoxanthineOvO/Hypo-Workflow.git ~/.codex/skills/hypo-workflow

如果你本地已经有一份 Hypo-Workflow checkout，开发或试用时也可以用 symlink：

mkdir -p ~/.codex/skills
ln -sfn /absolute/path/to/Hypo-Workflow ~/.codex/skills/hypo-workflow

其他平台不要照抄这两行。Claude Code、OpenCode、Cursor、Copilot 和 Trae 都有自己的同步方式。你只需要记住一点：安装完成后，在项目里能调用 /hw:init、/hw:plan、/hw:start 这些入口，就可以开始。

第一次别拿大重构练手

第一次使用最重要的建议是：不要一上来就把整个项目重构、数据库迁移、发布脚本、线上配置这种任务丢进去。

先选一个低风险、能回滚、结果容易检查的小任务。例如：

• 给项目补一份 docs/usage.md。
• 把 README 的安装说明整理清楚。
• 给一个已有 CLI 加 --version 输出。
• 给一个小函数补测试。
• 整理一段实验脚本的参数说明。

这些任务不一定酷，但非常适合熟悉 workflow。因为你第一次要学的不是“让 AI 做多大”，而是看清楚 Hypo-Workflow 怎样记录计划、怎样留下报告、怎样在你不满意时进入返工。

开始前最好做两件事。第一，确认项目已经在 git 里，至少你能看见改了哪些文件。第二，告诉 Agent 这次不要做远端发布、不要 push、不要删除数据、不要跑破坏性命令。Hypo-Workflow 本身会强调外部副作用确认，但新手第一轮把边界说清楚，成本很低。

第一步：初始化项目

进入你的项目根目录，然后对 Agent 说：

/hw:init

这一步会让 Hypo-Workflow 扫描当前项目，建立或刷新 .pipeline/ 里的基础文件。你可以把它理解成给项目建一个工作台。这个工作台里会逐渐出现状态、规则、计划、报告、日志和恢复入口。

初始化后，你不需要马上理解 .pipeline/ 里每个文件。先记住几个名字就够了：

• state.yaml：当前执行状态。
• cycle.yaml：当前 Cycle 的边界。
• rules.yaml：项目规则和用户习惯。
• PROGRESS.md：给人看的进度摘要。
• prompts/：拆出来的执行提示。
• reports/：每步做完留下的报告。
• log.yaml：生命周期日志。

这些文件就是 Hypo-Workflow 的本地事实源。以后当上下文断掉、窗口关掉、任务跑到一半停下来，Agent 不是只靠“记忆”接着猜，而是回来读这些文件。

第二步：把任务说成一个具体目标

初始化后，不要马上说“开始干活”。先把目标讲清楚。

一个不太好的说法是：

帮我优化一下这个项目。

这个目标太大，验收方式也不清楚。Agent 可能改一堆东西，最后你也不知道该不该接受。

更适合第一次使用的说法是：

我想用 Hypo-Workflow 跑一个低风险任务：给这个项目补一份 docs/usage.md。
内容包括安装方式、常用命令、一个最小使用例子和常见问题。
不要改业务代码，不要 push，不要发布。完成后我希望能通过 Markdown lint 或至少人工检查标题层级和链接。

这段话里有目标，有范围，有禁止事项，也有验收口径。Hypo-Workflow 后面的规划会围绕这些信息展开。

第三步：进入 Plan，不要跳过它的问题

接下来调用：

/hw:plan

很多人会把 Plan 理解成“让 AI 列个步骤”。在 Hypo-Workflow 里，Plan 更重要的部分其实是提问。它会先确认任务边界：这次改哪些文件？哪些文件不能碰？怎么验收？是否需要测试？是否允许调用 Subagent？是否有远端写操作？中间哪些地方需要停下来让你确认？

如果它问你问题，不要嫌烦。第一次使用时，问题越具体，后面越少返工。

你可以这样回答：

这次只允许新增或修改 docs/usage.md 和 README.md 中指向 usage 的一行链接。
不要修改源码、测试和 package 配置。
验收方式：检查文档结构、命令是否和 package.json 一致、README 链接是否有效。
如果发现实际命令不确定，先停下来问我，不要编。

Plan 完成后，Hypo-Workflow 会把工作拆成可以执行的 prompt 或 milestone。对新手来说，这一步的意义是：任务不再只是聊天框里的一段愿望，而是落到了 .pipeline/ 的文件里。

第四步：开始执行

确认计划没问题后，调用：

/hw:start

这时宿主 Agent 会按计划开始工作。它可能会读文件、编辑文件、运行检查命令，也可能在遇到不确定项时停下来问你。你要观察的不是它最后一句“完成了”，而是它有没有留下报告。

做完一个阶段后，去看 .pipeline/reports/。报告通常会说明做了什么、改了哪些文件、运行过什么检查、还有哪些风险或未完成项。这个报告很关键，因为它是以后恢复、审查和复盘的依据。

如果是一个很小的文档任务，可能一个 milestone 就结束了。如果是稍微复杂一点的代码任务，Hypo-Workflow 会按多个 milestone 推进。你不需要每一步都盯着命令表，只要知道：执行不是一口气冲到底，而是按计划留下可检查的阶段结果。

中途断了怎么办

长任务最常见的现实不是失败，而是中断。窗口关了，机器重启了，或者你忙别的去了，第二天才回来。

这时不要让 Agent “凭印象继续”。先问状态：

/hw:status

它会读 .pipeline/，告诉你当前 Cycle 走到哪一步、最近报告是什么、下一步建议是什么。如果确认要继续，再调用：

/hw:resume

resume 的意义不只是“接着干”。它会尽量从本地状态、报告、日志和 continuation 线索里恢复上下文。这样做的好处是，你不用重新把任务目标、禁止事项、验收方式再复制一遍。

这也是 Hypo-Workflow 和普通聊天式协作差别最大的地方之一。普通聊天断了，经常只能靠你重新描述；workflow 断了，应该能从文件里接回现场。

做完后不要急着接受

任务完成后，用：

/hw:accept

accept 不是一句礼貌性的“好的”。它是验收 gate。Hypo-Workflow 会检查当前任务有没有留下必要证据，报告是否完整，测试或检查是否跑过，worker evidence 是否满足当前配置。如果有 Subagent 或 worker separation，它还会关心角色证据、身份碰撞、生命周期和降级记录。

第一次使用时，你不一定会碰到完整的 Subagent 审计链路，但你至少会感受到一件事：完成不是模型自己宣布的，而是要过一个本地验收口。

如果你不满意，不要手动把流程糊过去。直接打回：

/hw:reject

然后给具体反馈：

文档里安装命令没有和 package.json 对齐。
常见问题部分太空泛。
请只修改 docs/usage.md，不要再动 README。

打回不是失败。它的价值是把你的反馈变成下一轮返工的输入，而不是散在聊天记录里。后面再执行时，Agent 能看到这次为什么没过。

你很快会用到的三个分支

跑完第一轮之后，可以再认识几个常用入口。

第一个是 /hw:explain。当你想问“这个文件为什么这样设计”“刚才为什么改了这个配置”“某个命令到底干什么”，可以用它。它的定位是 evidence-first 问答，回答应该引用本地文件证据。证据不足时，它应该说清楚 unknowns，而不是编一个听起来合理的解释。

第二个是 /hw:explore。当你只是想探索一个新库、试跑一个外部项目、看看某个方案可不可行，不一定想污染当前主工作流，就可以用 explore。它适合研究生和个人开发者的日常：先试，试完留下探索报告，再决定要不要进入正式 Cycle。

第三个是 /hw:patch。有些小修复不值得打开完整 milestone，比如修一个 typo、补一个链接、调整一条配置说明。Patch 轨道适合处理这种轻量改动，避免主线被小事情打断。

一个完整的新手路径

把上面的内容压成一条路径，大概是这样：

1. 安装 Hypo-Workflow 到你的宿主平台。
2. 进入一个低风险项目，确认 git 状态干净或至少知道当前改动。
3. 调用 /hw:init。
4. 说明一个小任务，写清楚范围、禁止事项和验收方式。
5. 调用 /hw:plan，认真回答它的问题。
6. 确认计划后调用 /hw:start。
7. 看产出文件，也看 .pipeline/reports/ 里的报告。
8. 中断后先 /hw:status，再 /hw:resume。
9. 满意就 /hw:accept，不满意就 /hw:reject 并给具体反馈。

第一次只要跑通这条线，就已经够了。你会知道 .pipeline/ 不是装饰，Plan 不是形式，Report 不是总结废话，Accept 也不是一句“看起来可以”。这些东西连起来，才是把 AI Agent 长任务从一次性聊天变成本地 workflow 的关键。

新手最容易踩的坑

第一个坑是任务太大。你说“重构整个项目架构”，Plan 再认真也很难一次拆得足够稳。先从一篇文档、一个小功能、一个明确 bug 开始。

第二个坑是验收口径太虚。比如“优化体验”“提高质量”“让代码更优雅”，这些说法都需要继续追问。更好的表达是“新增哪个入口”“哪些测试必须通过”“哪些文件不能改”“什么现象算修好”。

第三个坑是跳过报告。很多人只看最终文件，不看 .pipeline/reports/。但过几天你真正需要的，往往就是报告里的依据：当时为什么这么改、跑过什么检查、还有什么风险。

第四个坑是把 Hypo-Workflow 当成全自动工具。它不是。它更像一个放在 Agent 外面的工作台。你仍然要判断计划是否合理，仍然要确认外部副作用，仍然要看验收结果。区别在于，这些判断会被放进本地文件，而不是随着聊天窗口一起消失。

如果你是第一次用，我建议第一周只练三件事：用 /hw:plan 把目标说清楚，用 /hw:resume 从中断里接回来，用 /hw:accept 或 /hw:reject 明确验收。等这三件事顺手之后，再去碰 Subagent、Rules、Feature Queue、PR/MR、Release 这些更复杂的能力。

真正用熟以后，Hypo-Workflow 带来的变化不是“AI 突然变聪明了”。更准确地说，是你不再每次都从聊天框里重新解释项目，不再靠模型口头保证任务完成，也不再在中断后猜上次做到哪里。该记住的东西，让 .pipeline/ 记住；该停下来的地方，让 Gate 停下来；该返工的地方，用 Reject 把反馈写进下一轮。

这就是第一次使用 Hypo-Workflow 最值得跑通的东西。