如何管理你的机器人

如何管理你的机器人

与编码代理高效协作

2026年7月23日

作为维护者的“豪华游艇”，我花了很多时间与编码代理交流——真的很多。

我热爱开发这款应用，但要说和代理们的对话是件有趣的事，那可说不通。要让机器人始终按规矩行事，简直是一份全职工作。在每次提示之间等待许久，确保它们不犯下愚蠢的错误，还要时刻留意它们输出的代码是否垃圾……这些事情实在让人厌烦不已。

无论我投入了多少精力来完善文档、整理代理文件、提升技能，或者去研究这个月最热门的技术，LLM的上下文容量终究有限，它们根本无法真正学会新知识；而你精心设计、反复强调的关键指令，最终往往会被从上下文窗口中“甩”出去，好腾出空间给那些不知何物的东西。

而且，会话持续得越久，这种情况就越容易发生。

前沿的代理在压缩后仍能较好地保留上下文，代理记忆的确有所帮助，但并不完美；在处理复杂任务时，代理依然很容易迷失方向。

考虑到这些因素，我想分享一些自己为提升代理效率所做过的努力。当然，我并不是什么专家，这些经验大多来自不断试错，我也毫不怀疑自己还有许多可以做得更好的地方。

我们都在不断学习，而人工智能的格局也在飞速变化。

没有“灵丹妙药”

先说清楚：对于大型、复杂的项目，你一定会频繁地与代理打交道。要让它们始终沿着正确的轨道前行，既困难又需要高度警惕。代理天生就喜欢“聪明”，因此你得忙着提醒它们遵守既定的模式，复用已有的代码，而不是重新发明轮子。

你还会经常提醒它们要从全局出发，清理那些无意间产生的副作用。“你在小部件子系统中做了一个改动，结果把‘小玩意’模块给搞坏了。赶紧去修复它，并更新文档，确保以后不再犯同样的错误。”

人工智能时代的真正潜力？如今，我们都是管理者，肩负着引导一群聪明却冲动、健忘的初级工程师的责任。那么，让我们一起来探讨一些策略，帮助你减轻这份新近承担的管理重担。

代理文件：制定清晰的规则

代理文件是一个名为AGENTS.md的Markdown文件，通常位于仓库或项目的根目录下。代理文件是代理首先查找“地形图”的地方，因此这里正是你放置重要规则的地方——规定了代理应该如何行为，并告诉它在哪里可以找到更多相关信息。

一个非常简单的代理文件可能如下所示：

规则

• 始终践行红绿TDD。 • 对所有代码变更执行代码检查器（Linter）。 • 任务完成前，务必更新相关文档。 • 尽量复用现有代码，不要刻意创造新的模式，因为有些东西其实早已存在。

代理并不总是会严格遵循这些指示，有时甚至会忘记你在这里写下的那些至关重要的内容——即使你用粗体大写字母大声喊道：“这非常重要！但这是起点！”

如果你从这篇文章中只学到一件事，那就是：在你的项目中创建一个AGENTS.md文件。

代理文件究竟该包含哪些内容，取决于你的项目以及你与代理合作时的个人需求。我无法告诉你自己的项目应该有哪些内容。也许，只要简单地请求代理帮你创建一个代理文件，就能事半功倍。

或者，不妨看看这里的例子的相关案例。

Claude必须与众不同

遗憾的是，Claude并不想要AGENTS.md文件，它想要的是CLAUDE.md。如果你只使用Claude，那么你最终会创建一个CLAUDE.md文件，而不是AGENTS.md文件。

不过，如果你同时使用包括Claude在内的多种LLM，那就最好将你的指令都写入AGENTS.md文件中，然后单独创建一个CLAUDE.md文件，只在其中添加这样一行：

@AGENTS.md

这会告诉Claude去查看AGENTS.md文件，这样你就无需在两个文件中重复相同的指令。

使用多个代理文件

对于大型项目，你或许希望在项目各处分散存放多个AGENTS.md文件。如果你正委托代理负责应用的某个特定部分的工作，这种方式会非常有帮助；同时，还能减少代理需要阅读的指令数量，而不用把所有内容一股脑儿塞进根目录下的一个代理文件中。

以豪华游艇为例，其根目录下有一个代理文件，用于制定整个项目的总体规则；而在后端和前端目录中，则分别设置了更多针对不同区域的代理文件，其中载明了更具体的规则和相关应用信息。

豪华游艇是开源项目，你可以前往GitHub repo查看我常用的代理文件。虽然你未必会想完全照搬我的文件来使用在自己的项目中，但它们或许能为你提供一些灵感，帮助你构建属于自己的代理文件结构。

文档：帮助代理更好地理解

我的代理文件中包含了关于如何查找应用相关文档的信息。让代理们自己撰写文档吧。告诉他们，这些文档是为他们自己撰写的；因此，尽管这些文档需要具备人类可读性，但不必追求“人机友好”，而是要优先考虑让代理们能够高效地获取和利用这些信息。

每当代理修改应用时，只有在更新了相关文档并补充了关于此次变更的信息后，才应认为任务已完成。当然，实现这一操作的指令就在AGENTS.md文件中，但我有时还得提醒代理，在完成一项任务之前，一定要先完成这一步骤。

我把所有的文档都放在根目录下的docs文件夹中。与代理文件不同，我并没有将文档分为前端文档和后端文档，因为这种划分并不总是那么清晰。

许多系统都涉及跨领域的问题。通常，我会让代理自行决定如何组织文档，毕竟这些文档正是为它们而生的。

我在docs文件夹中放置了一个README.md文件，作为索引，用来告知代理应该参考哪些文档。与其费力地解释自己到底在说什么，不如鼓励你去看看文件。

就像其他文档一样，每当代理对文档进行修改时，只要做出任何可能对其产生影响的更改，它就应当负责更新这份顶层README。

技能：告诉代理如何去做

技能是一组指令的集合（一个Markdown文件，还可能包含其他脚本和参考文件），用于指导LLM如何完成某项具体任务。这是一个广义的话题，本文就不深入探讨了。

技能方面，我们有财富、现存、资源等，其内容远比我在此处所能涵盖的要丰富得多。

如果你发现自己在向代理下达指令时常常重复同样的内容，那很可能说明你需要增加一项技能。你也可以尝试自己编写一项技能，但或许直接请代理来编写技能（当然，你还需要对代理编写的技能进行审核和验证）会更加轻松。

例如，在豪华游艇项目中，我有一项技能，用于指导代理如何对刷新子系统进行修改——这个模块负责确保显示的Kubernetes数据始终保持最新。

这是一个复杂的系统，因此当代理需要与刷新系统交互时，给予它尽可能多的帮助至关重要。

你可能已经注意到，技能与文档之间存在一定的交叉点。在我看来，文档是“是什么”和“为什么”，而技能则是“怎么做”。

测试与代码检查器：安全屏障

在项目早期，采取的一项非常有效的措施就是强制执行测试与代码检查器。永远不要让代理认为一项任务已经完成，除非它已经编写了测试并运行了代码检查器。

我发现，红绿TDD（或红绿/重构）对LLM尤其有效，因为它能促使它们更深入地思考如何恰当地实现某项功能。如果你对红绿测试还不熟悉，其核心要点如下：

红色步骤——编写一个测试，明确描述你想要实现的目标。确保测试失败。

绿色步骤——编写最简单的代码，使测试通过。

重构——在确保测试持续通过的前提下，对代码进行优化改进。

在完成测试之后，你应该确保LLM对它生成的代码运行代码检查器，以捕捉那些由代码检查器专门负责检测的常见问题。良好的测试和高效的代码检查器，能为你省下大量麻烦。

Git：逃生通道

确保你…