当AI代理偏离轨道时，提交一个Issue来修复文档——然后测试修复效果
编写软件文档如今可以成为一门严谨的学科。
这是在代理编程课程中出现的一个常见问题：如何将选择控件转换为单选按钮组？我正在开发Bram，这是一款桌面应用程序，它利用编码代理接入GitHub驱动的工作流程。Bram的用户界面使用XMLUI构建，XMLUI是一个围绕React和CSS封装了简洁声明语法的框架。我们为XMLUI提供了模型上下文协议（MCP）服务器，并指示代理优先查找经过验证的可工作模式作为操作示例。然而，Claude这次没有找到现成示例，只能回头查阅RadioGroup组件的文档，经过一番摸索后才找到正确用法。一切顺利，对吧？
不。Claude本应直接找到方法并立刻解决问题。缺失的文档就是一个缺陷，而这份新增的“如何做”文档就是修复方案。这次问题不算严重，但我们的“How To”目录里塞满了复杂且来之不易的模式，代理很可能要费力重新发现它们。为了确保XMLUI能被代理可靠地掌握，我们一直在持续扩充该目录。
文档如何变得可测试
我们一直强调，文档是软件产品不可或缺的一部分。如今我们既为人类也代理写作，兑现这一承诺的必要性更加明显。不太明显的是，我们现在可以为文档引入系统性的严谨流程。我们不仅需要撰写我们认为用户想读的内容，还要写代理需要读的内容。
作为XMLUI的共同维护者，我对代理在构建XMLUI应用时遇到磕绊非常敏感。当本该轻而易举的事情变得棘手——因为MCP搜索未能返回它本该找到的答案——我会提交一个Issue，然后指示代理编写缺失的文档。
这份新文档就是一项可测试的修复。例如，我让Claude在MCP日志中查找那次“选择转单选”失败的搜索记录。响应如下：
两次“How To”搜索，均在21:12，均未命中：
“radio group mutually exclusive selection change value form input”——命中结果包括：使用自定义表单项、从API响应预填表单、用正则表达式校验表单项。内容与表单相关，但完全没有涉及单选按钮。
“select one of two options horizontal selector”——稍后用另一种措辞重新尝试，从用户体验角度而非组件角度切入，同样没有结果。
失败的搜索只返回了相关性很弱的匹配，最高相关度得分约为0.7。添加新文档后，我要求它重复搜索并对比结果。新文档以4.2居高位，是其他文档得分的六倍。（由于MCP服务器可以固定所查询的文档版本，因此可以直接进行A/B对比。）我还尝试了一些合成查询，比如“一组小选项的单选按钮”，这些查询也验证了改进效果。
扩大实践范围
当我深入工作、发现代理错失了本应存在的文档时，我可以专注而精准地做出回应。但这只是我个人的做法，而且我仅工作在XMLUI功能子集的一个应用上。为了自动发现应用程序组合中缺失的文档，我们可以借助三类信息来源。
MCP日志
你无法改进无法衡量的事物，因此MCP服务器会记录代理执行的查询及其返回结果。这推动了我们进行多轮迭代优化。
应用代码
真实应用组合本身就是一份模式清单，记录了人们需要发现和使用的内容。因此我们可以逆向工程：什么搜索能导向有效的“菜谱”？这里有一个行之有效的做法：
在这五个应用中派发子代理，返回开发者在“How To”目录中搜索的最常见模式，然后运行MCP搜索，看这些模式是否应该被命中。
MCP日志直接衡量了文档的差距。
会话日志
只有当有人需要某份文档却找不到时，缺失才成为问题。与会话日志中与MCP日志时间戳相关联的记录，可以显示开发人员/代理团队在原本简单的事情上陷入僵局和死胡同的片段。
做到可靠的相关性排序说起来容易做起来难。虽然为代理提供全文搜索（正如Bram所做的那样）有所帮助，但我尚未让代理可靠地自动呈现“挣扎图谱”。不过，它们在日志中发现的信号已经很有价值，未来有望进一步改善。
重新构想文档写作
和许多文科背景的人一样，我最初以软件文档作者的身份进入技术领域，然后很快转到了其他岗位。但在担任开发人员和技术记者/编辑数十年后，我又回到了这个角色，先是作为Turbot文档的贡献者，后是为XMLUI写文档。
我作为写作者的身份并不受这些文档的约束。它们不是文学作品。它们正是我们一直认为文档该有的样子：软件产品不可或缺的组成部分。现在，和所有其他软件组件一样，我们指导代理来构建它们。在这项工作中，编辑和工程缺一不可。当把这两门学科结合起来时，文档写作会变得比以往任何时候都更有趣、更引人入胜、也更具影响力。
