← 文章Articles
文章Articles · 002

写给 agent 的工序A process written for agents

从提需求到复盘的一串 skillA chain of skills from request to retro

2026.10.26 · #002

Matt Pocock 把一份需求从提出到复盘写成一串 skill,每一步写明 agent 交出什么、人在哪里接手。Matt Pocock turns a feature, from request to retro, into a chain of skills. Each step says what the agent hands over and where a person takes over.

Full text · in Chinese

Matt Pocock 是 TypeScript 课程 Total TypeScript 的作者,在 Vercel 工作过,后来转去全职教人用 AI 做工程。他用 Claude Code、Codex 写代码时,总看到 agent 在同几处出错,比如没弄懂他要什么、写出来的代码跑不通。他把修这些毛病的办法写成一套 skill,放在 GitHub 的 mattpocock/skills 仓库里,截至 2026 年 10 月 26 日约有 30 万个 star。

10 月 5 日他发了一段视频,介绍 1.3 版新收进的 implement-spec、pr、retro 三个 skill。先看这套 skill 的全局,再顺着主线一步步看。


0、全局 · Matt 的工程流程

1.3 版的仓库里有二十多个 skill,最要紧的是一条主线:一份需求从这头进去,那头出来一份人可以审的改动。

mattpocock/skills 流程地图:从提需求到复盘的主线、接报告和查故障两条旁路、回到下一轮的回边
mattpocock/skills 流程地图

主线从你自己有个想法开始,旁边还有两种常碰到的情况:有人报来 bug、提来需求,整理好以后直接进实现那一步;代码出了问题,先查出原因修好,再接到复盘。

复盘是这条线的最后一步,也是它绕回来的地方。retro 列出改进建议,人挑过、改了仓库,下一轮的 agent 就在更好的环境里开工。下面顺着主线一步步看,最后看这两种情况。

1、提需求 · grill-with-docs

Matt 在 README 里说,软件开发里最常见的失败是没对上:你以为对方懂了你要什么,看到做出来的东西,才发现他完全没懂。人和 agent 之间也一样。他说 grill 这一组 skill 最受欢迎。

grill-with-docs 让 agent 在动手之前变成提问的一方。它把要做的事摊成一棵决策树,一个决定下面分出跟它有关的下一层决定;每一轮把眼下就能问的问题一次问完,每题附上它推荐的答案,等人答完再问下一轮。能查到的事实它自己去查,要做决定的事交给人。每个分叉都问清楚,人确认双方想的是一回事,它才动手。

问的过程中,人用的词和项目的术语表对不上,它当场指出来;词说得含糊,它提一个准确的叫法。叫法一定下来,就当场写进这份术语表 GLOSSARY.md,不攒到最后,后面几步的 agent 都照着这份术语表说话。

2、写 spec、拆工单 · to-spec · to-tickets

这一步只在活要跨好几次对话时才走,一次对话做得完的,直接进实现。它要做到的是:新对话里的 agent 哪怕什么都不记得,读完这些文件也能接着干。

to-spec 把前面已经聊清楚的东西整理成一份需求文档(spec),不再重新问一遍,只记已经定下的事,人没定过的要求不能自己加进去。to-tickets 再把它切成一张张工单。切法有讲究:每张工单围绕一个能单独演示或验证的小功能,把它要动的数据库、接口、界面和测试都放进这一张里,大小控制在一次全新的对话里做得完;每张还写明要等哪几张做完才能开工。

to-spec 动笔前,会先问人功能从哪个接口、哪一层开始测;to-tickets 把拆法列成清单拿给人看,粗细合不合适、先后对不对,一直改到人认可,工单才发出去。

3、任务实现 · implement / implement-spec

一份需求拆成好几张工单以后,看起来最直接的推进办法,是人自己当 for 循环:让 agent 做第一张,等它做完,清空上下文,再让它做第二张;再等,再清空,再做第三张。Matt 觉得这样根本撑不下去。工单少、一次做一张的时候,用 implement 就够了;一整份 spec 的工单,交给 implement-spec。

implement-spec 拿着上一步认可过的工单,把这个循环接了过去。不依赖其他工单的,implement-spec 同时派给几个子 agent 去做,做完的改动都合到同一条分支上;一张工单要等的那几张都做完了,它再开工。

人不用再一张张派活、等结果、记着哪张能开工,剩下两件事:拆工单时把谁先谁后、几张工单共用的名字和接口想清楚;最后把合到一起的那条分支审一遍。Matt 自己更推荐写一个固定脚本来跑这个循环,更稳也更便宜,implement-spec 是给还没把脚本调顺的人用的。

4、agent 审 · code-review

implement 做完一张工单、implement-spec 做完整条分支,都会先让 Matt 的 code-review 审一遍,再往下走。

code-review 从两个方向各审一次:一边看代码是不是按这个仓库的规矩写的,一边看它做的是不是需求要的东西。两边各由一个子 agent 去审,谁也看不到对方的思路,报告也分开写,各自列出最严重的问题,不合成一个总评。找不到 spec 的时候,第二个方向就跳过,报告里写明没有 spec。单独跑时,两份报告交给人;在 implement-spec 里,审出的问题直接交给一个子 agent 去修,人最后审的是修完后的那条分支。

说明页给的理由是,一份改动可能一边过关、一边不过关:规矩全守了,做出来的却不是要的东西;或者需求全做到了,写法却坏了仓库的规矩。两边合成一个总评,过关的那一边会把不过关的那一边盖住。

5、代码交审 · pr

agent 说做完了,审的人要决定这次改动能不能合进主干。Matt 觉得,这仍是代码进主干最卡的一关。pr 这个 skill 给 PR 正文定了一个模板,三块各回答一个问题。

① 改了什么。Summary 用一张最小的图讲清改动,伪代码、调用树都行,这套做法几乎逐字来自 Dex Horthy 的 show-me。

② 真的能用吗。Evidence 摆出改前改后的实际运行结果,界面改动放截图,其他改动放一个原来失败、现在通过的测试。Matt 发现,一要证据,agent 往往会多跑一次测试、多截一张图。

③ 出了错能不能撤回。Merge Danger 写明改坏了能不能退回来、会波及多大范围。它把能不能合,从审的人心里的一种感觉,变成一句写明的、可以反驳的话:退得回来、影响小的,扫一眼就行;退不回来的,要慢慢读。

这一块是写改动的 agent 自己判的,它最容易写的偏偏是“退得回来、影响小”,所以 pr 的说明页提醒,这一行最该仔细核对。

6、任务复盘 · retro

Matt 说,1.3 版里 retro 是他在社交平台上看到反响最热烈的一个,他自己用着也觉得威力很大。一段工作做完,retro 回头翻这次会话的记录,把 agent 自己没提的麻烦找出来:找一个文件绕了好几圈,犯了一个检查本该拦住的错。Matt 的看法是,agent 很少主动说这些,凭着坚持,功能往往还是做出来了,同样的麻烦下次还会再来。

retro 找的是仓库的毛病,代码一行不动。Matt 在自己的仓库上跑过,其中一条建议是:仓库里明明有现成的检查脚本,却没有任何东西去跑它,该加一条 CI 流水线。这条改了,那个检查脚本每次推代码都会自动跑,不用等人想起来。

这些都只是建议,改哪条由人挑。Matt 劝别让 agent 自己按建议去改:没人挑就照着改,它会一直找到误报、一直去修,最后把仓库带偏。

7、接报告与查故障 · triage、diagnosing-bugs

主线从你自己有个想法开始。实际干活还常碰到两种情况:有人报来一个 bug,或者提来一个需求,要先弄清值不值得做;代码出了问题,要先查出原因。两件事也可能接连发生,别人报来的 bug 确认要修以后,照样得查原因。Matt 给这两件事各写了一个 skill,处理完再接回主线。

triage 只管别人报来的 bug、需求和外部 PR。它先确认这件事是真的、值得做,bug 要照报告里的步骤重现一遍,再给出处理建议:写成 agent 能直接开工的说明,回头问报告人,或者写明理由关掉。人点了头它才照办,写成说明的那些,直接进任务实现(第 3 节)。

diagnosing-bugs 对付难修的 bug:一眼看不出原因的、时有时无的、以前好好的,后来不知哪次改动弄坏的。它先做出一个几秒内就能稳定重现这个 bug 的命令,有了它才准开始猜原因,Matt 说这一步做对了,bug 就解决了九成。修好以后,人可以在同一次会话里接着再跑一次 retro(第 6 节)。


Matt 在 README 的结尾写,软件工程的基本功比以往任何时候都要紧,这些 skill 是他把基本功整理成一套可重复做法的尝试。

无论模型能力多强,真正生产级别的软件工程还是需要一些特定的 skill 经验。内容生成、最近很火的视频制作也一样,要写下来的,是一整套流程,以及人在哪一步接手的约束。

Claude Code、Codex、Kiro 这些工具之间的差别会越来越小,行业里攒下的经验,尤其是管流程的那一部分,反而会越来越有用。

工具会越来越像,差别在写下来的流程里。


延伸阅读

在这里看Find it on

扫码关注公众号Scan to follow on WeChat

公众号只能扫码关注,搜不到,也不能从链接直达。The WeChat account can only be followed by scanning this code.