Agent 可以很快写出一份设计说明。系统分层清楚,术语专业,末尾还有几条优点。读完以后,我往往能复述它的方向,却回答不了最关键的问题:数据究竟从哪里进入,经过哪个模块,谁修改状态,接口返回什么,失败以后怎么办?
作为程序员,我希望先用五到十分钟建立整体模型,再把注意力收缩到一个接口或一次状态变化。检查这个局部以后,还要能反推它对整个设计的影响。这个时间是阅读设计的目标,不是对所有读者的效率承诺。难点在于,很多 Agent 输出把关系埋进了长段概念里;追问一个细节,又不断扩展出新的话题。
我希望得到一种更友好的表达:读者能建立模型,找到局部,核对依据,并保留一个可以继续推进的结论。
Andrej Karpathy 关于理解模型输出的这条推文提供了一个很好的起点。他谈到用 ASD-STE100 改善文字,随后把注意力推进到图解、交互网页和定制讲解视频;随着模型承担更多执行工作,人类会花更多精力理解和监督结果。这里的重点包括为当前问题制作专用的可视化软件。原帖页面在本次核验中无法直接读取,推文内容通过可访问的文字镜像交叉查看;作者自己的年度回顾也讨论了图形界面与视觉输出。
在这个方向上,我想补上软件工程的审查经验:丰富的呈现方式应该让关键关系和证据更容易被检查。下面的三种视角是我的综合方法,并非 Karpathy 提出的一套三层标准。
三种视角共同设计同一份输出
| 视角 | 首先解决什么 | 应该让读者看到什么 | 单独使用的局限 |
|---|---|---|---|
| STE100 的语言原则 | 句子如何减少歧义 | 稳定术语,明确的主体、动作、条件和结果 | 一句话可以说得很清楚,却仍然是错误的结论 |
| 软件工程的可审查表达 | 哪些关系影响设计判断 | 边界、责任、契约、数据与状态,以及判断的依据 | 结构正确的文档仍可能难以阅读和操作 |
| Karpathy 提倡的视觉与动态呈现 | 人如何直接观察关系和变化 | 图解、关键帧、可暂停视频、可控交互 | 一个漂亮演示也可能隐藏假设或简化真实系统 |
图中的三条输入共同作用于同一份材料。换用交互网页以后,术语仍要一致;画出架构图以后,模块责任仍要能追到代码或契约。它们有重叠,也会互相约束,适合联合使用。
STE100 约束说法,也提醒我们保留条件
这里的准确名称是 ASD-STE100 Simplified Technical English。官方 FAQ说明,它是一种面向技术文档的受控英语,包含写作规则和受控词典。词语通常限定一种含义和一种词性;短句、单句聚焦一个主题、主动语态等原则,也可以借用于其他写作场景。
中文技术解释可以借用其中的原则,但不能据此声称符合完整的英语标准。下面是一个自拟的设计说明示例。
系统通过灵活的调度机制优化处理,并在需要时更新相关状态。
这句话短,信息却无法审查。谁调度?什么条件触发更新?哪个状态由谁持有?“优化”对应什么观察量?
假设这些约定确实已经存在,可以改成:
Worker 从队列取出任务。任务执行成功后,Worker 将结果写入结果库,再向队列确认完成。写入失败时,Worker 不确认任务;队列按重试策略重新投递。
这段话给出了主体、动作、顺序和失败条件。下一步就能检查结果库写入与队列确认之间的间隙:如果写入成功后进程退出,重试是否会重复执行?缺失的机制要标为未知或建议,不能为了让句子完整而补成既有事实。
少歧义不等于技术正确。 ASD 对 STE 工具的说明也强调,检查工具无法代替作者的判断。对 Agent 来说,语言整理和事实核验都要完成。
文字的组织形式同样要服从关系:并列责任用列表,真实步骤用编号,方案或字段映射用表格,因果推导用连贯短段。把一篇长文切成二十条,仍然可能找不到数据流;把每句话都变成独立段落,也会让读者自己补回逻辑。
软件工程提供的是审查入口
一份设计需要优先呈现那些会改变判断的关系。对异步任务系统,关键可能是状态归属与确认时机;对图像算法,关键可能是读取哪一代数据与写回位置;对缓存系统,关键可能是版本、失效范围与并发行为。
Google 的代码审查指南把整体设计、组件如何交互、功能正确性和复杂度列为重要检查对象,并要求结合周围系统理解修改。John Ousterhout 的书籍介绍强调控制复杂度,也专门讨论如何决定哪些事情重要。这些经验可以迁移到 Agent 的设计说明中;不同书籍对细节的主张并不完全一致,不能把所有写法合成一个强制模板。
对于工程设计,可以先展示下面这些判断入口,再按当前问题深入:
| 检查对象 | 第一时间需要明确的关系 |
|---|---|
| 边界与责任 | 系统处理什么,各模块拥有什么,不覆盖什么 |
| 数据与状态 | 输入来自哪里,谁读取、转换、写入,状态何时生效 |
| 接口契约 | 输入输出、前置条件、失败和取消语义 |
| 依据与取舍 | 哪段实现、哪条约束或哪项测试支持这个选择 |
| 整体影响 | 修改局部后,哪些假设、调用方或行为会变化 |
自描述能力并不意味着读者永远不需要查资料。它意味着这份材料脱离聊天后,仍然有范围、术语、图例、假设和证据入口。图中的箭头要说清表示调用、数据流还是依赖;对真实实现的判断要对应文件、符号和版本;代码没有表达出来的设计原因,需要一段短说明。
同一个公式,动态演示能揭示什么?
考虑五个数的一轮三邻域平均。输入为 A = [0, 0, 9, 0, 0],索引为 0–4。首尾保持为 0,仅更新内部三个位置。同步规则是:
B[i] = (A[i-1] + A[i] + A[i+1]) / 3,i = 1, 2, 3
本轮所有读取来自同一个旧数组 A;结果写入 B。
另一段代码直接读取并覆盖工作数组 W:
const W = A.slice();
for (const i of [1, 2, 3]) {
W[i] = (W[i - 1] + W[i] + W[i + 1]) / 3;
}
公式看起来相同,读取规则已经不同。最值得停下来检查的是第二次更新。

图中 READ OLD A 表示始终读取旧数组,READ CURRENT W 表示读取正在变化的工作数组。同步版本的左邻居仍是 0;直接原地版本的左邻居已被第一次更新写成 3。差异来自输入代际。
下面的无声视频用十秒展示初始状态、三次更新和最终结果。可以暂停在第二次更新,比较两个算式。
视频适合先看到演化。进一步审查时,读者需要停在某一步,或改变一个能区分规则的条件。下面的交互页面提供步进、重置和遍历方向切换;它默认不自动播放。
独立打开交互演示。如果嵌入页面无法使用,下面保留同一模型的静态结果。
| 读取规则 | 从左到右更新 | 从右到左更新 |
|---|---|---|
| 读旧 A,写 B | [0, 3, 3, 3, 0] | [0, 3, 3, 3, 0] |
| 直接读写当前 W | [0, 3, 4, 4/3, 0] | [0, 4/3, 4, 3, 0] |
改变方向以后,同步版本的结果保持不变,直接原地版本的结果变成镜像。读者可以据此提出更具体的问题:“需求是否要求整轮读旧值?实现有没有读到已更新邻居?”
这里还有一个容易漏掉的边界:原地写入本身不必然违反同步规则。 从左到右更新时,如果缓存被覆盖的旧左邻居,也能在这个一维例子中得到同步结果:
const C = A.slice();
let oldLeft = C[0];
for (let i = 1; i < C.length - 1; i++) {
const oldCurrent = C[i];
C[i] = (oldLeft + oldCurrent + C[i + 1]) / 3;
oldLeft = oldCurrent;
}
// C = [0, 3, 3, 3, 0]
因此,应审查实际读取的数据,而不是仅凭缓冲区数量下结论。直接原地更新也可以是另一种算法;只有需求规定同步时,上面的直接读写版本才不满足契约。
这份演示已经用断言核对两个方向的逐步数值,并检查交互模型与视频轨迹一致。它只覆盖五个数、固定边界、一轮更新;没有测量性能,也没有验证真实系统的线程调度、GPU 内存可见性或资源生命周期。
让讨论形成“面 → 点 → 面”的审查循环
这个例子体现了我希望 Agent 支持的阅读过程:
- 建立总览。 先确定输入、更新范围,以及整轮读取旧值的规则。
- 聚焦局部。 停在索引 2,不必重读所有背景。
- 追到依据。 比较读取的三个数、公式和对应代码。
- 回看整体。 检查遍历顺序能否改变结果,判断读取规则是否满足需求。
- 保留结论。 记录已经确认的内容、成立条件和未验证部分,继续下一个影响设计的点。
在真实项目里,局部可以换成一个接口、一条失败路径或一次资源释放。这里的“下钻”是呈现可检查的对象和依据,读者无需查看 Agent 的隐藏思维过程。
一个可继续使用的结论记录,可以很短:
| 项目 | 当前结论 |
|---|---|
| 焦点 | 本轮是否全部读取旧数组 |
| 条件 | 一维三邻域、边界固定、只做一轮 |
| 依据 | 第二步读取值;两个遍历方向的轨迹;对应代码 |
| 已确认 | 直接读写当前 W 的版本不满足本例的同步规则 |
| 保留项 | 缓存旧邻居可以实现同步;真实并发与性能仍需验证 |
这样的记录是后续讨论的锚点。用户继续问“只看边界处理”时,Agent 应保留已有术语和结论,把注意力集中到边界。会改变当前判断的依赖必须展开;无关的性能优化或界面建议可以暂存。新证据改变前提时,应明确修订锚点。
这个循环也不要求用户在每个步骤点击批准。Agent 可以自主完成已授权的研究和检查,再把需要判断的对象呈现出来。可审查表达要减少重建上下文的负担。
媒介选择要对准观察目标
Karpathy 对视频和交互的重视值得认真执行。复杂关系已经出现时,Agent 应主动制作能观察它们的材料;如果只在长文结尾建议“可以配一张图”,读者仍然承担着还原关系的工作。
不过,不同媒介承担不同任务:
| 阅读任务 | 优先制作的材料 | 保留什么以便审查 |
|---|---|---|
| 找到系统边界与依赖 | 架构或责任关系图 | 图例、模块定位、契约入口 |
| 跟踪数据读取与写回 | 数据流图与字段映射 | 中间状态、代码符号、输入输出 |
| 理解时间或空间演化 | 短视频、动画、关键帧 | 暂停或重放、规则、静态步骤 |
| 探索参数或反例 | 可控交互页面 | 当前参数、观察量、源码与简化假设 |
| 比较选择及依据 | 条件明确的表格 | 来源、取舍、未知项 |
图片和视频不需要越多越好。一个简单事实可以直接回答;复杂算法则可能需要动态材料。选择标准是读者能否看到那个决定结果的变化、能否停下来检查它。
还要区分三种状态:模型已理解、推导成立、实现已验证。 十秒视频可能迅速帮助理解一个局部;要确认推导,需要检查规则和反例;要确认实现,需要对应版本的代码与实际验证。不能把“我看懂了”自动升级成“系统没有问题”。
放进 Skill、博客规则和 Harness
如果希望这种表达稳定出现,需要同时改写默认行为和交付方法。
| 位置 | 适合放什么 | 如何检查生效 |
|---|---|---|
| 通用解释 Skill | 总览与局部审查、术语一致、焦点与结论锚点、媒介选择 | 简单问题不膨胀;复杂问题能定位到输入、状态和依据 |
| 博客写作规则 | 文章主线、来源、独立阅读所需的上下文、图文与演示 | 脱离聊天仍可理解;读者能下钻并回看主问题 |
| Harness system prompt | 简短稳定的默认要求 | 日常会话保持明确、聚焦,并区分演示和验证 |
| Harness 按需 Skill | 完整方法、示例与接入适配 | 根据真实加载机制触发,复杂任务使用正确媒介 |
| 宿主呈现能力 | 图、网页、视频与静态后备 | 实际可打开、可操作,图文和实现规则一致 |
对我自己的 DSH harness,合理的落点是短 system prompt 加按需加载的完整 Skill。先检查 DSH 当前的提示词注入、Skill 加载和渲染接口,再接入真实能力;不能编造配置字段,或者把全部方法重复注入每一层。接入说明和文件准备完成,也不等于已在 DSH 部署验证。
评估时可以使用真实问题:读者能否指出关键关系?能否预测输入变化后的结果?能否找到假设、依据和反例?能否从局部回到整体判断?无需用字数、图片数量或主观总分来代替这些检查,也不应提前承诺某个固定的 token 节省或阅读速度提升。
在关于 Agent 协作疲惫的讨论里,问题是人如何持续把控工作;在Agent 时代的代码质量讨论里,问题是产物如何保持清楚和可维护。这里延伸到输出本身:随着 Agent 承担更多工作,一份友好的解释应该让人找到值得关注的点,并有依据地决定下一步。
STE100 帮助句子减少歧义,软件工程帮助选择审查对象,图解、交互和视频让关系与演化可以被直接观察。它们共同支持的目标,是让人保持理解和判断的能力。