TL;DR
Agent 能迅速生成实现、测试和说明,但这些产物可能共同继承一个错误假设。我们在 WhyJ-Quant 的实践中,把稳定原则交给 AGENTS,把任务方法交给 Skills,把确定性检查交给 CI,再用平台规则约束合并。需要保留的经验是:明确责任,让错误可重现,让检查对应实际交付的对象,同时承认它没有证明的部分。
产物齐了,为什么仍不能交付
使用 Agent 开发后,一次需求很快就有了代码、测试、文档和 PR。评审却没有同样变快:维护者仍要判断,这几份材料是否在描述同一个问题,测试是否真的能识别错误。
仓库里出现过一个直接的反例:本金 100000,零费用,持有 1000 股,价格从 100 涨到 110,期末权益应为 110000。旧回测实现却给出约 111000,而当时测试仍然全绿。后来的独立账本回归用现金和股数核对结果。它补上的,是此前没有检查的业务含义。
文档也会放大错误。实现已经修正,旧说明还在描述过时的计算口径;下一轮 Agent 若把旧说明当作要求,就可能把错误改回来。保留更多文档,并没有自动保留更准确的上下文。
交付流程里还有另一种错位:PR 的代码检查已通过,修改描述又触发一轮策略检查;PR 随后合并、Issue 自动关闭,检查器仍按开放 PR 的规则要求 Issue 保持开放,于是“合并成功”之后出现红灯。
这些历史案例来自原始 Ops 复盘和评测文章,本次没有重跑历史任务。它们共同改变了我们的判断:完成一份产物之后,还要确认它与需求、验证和交付决定之间的关系。
把规则交给真正能执行它的地方
最初的反应很容易是继续扩写 AGENTS.md。可一份越来越长的说明,既增加阅读成本,也无法直接阻止错误合并。我们采用的分工是:
- AGENTS 留下稳定原则:先理解问题、保持简单、控制修改范围、核验结果。
- Skills 保存特定任务的方法。例如,完成 PR 描述后,再检查最后触发的运行。
- Docs 用文字说明设计意图、责任边界与取舍;Blog 解释这些判断如何形成。
- 脚本和 CI 执行可以明确判定的检查;分支保护决定哪些检查是合并条件。
一项要求只有找到执行者,才知道它能保证什么。Skill 要求“等待检查”,仍然依赖执行者遵守;把检查配置为合并条件,平台才会据此限制合并。反过来,脚本可以发现 PR 缺少验收说明,却不能判断说明是否切中问题。
同样的原则用于文档:一个主题保留一个当前入口,进度和运行回执留在 Issue、PR 与 CI。删减重复材料时,保住关键限制与选择理由,避免让读者重新拼接一套设计。OpenAI 的 Harness Engineering 实践也采用简短入口连接仓库知识;我们借鉴这种组织方式,没有借用它的效率结果。1
红灯要修在哪里,取决于错误的假设
审计 Actions 时,不能把所有失败都叫作“偶发”。产品计算错误、测试依赖本机环境、异步清理竞态和策略脚本版本不一致,需要不同的修复。
Windows 上的一次超时很典型:外层测试约五秒就结束,内部操作却允许执行两分钟。测试开始删目录,后台任务还在写文件,后续错误看起来像随机故障。延长超时只能减少出现概率,没有解决谁负责停止任务。
修复后的 fixture 持有自己的在途任务:先拒绝新工作,再取消并等待已有任务结束,最后释放服务器和临时目录。关键是资源的使用者已经退出,而不只是调用了 abort()。对应逻辑保留在评测测试中。
策略检查则要处理另一种生命周期。新 workflow 曾检出了过旧的基线,找不到刚加入的策略脚本;后来让策略与可信的工作流版本对齐,并只读取 PR 元数据,不执行 PR 提供的代码。检查器也区分开放与已结束的 PR,避免把正常关闭当成违规。
这些修复的共同方法,是找到一个能区分正确与错误的反例,再把检查放到负责该问题的层。账本测试应独立计算预期值;取消测试应验证事件顺序;策略测试应覆盖状态变化。重复被测逻辑或反复重跑,都不能替代这一步。
让检查覆盖实际交付,而不只覆盖源码
代码回归、PR 协作策略、Desktop 安装验收和发布承担不同责任。源码能构建,不代表发布包能安装;安装成功,也不代表用户机器上的启动和真实服务都已验证。因此,检查对象需要沿着交付路径逐步接近用户拿到的东西。
在现有 CI 中,Linux 与 Windows 的结果汇总到 CI required;聚合检查只有在平台任务成功时才通过。这个稳定名称方便配置分支保护,但名称里写着 required,并不意味着平台已经强制执行。
分支保护需要选择实际的检查名称;要求分支与最新 main 对齐,可以降低各分支独立通过、合在一起出错的风险,也会增加同步和重跑成本。2
签名、线性历史和质量检查则解决不同问题:签名验证来源,线性历史帮助阅读与回滚,测试核对行为。应按团队的交付方式选择它们,不能用一个开关替代另一个判断。
最后一次检查还要对应最后一次修改。PR 描述会触发策略校验,因此“这个提交曾经绿过”并不足够。合并前要核对当前代码、描述和相关检查;发布时再确认产物来自已验收的版本。具体操作维护在 CI 与发布文档,不在文章里复制一份容易过期的设置手册。
留下了什么,还没有证明什么
这轮实践留下了能重现算术错误的用例、明确持有异步任务的测试 fixture,以及识别 PR 生命周期的策略检查。本文核对了相关源码;这些是可检查的设计变化,不是本次重新完成的产品验收。
代价同样存在。跨平台与安装包检查消耗时间,跟随 main 重跑增加等待,策略和反例也需要维护。过细的流程会把精力消耗在填模板上;只有形式检查通过,也可能让人误以为业务判断已经完成。
我们没有据此测得 Agent 的缺陷率或效率提升,也没有在本次重新读取远端保护设置、验证正式发布或真实行情服务。CI 能检查明确条件,评审仍需判断需求与取舍,运行中的服务仍需独立观察。
仓库运维的设计重点,是让每条规则有明确的责任人或执行机制,并让下一轮工作容易找到它。 一次失败值得留下错误假设、最小反例和有效检查;详细流水不必随每篇文档永久增长。这样的经验才有机会被复用,而不是成为下一轮需要清理的上下文。
读后可以选一次自己的历史失败:找出错误假设、负责的层和最小反例,再确认相应检查是否真的进入了交付流程。
References
- Ryan Lopopolo. Harness engineering: leveraging Codex in an agent-first world. OpenAI, 2026.
- GitHub. About protected branches. GitHub Docs.
- WhyJ. Agentic / Vibe Repo Ops:原始失败与修复记录. WhyJ-Quant, 2026.
- WhyJ. 测试全绿,为什么仍不能交付结论. WhyJ-Quant, 2026.
- WhyJ. 报告要固定,设计要演进. WhyJ-Quant, 2026.