我前一阵子判断错了一件事。
我以为把 AGENTS.md 写好,Agent 进了仓库就能干活。AGENTS.md 是放在仓库根目录、专门写给 Agent 看的说明书。后来我才发现,我写的那份只管得了开头。
真正让我卡住的是另一个问题:今天活干到一半停了,明天换一个 Agent 来,它能接着干吗?
一、开得了头,还得接得上
AGENTS.md 当然重要。没有它,Agent 一进来就得先猜:这个项目是干什么的,先读哪份文档,测试怎么跑,做到什么程度才算完,哪些文件是真规矩,哪些只是旧草稿。猜错一次,后面就全歪了。
有了它,Agent 知道先看什么、用什么命令、什么不能碰,开头算是顺了。
可第二天换个 Agent 来,它要面对的是另一堆问题:上次做到哪了?为什么当时选了这个方案?哪些路已经试过、走不通?这些 AGENTS.md 里都没有。要是仓库里也找不到,它就只能从头再猜一遍。
二、接力要留下哪几样东西
要让下一个 Agent 接得上,仓库里至少得有几样东西各有各的位置。每样东西回答一个问题。
现在到底是什么状况。 我放在 docs/current-state.md。这里只写验证过的现状,目标、想法、愿景都不往里放。
上次做到哪了。 放在 docs/progress.md。上次做到哪一步、卡在哪、下一步干什么、哪些路已经试过别再试,都写在这里。这一份最管接力。
当初为什么这么做。 放在 docs/decisions.md,也可以按 ADR(架构决策记录,一个决定一份短文档)的格式写。为什么选这个方案、为什么放弃另一个、哪些限制是真的,都记下来,免得它们只是聊天里一闪而过的念头。
哪块功能归哪儿管。 放在 docs/capability-map.md。小仓库不一定要有。可一旦项目分成好几个子项目、好几个部署环境、好几个服务,这份就省不得。不然每来一个新 Agent,都得先把目录翻一遍,弄清楚谁管什么,花的力气不少,产出几乎没有。
反复要做的事怎么做。 放在 .agents/workflows/。启动、验证、回归测试、预览、发布,这些事要是每次都现想一遍,时间就全耗在重新摸清情况上了。
做出来的东西放哪。 放在 artifacts/。截图、性能测试结果、执行记录、临时报告、调试输出,要是没有固定的位置,很容易又掉回聊天窗口里,换一轮对话基本就找不着了。
文件名可以按各自仓库的习惯来,要紧的是每一份写什么、不写什么。现状、进度、决策搅在一起写,下一个 Agent 很容易分不清哪句是验证过的事实,哪句只是上次的猜测。
这些东西要是不在仓库里,就只能留在聊天记录里、留在人脑子里,或者干脆丢了。到那一步,想保住上下文就只剩两个办法:指望模型自己记住,或者指望操作的人自己记住。两个都靠不太住。
三、怎么知道接上了
所以检验的办法要硬一点,光看 AGENTS.md 写得清不清楚不够。
找一个全新的 Agent,不给它看上一轮的聊天记录,给它 30 秒到 2 分钟,让它只看仓库,回答这几个问题:先读什么,现在真实的状态是什么,上一轮做到哪,下一步该做什么,某个功能该去哪个模块改,用什么命令验证改对了没有。
答得上来,就算接上了。答不上来,这个仓库就还得接着收拾。
四、新项目、旧项目都一样
这件事不只适合整理旧仓库,新项目一开始就可以这么做。
旧项目要改造:把散落的几份规则文件收成一个入口,把搅在一起的现状、进度、决策拆开,补上进度、决策、工件和流程的固定位置,让”昨天做到哪”不再只存在聊天记录里。
新项目要提前留好位置:一开始就把 AGENTS.md 和”什么才算做完”的规矩立住,一开始就定好现状、进度、决策、工件放在哪;如果有好几个子项目,也一开始就定好模块分工写在哪,流程也一开始就有入口,别等到第二周再补。
这样做,你用不着训练哪个 Agent 去记住项目,项目自己就把该记的都记下了。
我把这些整理成了一段可以直接发给 Agent 的提示词,放在文末附录里,复制过去就能让它照着改造你的仓库。
结语
回到开头那个问题:明天换个 Agent,它能接着干吗?
能。前提是今天停下来的时候,现状、进度、决策、工件和流程都已经写进了仓库,每样都在该在的地方。Agent 一轮一轮地换,活儿留在仓库里,谁来都能从上次停下的地方接着往下做。
附录:可以直接复制给 Agent 的提示词
如果你不想先手工建 skill 文件,可以直接把下面这段提示词发给 Agent。
你现在的任务不是实现某个具体功能,而是把当前项目改造成一个 AI-Friendly workspace,使后续 Agent 可以在这里持续迭代、持续接力,而且不依赖上一轮聊天记录也不会丢失关键上下文。
目标:
1. 建立一个可信的 canonical repo entrypoint,默认是根目录 `AGENTS.md`
2. 把 `CLAUDE.md`、Cursor 规则,以及已有仓库里的其他兼容入口压成薄适配层,而不是多份并行规则体
3. 把 durable context 沉淀到 workspace,而不是沉淀在聊天历史里
4. 明确 execution contract,让 Agent 不能早停、不能把检查当验证、不能只做分析不落地
5. 给重复启动、验证、发布、恢复动作建立清晰 workflow 入口
你需要优先把项目变成一个可持续接力的 workspace,而不只是“让 Agent 看得懂一点”。
工作原则:
- workspace 是 continuity 的载体,不要把 continuity 主要放在 chat history 里
- 一个 repo 最好只有一个 canonical 规则入口,默认使用 `AGENTS.md`
- 当前现实、目标设计、运行中进度、历史决策、生成工件,必须分开落点
- 多子项目或多边界 repo,应该把 `capability-map` 当默认 practice,而不是可有可无的注释
- 能复用现有文件就复用,不要盲目新建平行文档
- 如果 repo 已有更强的命名约定,可以保留,但必须保证 truth surfaces 清晰
- 不要停在分析;只要能直接改进 repo,就直接改
请按下面流程执行:
1. 审计项目入口与现有 truth surfaces
- 找出根目录及关键子目录下的 `AGENTS.md`、`Agent.md`、`CLAUDE.md`、`.cursor/rules/`、README、架构文档、进度文档、ADR、workflow 文档、artifact 目录
- 判断哪些文件是 canonical,哪些重复、漂移或互相冲突
- 判断当前 continuity 是否主要依赖聊天记录而不是 workspace 文件
2. 选择 canonical entrypoint
- 默认优先根目录 `AGENTS.md`
- 如果 repo 已深度采用 `Agent.md` 或其他更强约定,可以沿用,但必须把其他入口改成 thin adapters
- 不允许让多个入口文件同时演化为不同版本的项目规则
3. 安装 adapter policy
- 把 `CLAUDE.md`、Cursor 规则,以及非 canonical 的 `Agent.md` / `AGENTS.md` 收敛成薄适配层
- 它们应该指向 canonical entrypoint,而不是各自再写一套完整 repo law
4. 建立或收紧 workspace truth surfaces
- 至少检查这些面是否存在且边界清晰:
- `AGENTS.md` 或等价 canonical entrypoint:操作入口、阅读顺序、bootstrap、execution contract、skill policy
- `docs/current-state.md` 或等价文件:已验证的当前现实
- `docs/progress.md`、`docs/handoff.md` 或等价文件:当前做到哪一步、下一步、已尝试路径、待验证项
- `docs/decisions.md` 或 ADR:重要决策、约束、放弃过的方案及原因
- `artifacts/` 或等价目录:截图、benchmark、trace、报告、生成工件
- `.agents/workflows/` 或等价目录:重复启动、验证、发布、恢复流程
- 如果 repo 有多个子项目、多个部署面或明显 ownership 边界,额外检查 `docs/capability-map.md` 或等价文件是否存在,并确保它能回答模块归属与修改入口
- 如果 repo 已有等价对象,就 tighten;如果没有,就补最小可用版本
5. 分离 truth layers
- 当前现实不能和目标设计混写
- 运行中进度不能和 durable decisions 混写
- 临时推断不能直接伪装成 verified reality
- 生成工件不能散落在聊天里而没有 repo-local landing zone
6. 安装 execution contract
- 明确什么叫 `Verified Done`
- 明确什么叫 `Real Blocker`
- 明确什么叫 `Safety Stop`
- 禁止这些行为:
- 只做分析不落地
- 没验证就宣称完成
- 第一条命令失败就停止,而不继续诊断
- 用代码阅读代替运行验证
7. 添加 workflow entrypoints
- 如果启动、验证、构建、预览、发布、恢复具有重复性,就建立清晰 workflow 文档
- workflow 文档应该是 procedure,不是理论说明
8. 最终验证
- 一个全新的 Agent,在不读取上一轮聊天记录的前提下,是否能在 30 秒到 2 分钟内回答:
- 先读什么
- 当前真实状态是什么
- 上一轮做到哪
- 下一步应该做什么
- 功能 X 应该去哪个模块或子项目修改
- 用什么命令验证修改是否成立
- 如果不能,继续 tighten workspace
输出要求:
1. 直接修改 repo,而不是只给建议
2. 优先输出:
- 更新后的 canonical entrypoint
- thin adapter files
- current state / progress / decisions / artifacts / workflows 的最小可用落点
- 对复杂 repo,补充 capability-map 或等价 ownership surface
3. 最后给出简短总结:
- 改了什么
- 验证了什么
- 还有什么未验证
- 为什么现在这个 workspace 比之前更适合 Agent 持续接力
停止条件:
- 只有在 `Verified Done`、`Real Blocker`、`Safety Stop` 三种状态之一时才能停止
如果当前目录不是 repo root,先判断根目录再开始;如果是 monorepo,允许在根入口之外补充少量子目录级 context routing,但不要制造新的规则分叉。
讨论
评论
直接在本站留言交流。
评论正在加载…