Theo 如何从智能体的实际错误中改进 AGENTS.md 和 Skills

我最近合并的代码比以往任何时候都多，部分原因是 T3 Code 让并行工作更容易。我还花了几个小时编辑智能体指令文件，随后又测试和调整。这些小小的 Markdown 修改改善了我的开发体验。我想解释的是自己的过程，而不是给你一套照搬的配置。

我在多台机器上工作，因此需要确保指令和 skills 出现在正确的位置。我曾开始构建一套自定义管理系统，但各种边界情况很烦人。于是我改用 fleet 仓库保存共享的 Markdown、配置和元数据，让智能体知道哪些 skill 应该放在哪些机器上。

Fleet 仓库包含通用 skills、仅适用于某个智能体运行工具的 skills，以及供管理其他机器的控制中心使用的 skills。元数据记录平台等要求。修改 skill 后，在 fleet 仓库工作的智能体可以根据这些指令，将其分发到适当的机器。

我旧的全局 AGENTS.md 和 CLAUDE.md 文件包含一些基本默认项：项目和用户指令优先、避免不必要的 TypeScript any、选择有针对性的检查，以及偏好的包管理器。我很长时间几乎没改过它们。它们有用，但新的工作方式暴露了更多反复出现的问题。

新的全局文件先介绍我自己，以及我偏好用简单系统实现有雄心的想法。我曾看到智能体添加过多代码和机制，几句话就帮助它们调整了方向。我使用对话式的语气，部分原因是模型往往会模仿输入的语气。

一般偏好包括类型安全、有针对性的测试、有用的注释，以及谨慎处理未经请求的破坏性操作。我希望智能体能提出有价值的想法，而不是把简单任务做得过于复杂。看到生成代码中一些不喜欢的模式后，我也补充了 TypeScript 专用偏好。

我告诉智能体：提问只需读取和回答，因为有些智能体在我只想了解情况时就修改文件。我还要求流程与任务规模相称，避免不必要的子智能体；确实并行工作时，要先明确文件归属，避免相互冲突。这些都是针对我自己工作方式的调整，不是所有人都应该复制的规则。

我有意没有把全局文件作为模板发布。它的价值在于每条指令背后的思考和促成它的经历。全局文件会影响很多项目，因此你应当掌控和编辑它，并根据自己反复遇到的需求进行调整。

Skill 解决的是另一个问题：我不断重复相同的指示，却得到不一致的行为。我的 babysit-PR skill 来自处理多个审查机器人参与的拉取请求的经历。它描述如何跟踪审查和 CI、检查当前改动并推动工作。

我发现智能体有时会通过我的账号回复，却没有表明身份；有时又把每条机器人评论都当成必须处理的要求，导致改动范围扩大。我的指令要求它们对照源码验证发现，区分真实失败与基础设施问题，并解释不采纳反馈的理由。标注模型身份则能让别人知道是智能体代表我回复。

关键限制是：修复真实问题，但不要让审查反馈使拉取请求偏离原始目标。截图和视频在有助于审阅者理解改动时也可以使用。重要的是结果和证据，而不是不加区分地满足每条自动建议。

Skill 描述尤其重要，因为智能体会利用它判断是否加载完整指令。我把描述当作触发条件：写明哪些请求应激活这个 skill，而不是把整套流程都塞进描述。具体行为仍取决于所使用的智能体系统。

我把创建 PR 和跟进 PR 分成两个 skill，因为有时只需要其中一项。当我要求打开或创建拉取请求时，file-PR skill 会触发。智能体本来就能创建 PR，但这个 skill 改善了它们解释改动的方式。

一份旧 PR 描述罗列了实现细节，却没有说清楚哪里出了问题。我记得实际问题是 T3 Code 的版本差异警告不正确。这个例子让我意识到，维护者需要先知道用户遇到的问题和期望结果，再看内部改动清单。

我的指令要求智能体检查是否已有对应 PR，对照目标审阅差异，并遵循仓库标题惯例。我给出了不佳标题和更好标题的具体例子，后者说明改动带来的效果。这比抽象地要求“写好标题”更能传达区别。

对于描述，我要求先用平实语言说明问题，再简要解释解决方案。如果知道，我还会记录完成工作的模型和运行工具。在我的配置中，我倾向于创建可直接审查的 PR，让审查机器人运行；其他仓库可能需要不同惯例。

一个较新的例子解释了提示词暂存问题：切换提供商后，保存的提示词看似消失，恢复时还会带回不想要的模型选择。这让审阅者明白为什么要做这个改动，比罗列文件和函数更容易判断。

全局指令只是其中一部分。T3 Code 也有面向贡献者的项目专用文件，包含针对代码库的细节。我把生成草稿当作参考，而不是最终答案；还让智能体调查我的真实工作历史，寻找反复出现的失败模式。

我让几个模型检查本机的 Codex 和 Claude Code 历史，分类错误并提出改进。一份审计发现了停止错误进程、不必要的全仓检查和 PR 流程问题。这些结果帮助我确定要增加哪些具体指令，但它们来自我的个人会话，并不是受控的模型比较。

另一份报告按模型和类别统计每 100 条用户消息中的纠正次数。我会谨慎解读：我给不同模型安排的任务和上下文不同，纠正更多可能反映任务难度或个人偏好。这些数字是帮助寻找值得调查模式的线索，不是可靠排行榜。

当一个会话进展不顺时，可以问智能体为什么选择那条路径、依据了哪些信息。原因可能是过时的指令，也可能是较早出现的误解被带入后续上下文。对于耗时异常的任务，可以分类工具调用，找出时间花在哪里、哪些步骤有帮助。

项目 README 帮助人和智能体理解项目是什么；智能体指令文件则应重点说明如何工作，以及修改前需要知道什么。两者可以有重叠，但我希望后者帮助智能体与开发者协作，并有效导航仓库。

我最喜欢的补充之一是术语表。它定义 user、agent、provider、client、environment、project 和 thread 等词。好处不只是让智能体理解提示词；共享词汇还帮助它用团队熟悉的语言向我解释工作。

项目文件简要介绍 T3 Code：它是围绕智能体提供商构建的图形界面，具有 Web、桌面和移动客户端。这给智能体提供背景，不必每次从头弄清产品。文件还列出改动应尊重的产品特性，例如开放性、性能和远程访问。

文件描述了不同的客户端和连接方式，因为一个客户端能工作的改动，换到别处仍可能失败。有些细节会过时：我注意到文件中一条移动应用可用性说明已经需要更新。指令文件和代码一样需要维护。

我写了一段说明，表达自己偏好简单系统、避免不必要的机制、抵制范围蔓延。我把许多项目指令视为合理默认项，在适当情况下开发者可以覆盖它们。用户的明确偏好很重要，因为通用默认项未必适合眼前任务。

许多贡献者会在自己正在修改的 T3 Code 实例中运行智能体。因此，进程和数据处理很重要：如果智能体停止错误的服务器或触碰实时状态，就可能中断用户当前的环境。这些提醒来自我实际工作中反复发生的问题。

“检查每个使用端”一节针对一个常见缺陷：功能在测试过的路径上有效，却遗漏了其他地方。宣布完成前，应检查适用的入口、Web、桌面和移动客户端，以及各个提供商适配器。明确决定“此处不支持”，也比悄悄漏掉某个使用端更好。

清单还包括共享契约、反向状态、连接模式和文档。例如，增加 snooze 却没有 unsnooze，会造成只能进入、无法退出的交互。如果网络传输契约发生变化，相关服务端和客户端定义也需要关注。具体适用哪些检查，取决于改动内容。

我还希望用户文档与维护者文档有各自的入口。模型经常把内部实现细节写进面向用户的文档，因此明确区分有助于把解释写给正确的读者。我一直在推动文档改动，让这种区分更清楚。

开发服务器指令记录了这个仓库中真正可用的命令，因为智能体曾反复选错 Vite Plus 调用方式。其他指令则隔离开发数据和运行中的安装，提供正确的远程连接信息，并记录智能体启动的服务器进程 ID。这些都是针对实际错误的具体修复。

我也调整了验证和测试数据的指导。对于前端工作，项目指令说明何时进行真实客户端的集成检查，以及可使用哪些测试 skills。目标是在获得有用证据的同时，避免不必要的浏览器会话或反复执行大范围检查。

项目文件还包含架构偏好：把复杂性留在适配器边界，保持编排简单，让 UI 组件职责清晰。它也提醒贡献者，用户会注意到掉帧、误导性的加载动画和过时标签。我希望智能体在这些偏好与任务冲突时说出来，而不是悄悄做出复杂方案。

这些指令让我的提示词变短了。一次营销网站改动中，智能体展示了带标签的 HTML 原型；我只需选择想要的组合，再要求它创建和跟进 PR。另一个例子中，我描述 settle 按钮故障，要求诊断、修复并执行 PR 工作流。简短请求之所以有效，是因为详细偏好已经在上下文里。

我的控制中心 skills 还能帮助配置机器。我先手动配置一台电脑，再让智能体检查配置和历史记录，将设置写下来。随后我在另一台机器上测试这些指令，纠正遗漏和不必要的操作，最后把结果整理成配置机器的 skill。

Fleet 中还有一份 HTML 设备清单，记录机器角色、规格和连接方式。中央机器拥有配置新机器的 skill，共享仓库则保存需要分发到其他地方的 skills。这套安排反映的是我自己的网络和访问条件，并不是通用配置教程。

一个共享 skill 可以把本地文件上传到我的公共文件托管服务并返回链接，前提是具备明确要求的凭据。这样，智能体就能在 PR 中分享录屏或截图，也能让我在手机上查看。它的意义是改善沟通：智能体可以向人展示发生了什么，而不只是文字描述。

这些文件的更广泛目标并不只是让模型写出更好的代码。我希望它的报告、审查和演示对我以及其他维护者有用。上传文件这样的能力之所以重要，是因为它让人更容易检查结果。

我的 HTML communication skill 会生成供人阅读的文档、计划、报告或 UI 原型，并上传到我自己的服务。它最初还包含读取该服务链接的指令。录制过程中我意识到这个 skill 负担过重，于是决定把创建和读取分开。

我给智能体一个具体的修改请求：重新阅读当前文件，把功能拆成两个 skill，让描述聚焦触发时机，并在提交或分发修改之前停下来。明确的停止点让我可以先检查结果，再决定下一步。

修改后的 HTML skill 区分供人阅读的文档和作为产品代码发布的 HTML。它要求生成自包含文档，为原型加标签以便比较，并规定上传真正成功之前不能声称已经成功。我检查结果后，才授权将它应用到 fleet。

我又做了一处小改动，让自己在工作流中只需说“HTML”就能触发沟通 skill。在 fleet 和远程访问已经配置好的前提下，我可以让智能体把更新后的指令分发到各台机器。普通 Markdown 能做到这些很强大，但它依赖我已经搭建的基础设施。

我从未要求你安装我的所有 skills。你应该根据自己项目中的需求和失败逐步建立自己的集合。检查智能体实际做了什么，编辑指令，测试变化，再继续改进。理解自己的智能体如何工作，比复制我的具体文件更有价值。