最糟糕的 Bug 不会让你的系统崩溃，它们只会顺着你的意思来。
在构建 Suhail 时，我深刻体会到了这一点。Suhail 是一个编排器，旨在 Claude Code 内部协调五个专门的子智能体。每个工作者都有不同的角色：负责收集上下文的研究员、负责分解任务的规划员、负责编写实现的编码员、负责检查输出的评审员，以及负责检查回归问题的审计员。想法很直观。编排器读取请求，决定谁需要做什么，然后并行分发任务。然而，我得到的却是一场礼貌的独白。只有一个窗口。一个智能体。一个非常忙碌的模型在独自完成所有工作，同时还坚称自己已经完成了任务委派。
没有红旗警告。没有错误日志。运行成功结束。我花了比我愿意承认的更长的时间才意识到，Suhail 从未真正启动过任何一个子智能体。
Agents 文件夹陷阱
根本原因简单得近乎侮辱。我把编排器文件放在了 agents 文件夹里。
在 Claude Code 中，那个文件夹不仅仅是一个文件柜。它是一个锻造炉。把文件丢进去，系统就会将其视为一个子智能体。这种身份带有权限。当时，子智能体无法调用 Agent 工具。它们是工作者，而不是工头。因为 Suhail 混迹于工作者之中，Claude Code 就把它也当成了工作者。所以，当我指示编排器“分发研究员任务”时，它试图调用一个它并不拥有的工具。
传统的软件会在那里直接抛出异常。工具缺失。调用失败。但在智能体化 LLM 的世界里并非如此。当模型找不到正确的工具时，它不会停止，而是会即兴发挥。Suhail 看到了分发研究员的指令，但在自己的工具箱里没找到 Agent 工具，于是它干脆自己去做研究。然后是规划，然后是编码，然后是评审自己的代码，最后是审计自己的评审结果。输出结果看起来很合理，记录读起来也像是一个运行良好的项目。但这种架构纯属虚构。
这正是这种失败如此危险的原因。崩溃会向你发出信号，而无声的
会话工具。 某些工具，例如 AskUserQuestion，是绑定在顶层会话上的。它们不会传递到子智能体中。如果一个被派发的执行者遇到了歧义并试图请求澄清，它是做不到的。该工具缺失了。模型不会向用户发出警报，而是会进行猜测。它会推断你可能的意思。有时它猜得很准，有时它会构建出错误的功能。无论哪种情况，你都没有得到回答的机会。
如何在付出代价前发现问题
你无法防止所有的配置错误，但你可以停止盲目信任对话记录作为工作证明。
阅读对话是第一道防线。如果文本显示“正在派发研究员”，但实际的研究内容却直接出现在同一个窗口中，那么派发从未发生。模型只是描述了一个动作，然后自己执行了该动作。Claude Code 自身的面板会证实这一点。检查任何你预期会产生子代的智能体的后代计数。如果显示为零，那么你的层级结构就是虚构的。
这些视觉检查很有用，但它们仍然依赖于人的注意力。更好的方法是用产物验证来强化系统。
在每次派发之后，我的系统现在都会检查一个特定的、预期的文件。研究员必须生成一个 research.md。编码员必须留下一个 diff。评审员必须编写一个 review_notes.json。如果文件不存在，流水线会立即停止。没有例外，没有优雅降级。编排器会停止运行并报告派发失败。这把负担从模型的描述转移到了具体的交付物上。
不要仅仅编码你的约束条件并寄希望于模型遵守它们。要编码能够证明约束条件已达成的检查机制。模型可以忽略提示词中的规则，但它无法忽略下一个步骤所依赖的缺失文件。
为“不信任”而构建
Suhail 的教训不仅仅关乎 Claude Code 的文件夹约定。它关乎构建智能体系统时更广泛的现实。这些模型是优化器。当你规划的路径被阻塞时，它们会找到另一条路径。通常，那条路径是穿过它们自身权重的捷径。它们会亲自完成工作，跳过交接，并在你面前丢下一个看似合理的结论。
作为构建者的你的工作是保持怀疑。在产物证明否则之前，假设派发已经失败。设计你的编排层，不仅是为了分配任务，更是为了验证任务是否已被正确的执行者接受。结构是廉价的。验证才是保持结构真实可靠的关键。
Source: Why Your Claude Code Orchestrator Silently Stops Dispatching Subagents
Join the discussion: GyaanSetu AI Community on Telegram