讲得清、人能用、脚本优先

先说结论

我们组现在是按节点往同一条 Workflow 上接东西。不管你是新写了一个 skill，还是新做了一个 node，本质上都是往工作流里加一个节点。对这样的节点，我们有三条硬要求：讲得清、人能用、脚本优先。

这三条不是为了形式上的规范，而是为了同一件事：这个节点在任何时候都有人能接手。作者讲得清，出了问题才有人懂；人能用，Agent 挂掉时才有人兜得住；脚本优先，平时才跑得稳、跑得省。

任何一条不满足，节点就打回去重写。

目录

1. 背景：大家在同一条工作流上接节点

我们组的测试工作已经工作流化了：发现版本、准备环境、读取任务、板端执行、整理结果、发送通知，每一步都是一个节点，节点之间只靠约定好的输入输出衔接。

谁要加一个新流程，或者写了一个 skill 想分享给大家、放进现有工作流，都要以 skill 或 node 的形式提交。这两者没有实质区别：都是一段有明确输入输出、会被别人和 Agent 反复调用的能力。

AI Coding 让写一个节点变得很快。快本身不是问题，问题是作者可能完全不理解自己交上来的东西。个人项目里，这只是自己的风险；放进共享工作流，一个节点出事，整条流程就停了。

所以我们在节点准入这里立了三条原则。

2. 原则一：自己写的东西，自己要讲得清

提交节点时，作者要在组会或者其他场合给大家讲一遍：它做什么、内部怎么走、输入输出是什么、哪里可能出问题。

这一步真正的目的，不是让听的人听懂，而是让讲的人自己理清楚。道理和费曼学习法、小黄鸭调试法一样：讲不出来的地方，往往就是没想清楚的地方。

现在不少人是纯氛围编程（Vibe Coding）的写法：AI 生成、跑通、提交，对里面的东西一无所知。这样的节点一旦接进工作流出了问题，唯一的办法就是再开一个 AI，让它从头去读代码。

如果对提交的东西完全没有约束，常见的问题有两类：

  • 兼容性差。我们的节点至少要在 Windows 和 Linux 两个平台上都能跑，放任不管时，路径、编码、命令差异往往没人考虑。
  • 内部逻辑乱。流程层层嵌套、职责不清，作者自己也说不出某一步为什么存在。

归结起来就一句话：自己写出来的东西，一定要能给别人说明白。

3. 原则二：Agent 能用，人也要能用

节点不能只满足「让 Agent 走一遍没问题」，它在人手里也必须能正常用。

原因很直接：Agent 会挂。可能是后面的模型出了问题，也可能是 Agent 框架本身出了问题。这时候不能当甩手掌柜，得有人马上接得上。

具体要求有两条：

  • 能力要封装好，最好做成 CLI，一行命令就能跑，参数尽量少。
  • 说明文件要写得精炼、简洁、易懂，人一眼就能看明白。

一般来说，人能看明白的说明，Agent 也能看明白。反过来却不一定：Agent 能硬啃下来的复杂调用方式，人在紧急时刻往往根本上不了手。

4. 原则三：脚本优先

执行方式的优先级是：脚本 > Agent > 人。

一个节点如果脚本能跑，Agent 一般也能跑。但一旦交给 Agent，灵活性和不确定性是一起来的：这次这么做，下次可能那么做，出错的概率也不算小。而且 Agent 更费钱，也更费时间。流程足够固定时，用脚本代替一定是最优解。

执行方式 优点 代价 适合
脚本 确定、快、便宜 要求流程固定 输入输出明确、可以重复的步骤
Agent 灵活，能应对变化 不确定、费钱、费时 探索阶段、异常处理
人 能判断、能负责 最慢、最占人力 需要做决定、担责任的环节

这不是说一开始就不能用 Agent。节点刚起步时，很多步骤只能先让 Agent 去做，这没关系。但 Agent 跑通以后，要回头试一试：这一步能不能用脚本、用 CLI 固定下来？哪怕复杂一点，只要能做出来，就把它落地成脚本。

初期用 Agent 探路没问题，但要长期稳定运行，能不用 Agent 的地方就尽量不用。

5. 一个例子：测试执行节点

我们有一套 Agent 驱动的自动化测试工作流，中间最重要的节点是测试任务执行。它分两类：一类是按测试单执行测试用例，一类是按问题单复现问题。

这个大节点内部其实有很多小步骤：从 Jira 拉取这次要执行或复现的任务、准备环境、在开发板上执行，最后整理结果，把报告交给下一个节点。

5.1 不按原则来：做成一个黑盒

最快的做法，是把整个节点交给 Agent，做成一个黑盒。一两天，最多两三天，就能开发出来。代价也很明显：

  • 做的人对里面的框架完全不了解，这违反了原则一。
  • 内部流程复杂，Agent 一旦挂掉，人想介入，会发现还不如从零开始手动做，这违反了原则二。
  • 可从零手动做，又接不上前后节点：不知道任务该怎么取，也没法按下一个节点要的格式正常提交报告。结果就是一个节点出问题，整条工作流跟着废掉。Agent 驱动的节点尤其容易这样。

落到具体步骤上，问题会更细：

  • 拉取 Jira 任务时，Agent 有时现写一段脚本，有时直接调底层的 REST API，有时调用要带一长串参数。它很灵活，但人没法照着做。
  • 输出报告时，让 Agent 手写一份 JSON 很轻松，让人手写就很麻烦。

5.2 按原则来：拆开、封装、脚本化

按三条原则来做，开发时间会长一些，但节点的形态完全不同。

首先是理清结构。作者要给别人讲清楚这个节点，就必须先把它拆成若干小步骤，知道每一步的输入输出。

然后是拉取任务。底层仍然是 Jira 的 REST API，但我们不让 Agent 每次直接去调它，而是在上面封一个 Python 脚本。Agent 用的时候直接调这个脚本，就能知道这次要执行什么任务；人用的时候，同样一行 CLI 命令，拿到同样的结果。人可以无缝顶替 Agent 的位置。

最后是提交报告。同样封成 CLI，只需要填几个参数，比如通过与否、结论是什么，命令就直接生成下一个节点需要的报告，没有人需要手写 JSON。

1
2
3
4
5
6
# 以下命令仅为示意
# 拉取本次要执行的任务
python fetch_tasks.py --ticket TEST-1234

# 提交执行结果，生成交给下一个节点的报告
python submit_report.py --result pass --summary "当前版本已无法复现"

这样一来，Agent 挂了，节点不会挂；节点不挂，整条工作流就不会挂。

对比项 黑盒做法 按原则做法
开发时间 一两天 更长，需要拆分和封装
作者理解 基本不了解内部 能讲清每一步
拉取任务 Agent 现写脚本或直接调 REST API 封装好的脚本，一行命令
提交报告 手写 JSON CLI 填几个参数
Agent 挂掉时 人接不上，整条工作流停摆 人用同样的命令接上，工作流继续

6. 三条原则其实是一件事

三条原则看起来各管各的，其实指向同一件事：节点在任何时候都有人能接手。

  • 原则一保证有人懂：作者理解它，出了问题知道从哪里查。
  • 原则三决定平时谁来跑：能固定下来的交给脚本，稳定又省钱。
  • 原则二决定出事时谁来兜：Agent 挂了，人用同样的 CLI 顶上。

原则二和原则三，很多时候是同一个动作：把一步能力封装成简单的脚本或 CLI，平时 Agent 调它，出事时人调它。反过来，让 Agent 每次直接调底层接口、现写脚本，看起来很灵活，实际上同时违反了这两条。

7. 收个尾

AI Coding 让写一个节点变得很便宜，但要让一个节点在工作流里长期稳定地跑下去，成本并没有跟着降下来。

原则 防住什么 怎么验收
讲得清 作者不懂自己的节点，出事只能让 AI 从头读 能在组会上讲清结构、输入输出和风险
人能用 Agent 挂掉后节点跟着挂，整条工作流停摆 人能用一行 CLI 顶替 Agent 完成这个节点
脚本优先 Agent 带来的不确定性、成本和耗时 已经固定的步骤都落地成了脚本

这三条是我们组内一直在用的底线。写得快不算本事，写出来的东西能被别人接得住，才算真正交付了。