SuperAPI AI 工具集

draw-the-owl

智能体与模型

查看项目

更新于 10-16 08:30

技能介绍

用途

Draw the Owl 是一种与 AI 智能体协作构建功能的模式,来自 Mitchell Hashimoto。它的核心洞察是:智能体功能工作的约束不在于代码能否运行,而在于人类能否审查。一个你无法审查的 diff 就是一个你无法信任的 diff,无论测试多么绿。因此这个循环优化的是把改动缩小到你的可审查阈值以下,而不是一次性得到一个能工作的功能。

名字来自“画猫头鹰”梗——第一步:画两个圆;第二步:画出剩下的猫头鹰。第一个提示故意就是那么欠明确:松散地引导智能体实现整个功能,并预期得到垃圾。垃圾不是交付物,它是侦察——它揭示问题的真实形状,以便你把它切分成值得审查的片段。

何时使用

  • 用智能体实现非平凡或全新的功能。
  • 智能体产出的 diff 难以有把握地审查——通常是因为它很大(粗略地超过约 1500 行可审查行),但要判断的是审查工作量,而不是原始行数。
  • 用户称某个改动“太大”“要审查的太多”,或要求“拆分这个”/“拆成更小的 PR”。
  • 规划如何把功能工作分散到多个并行智能体上。
  • 任何“直接把整个东西做出来”的请求,而你希望得到可维护、可审查的结果,而不是一个巨大的不可审查提交。

何时不使用

  • 小型、自包含的改动,显然会远低于阈值——修 bug、重构一个模块、调整配置。拆分这些纯属额外开销。
  • 机械式、统一的扫描(重命名、codemod、依赖升级),diff 很大但每个 hunk 形状相同,审查起来很简单。大小是审查工作量的代理,不是目标本身。
  • 纯探索或研究,不合并任何代码。
  • 工作本身已经是一串干净的小提交——你已经越过了这个问题所解决的阶段。

循环

1. 画猫头鹰

提示智能体实现整个功能,松散引导。不要过度指定;重点是看智能体伸手去够什么、改动实际触及什么。预期结果是错误的、蔓延的,或两者兼有。这是预期结果,不是失败——你买的是关于问题形状的信息,不是可合并的改动。

2. 对照预算衡量

看 diff 大小。

  • 低于约 1500 行:正常审查并迭代。你低于可审查阈值;猫头鹰已经好到可以就地精修。到此为止——不要为了拆分而拆分。
  • 超过约 1500 行:改动太大,无法好好审查。不要硬着头皮审查。拆分(第 3 步)。

1500 行这个数字是启发式,不是定律——它是“超过我一次审查能装进脑子”的代理。根据代码库和你自己的审查耐力调整它:密集、不变量繁多的核心代码需要更小的预算;样板多或测试充分的表面可以容忍更多。重要的是有一个阈值并尊重它,因为它防范的失败模式是给一个你并未真正理解的 diff 盖章。

衡量时扣除可轻松审查的体量(生成文件、锁文件、大规模重命名)——那些行不消耗审查工作量。大小代表审查工作量;判断工作量,而不是原始计数。

3. 拆分成原子任务——并泛化它们

让智能体把问题拆成原子的、增量的、可独立审查的任务。你自己也并行做一遍并比较——智能体的拆分和你的会在有信息量的地方不一致。

关键的人类步骤:智能体会把拆分过度拟合到它刚产出的具体方案上。它们会给你形状像“提取我碰巧写的 parseFooBarResponse 辅助函数”的任务,而不是功能实际拥有的通用、持久的接缝。把任务列表按摩回正确的通用形状——无论这只猫头鹰是怎么画出来的,那些边界都会存在。这是你的架构判断力发挥作用的地方;这是智能体无法可靠完成的部分,因为它只能从自己的第一次尝试来推理。

好的接缝通常是:数据模型/模式变更,然后是消费它们的层,然后是 UI/API 表面,然后是接线和测试——每个都作为足够小、可独立审查、最好可独立合并的改动落地。

此时如果猫头鹰的代码是垃圾就扔掉。它的工作是教你拆分;各个片段要重新构建。

4. 分派片段,递归进行

在增量任务上启动新智能体,在依赖图允许的范围内并行化。每个片段本身也受同一规则约束:如果子任务的 diff 超出预算,也拆分它。循环是递归的——你不断切分,直到每个落地的改动都可审查。

要同时运行多个智能体,这正是 tmux-pm 模式:一个 PM 会话在隔离的 worktree 中分派有界 worker,每个负责一个原子任务,回报以供审查和合并。要把单个拆分后的任务交给一个干净上下文的新智能体,使用 handoff 技能来写任务提示。前沿模型在高/xhigh 努力下运行得足够慢,你可以在积极审查其他部分或做自己工作时保持几个片段在飞行中——延迟是特性,不是成本,因为它匹配人类审查的节奏。

5. 重画猫头鹰

定期对剩余部分重新运行“画猫头鹰”提示。随着拆分后的片段落地,剩余功能缩小;某个时刻,一次全新的整体功能尝试会回到可审查阈值以下,你就完成了——最后一只猫头鹰就是可合并的。这是收敛条件:不断画猫头鹰并切分,直到有一只合适。

一个底线情况:有些功能有一个不可约的核心,本身就超预算——单个密集状态机、协议编解码器——没有任何接缝能把它切得更小。当最小的诚实接缝仍然超过阈值时,停止递归。改为缩小每轮预算,缓慢而审慎地审查那个核心,最好结对进行;拆分已经尽力了,剩余成本是真实的审查注意力,而不是更多切分。

保持人类在环

这个模式故意是人在环中的,而功能工作正是这一点最重要的地方。功能触及人类边界——UI、API 形状、命名、产品行为——没有测试能完全钉住,而全新代码可能引入违反你从未写下的不变量的架构病理。审查阈值的存在是为了让人类在这些边界决策固化之前真正看到它们。把你能够编码的不变量写进规格和测试,以便未来的轮次机械地捕获它们,但假设规格是不完整的,并亲自审查接缝。

连续的智能体驱动智能体循环有其位置,但对于日常把事做完的功能工作,上述可审查片段循环是更高产的模式:每个片段落地时要么可直接合并,要么只需轻微的人类精修。

检查清单

  • 第一次尝试是松散的“画猫头鹰”提示,而不是过度指定的。
  • diff 对照审查工作量预算(约 1500 行,已调整)衡量——比较前减去生成/锁文件/重命名行。
  • 如果超预算:由智能体和你分别拆分,然后调和。
  • 智能体提议的任务已从一次性方案的形状泛化开。
  • 片段已分派(尽可能并行),每个都重新对照预算检查,必要时进一步拆分。
  • 随着片段落地重画猫头鹰,直到剩余部分可审查。
  • 人类审查了人类边界接缝(UI/API/命名/不变量)。

另见

  • tmux-pm——编排构建拆分片段的并行 worker 智能体。
  • handoff——为交给另一个智能体的每个拆分片段写干净上下文的任务提示。