Specsmaxxing：用YAML写AI编程规格，告别Agentic Coding的混乱

AI代理编程（Agentic Coding）火了，但用过的人都知道一个痛点：AI经常写出你不想要的东西。你需要反复调整prompt，来回迭代多次，才能得到勉强可用的代码。更糟的是，AI还会"幻觉"出不存在API、编造配置项、创造不存在的文件路径。

「Specsmaxxing」应运而生——一种通过结构化YAML规格文件来精确控制AI编程输出的方法论。

什么是Specsmaxxing？

Specsmaxxing的核心理念是：在让AI写代码之前，先用精确的YAML文件定义清楚你想要什么。这个YAML文件（称为spec）包含了项目的完整规格说明：

• 项目结构和文件组织方式
• 每个模块的输入、输出和行为约束
• API接口的精确签名（endpoint、method、request/response schema）
• 数据模型和验证规则
• 错误处理策略
• 测试用例和预期结果

为什么YAML而不是自然语言？

自然语言很灵活，但对AI来说过于模糊。「做一个用户登录功能」可以是100种不同的实现方式。YAML精确定义了每一个细节：

# user_auth.yaml
module: user_auth
endpoints:
  - path: /api/login
    method: POST
    request:
      body:
        email: {type: string, format: email, required: true}
        password: {type: string, min_length: 8, required: true}
    response:
      200:
        body:
          token: {type: string}
          user: {type: object, ref: User}
      401:
        body:
          error: {type: string, enum: [INVALID_CREDENTIALS]}
    rate_limit: {max: 5, window: 60s}
  - path: /api/register
    method: POST
    request:
      body:
        email: {type: string, format: email}
        password: {type: string, min_length: 8, pattern: "^(?=.*[A-Z])(?=.*[0-9])"}
        username: {type: string, min_length: 3, max_length: 30}
    response:
      201:
        body:
          id: {type: string, format: uuid}
      409:
        body:
          error: {type: string, enum: [EMAIL_EXISTS, USERNAME_TAKEN]}

当AI拿到这样一份YAML规格时，它不需要「猜测」你的意图——所有约束都已经明确定义。这彻底消除了AI的幻觉和偏差。

实际效果对比

一个典型的使用场景对比：

传统方式：用自然语言prompt描述需求 → AI生成代码 → 审查发现不对 → 修改prompt → AI重新生成 → 发现新问题 → 重复迭代5-10轮。总耗时约2-3小时。

Specsmaxxing方式：花30分钟编写YAML规格 → AI读入规格 → 一次生成可用的代码 → 小幅调整。总耗时约45分钟。

Acai.sh：Specsmaxxing的开源工具链

Acai.sh是一个专门为Specsmaxxing设计的开源工具包，工作流程如下：

1. Specify（定义）：编写YAML规格文件，定义项目架构和所有模块的精确行为。
2. Ship（交付）：将YAML规格交给AI代理，让它一次性生成所有代码。
3. Review（审查）：AI自动运行测试，生成审查报告，标记与规格不一致的地方。
4. Iterate（迭代）：修改YAML规格，重复上述流程。

这个流程与传统的Spec-Driven Development（SDD）一脉相承，但加入了AI代理的自动化能力。

最佳实践

通过大量实践，社区总结出以下Specsmaxxing最佳实践：

从全局到细节：先写高层架构规格，再逐步细化到模块级别。

先定义接口，后实现逻辑：确保所有模块的接口（API endpoint、函数签名）在实现之前就已经确定。

示例驱动：为每个接口提供至少一个正例和一个反例的请求/响应对。

版本管理：YAML规格文件应当和代码一样纳入Git版本管理。

不要过度约束：只约束业务逻辑，不要约束实现细节（如变量命名、代码风格），给AI留出优化空间。

局限性

Specsmaxxing并非万能：对于探索性项目（需求不明确的阶段），过度前置的规格定义会阻碍迭代速度。对于简单脚本和一次性任务，编写YAML规格的成本可能超过手动编码。但对于中大型项目和团队协作场景，Specsmaxxing的价值是显著的。

Specsmaxxing不是要取代思考，而是让思考的结果更精确地传达给AI。