你见过最精妙的魔术吗？
不是刘谦那种。是一场价值数百亿的技术骗局——AI公司告诉你：写个文档吧，AI帮你写代码。
不用写Bug缠身的Python，不用熬夜调参。只需要动动嘴，描述你想要什么，代码自己生成。
听起来是不是很美好？
但有个前提：你得先写出足够详细的规范。
而问题来了——足够详细的规范，本身就是代码。
OpenAI的"魔法"：一份读起来像代码的文档
让我举个具体的例子。
OpenAI搞了个大新闻，叫Symphony项目。官方说法很漂亮：只需要一份SPEC.md规范文档，AI就能自动生成整个项目。
这不就是在说"给我一个需求文档，还你一个完整系统"吗？
理想很丰满。但当我打开那份SPEC.md文档时，整个人都傻了。
这叫规范？
看看第4.1.6节，"Live Session"的数据结构定义，满屏的字段说明：session_id、thread_id、turn_id、codex_app_server_pid……这不就是数据库建表语句吗？
再看第8.3节，"Concurrency Control"，直接甩出公式：
available_slots = max(max_concurrent_agents - running_count, 0)
这是规范还是代码？
最绝的是第6.4节，标题赫然写着"Config Fields Summary (Cheat Sheet)"——配置字段汇总（作弊小抄）。
还特意加了句说明："This section is intentionally redundant so a coding agent can implement the config layer quickly."
啥意思？为了让AI能看懂，我特意把内容重复写好几遍。
这已经不是在写规范了，这是在手把手教AI写代码。
还有第16节，"Reference Algorithms (Language-Agnostic)"，直接塞了一段函数实现：
function start_service():
configure_logging()
start_observability_outputs()
...
说实话，这和直接给我看源代码有什么区别？
误解一：规范比代码简单
AI编程代理的支持者有两个核心误解，我来逐一拆解。
第一个误解：规范文档比对应的代码更简单。
他们描绘的蓝图太诱人了：工程师以后不用写代码了，只需要写写文档，指挥一群AI代理干活。工程师摇身一变，成了"需求经理"。
这事儿能成的前提是——写文档比写代码省事儿。
但Symphony的SPEC.md已经证明：想让规范精确到能可靠生成可运行代码，这份文档必须扭曲成代码的样子，或者某种高度结构化、形式化的"伪英语"。
计算机科学祖师爷Dijkstra早就看透了这一点。他说过一个概念叫"窄接口"（narrow interfaces）——工程协作中，跨接口的沟通成本是躲不掉的。你想用自然语言糊弄机器？门都没有。
古希腊数学为什么卡壳？因为它停留在口头和图像层面。阿拉伯代数为什么衰落？因为它又回到了修辞风格。直到韦达、笛卡尔、莱布尼茨、布尔这些人搞出了形式符号系统，现代文明才得以诞生。
AI编程代理正在用血淋淋的事实证明：你逃不掉"窄接口"。你只能把工程劳动转换成另一种形式——表面上不一样，但精度要求一模一样。
误解二：规范比编码更需要思考
第二个误解更隐蔽：规范工作比编码工作更需要思考。
支持者换了个说法：先过一遍规范文档，质量有保障，能促进更好的工程实践。
听上去很对，是吧？
但问题来了——这种"深思熟虑"在当今的科技行业已经成了奢侈品。
当公司全员都在追求"快速交付"时，谁还有耐心慢慢磨规范？
结果就是Symphony这种鬼东西：看起来像规范，读起来像规范，但经不起细看。
第10.5节简直是个灾难。摘一段给你看：
linear_graphql extension contract:
- Purpose: execute a raw GraphQL query...
- Availability: only meaningful when tracker.kind == "linear"...
- query must be a non-empty string.
- query must contain exactly one GraphQL operation.
这叫什么？这叫"规范形状的垃圾"——句子看起来像规范，但既没有连贯性，也没有整体目标，更没有对大局的理解。
说白了，这就是AI生成的内容：堆砌了一些专业术语，但毫无思想。
如果一份"规范"追求的是快速交付，而不是清晰严谨，那它必然是垃圾——不管是人写的还是AI写的。
现实：代码根本生成不出来
光说理论不过瘾，我决定亲自验证一下。
Symphony的README里写着：
Tell your favorite coding agent to build Symphony in a programming language of your choice...
太棒了，那我让Claude Code用Haskell实现一个（没错，我博客叫haskellforall）。
结果呢？
失败了。
不仅有各种Bug要我手动修复，更离谱的是，有时候程序显示"运行成功"，但实际上什么也没干。给它的示例任务——"创建一个空白git仓库"——AI代理就卡住不动了。
一份"足够精确的规范"依然无法可靠生成可工作的代码。
这个问题不是Symphony独有的。YAML够有名了吧？规范极其详尽，有 conformance test suite，但市面上绝大多数YAML实现依然不能完全兼容规范。
Symphony想解决这个？行，那把规范写得更详细点。
但它现在已经很长了——篇幅达到了所附Elixir实现代码的六分之一。
再扩下去，就要重现博尔赫斯那篇著名短篇《论科学的精确性》里的情节了：
在那个帝国，绘图艺术达到了极致——一幅省份的地图占据了一整座城市，帝国的地图占据了一整片疆土。后来，测绘师们做了一张和帝国一样大的地图，每一个点都完美重合……但它毫无用处。
当规范和代码一样长甚至更长时，写规范还有意义吗？
真相：垃圾进，垃圾出
说了这么多，我想说清楚一件事。
规范从来都不是省时间的工具。
如果你追求的是快速交付，那直接写代码吧，别绕弯路搞什么中间文档。
更根本地，"垃圾进，垃圾出"的原则在这里同样适用。
没有清晰详细的输入，就别指望AI代理能帮你补足那些缺失的细节。AI不会读心术——就算会，你自己的想法都是糊涂的，它又能怎样？
尾声
下次有人跟你吹"AI编程代理革命"的时候，问他一个问题：
你的规范文档写得比代码还详细了吗？
如果是，那为什么不让AI直接写代码？
【MiniMax-M2.1锐评】：这篇文章撕开了AI编程代理的华丽包装，用Symphony这个"官方标杆"自扇耳光，告诉读者：所谓"规范生成代码"，本质上就是"代码生成代码"，换了个马甲而已。
参考链接：
https://haskellforall.com/2026/03/a-sufficiently-detailed-spec-is-code