从 AGENTS.md 到 AI-Friendly Workspace

我前一阵子判断错了一件事。

我以为把 AGENTS.md 写好，agent 进仓库就能干活。后来才发现，它解决的是开场，不是接力。

开场的问题是：它知道先看什么、用什么命令、什么不能碰。接力的问题是：今天停在半路，明天换一个 agent，它还能不能从仓库本身接上，而不是重新猜一遍。

这两件事不是一回事。

AGENTS.md 当然重要。没有它，agent 一进来就会先猜：这个项目是什么，先读哪个文档，测试怎么跑，什么叫 done，哪些文件是真规则，哪些只是旧草稿。猜错一次，后面就都歪了。

但一个项目能不能持续接力，不主要看入口文件，而要看工作区里有没有几样东西真的落下来了：

当前现实写在哪里
现在做到哪一步写在哪里
为什么这么做写在哪里
功能边界和模块归属写在哪里
启动、验证、发布这些重复动作写在哪里
截图、trace、报告这些工件又落在哪里

这些东西如果不在仓库里，就只能在聊天记录里、在人脑里，或者干脆丢了。

所以我现在更愿意把这件事说得直一点：

AGENTS.md 管入口，current-state / progress / decisions / capability-map / workflows / artifacts 管连续性。两层都立住了，workspace 才开始像样。

我想分享的 skill，不该只管入口

如果要给这个 skill 一个工作定义，我觉得它至少该做三件事：

立住一个 canonical AGENTS.md
把进度、决策、工件、模块边界这些该落盘的东西落下来
写清 execution contract 和常用 workflow，别让 agent 每次都临场发挥

如果一个仓库现在还停留在“各种 AI IDE 文件互相打架、规则分散、done 不明确”的阶段，光做第一步就已经很值。

但如果目标是：

让项目变成一个 agent 可以持续迭代、持续接力、持续演化，而且不容易丢上下文的 workspace

那只做第一步还不够。

仓库会“开机”，和仓库能“续跑”，中间差着一整层工作面。

真正缺的不是更多提示词，而是 durable context surfaces

AI-Friendly workspace 说到底是一个结构问题：先有 AGENTS.md，再有一组真正在时间里能留下来的文件和工件。

它至少应该让下面几类东西有明确落点：

repo/
  AGENTS.md
  docs/
    current-state.md
    progress.md
    decisions.md
    capability-map.md
  .agents/
    workflows/
  artifacts/

关键不在于目录长什么样，而在于每一层到底写什么。

AGENTS.md 管入口。它回答的是：先读什么、遵守什么、怎么证明这次没有胡来。

docs/current-state.md 管现实。里面只能写已经验证过的现状，不能把目标状态、想法、愿景一起倒进去。

docs/progress.md 管接力。上次做到哪、卡在哪、下一步是什么、哪些路已经试过但别再试，这些都该写在这里。

docs/decisions.md 或 ADR 管因果。为什么选这个方案，为什么放弃另一个方案，哪些约束是真的，不是聊天里一闪而过的念头。

docs/capability-map.md 管边界。小仓库不一定非要有，但只要项目开始分成多个子项目、多个部署面、多个服务边界，它就不该省。否则每来一个新 agent，都要先做一轮低价值的目录考古。

.agents/workflows/ 管重复动作。启动、验证、回归、预览、发布这些事，如果每次都重新想一遍，时间就白白烧在重建上下文上。

artifacts/ 管工件。截图、benchmark、trace、临时报告、调试输出没有固定落点，就很容易重新掉回聊天窗口，过一轮 session 基本就等于没了。

如果这些面没有立住，所谓“上下文保留”最后经常只剩两种脆弱方案：

指望模型自己记住
指望操作者自己记住

这两种都不太可靠。

所以这个 skill 应该怎么优化

我现在对这个 skill 的要求，反而比一开始简单。

它不用显得很聪明，但至少要把下面几件事做扎实：

只有一个主入口，不要多份规则并行演化
当前现实、运行中进度、历史决策分开写，不要搅在一起
重复动作有 workflow，重要工件有落点
多子项目 repo 要把边界写清，不要每次都重新考古

最后的验收标准也不该是“入口看起来清楚”，而应该更硬一点：

一个全新的 agent，给它 30 秒到 2 分钟，它能不能只靠 workspace 里的持久对象接上旧任务，而不是依赖上一轮聊天历史。

如果做不到，这个 workspace 还不够格。

可直接复制给 Agent 的版本

如果你不想先手工创建 skill 文件，可以直接把下面这段 prompt 发给 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，但不要制造新的规则分叉。

这件事对新项目和旧项目都成立

它不只是一个“整理旧仓库”的 skill，也应该能拿来初始化新项目。

对旧项目，它应该做的是改造：

收敛入口文件
拆开混杂的 truth layers
补进度、决策、工件、workflow 的持久落点
让“昨天做到哪”不再只存在于聊天记录

对新项目，它应该做的是预埋：

默认一开始就把 AGENTS.md、适配层和 execution contract 立住
一开始就决定 current state、progress、decisions、artifacts 落在哪
如果是多子项目 repo，一开始就决定 capability-map 放在哪
一开始就让 workflow 有明确入口，而不是长到第二周再补

这会让整个项目的 operating model 稳很多。因为你不是在训练某一个 agent 记住项目，而是在让项目本身变成一个更好的外部记忆和协作基底。

我现在的结论

所以如果现在让我给这个 skill 下一个更完整的判断，我会这么说：

它首先要解决入口规范化和执行契约
但它的完成标准不能停在这里
它真正的目标，是把项目变成一个 agent 可以持续接力的 AI-Friendly workspace

最关键的优化方向，不是再往里面塞更多“如何提示模型”的建议，而是把 AGENTS.md 和 durable workspace surfaces 这两层一起立住。

说得再直白一点：

不要把连续性寄托在 agent 身上，要把连续性沉淀到 workspace 身上。

只有这样，agent 才更像一个会不断更替但能持续接力的执行者，而不是每次 session 都重新出生一次。