Repo as an Agent

一个设计得足够好的 repo，本身就可以成为一个不断自我改进的 Agent。

这里的 repo 不只是代码存放的位置，Agent 也不只是某次被调用的模型。Repo 保存目标、知识、工具、反馈和约束；模型进入其中，读取当前状态，采取行动，再把结果写回去。下一次即使换了一个模型，工作仍然可以从上次结束的位置继续。

严格地说，一个静止的 Git 仓库不会自己行动。它仍然需要模型、Harness 和运行环境来把它唤醒。Harness 是承载 Agent 的系统，负责向模型提供上下文、工具和执行能力。但如果这些东西可以更换，而 repo 仍然保留同一种工作方式和持续积累的能力，那么 Agent 最稳定的部分或许已经不在模型里，而在 repo 里。

模型不是 Agent 的全部

我们很容易把 Agent 的能力归因于模型：模型更聪明，Agent 就更强；一次回答不好，就换一个更大的模型再试。

这种理解忽略了模型每次开始工作时面对的环境。同一个模型进入两个仓库，表现可能完全不同。

一个仓库只有源代码，没有架构说明，不知道怎样启动，测试长期失败，关键决策留在聊天记录里，出错后也没有可读取的日志。Agent 每次进来都要重新猜测。它或许能完成局部修改，却很难稳定地把一件事做完。

另一个仓库把产品目标和技术决策写进可检索的文档，用 AGENTS.md 告诉 Agent 从哪里开始，用脚本提供统一的操作入口，用测试、类型检查和 CI 给出明确反馈，还能启动真实页面，让 Agent 直接观察修改结果。模型没有变化，它能完成的工作却明显增加了。

OpenAI 对一次 Agent-first 开发实验的总结也指向这一点。他们发现，早期进展慢并不只是 Codex 能力不足，而是环境没有被充分定义。团队后来的主要工作变成了设计脚手架、工具和反馈回路，并把仓库知识作为唯一可信来源。随着测试、验证、评审、反馈处理和故障恢复逐步进入 repo，Agent 才能从一个 prompt 开始，独立完成复现问题、修改、验证、提交评审和修复 CI 等工作。

Factory 把这种差异称为 Agent Readiness，也就是一个 repo 对自主开发的准备程度。它检查的不是模型有多强，而是仓库是否具备可靠的构建、测试、文档、开发环境、可观测性和安全治理，再用五个成熟度等级描述 Agent 能够独立工作到什么程度。这个框架让一个原本模糊的判断变得可以检查：当 Agent 表现不好时，问题不一定出在模型，也可能是 repo 还没有提供足够快的反馈、明确的指令和可操作的环境。

Repo 因而不只是 Agent 要处理的对象。它也在定义这个 Agent 是谁，以及它能做什么。

Repo 已经具备 Agent 的主要部分

从这个角度看，一个成熟 repo 里的常见文件，会呈现出另一种含义。

AGENTS.md、架构文档和决策记录是长期记忆。它们保存这个项目特有的事实和做事方式。
源代码、CLI、脚本和 Skills 是行动能力。它们不仅描述该做什么，还能被直接执行。
测试、类型检查、lint、CI、日志和页面验收是感知与反馈。它们告诉 Agent，刚才的行动是否产生了预期结果。
Issue、计划和任务文件保存尚未完成的目标。
Git 记录发生过什么，允许比较、追溯和回退。
人的 review 负责机器反馈无法决定的部分：目标是否值得、取舍是否合适、结果是否真的可以接受。

这些部分组合起来，形成了一个跨越多次模型调用的行动主体。模型负责当下的推理，repo 负责连续性。

这也是为什么所谓 self-improvement，不一定意味着模型在训练自己的权重。Self-Improving Coding Agent 的研究采用了更严格的定义：Agent 修改自己的实现，再用 benchmark 选择表现更好的版本。但在日常开发里，更常见也更实用的自我改进发生在模型之外。模型权重没有变化，Agent 工作的环境变了；下一次运行因此少犯一次已经犯过的错，多拥有一种已经验证过的能力。

改进发生在反馈被写回之后

只完成一次任务，还不算自我改进。

Agent 修复了一个 bug，代码当然变好了，但如果它下次仍然会制造同一种 bug，得到改进的只是产品，不是 Agent。真正的分界线在于：这次反馈有没有改变未来的行为。

一次失败可以被写回不同层次。

如果 Agent 只是不知道运行命令，可以补充简短的仓库说明。如果某类任务总要经过相同步骤，可以把它整理成 Skill 或脚本。如果某条约束不容违反，最好的做法通常不是再写一句提醒，而是把它编码成测试、lint 或类型规则。自然语言告诉 Agent 应该怎样做，自动检查则让错误的做法无法悄悄通过。

于是，一个完整的改进回路是：

折页人把有缺口的齿轮重新装回 repo 机器，旁边完整的齿轮代表下一次运行得到改善 — 失败只有被装回 repo，才会变成下一次行动的一部分

Eric Ma 把这种变化称为 operational self-improvement：不是等待模型升级，而是让反馈留在 AGENTS.md 和可复用的 Skills 里。衡量它的方式也很朴素——同一句纠正是否还需要由人反复说，昨天完成的工作有没有降低今天完成同类工作的成本。

这个博客 repo 已经有一点像这样的 Agent

这篇文章本身就是一个例子。

当我提出“以 repo as an agent 为主题写一篇 draft”，repo 里的规约已经定义了 draft 的含义：先研究和润色中文源稿，不提前生产英文、日文版本，不提交，也不发布；写入文章系统以后，启动对应页面供我批注。

Agent 不需要我每次重新解释文章放在哪里、什么阶段可以翻译、应该运行哪些检查。AGENTS.md 保存边界，writing Skill 保存可复用的写作方法，Content Collection 决定文章结构，Markdown smoke check 和构建命令负责发现格式问题，Portal 把真实页面和人的批注重新接回工作流。

更重要的是，这个 repo 还规定了反馈如何成为长期经验。单篇文章里的修改只服务于当前文章；只有同一种理由在多篇已审阅文章和不同场景中反复出现，Agent 才会提议把它写进 Skill，而且仍然需要人确认。

这是一种很小的学习机制。它没有训练模型，却在区分短期反馈与长期规则，决定什么应该被遗忘，什么值得进入下一次运行。文章越多，真正稳定的方法可以逐渐留下来，后续生产不必从零开始。

记得越多，不等于改进越多

把 repo 变成 Agent，不是不断往 AGENTS.md 追加文字。

2026 年一项关于仓库级上下文文件的研究发现，在其实验设置中，加入 AGENTS.md 并没有普遍提高 coding task 的成功率，平均推理成本反而增加了 20% 以上；其中非标准的项目指令会被 Agent 遵循，但常见的 repo overview 并没有带来帮助。研究者因此建议：不要默认上下文越多越好，任何声称能提高表现的仓库说明都应该经过评估。

这提醒我们，自我改进也可能退化成自我污染。

错误的总结会被下次运行继承，过时的文档会把 Agent 引向已经不存在的结构，偶然偏好会变成永久限制，越来越长的指令会挤占真正任务所需的上下文。Repo 会放大好模式，也会放大坏模式。

所以，一个可自我改进的 repo 还需要遗忘、校正和晋升机制：临时经验先留在当前任务，重复出现后再成为文档，能够机械判断的规则继续下沉为测试和工具；失效的说明则应被修改或删除。AGENTS.md 更适合做地图，而不是百科全书。

Repo 是 Agent 可以持续改造的自己

判断一个 repo 是否开始成为这样的 Agent，可以问几个具体问题：

换一个新的模型实例进来，它能否恢复这个项目的目标、边界和当前状态？
它能否直接运行工具，观察真实结果，而不是只生成一段看起来合理的代码？
一次失败能否留下可执行的修正，让相同错误以后更难发生？
人的判断能否进入系统，同时避免一次性的意见永久污染未来工作？
Repo 能否检查、清理和修改用来约束自身的文档、测试、Skills 与脚本？

如果答案逐渐变成“能”，模型就更像一次被临时调入的推理能力。真正跨越时间存在的，是 repo 里持续变化的代码、记忆、工具和反馈回路。

过去，我们把 repo 看成软件的源代码。以后，它也可能是 Agent 的源代码。

每次运行，Agent 都在修改产品；设计得好的时候，它也在修改下一次的自己。