Tool as Agent Harness

AI 写代码已经很好，但仍然没解决的问题是：让 Agent 把一个真实任务一路做到 done，做完再从队列里领下一个------整个过程不需要人守在每一步。

前半个问题最近有个说法叫 Code as Agent Harness：让代码仓库本身成为 Coding Agent 工作机制的一部分。合理的 repo 结构、清晰的文档、确定性的构建和测试命令，都是为了让 Agent 单独改一处代码时更安全。

但 repo 不够。repo 告诉 Agent 怎么改 ，却不会记住任务当前进行到哪一步 、离完成还差哪些条件 、五个并行的 Agent 各自在做什么 。这件事要交给 Agent 之外的一个工具来做------相当于给 Agent 外挂一个状态机。本文讲的就是这个工具。我做了一个很简单的实现 taskline，用它跑两层循环：做完单个任务（L1），和清空任务队列（L2）。

为什么需要一个工具，而不只是 repo

Coding Agent 有几个结构性弱点，靠提示词是补不上的：

上下文有限。 多轮工具调用后，窗口被琐碎信息填满，触发 compaction 又会把线索丢掉，Agent 忘了自己已经试过什么、为什么失败。
模型会漂移。 完全靠它自己判断，它会在真正完成之前就觉得"差不多了"。
自我验证不可靠。 Agent 给自己打分，不是一个可信的信号。
并行会冲突。 多个 Agent 指向同一个队列，会重复领同一个任务，互相覆盖代码。

这几件事本质上都是状态问题，解法也是同一个：把状态从 Agent 的脑子里搬出来，放进一个 Agent 能读写的工具里。工具持久化"什么做完了、什么在进行、什么失败了"；用检查而不是感觉去卡准出条件；把任务所有权发出去，Agent 卡住了再收回来。相当于给 Agent 一个外置状态机------一个 harness。

先约定几个词，方便后面表述：

任务：一个有明确目标和验收标准的工作单元，可能是 feature、bug、性能优化或文档改动。
任务队列：正式开工前，按优先级汇总排序好的一批任务。
L1 ：把一个任务走完整个生命周期到 done 的循环。
L2 ：不断从队列里领下一个任务，直到清空的循环。

L1 · 做完一个任务

一个任务会走一条固定的生命周期，每个阶段都有准出条件------满足才能进入下一阶段，不满足就退回前面的阶段。

任务生命周期与准出条件

taskline 给模型一个 CLI 和一个 taskline-management skill，要求它按这条生命周期走：做这个阶段的事、交这个阶段的东西、满足准出条件、再往前走。

阶段	交付物	准出条件
pending	暂存态：还没准备好的想法、未来任务，或因等待信息／判断／外部条件而挂起的任务	阻塞解除、上下文补齐后 → 未启动的任务进 `start`，进行中的任务回到能继续的阶段
start	原子认领任务（`task next --claim`），同步 `main`，建独立分支，确认工作区干净	任务已被当前 Agent 认领，基线和分支就绪 → `spec`
spec	`Spec` 文档：需求、范围、非目标、验收标准，选定方案 + 架构复核，IDL/API，实现计划，测试用例	产品契约无阻塞性歧义、方案符合架构、`Spec` 写入 taskline → `dev`
dev	测试优先的实现 + `Dev Notes`（做了什么、遇到什么问题、相对原方案的调整及原因）	功能实现、相关测试通过、本地可完整验证、`Dev Notes` 已更新 → `test`
test	受影响范围内完整的单测/模块/E2E/浏览器检查，自我 Code Review，`Test Report`；提交、推送、创建并绑定真实 PR	所有检查通过、`Test Report` 已记录、有效 PR 已绑定任务 → `review`
review	等待 CI + 至少一次人工或 Bot Review；处理所有评论；合并 PR；`Review Report`	≥1 次已发布的 Review、评论均已处理，且服务端确认 CI 成功（或未配置）、Review Thread 已处理、PR 已合并 → `done`
done	任务完成并留下完整证据；同步本地 `main`，清理开发分支	无

重点不在于具体这七个阶段，而在于准出条件是被强制的，不是建议 。spec/dev/test/review 的工作要求由 skill 约束；review → done 这道门由 taskline 服务端校验：没有有效 PR、没合并、Review Thread 没处理、CI 没过------任务就是关不掉。一个只是嘴上说"完成了"、拿不出证据的 Agent，根本没法往前走。

taskline 已完成任务详情

状态不只单向前进。test、review 或 CI 发现真实缺陷时，任务退回 dev，修好再重新进 test。对只改单个文件、不影响外部行为、也不引入测试脚手架或新依赖的机械变更，可以跳过独立的 spec，但不能跳过测试、PR、Review、CI、合并这些交付证据。

一个已完成的任务会保留认领信息、阶段文档、PR 和依赖关系。这些结构化记录一物两用：既是 Agent 恢复上下文的外部记忆 ，也是任务能一路推进的交付证据。

L2 · 清空队列

L1 把一个任务做完。L2 要做的是让一个------或几个------Agent 不断领下一个，直到队列清空。

把两层的职责分清楚：L1 管一个任务内部的阶段、交付物和准出条件；L2 管任务之间的可执行性、依赖、优先级、所有权和租约。

四个问题，以及工具对每个问题的回答：

全局状态要能在重启后恢复。 任务一多，就不能靠某个 Agent 的上下文记住什么做完了。→ 把状态、文档和操作记录存成任意 Agent 都能读回来接着做的结构化数据。
Agent 要知道下一步做什么。 任务之间有依赖和优先级。→ 显式记录，只把当前满足条件的任务放进可执行队列。
并行的 Agent 不能冲突。 → 通过原子认领 确定所有权，每个 Agent 有独立工作区，互不覆盖。
异常要能恢复。 Agent 可能崩溃或长时间卡住。→ 给所有权设租约：正常工作时续期，异常中断后服务端释放，别人重新认领。

taskline 任务依赖图

这正是面向 Agent 的工具和普通项目管理工具的区别。普通工具帮人看任务、协调分工。面向 Agent 的工具要可靠地回答机器的问题：现在哪个任务可执行、谁拥有它、所有权什么时候失效、进入下一阶段需要什么证据、中断后由谁继续。它管的不只是任务列表，而是一套 Agent 可以照着执行的并发和生命周期语义。

taskline 就是把这些东西------状态、依赖、优先级、认领、租约、交付物、准出条件------变成 Agent 通过 CLI 操作的结构化契约。Agent 按 skill 的描述：

查询队列，认领下一个可执行任务；
用 L1 生命周期跑完，把交付物和验证结果写回任务；
再查询、再认领；
没有可执行任务时结束本轮，报告队列是清空了还是仍有阻塞。

用 /goal、定时任务或任何持续执行机制触发这个 skill，循环就自己转起来了。

taskline 任务看板

关于多 Agent 并行：太多会难以管理。目前对我比较合理的是三个工作区、三个 Agent。可以选其中一个作为主 Agent------日常沟通产品和技术方向、更新任务------另外两个并行干活。

需要搭什么

如果想复现这套东西，工具需要提供：

结构化的任务状态和附件，让 Agent 在任何重启或 compaction 之后都能感知当前阶段和上下文。
显式的依赖和优先级，让只有满足条件的任务可执行，且执行顺序确定。
原子认领 + 租约，让所有权无歧义，卡住时自动释放。
为并行 Agent 提供相互隔离的工作区。
可检索的操作记录，方便排查和复盘。
一个 CLI，用于认领、查看、维护任务、附件、依赖和记录。
一个 skill，让 Agent 理解统一的生命周期，并用 CLI 驱动整个流程。
一个停止条件：没有可执行任务时结束本轮，并报告队列已清空还是仍有阻塞。

taskline 是为我个人日常开发做的一种实现，机制刻意做得简单固定，不一定适合所有项目。重点不是 taskline，而是这套原则。你可以复用它------扩展你已有的项目管理工具，或者让 AI 做一个适合自己的版本。（taskline 本身主要通过 Codex 加 taskline 迭代完成，所以它也是它所描述的这套基建的一个现成案例。）

结语

Code as Agent Harness 让单次改动变得安全；Tool as Agent Harness 让一个完整任务变得可靠、一整个队列变得持续。两者的动作是同一个：把 Agent 靠不住、不该由它自己记的状态------任务进行到哪、离完成还差什么、谁拥有什么------搬到 Agent 之外的东西里，由它持久化、由它强制。做好这一步，Agent 就不再需要人守在每一步，只需要人守在边界上。

材料链接

综述 Code as Agent Harness ：arxiv.org/abs/2605.18...
探索、brainstorm、TDD 等开发工作流 Skill------obra/superpowers：github.com/obra/superp...
codebase-design、domain-modeling 等工程 Skill------mattpocock/skills：github.com/mattpocock/...
本文用到的项目看板工具 taskline：github.com/celalnsa/ta...