氛围编程 和 智能体开发 最佳实践

想象一个场景。机器人回复「会议室已经订好了。」用户打开日历，那里却没有预约。查日志才发现，服务只收到了请求，事务并未提交。如果开发这个机器人的编码 Agent 此时也汇报「接入完成，测试通过」，你就得检查两次「完成」分别指什么。

做氛围编程时，可以先用原型弄清用户想怎么操作，再运行真实流程，检查改动有没有带来预期结果。开发替用户办事的智能体时，要让工具回执、业务状态和用户收到的答复对得上。小哈公社介绍的 REA 案例从一个老游戏讲起，展示了怎样一步步找到可核对的结果。 《REA作者一个人，重新发明软件开发》

DX-Ball：从漏掉参数的伪代码追到 63 个字节

DX-Ball 是一款 Windows 打砖块游戏。重建项目要恢复一个小功能：砖块在屏幕哪一侧被击中，声音就该偏向哪一侧。REA（Reverse Engineer Anything）把 Ghidra 等分析工具接到 Agent 可调用的 CLI 和 MCP 接口上。这个案例里，Ghidra 把声像辅助函数显示为无参数，伪代码里主要剩下一次类型转换调用。照这份伪代码写 C，编译器照样可能给出一个可运行的函数。 REA 项目 · DX-Ball 取证记录

调查的转折点是换一种方式看同一个函数。指令视图显示，它从栈上取了一个整数。再往上一层看，砖块命中的调用方把坐标乘以 30、加 20，然后把结果压栈。回到函数内部，顺着浮点指令引用的地址读字节，可以解出 1.5625、500 和一个单独存放的缩放值。计算顺序是先乘 1.5625、减 500，再乘缩放值，最后转为整数。指令和字节是观察所得，常量数值是按字节序解码所得，“参数表示屏幕横坐标”是结合调用方作出的解释。几类信息都有位置可查，后续的人可以从其中一步重新验证。 指令、调用关系与字节读取记录

重建代码有两份验证。第一份把 0 到 640 的 641 个位置与五个缩放值组合，做了 3,205 次原始 x86 函数行为对比。第二份在指定的 VC4.0 环境中编译，应用核查过的重定位并核对引用常量，得到完整函数 63 个字节一致。前一份回答这些输入的结果是否一致，后一份回答指定工具链能否复现函数。游戏里声音何时触发、其他调用方怎样传参，仍要到相应入口验证。这些数字来自项目公开记录。 重建后的 C 函数 · 验证范围

做氛围编程也会遇到同样的断点。一个“改到明天”的原型很快就能拿来问用户：改期时是否保留时长，遇到冲突要不要给备选时间？一旦要接真实日程，就得接着查时区、权限、事务和重复投递。原型回答交互怎么设计，业务验收要能指出具体哪条记录发生了什么变化。

动手之前，先把问题找对

GitContribute：从一条 Issue 走到最小回归

接手一个陌生仓库，先看现行约束、相关 Issue、已经尝试过的 PR 和当前实现，才知道哪里值得改。GitContribute 把这些材料和验证结果存入本地 SQLite。同步远端和检索已同步的资料是不同动作。工作区执行还有单独的能力入口。这样，Agent 查到“没有相关 PR”时，可以同时看到资料是否同步过、结果有没有截断、当前身份能看到什么。旧缓存里的空结果只说明这份缓存没查到。 GitContribute 架构与能力

Triton 的一个真实修复很适合演示这种调查。自动调优先把十个配置筛到六个，再用性能模型排序。用户设了 top_k=0.5，按筛后集合应该对三个配置跑基准测试，实际却跑了五个。多跑的配置也合法，结果看起来正常，常见的输出正确性测试发现不了这笔额外开销。报告还查到更早的一次修复已保证向下取整后至少保留一个配置，分母仍然是原始集合。 Triton Issue #10964

合并的补丁把分母改为筛选后的集合长度，保留至少一个配置的保护。新增回归走自动调优入口，通过可记录的性能模型和基准测试回调，断言六个候选都被估算，只有前三个进入基准测试。这份回归锁定的是筛选行为。若要再声称 GPU 调优节省了多少时间，还要跑真实负载。这个案例可以直接借到业务开发里。先写下应该发生的业务动作和次数，再让测试观察这些动作，结果往往比只检查返回值更清楚。 已合并的 PR 与回归差异

LeanToken：工具结果变短，整项任务可能更贵

LeanToken 做的事是让 Agent 有针对性地检索文件、符号和代码范围。它最有意思的材料是一轮失败实验。项目对比了三种做法：较宽的原生仓库探索、较轻的原生探索，以及使用 LeanToken 的结构化检索。固定四个文件定位任务，每个任务在每组重复五次，每轮共 60 次。成功按是否找齐预先标注的实现和测试路径计算。输入计量覆盖这次任务的父子 Agent，表中请求数是子 Agent 发给模型提供方的平均请求数。 LeanToken 测量方法与公开运行样本

轮次与方法	找齐路径	子 Agent 平均请求数	每次平均输入 Token
第一轮 · 较宽原生探索	13/20	5.05	152,934
第一轮 · 较轻原生探索	13/20	4.70	119,910
第一轮 · LeanToken 多次检索	11/20	8.20	180,980
第二轮 · 较宽原生探索	13/20	5.15	155,378
第二轮 · 较轻原生探索	12/20	4.90	121,397
第二轮 · LeanToken 集中交付上下文	15/20	3.75	96,967

第一轮的 LeanToken 比较轻的原生组多用了 50.9% 输入。返回的源码片段已经很短，多次检索仍引发了更多模型请求，每次请求又带上会话与工具上下文。第二轮只允许先取一份集中打包的上下文，缺少必要实现或测试文件时才补一次定向搜索，并重新跑了两个原生对照组。相较于本轮较轻和较宽的原生组，总输入分别减少 20.1% 和 37.6%。实验里有个 Express 任务在两轮所有组都没找到完整路径，报告保留了这条失败。数字适用于这四个定位任务、当时的模型和协作配置，补丁能否写对需要另外验证。 同一实验的两轮对照与限制

实际开发时，可以先用熟悉的代码搜索拿到入口、行为合同和相关测试。确实存在跨仓库或跨语言的检索困难，再考虑专用索引。衡量收益时，从用户提出任务一直数到拿到可用证据，连同工具说明、补查、重试和交接一起计量。每条工具响应省下来的字符，只占这笔成本的一部分。

把能检查的部分交给验证器

Jacobian 把数学操作做成可查询的合同。Agent 可以先看某项操作接受什么输入，再调用并得到有类型的结果。例如给出一个有理数矩阵，让工具返回精确行列式，就能把“计算这个值”的工作从对话中抽出来复查。作者在研究笔记里谈到，让模型临时编写计算脚本时，脚本本身也会出错和返工。对反复出现且有明确输入输出的计算，复用 SymPy、Python-FLINT、Z3 等已有后端，可以把注意力留给选择计算对象、检查假设和解释结果。 Jacobian 操作与后端 · Morluto 的研究笔记

Erdős #81 的候选证明提供了一个更难的例子。研究仓库同时保留了精确计算结果、有限证书的回放脚本、手稿和 Lean 形式化。项目记录的主回放检查了 7,964 份线性规划证书与 1,889 步变换。Lean 的主要结论则显式接收 ExternalInputs.Inputs，把三项外部数学接口留在定理边界上。有限回放覆盖具体实例，Lean 检查给定这些输入后的推导，手稿和外部条件仍需要独立专家审查。 Jacobian 计算结果样例 · 形式化边界与审查状态

最能迁移到日常开发的是他们给验证器准备的一份坏输入。某份证书声明每个块最多有三个顶点，测试故意交给验证器一个四顶点团，要求它拒绝。这样才能查出验证器是否真的检查了大小上限。预约场景也可以故意让测试替身返回一份结构正确的“成功”回执，同时保持业务记录原样，检查验收流程是否会判失败。再故意用越权身份发出格式正确的请求，检查真正的服务入口是否拒绝。写出能通过的用例，也写出一旦关键检查失效就会被误放行的用例。 验证器的反例与修订

性能优化先找热点，再证明改动有用

看到报价系统里有一段嵌套循环，可以怀疑它在做重复工作。看到接口偶尔很慢，也可以怀疑一次业务操作触发了多次数据库往返。这是两条不同的调查线。SmokingGun 静态扫描代码，给出值得检查的复杂度模式，并可导入已有测量资料。flameox 则协调 profiler、benchmark 或 trace 工具，围绕明确的命令或输入记录运行环境、观察结果和覆盖范围。前者有助于选择测哪里，后者有助于回答那段代码实际占了多少时间。 SmokingGun 的扫描与证据边界 · flameox 的采集合同

以会议改期为例，可以在同一批合成数据、相同并发和缓存条件下，分别测旧版和候选版。若猜测瓶颈在查询，先看每次改期发出了几次查询、哪段耗时，再比较请求的中位数和尾部延迟。如果优化后请求快了，还要在同一批样本上核对改期结果、冲突拒绝和越权保护。Triton 的测试能数出多执行的基准次数，DX-Ball 的测试能对照函数结果。这两种证据配起来，才足以解释改动省掉了什么工作，以及业务行为有没有随之变坏。

AGENTS.md 先写给真正会读它的人

规则文件的价值，可以顺着一次失败检查。REA 的 AGENTS.md 要求找到错误第一次发生的边界，再检查同类入口有没有复制同一个错误。譬如底层把“未知”变成了某个默认值，只改 CLI 的文案，MCP 仍可能报出虚假的确定结果。REA 的验证工作流还有一个具体例子：在真实 Ghidra 上经生产桥接代码检查 ARM、Thumb 和 MIPS 指令上下文，并在 ARM 用例里注入不可用值，看桥接层能否保留未知状态。测试运行在实际分析引擎上，输入指令字节供分析使用。 REA 的 AGENTS.md · Ghidra 验证工作流

对读几个仓库，会发现同一原则需要不同的执行入口。GitContribute 在规则里要求保留缺失和过期资料的未知状态，工具合同把已同步资料的查询、主动联网取证和获准运行命令分开。LeanToken 要求检索保持确定性、精确的 Token 预算和一致的索引快照，微基准即使更快，也仍要通过这些正确性检查。REA 安装器则把即将发生的配置写入列出来，在写前取得批准。规则可以告诉模型该怎样选择工具，真实权限还要由工具与服务执行。 GitContribute 开发规则 · LeanToken 开发规则 · REA 的配置与权限规则

规则过宽也会让 Agent 卡在错误的地方。REA 有个真实 Issue：运行完整的 doctor，可能看到某个可选分析引擎或其他客户端注册失败，眼下要做的静态 JavaScript 分析却可以直接跑。已有命令也能按所用引擎做定向检查，合并的修订把这种区别放进快速上手。写项目规约时，遇到环境缺项，先问它影响当前哪一步。能完成的任务继续走，依赖这项能力的结论保留为待验。 环境检查问题与修订 · 合并的文档改动

写自己的 AGENTS.md，可以从一条维护任务反推该放哪些内容：

• 读者。 父工程的编码 Agent 需要找到源码、修改边界、测试入口和发布权限。EasyClaw 原生智能体工作区根的 AGENTS.md 会被运行中的智能体读取，应写业务上何时追问、怎样使用工具、怎样说明当前状态。维护智能体的 Git、构建和测试规约放在智能体目录之外的父工程或其引用文档。写上“仅供开发”也不会改变运行时的读取路径。
• 状态归属。 预约成功由日程服务的业务状态和回执决定。工具合同应能让调用方区分已提交、明确拒绝、处理中和暂时无法核实。模板和提示词按这些状态生成回复。
• 授权与验收。 服务端校验预约归属与可修改性。测试员从实际业务入口验证拒绝，并回查记录。测试配置、预期结果和运行证据放在被测工作区之外，避免被测对象提前读到答案。

用一次会议改期串起三个 EasyClaw 项目

从一个原型开始。用户说“把我明天上午十点的会议推迟半小时”。先和使用者核对要保留时长，确认“明天”按哪个时区解释，以及有两场候选会议时该怎么澄清。然后定义最小的成功结果。在虚构场景里，已登录用户有一条 10:00–11:00 的预约，改期后同一个预约变成 10:30–11:30，仍归该用户所有。记录里的时间、工具回执和实际送达的消息应一致。

• easyclaw-dev-skill。 从实际项目类型和开发源出发，定位原预约 API 的身份、时间和更新合同，核对当前安装版能用的调试入口。若测试环境回执与生产候选行为不一致，先查候选是否加载了预期的 CLI、Bridge 或服务版本。遇到工具缺陷，再定位与运行版本对应的源码和聚焦测试，修好后回到原调用路径验证改期。
• easyclaw-dev-robot。 模型负责把“推迟半小时”转为目标动作，遇到多条候选先澄清。业务 API 沿当前登录身份检查归属和冲突，并记录写入结果。若渠道重投，用同一业务操作标识关联请求。若写入后超时，优先按原标识回查，具备幂等合同才以同一标识重试。状态未核实时按未知或处理中答复，等拿到已提交证据再报成功。
• easyclaw-dev-agent。 在真实宿主上固定被测版本、场景和判据，两轮使用独立会话并恢复等价的初始业务数据。第一轮可直接提出改期，第二轮用语义等价的问法，遇到澄清只补充该用例允许的信息。每轮分别记下会话、工具回执和实际业务回读。缺少读取权限或真实渠道时，把相应判断记为待核实并注明原因。

下面这张表可以直接当作测试用例的起点。每个场景从可复查的初始状态开始，写入次数以业务记录或审计事实为准。

场景	应观察到的业务证据	用户收到的结果
正常改期	同一条预约移动到 10:30–11:30，归属和时长正确	回执中的日期、时区和新时间与记录一致
时段冲突	服务明确拒绝，原预约仍在 10:00–11:00	说明冲突，可按业务规则提供备选
越权改期	换成无权限账号发送有效参数，服务拒绝，目标记录保持原样	说明无法办理，并保护他人的预约信息
同一消息重投	重放同一操作，只有一次有效变更，记录停在 10:30–11:30	以已有处理结果回复
已提交但响应超时	注入响应丢失，按原操作回查确认已提交，审计显示只有一次写入	状态未确认时先如实告知，查明后再给最终回执

这个场景最容易查到三种不同的失败。模型选错会议，要回看消歧。服务拒绝后仍报成功，要沿工具结果到用户回执的映射查。评审把“说了成功”判作“业务已完成”，就回到场景表补上独立业务回读。表中的时间和预期记录用于设计测试，真实结果要由目标环境给出。

从一次验收走到下一次改进

用户最常卡在找空闲会议室，还是在已约会议的改期？做原型之前，先挑一小批真实的典型任务，观察用户在哪里耗时间、哪一步要人工接管。上线后，按有资格办理的请求统计业务完成率，再单独看反复澄清、人工补救和重复写入。机器人回复得更快或更客气，可以从会话里看出来。用户是否真的省了步骤，需要对照最后完成的业务动作。

出了错，能查到当时为什么走到那一步，会比留一长段“模型认为自己做对了”的解释更实用。internalcot 可以让 Agent 把选取的工作笔记显式写出，供人查看。业务系统可以借这个思路，记录已确认的目标、实际调用和证据位置。笔记里的判断还要跟工具回执及业务状态核对。Morluto 主页把 Preference 定位为预测研究基础设施，也指向同一个问题：专业任务依赖可取得、可核查的领域信息。 internalcot 的可见工作笔记 · Preference 的作者项目说明

Reef 把这种反馈关联做成了具体接口。一次运行返回回执标识，后续反馈引用这次交互并附上评分或解释。其 harness_evolve 配方从反馈产生候选，用配置好的任务比较现版和候选，通过比较后发布，并保留版本历史。业务机器人可以从更小的做法开始。把一次“超时后重复改期”的故障脱敏，保留原操作和当时的可见状态，在隔离环境复跑现版与候选。复测还要跑正常改期、越权和冲突用例，确认修复的收益与代价。 Reef 的反馈、候选评估和版本历史

发布时给候选留一个可回退的版本标识。若小范围上线后出现重复写入或越权放行，先停止受影响的写入路径，切回已验证版本，再按操作标识核对已经发生的变更。已提交的业务数据需要单独核对和处置，切回程序版本只改变后续执行。下一次再看到机器人说“已经改好了”，就打开日历核对同一条预约，也把这次运行留成日后能复查的依据。