围绕我们的编码代理构建控制层：八种故障模式，八大支柱

使用AI构建的团队通常最终会构建两个产品：他们交付的东西，以及围绕代理的系统——这个系统让代理在构建他们交付的东西时变得有用。

我们构建了这样一个系统来帮助我们交付Nimbalyst。我们称之为团队控制层。这篇文章是关于我们从中获得的经验。

什么是控制层

控制层是模型周围的持久层：指令、工具、权限、上下文和验证。

Claude Code和Codex在这种意义上是控制层。每个都用一个系统提示、一个工具表面、一个权限模型和一个执行循环来包裹模型。Anthropic和OpenAI拥有那一层。

你的团队拥有下一层：代理与你一起进行产品工作的工作空间，包含你的文件、任务、图表、差异和决策。这一层承载着你团队积累的知识：你们如何构建东西，你们已经决定了什么，什么与什么相关，代理被允许在什么地方行动，以及它如何检查自己的工作。

上下文和控制层之间的界限可能会模糊。一个工单或规格说明是特定于任务的上下文，但使该工单可搜索、可链接、可版本化、并可由任何代理检索的机制，是控制层的一部分。

一个好的控制层中几乎没有什么是新颖的。它主要是围绕你的项目组装起来的其他人的部件：Claude Code、Codex、MCP、Playwright、一个追踪器、一个图表工具、一个编辑器、一个测试运行器、你的仓库、你的文档。控制层是这些部件组合在一起的方式，使得代理能够为任务提取正确的上下文，并验证它产生的东西。

1. 上下文

目标：了解项目。

此支柱解决的中断模式： 代理不了解你的代码库、规则、决策或约定，所以它解决每个问题时都像从未见过这个项目一样。

上下文是我们项目中特有的一切：代码、规格、设计文档、追踪器条目、数据模型、过去的决策、约定、示例和配方。

在我们的控制层中，这意味着：

• 代码、规格、计划和原型图作为本地文件存在，格式是代理可以直接读取和编辑的。

• 架构图以Excalidraw文件的形式存在，而不是被困在幻灯片中的截图。

• 决策被捕获为追踪器条目，而不是埋在聊天记录中。

• 错误历史是可搜索的，因此代理可以看到症状、根本原因和之前的修复。

• 根指令文件如CLAUDE.md和AGENTS.md在会话开始时加载，并指导代理访问其余内容。

• 路径作用域规则文件仅在代理触及相关目录时加载，因此React规则在渲染器代码中出现，Swift规则在iOS包中出现。

• 一个技能系统持有可重用的指令，用于重复性工作：我们如何编写测试、添加分析事件、发布包或调试失败的屏幕。

• 持久化每用户记忆跨会话捕获偏好和已验证的方法。

一个编辑渲染器代码的代理加载React规则而不加载iOS规则。一个修复回归问题的代理在编写代码之前找到先前的错误、根本原因和修复。每个会话开始时，团队积累的决策已经在范围内，而不是从提示中重新推导出来。

2. 溯源

目标：追溯原因。

此支柱解决的中断模式： 代理无法遍历已存在的工件之间的链接，因此每次变更背后的理由都必须重新解释或重新发现。

溯源是代码变更如何保持与产生它们的意图相关联。一个持久化的、类型化的记录，解释每个变更存在的原因，可以从任何方向导航：从文件、从会话、从追踪器条目、从提交。底层数据结构是一个类型化的工件间链接图；其价值在于能够问“为什么是这样？”并得到答案。

在我们的控制层中，这意味着：

• 一个类型化的链接图，连接追踪器条目、计划、规格、图表、原型图、会话、差异、文件、提交和决策。

• 这些工件在同工作空间内的原生编辑器，因此链接可以解析到实际的工作内容。

• 文件编辑历史与产生它的会话相关联，因此任何文件都能显示编写它的对话。

• 追踪器条目类型对应团队携带的不同意图：错误、功能、决策、计划、事件。

• 决策追踪器条目记录为什么做出架构选择，这样未来的会话问“为什么是这样？”能得到答案，而不是猜测。

• 错误追踪器条目在我们发现问题时就提交，在编写修复代码之前，因此症状和根本原因与修复保持关联。

• 一个MCP界面，使得不同代理可以在会话期间遍历同一个图。

一个错误可以链接到失败的截图、修复会话、差异和提交。一个功能请求可以链接到计划、原型图、实现会话和发布说明。Git捕获了什么发生了变化。溯源捕获了我们为什么以及如何到达那里。

3. 能力

目标：行动与观察。

此支柱解决的中断模式： 代理无法对世界行动或观察其行为，因此它被困在文本通道中，要求用户运行每个命令并粘贴每个输出。

能力涵盖让代理对实时状态行动并验证其行为的工具：读取日志、查询运行中的数据库、驱动UI、截取屏幕截图、运行测试，并循环直到结果正确。

在我们的控制层中，这意味着：

• MCP工具，读取应用程序实时日志并通过应用查询运行中的数据库，而不是直接访问（不安全）。

• 驱动应用程序本身的工具：重启、重新加载、安装扩展、热重载代码。

• 一个渲染器评估工具，在运行中的UI内部运行JavaScript以检查DOM、状态或原子。

• 一个截屏工具，捕获任何打开文件的渲染内容。

• 一个由Playwright驱动的UI循环，使代理可以与运行中的应用交互、截取屏幕截图并验证结果。

• MCP工具，封装代理每天使用的第三方系统：GitHub、分析仪表板、浏览器、追踪器。

• 一个沙盒化shell，使代理可以运行测试、脚本和安全的codemods，并运行wrangler tail、curl和gh，而不是要求用户粘贴输出。

• 一个扩展SDK，使团队可以编写自己的MCP工具并将其部署在工作空间内。

在更改React组件后，代理可以打开屏幕并检查截图。更改持久化逻辑后，它可以验证行是否实际更改了。一个能够对世界行动并观察结果的代理通常可以自己闭环。

4. 工作流

目标：重用流程。

此支柱解决的中断模式： 代理重新发明如何执行每个任务，所以相同类型的工作每次形状不同，基础内容必须在每个会话中重新解释。

工作流是编码会话的形式：如何开始、如何计划、如何获得帮助以及如何并行化。

在我们的控制层中，这意味着：

• 在**.claude/commands/**中的仓库本地斜杠命令，用于我们反复执行的步骤：计划、实现、审查、发布。

• 对于非重要的任务，一个标准的“先计划后执行”流程，因此代理在更改文件之前承诺一种方法。

• 一个调查、设计、实现的递进流程，使研究和计划作为自己的步骤进行，而不是与代码混在一起。

• 子代理用于探索、规划和实现，它们承担广泛的搜索，保护主会话的上下文。

• 一个技能系统，用于可重用的习惯，如编写测试、添加分析事件或发布包。

一个**/release-alpha命令以相同的方式运行版本号更新、变更日志和标签步骤。一个/investigate后跟/design**会产生一个计划文档，下一个会话可以从中拾起，而不是从空白提示重新开始。工作流层使每个会话免于自我重新发明。

5. 约束

目标：保持在界限内。

此支柱解决的中断模式： 代理因为没有任何东西阻止它而做出危险的事情，一个有能力但没有约束的代理会比预期更快地做出危险的事情。

约束是我们如何阻止代理快速做错事。它涵盖硬性规则、审批边界、权限范围、工具允许列表、预算限制和审计追踪。

在我们的控制层中，这意味着：

• 路径作用域规则，阻止代理编辑特定文件或目录。

• 指令文件中的硬性规则，针对代理绝不允许做的事情，比如读取**.env**文件或接触凭证，每条规则都附有过去教会我们这一点的事件。

• 每个工具的权限范围和允许列表。

• 对触及共享或昂贵状态的操作的审批流程：推送到main、删除表、调用付费API或运行破坏性shell命令。

• 工作空间信任模式，区分“可以编辑文件”和“可以做任何事”。

• 持久化的审批、工具调用和文件更改的审计追踪。

• 审查界面，使代理实际更改了什么一目了然。

在实践中，这意味着让代理重构渲染器代码但不接触发布脚本，查询开发数据库但不查询生产数据库，以及在测试循环上花费token但不加检查地触及付费第三方API。约束是与能力配对的支柱。我们给予代理的每一个新工具都需要一个匹配的范围，否则一旦代理在错误上下文中使用它，它就会成为负债。我们将两者一起构建。

6. 验证

目标：证明修复。

此支柱解决的中断模式： 代理在没有证据的情况下幻觉“修复完成”，因此一个自信的声明和一个可行的更改是两回事。

验证是代理在将更改交回之前证明其有效的方式。它涵盖测试、类型检查、首先复现错误失败，以及代理自身工具调用的模拟运行。

在我们的控制层中，这意味着：

• 一种“先失败测试”的纪律：在编写修复之前先编写失败的测试，这样错误就有了下一个代理可以重新运行的复现案例。

• 一个跨越包的Vitest单元套件，提供对逻辑层面更改的快速反馈。

• Playwright端到端测试，用于真实流程，每次运行一个规范，这样失败直接指向一个地方。

• 一个AI工具模拟器，让端到端规范可以伪造AI工具调用并断言代理做了什么，而无需为真实模型付费。

• 将快速类型检查融入循环，这样代理甚至在测试运行之前就能捕获漂移。

一个针对同步错误的修复以Playwright规范开始，该规范打开损坏的文档并断言正文加载，然后代理修复代码直到该规范变绿。一个渲染器更改在代理声称完成之前运行单元套件和类型检查。

如果代理无法端到端地展示更改有效，则它尚未完成。

7. 可视化界面

目标：展示工作。

此支柱解决的中断模式： 代理无法以有用的形式向人类展示结果，因此决策、差异和工件消失在无人真正审查的聊天文本墙中。

很多软件工作是可视化的。Markdown审查、UI原型图、架构图、数据模型、差异、截图和草图是任务输入的一部分，而不是演示点缀，因此它们属于代理工作的工作空间。

可视化界面是代理工作的地方，也是我们审查其行为的地方，在同一个地方。当文本或静态可视化不是合适的格式时，语音、交互式提示和逐步讲解是该工作空间编排的渠道。

在我们的控制层中，这意味着：

• 一个工作空间，其中原型图、差异和追踪器条目并排放置，因此被审查的东西和代理工作的地方是同一个地方。

• 一个Markdown编辑器，具有代理编辑的红/绿差异，以及跨会话中代理接触的每个文件的差异审查。

• 原型图、图表和数据模型编辑器作为一级文件类型，代理可以直接读取和生成图像和截图输入。

• 内联图表和渲染截图返回在对话中，因此数值结果和UI更改不会消失在文本墙中。

• 对高风险操作如合并、部署和推送到main的审批关口，在批准前在一个视图中显示差异和链接的工单。

• 与追踪器条目、差异和决策相关联的线程讨论，因此推理与工件相邻，而不是消失在聊天工具中。

• 持久化的交互式提示组件，用于分支决策、多字段输入和审批，因此阻塞性问题在导航和重启后仍然存在，而不是埋在聊天中。

• 当代理需要引导用户通过流程时，覆盖在同一UI上的逐步讲解和工具提示。

• 当用户想听和说而不是读和打时，同一会话的语音频道。

• 会话结束时的团队交接帖子，总结交付了哪些内容、哪些仍在进行中以及还存在哪些风险。

代理可以编辑原型图、渲染、将其与需求截图比较，然后在合并前在同一工作空间中审查红/绿差异。一个可视化工作空间使决策与工件相关联，而不是将它们埋在聊天中。

8. 协调

目标：追踪每一个代理。

此支柱解决的中断模式： 并行运行多个代理的人类会失去对谁在做什么、在哪里做以及为什么做的追踪。工作进入标签页墓地，没有共享记忆或交接。

一个代理在一个会话中是起点。实际的产品工作需要多个：规划者、实现者、审查者、研究者、错误修复者，有时会有十几个会话在不同分支上并行运行。协调是运行所有这些的人类保持单一概览的方式：谁在做什么，交接点在哪里，哪些会话接触了哪些文件，还有哪些未完成。

在我们的控制层中，这意味着：

• 具有持久元数据（名称、标签、阶段）的会话在看板板上列出，因此团队可以一目了然地看到每个代理在做什么。

• 工作流将同一问题的相关会话分组，这样花了五个会话才追踪到的错误保持连接。

• 一个元代理，使一个会话可以派生和监督其他会话：跨拉取请求的并行审查者，一个验证修复端到端的兄弟会话，长期运行的背景工作并在完成后回传。

• Git工作树和隔离的开发实例，使多个代理可以编辑同一个仓库而不相互干扰。

• 会话结束或派生子会话时的交接简报，使下一个会话继承文件、链接和约束，而不是从空白提示开始。

• 文件编辑历史与产生它的会话相关联，因此重叠的工作在变成合并冲突之前是可见的。

一个错误分类会话可以派生一个兄弟在隔离的工作树中复现问题，然后第三个编写失败的测试，然后第四个在功能分支上实现修复。每个都继承父会话的相关部分上下文，尽可能并行运行，并报告回同一个工作流。有了这个支柱，控制层本身追踪谁在做什么，在哪里做，以及为什么做。

一个错误，全部八大支柱

一个实际例子，来自我们运行的一个真实工作流。错误：重启后，一个同步的追踪器条目显示为空正文。正文在本地数据库中存在，但服务器端协作文档被错误地初始化，因此下一个打开该条目的会话什么也看不到。

八大支柱如何体现：

• 上下文。 会话加载了CLAUDE.md，它指向了同步架构文档和CollabV3数据隔离规则。一个关于Y.Doc初始化的路径作用域规则自动加载，因为会话触及了同步目录。

• 溯源。 错误被提交为追踪器条目，链接到四个先前的会话，这些会话曾宣布“已修复”但实际并未修复。打开追踪器显示了按时间顺序的链条，因此新会话继承了已经尝试过的方法，而不是重复。最终的修复作为关闭说明被放入追踪器中。