最近看到两篇有趣的文章。一篇是 OpenAI 的 Harness engineering，另一篇是 yage 的 Context Infrastructure。它们都讲了同一件事：agentic 任务现在主要的阻塞已经回到 context engineering。最新的旗舰模型已经拥有足够的智能，但缺乏足够高质量的 context 来指导 agentic 任务。
这一周折腾 AI coding，我越来越觉得，真正难的地方可能不是“让模型会写代码”，而是“让它下次别像失忆了一样让我再重说一遍”。
我想要的效果其实很朴素：让 Agent 替我编程，而不是只是完成编程。在软件工程里，这可以近似等价于另一个问题：记录一个项目是怎么一步步变成今天这样的。你以为 git commit history 能表达这件事吗？完全不够。commit 历史充其量告诉你“现状”，但丢失了除此之外的一切隐性 knowledge：它为什么会这样长、踩过什么坑、“经验之谈”，技术和现实 trade-off，风险点和技术债、代码风格偏好。如果这些东西能被结构化地存储下来，未来 Agent 在接手新功能、重构、排查问题时，就不必从我那点可怜的口头交代里玩密室逃脱，然后还要被我一次次地纠正”你在干什么.jpg”。
我累，AI 也贵。
因此我想尝试给仓库装上结构化的记忆，而不是堆叠 AGENTS.md。
我最初想解决的，其实不是文档问题
表面上看，这像是又造一遍文档轮子。可真往下走，会发现将大量文档暴露给 Agent，其实是一件挺复杂的事情。
很多时候，代码仓库里其实并不缺信息。缺的是理由。代码写在那儿，测试也写在那儿，目录结构也一目了然，但为什么是这个边界、为什么用了这个权衡、为什么上次试图那样改却放弃了，这些往往不在代码里。它们散落在聊天记录、PR 讨论、脑内记忆、外部系统文档里。而以上所有信息基本都是碎片化的，哪怕局部有序，对于一个项目整体而言，也不是 organized、可直接复用的结论信息。
我的目标：
- 让项目上下文存活在仓库里，而不是某个工具的私有脑袋里。上下文整体对于工作有指导属性
- 可移植于各种工具：Codex、Claude Code
- 不论新老项目都能应用同一套记忆管理框架
- 构建反馈，自动化运行，让 Agent 自己去构建、更新、优化这些文档
因此合适的载体是一个叫 doc-flow 的 skill。同时，反馈循环非常重要，因为始终构建数据飞轮是我们学到的 bitter lesson。我最终的期望是这套系统只靠自己就能转起来，不需要人来干预，人可以降格为操作员。
另外，这背后还有一个技术前提：使用的模型经过 Agentic RL，具备主动、渐进式检索的能力。
doc-flow 的关键决策，不在于“多做”，而在于“少做”
一开始很容易把这件事想成一个大而全的“自动文档系统”。但后来我越来越觉得，真正重要的设计决策，恰恰都是那些克制的部分。
首先，doc-flow 不是拿来替代代码的，也不是拿来把所有工作痕迹都永久保存的。它只保留两层：
- 一层是 durable docs，也就是相对稳定、未来仍然有指导意义的东西，例如 architecture、constraints、decisions、lessons、risks。
- 一层是 worklog，也就是任务进行中的临时记录：计划、发现、转向、验证、handoff。
这两层一开始看起来简陋，后来反而越来越像一个必要的约束。因为如果没有这个分层，事情会迅速走向另一个极端：什么都记，于是什么都不好用。把所有中间思路都直接写进 durable docs，最后得到的不是“项目记忆”，而是我家的储藏室：什么都有，什么都找不到。
其次，我一开始以为 bootstrap 就足够了。后来才发现，fresh repo 和 existing repo 根本不是一回事。一个空仓库可以放心搭脚手架，一个已有历史的大仓库，最怕的是互相冲突的文档。所以后来我把模式收敛成四个：bootstrap | adopt | work | distill。
这四个词实际上是在回答四个不同的问题：
- 仓库还没有这套记忆系统时，怎么开始？
- 仓库已经有自己的文档和历史时，怎么接入而不是篡位？
- 真正做事的时候，哪些东西应该留下痕迹？
- 临时痕迹什么时候、以什么标准被提升为长期记忆？
再往后，还有一个很微妙但很关键的决策：AGENTS.md 到底要写多少。
最早我的直觉是，既然想自动化，就往 AGENTS.md 里多塞一点规则，让 Agent 每次进来都知道要做什么，但这样的话我还写什么 skill？而且这种系统级 instruction 一旦写得啰嗦，很快就会变成另一种形式的污染，还占上下文。最后秉持极简的做法，只留一个 pointer：告诉 Agent 去看 docs/index.yaml，去用 doc-flow。至于具体怎么 work、什么时候 distill，应该放在 skill 里详细说明。
遇到 Trellis 之后，我才意识到我们其实在讨论同一个问题
后来我在网上发现了另一个类似的项目 Trellis。
第一眼看过去，它确实和 doc-flow 很像：也会在 AGENTS.md 里注入路由说明，也强调 repo-local context，也在试图把 Agent 的工作过程从“即兴发挥”变成“有反馈的流程”。但再往里看，差别就越来越明显了。
Trellis 的 AGENTS.md 同样很短，真正的控制平面在 .trellis/ 里面：有 spec、有 tasks、有 workspace journal、有 workflow，还有给不同工具生成的 commands、skills、hooks。以 Claude 为例，它不仅生成了一堆 /trellis:* 命令，还在 session start 的 hook 里主动注入 workflow、spec index、当前任务状态和 start 指令。比起我在 instruction 里“要求” Agent 去执行 skill，通过 hook 在固定阶段执行显然确定性更高。在自动化和具体工具适配上，这个项目做的肯定比我一个下午 vibe coding 出来的 skill 要好 :)
我一开始看到 .claude/commands/trellis 那十几个命令文件，下意识地以为这套系统已经开始向繁文缛节滑坡了：上下文里塞这么多东西，有必要吗？后来仔细看了实现，我才发现情况没那么简单。那十几个命令并不是每次都全部塞进上下文里。真正的高频注入，主要来自 session-start hook；命令文件多是按需调用的。
这点很重要。它说明 Trellis 不是单纯地“多写点文档、多加点命令”，而是给 agentic workflow 增加控制论意义上的反馈回路。
不过目前为止我没有发现什么 benchmark 能证明“注入更多指令、拆出更多命令”，模型效果一定更好。能支持它的主要还是更广义的 harness 经验。OpenAI 的 Harness engineering 和 Anthropic 的 Effective Harnesses for Long-Running Agents 都在强调外部脚手架、任务状态和 repo-local context 的价值；但另一方面，像 Lost in the Middle 这类长上下文研究也在提醒我们，更多上下文不等于更有效的上下文。上下文窗口不是无限垃圾桶，这点和人脑其实没什么本质区别。
doc-flow 和 Trellis 其实在处理同一个母问题：上下文管理。只是它们选择了不同的控制强度。
doc-flow 更像 memory substrate。它关心的是：
- 什么该成为长期记忆？
- 什么只该停留在任务现场？
- 下一个 Agent 要从哪里进入？
Trellis 更像 workflow controller。它不仅关心记忆，还关心：
- 什么时候触发读取？
- 什么时候触发写入？
- 哪些事件该被 hook 捕捉？
- 当前任务如何切分、检查、归档、迁移？
同样是在“让 Agent 不再像失忆一样工作”，Trellis 的方法是提高控制力，doc-flow 的方法是保留灵活性。
这时候我脑子里反而冒出了一个很老派的词：控制论。
自动化从来都不是“加更多按钮”这么简单。按钮太少，系统干预不了；按钮太多，系统干预不动。零干预当然自由，但自由的另一面往往是失控；全流程严防死守也很可靠，但代价可能是复杂度陡增，最后人开始伺候流程。
从这个角度看，Trellis 的复杂度并不完全是“过度设计”。如果你的目标真的是做一个跨工具、长周期、多任务、多 Agent 的开发 harness，那么它需要 hooks、需要 commands、需要 update/migration engine，甚至需要一套专门处理模板升级和用户修改冲突的机制。这些东西不是装饰，它们是在替这个系统支付“自动化税”。
但这不意味着每个想做上下文管理的人，都应该照着抄一遍。至少对我来说，Trellis 最大的价值不是让我决定把 doc-flow 也扩展成一个 13 命令、全平台 hook、带迁移引擎的系统。恰恰相反，它帮助我更清楚地看见了自己的边界：我现在更想要的是一个轻量闭环，而不是一个 workflow OS。
这个“轻量闭环”是什么意思呢？大概是：
- 高频事件优先落到 working memory，而不是频繁重写 durable docs；
- durable docs 只在少数高价值边界上更新，比如 handoff、push、PR 前；
- always-on routing 保持极简，别在入口处堆三字经；
- 自动化可以有，但要优先选择那些便宜、可逆、低噪音的控制点。
说白了，我不想让 Agent 每次进仓库都先读一遍四书五经。毕竟我们做这些，只是为了让它更像一个能持续记住上下文的工作伙伴。
最后一点感想
这次折腾下来，我对“文档”这个词反而有了点新的理解。
过去说到文档，总容易想到 README、PRD、方案设计、接口说明，是一种静态说明书或者汇报材料。但在 agentic 这个语境里，文档更像一种工作记忆的组织方式,是给未来的协作者——无论那是人还是 Agent——留下一条可追踪的认知路径。
这也是 doc-flow 和 Trellis 的价值。它们表面上一个轻，一个重；一个像 skill，一个像 framework。但本质上，它们都在试图回答同一个问题：当 Agent 开始替我们写代码时，仓库本身要怎样才能拥有记忆？
从这个角度看，真正的问题就不再是“要不要写文档”，而是：
- 哪些东西是这个项目长期、稳定的信息、原则、标准？
- 哪些东西只是短期任务的进度追溯？
- 系统应该在多大程度上自动帮我维护这种分界？
这三件事构成的上下文应该足以让一个项目不断自举迭代了，人的输入因而无足轻重。那么，更深一步地提问：**假如人不再拥有全部的上下文，是否还拥有跟 AI 协作的基础条件？**我们现在主要的构建仍然围绕在如何为 AI 提供更完整的上下文。假如某一天这个问题被完全克服了，届时是否不再需要人去审核、输入增量信息、同意(consent)了？人还能做什么？还需要人吗？那时的人会去做什么？
我也没有答案。
至少眼前，我希望 Agent 有办法获取我每天工作项目里的隐性上下文，这样就不必每次都给 AI 交代这个项目的去年病史了 ;)