如何用 Agent 执行长任务
从 25 小时实验到可复用的 Skill,我如何让 AI 先写文档,再写代码。
一、思考如何执行长任务
订阅了codex 之后,我一直在想怎么能够让他无监督的执行任务,只有在结束的时候我来验证,搜索了之后,这样就不用我问一句他答一句的来实现我的想法
二、文档先行
在项目 docs 目录下生成四份核心文:
1 | Prompt.md # 冻结目标 |
| 文件 | 作用 | 关键内容 |
|---|---|---|
| Prompt.md | 冻结目标 | 目标、非目标、约束、交付物、Done when |
| Plan.md | 里程碑规划 | 可验收的里程碑、验证命令、stop-and-fix 规则 |
| Implement.md | 执行手册 | 主循环、验证命令、代码规则、停止条件 |
| Documentation.md | 状态日志 | 当前状态、决策记录、运行方式、已知问题 |
Prompt.md 的作用是防止 Agent“造出很厉害但错误的东西”。它必须写清楚:做什么、不做什么、硬约束、交付物、以及“Done when”。
一个具体片段:
1 | ## 项目目标 |
Plan.md 把开放式工作切成一个个可独立验收的里程碑。每个里程碑都带验收标准和验证命令。
例如:
1 | ## M4 听力播放器 |
最关键的一条规则是 stop-and-fix:验证失败,先修复,再进入下一里程碑。
Implement.md 是 Agent 的 runbook。它告诉 Codex 每次运行前读什么、主循环怎么走。
一个简化片段:
1 | ## 每次运行前 |
Documentation.md 是共享记忆和审计日志。每完成一个里程碑,就更新当前状态、记录关键决策、更新已知问题、添加变更日志。
例如:
1 | ## 当前状态 |
这四份文档不是启动时的一次性计划,而是持续更新的活文件。长任务的可靠性,来自这种“外化的状态”。
三、问题来了:每次新项目都手动写文档,太累
这套方法有效,但有个明显的痛点:每次做新项目或者实现一个新功能,都要手动生成这四份文档,还要保证结构一致、内容完整。想法很多的人,会被这个流程拖死。
更好的做法是:让 Codex 自己先生成这四份文档,然后按文档执行。
有三种实现方式,从轻到重。
方案一:元提示词
每次把一段固定提示词粘给 Codex。它先以“一次一个问题”的方式澄清需求,然后生成四文档,等你确认后再开始执行。
一个可用的元提示词开头:
1 | 你是一个项目规划专家。我将描述一个项目需求,请你生成完整的项目文档包。 |
优点是简单,不需要配置。缺点是每次都要粘贴,容易遗漏或变形。适合一次性项目。
方案二:AGENTS.md
在仓库根目录放一份 AGENTS.md。Codex 执行任务前会自动读取它。
例如:
1 | # AGENTS.md |
这样你每次只需要说“我要做一个新项目,需求是……”,Codex 就会按规范自动生成文档并执行。适合单个长期项目。
方案三:Skill(推荐)
如果你有很多想法,会反复做新项目,最彻底的方式是把整套流程封装成一个 Codex Skill。
Skill 的本质是:把一套可重复的工作流程,用自然语言加少量脚本固化成 Agent 可读的指令。它和人类组织的 SOP 文档没有本质区别,只是读者从人变成了模型。
文件结构可以是这样:
1 | ~/.codex/skills/docs-bootstrap/ |
SKILL.md 的核心内容:
1 | # docs-bootstrap |
以后你只需要说:
用 docs-bootstrap 做一个新项目:我想做……
Codex 会自动澄清、生成文档、等待确认、按计划执行。
Skill 的优势是跨项目复用、可分发、渐进式披露、Token 效率高。它把“每次手写工作手册”变成了“把工作手册本身变成产品”。
现有的 skill goal-pipeline 就是类似的skill
三、需求澄清:一次只问一个问题
无论是元提示词还是 Skill,需求澄清阶段都要有纪律。
规则可以写死:
一次只问一个问题。
每个问题附上推荐答案和理由。
用户可以用 “y” 确认,或提出修改。
能从仓库推断的事实,不要问用户。
非阻塞的不确定项写入 ASSUMPTIONS.md。
阻塞项立刻停下来问。
实际对话可能像这样:
1 | Codex:第一个问题:这个刷题网站是私有部署,还是公开运营? |
这套规则把“拷问”从风格变成了可重复执行的协议。它确保在写任何代码之前,目标和边界已经对齐。
四、执行循环:计划 → 实现 → 验证 → 修复 → 更新文档
文档生成后,Codex 进入执行循环:
阅读 Prompt.md、Plan.md、Documentation.md
选择 Plan.md 中第一个未完成里程碑
计划最小实现
编辑代码
运行验证命令
修复失败
更新 Documentation.md
进入下一里程碑
每个里程碑都必须有可执行的验证命令,比如:
1 | pnpm lint |
一次实际的执行日志可能像这样:
1 | [M4 听力播放器] |
更严格的做法是让每个任务携带 TDD 契约:先写的失败测试、预期的失败信号、最小通过实现的边界、验证命令。强制垂直切片的 RED → GREEN → REFACTOR,拒绝“加 model”“加 API”这类横向切片。这把质量保证从“事后验证”前移到了“任务定义本身”。
你只需要在两个节点介入:需求澄清阶段和里程碑验收阶段。中间过程由 Codex 按文档自动推进。
五、文档要“活”起来
Documentation.md 不是摆设。每完成一个里程碑,必须更新:
当前状态:当前里程碑、已完成、下一步、阻塞
决策记录:日期、决策、原因
如何运行项目
Demo 流程
已知问题
变更日志
一次更新示例:
1 | ## 当前状态 |
每次修复非平凡 bug 后,记录问题和修复方式。每次新增依赖时,记录依赖名、版本、引入原因。
这样即使你离开几小时,回来只需要读这一份文件,就能恢复全部上下文。长任务的可靠性,来自这种持续的状态外化。
六、关于 Skill 与随机性的思考
Skill 就是自然语言写的 SOP。每个人写的不一样:语言不同,思路不同,描述方式不同。这些差异会实质影响大模型的运行结果。
指令的明确性、结构的清晰度、示例的有无、边界的定义、术语的一致性,都会改变 Agent 的执行路径。同一个 Skill 多次执行,结果也不会完全一样,因为推理是采样的。即使 temperature 设为 0,由于浮点运算和硬件差异,也未必完全可复现。
但这不意味着结果是混乱的。好的 Skill 不追求路径一致,而追求终点合格。它用验证命令、验收标准、里程碑检查点,保证每次输出都落在可接受的范围内。
Skill 有相对好坏,但没有绝对第一。好坏必须绑定到具体优化目标才有客观意义:
| 优化目标 | 更优的 Skill 设计 |
|---|---|
| 长任务不漂移 | 带里程碑验收 + 持续状态日志 |
| 省 Token | 渐进式披露,按需加载 |
| 跨模型可移植 | 不依赖特定模型特性 |
| 减少返工 | 强制 TDD 契约 + 垂直切片 |
| 快速原型 | 轻量元提示词,少文档 |
所以,Skill 的质量不该用“写得好不好”来评价,而该用“在多次执行下的成功率分布”来评价。你可以对同一个 Skill 跑 10 次,看里程碑通过率、漂移次数、返工次数,用数据判断它好不好。
例如:
1 | Skill A:10 次运行,8 次全部里程碑通过,平均返工 1.2 次 |