AGENTS.md 反过度设计：不为理论风险扩复杂度
Dave Kiss 点赞 opencode 的 AGENTS.md 规则：加复杂度前先讲清失败模式与成本，征得用户同意。
原始内容
This is such a banger rule in @opencode's AGENTS.md "Before adding complexity for a speculative or vanishingly unlikely race or security edge case, explain the concrete failure mode, likelihood, and complexity cost to the user and get their buy-in. Do not silently expand scope for theoretical robustness."
中文译文
机器翻译，保留原文供核对。
这条规则在 @opencode 的 AGENTS.md 里简直太棒了： “在为推测性的或极不可能发生的竞态或安全边缘情况增加复杂度之前，先向用户解释具体的失效模式、发生概率和复杂度成本，并取得他们的同意。不要为了理论上的稳健性而悄悄扩大范围。”
深度解析
是什么：推文引用了 opencode 仓库 AGENTS.md 中的一条规范，并用截图高亮。品格不是产品发布，而是写给编码 Agent 的「工程协作契约」。
核心规则链条：同一文件里的几条规则构成一条完整的克制逻辑：①在拥有该值的边界处只校验一次未知输入，向内传递已定类型，不要重复 typeof === "object" 之类的防御；②不要预先抽取只用一次的 helper，除非它遮蔽了真正复杂的边界；③只在同时说清「具体失败模式、发生概率、复杂度成本」并拿到用户同意后，才为罕见的竞态或安全边界情况加复杂度；④尽量避免 try/catch，避免 any。高亮那条是这套逻辑的收口：复杂度必须有明确买主。
关键洞察：这是把人类资深工程师的隐性判断显性化。Agent 的通病是「宁滥勿缺」式健壮性——为理论上可能的状态加分支、加兜底、加抽象层，最终代码变长、可读性变差、真实缺陷反而被掩盖。规则的价值不在技术，而在流程：它把「是否值得」从 Agent 单方面决策，转成交付给用户的一道确认题，从而抑制静默的范围蔓延（scope creep）。这与代码评审中「拒绝为不可能路径写测试」的资深直觉一致。
边界与风险：规则依赖 Agent 对「几乎不可能」的判断能力，也可能被当作偷懒的挡箭牌拒绝合理防护；对真正高风险领域（支付、权限、并发写入）需要显式的例外清单。此外它是软约束，需配合测试与评审兜底。
可复用点：任何 AGENTS.md / CLAUDE.md 都可直接照搬这条句式——「说明失败模式、概率与成本，然后征求同意」，是把工程品味写进指令文件的高性价比做法。
精选追评与案例
将规则拆解为失效模式、概率、成本三要素，并指出可复用到其他 system prompt 的写法。
这条规则本质上是把「工程师的防御性直觉」交给了 agent 来执行——人写代码时也会本能地给边缘情况加 try/catch，但 agent 的「本能」是模型权重，不可控。AGENTS.md 里写死「先解释 failure mode、likelihood、cost，再要 buy-in」，等于给 agent 的过度工程倾向装了刹车片。更值得抄的是它的表述结构：具体失效模式 + 概率 + 复杂度成本，这三要素可以直接复用到任何 agent 的 system prompt 里。
提供可验证的测试方法：观察 agent 是否会在写代码前停下来询问。
@davekiss @opencode It is a suggestion, but a checkable one: it asks for an output before any code (failure mode, odds, cost), so you can see whether it fired. A bare "don't" leaves no trace either way. Test it before keeping it: ask for a fix where a race is plausible and see if it stops to ask.
中文译文 · 机器翻译
它是一条建议，但可以被检查：它要求在写任何代码之前先给出输出（失效模式、概率、成本），所以你能看出它有没有触发。单纯的“不要”无论哪种情况都不会留下痕迹。 在保留它之前先测试：让它在竞态看似可能发生的场景里做一个修复，看它是否会停下来先问。
指出重试场景下防重复写入属于基本正确性，划清了规则边界。
@davekiss @opencode once retries enter the system, preventing duplicate writes is basic correctness, not speculative race protection
中文译文 · 机器翻译
一旦系统中出现重试，防止重复写入就是基本的正确性要求，而不是推测性的竞态防护
点出概率与成本评估缺乏工具支撑时的可靠性疑问。
@davekiss @opencode I think AI may still be able to help describe “failure scenarios,” but when it comes to “likelihood” and “complexity cost,” I’m curious how reliable these assessments can be without tools to provide robust reference data.🤔🤔🤔
中文译文 · 机器翻译
我认为 AI 或许仍然能帮助描述“失效场景”，但到了“发生概率”和“复杂度成本”，我很好奇：在没有能提供可靠参考数据的工具时，这些评估能有多可靠。🤔🤔🤔
补充风格指南中的相邻规则，可与本条配对使用。
@davekiss @opencode the bullet right above it in the style guide is the perfect pair: "Do not extract single-use helpers preemptively"
中文译文 · 机器翻译
风格指南里它正上方的那一条是绝配：“不要预先提取一次性使用的辅助函数”