一个Cursor用户发现：让AI写代码3个月后，代码库变成了"意大利面条"。

这不是技术债，是技术灾难。当AI编码助手（AI Coding Agent）开始批量生产代码，我们反而需要更严格的代码规范——比人类写代码时更严格。

「一只编码助手能让代码库变烂，一群编码助手能让代码库爆炸」

这份来自AI基础设施公司Convex的工程师指南，本质上是一份"人类如何驯服AI代码"的生存手册。它提出的核心矛盾很尖锐：AI让写代码变便宜了，但维护成本正在指数级上升。

正方：AI应该像人类一样写"语义化函数"

Convex团队的第一条军规：代码必须自解释（self-documenting）。

他们区分了两种函数类型。语义函数（semantic function）是代码库的"原子"——只做一件事，输入输出清晰，无副作用，极度可测试。从quadratic_formula()到retry_with_exponential_backoff_and_run_y_in_between()，好的语义函数哪怕只用一次，也能帮未来的维护者（人类或AI）快速索引信息。

实用函数（pragmatic function）则是"流程组织者"，把多个语义函数和独特逻辑打包成复杂流程。比如provision_new_workspace_for_github_repo()或handle_user_signup_webhook()。它们注定会频繁变动，所以测试靠集成测试而非单元测试。

这套分层设计的隐含假设是：AI可以像人类一样理解抽象边界，并自觉维护这种分层。

反方：AI根本不懂你在写什么，规范是徒劳的

质疑者的核心论点：LLM（大语言模型）的上下文窗口有限，且对代码库的"全局理解"是幻觉。

当你让Cursor补全一个函数，它只能看到当前文件和少数相关文件。所谓的"语义函数"设计，对AI而言只是文本模式的延续——它不会真正理解"这个函数应该被复用"，只是模仿了训练数据中的常见写法。

更残酷的观察来自一线开发者：AI生成的代码往往"看起来对，跑起来错"。它能完美遵循命名规范，却在边界条件上翻车；能写出漂亮的类型签名，却隐藏了时序依赖的bug。当AI批量生产这种"表面合规、实质脆弱"的代码时，严格的规范反而成了遮羞布——让问题更难被发现。

还有效率层面的质疑。Convex团队要求"语义函数尽可能小"，但AI的计价模式是按token（词元）收费。过度拆分函数意味着更多的API调用，更高的成本。当商业压力遇上代码洁癖，规范能坚持多久？

我的判断：规范的价值不在约束AI，而在约束人类对AI的滥用

Convex这份指南的真正读者不是AI，是用AI的人。

"意图明确"（intentional）这个词在原文标题中出现两次，泄露了核心焦虑：当代码生成变得零摩擦，人类容易失去对"为什么要这样写"的追问。规范的存在，是强迫人在提交前做一次人工审核——不是检查语法，是检查设计意图是否清晰到足以被另一个AI（或6个月后的自己）理解。

语义函数 vs 实用函数的区分，本质是在代码库中建立"稳定层"和"变动层"的防火墙。AI可以随便改动实用函数，但动语义函数时需要额外警惕。这种架构分层在AI时代比之前更重要，因为AI的"遗忘成本"为零——它不会记得三个月前为什么这样设计，只会根据当前上下文生成最可能的补全。

一个冷观察：这份指南本身被做成了"技能"（skill）——可以喂给Cursor的AI助手。这像是一个递归隐喻：我们用AI生成的规范，来约束AI生成的代码。也许最终的解决方案不是更好的规范，而是更好的元AI——专门负责审核代码设计意图的AI审查员。

在那之前，人类还得继续扮演那个讨厌的角色：在AI狂欢后默默收拾残局的代码管家。