当我们谈论 AI 编程助手的可靠性时，一个被频繁忽视的问题是：AI 会在代码中「创造」出不存在的功能、遗漏边界条件、甚至凭空捏造 API 调用。这种现象被开发者社区戏称为「AI 精神病」—— 模型表现出流畅但完全错误的输出，如同精神病患者构建了一套自洽却与现实脱节的认知系统。应对这一挑战的核心方法论，正是将需求文档从自然语言的模糊地带，迁移到 YAML 等结构化规范格式中。
「AI 精神病」的成因与表现
大语言模型本质上是一个概率预测引擎，它的每一次输出都是在海量训练数据中寻找「最可能的下一个词」。这种机制导致模型倾向于生成语法正确但语义错误的内容 —— 它可以写出一段完美的 TypeScript 接口声明，却完全忽略了你项目中真实的 API 响应结构。在实际工程中，这种幻觉表现为：代码通过了静态检查，却无法运行；单元测试全部绿色，却在实际业务流程中崩溃；或者是代码引用了根本不存在的第三方库。
传统的解决方案依赖更长的上下文窗口、更精细的提示词工程，或者在生成后进行人工 code review。但这些方法都有一个根本缺陷：它们试图用「更多的语言」来解决「语言本身的不确定性」。当你的需求本身歧义时，任何基于自然语言的约束都可能被模型以意想不到的方式误解。结构化规范的价值，正是在于用机器可解析的格式消除歧义。
YAML 规范的核心设计原则
一个有效的 AI 可读规范应该包含以下几个关键层次。首先是元数据层，定义规范的版本、作者、关联的功能标识符，以及与其他规范之间的依赖关系。这一层确保 AI 理解它在处理哪个具体的功能需求，以及这个需求在整个系统中的位置。其次是约束层，明确列出技术约束、数据格式要求、性能预算、兼容性要求等硬性边界。这些约束以结构化字段形式存在，AI 无法通过「忽略部分提示词」来绕过它们。
第三层是行为描述，用结构化清单替代自然语言叙述。以一个用户登录功能为例，自然语言可能会说「当用户输入错误密码时，应该给出友好提示」，但 AI 可能会随意解读「友好」的含义。结构化格式则会要求明确指定：错误提示的具体文案、是否记录登录尝试次数、锁定账户的阈值是多少、锁定持续多长时间。这些看似繁琐的细节，恰恰是消除幻觉的关键。最后是验证层，定义如何验证实现是否符合规范，包括可执行的测试用例、验收标准、甚至 CI/CD 流水线中的检查规则。
工程落地的关键实践
在实际项目中引入 YAML 规范时，建议采用渐进式策略。初期可以只在核心业务逻辑和高风险功能上应用规范，例如支付流程、数据同步、权限校验等。这些领域的幻觉成本最高，规范化的投入产出比也最显著。随着团队对规范格式的熟悉，再逐步扩展到其他功能模块。
规范的可维护性同样重要。过于庞大的规范会变成另一个难以管理的负担，而过于稀疏的规范又无法起到约束作用。一个实用的原则是「单一职责」：每个 feature.yaml 只描述一个独立的功能特性，通过明确的 ID 系统建立规范与代码之间的双向追踪。Acai.sh 工具链正是基于这一理念设计的，它允许开发者从代码注释和测试中提取规范引用，形成可搜索、可追溯的连接。
监控与迭代
即使有了完善的规范，AI 仍然可能在实现过程中产生偏差。因此，建立持续的监控机制至关重要。这包括定期运行规范的覆盖率检查，确保每个规范要求都有对应的测试用例；追踪 AI 生成代码的回滚频率，识别高频出错的规范类型；以及维护一个「幻觉案例库」，记录每次 AI 产生错误输出的上下文，用于迭代优化规范格式和提示词策略。
当 AI 生成的代码被人工审查驳回时，这不仅是缺陷，更是改进规范的契机。通过分析驳回原因，你可以发现规范中的模糊地带，并在下一次迭代中将其明确化。这种反馈循环，正是将 AI 编程从「抽彩票」模式转变为「工业化」生产模式的关键路径。
资料来源：本文核心观点基于 Acai.sh 项目文档与 Hacker News 上关于「Specsmaxxing」的讨论。