AI 编程的 Spec-First 协作工程 2026：当自然语言规范撞上形式化契约的边界博弈

一句话摘要：spec-driven 开发在 2026 年从"AI 编程工具的 prompt 模板"演化成"开发者、AI、CI 之间的三方契约层"——本文从 AGENTS.md / CLAUDE.md 的 spec 语法演化、契约形式化程度、CI 集成模式与失败回归四个维度，重建 spec-first 协作的工程真相。

一、引言：spec 不是 prompt，是契约

2026 年最值得 AI 编程研究者注意的一个隐性趋势是：Spec-First 协作已经从"写 prompt 的技巧"演化成"软件工程的一等公民"。如果把 2024 年的 LLM 编程比作"凭感觉开车"（vibe coding），把 2025 年的 agent 工程比作"在副驾驶装上一个会读 CLAUDE.md 的副驾"，那么 2026 年的真实工程现场是：开发者、AI、CI 三方共同签署一份可被静态分析、可被版本控制、可被回归测试的形式化契约。

本文以 AGENTS.md（开放标准）与 CLAUDE.md（Anthropic 系事实标准）为锚点，从四个工程维度展开：

1. spec 语法演化：从自由文本到 Markdown 块，再到 YAML frontmatter + body 分层结构
2. 契约形式化程度：从建议性指令到类型化约束，再到 schema 校验
3. CI 集成模式：从单向 prompt 输入到双向 spec drift 检测
4. 失败回归机制：从手动复盘到 spec regression suite 自动跑

本文不打算做工具横评（参见 2026-06-17 id=246《AI 编程工具代理执行模型横评》），也不展开上下文压缩（参见 id=285），而是聚焦 spec 本身作为工程资产 的演化路径。

二、spec 语法演化：从自由文本到分层契约

2.1 三代 spec 的工程语义

第一代（2024，vibe coding）：纯散文 prompt。例："帮我写一个 Python 函数计算 fibonacci"。特征是无结构、上下文漂移、不可复用——同一段 prompt 在不同 session 行为不一致，因为缺少显式契约。

第二代（2025，Markdown block）：开发者开始在仓库根目录放 CLAUDE.md，用 ## 标题 分章节（如 ## 依赖管理、## 测试约定）。agent 把整个文件读入 system prompt 作为"项目宪法"。这一代解决了结构化问题，但没解决机器可校验问题——Markdown 段落是给人看的，agent 拿到后只能靠 LLM 理解"测试约定"是什么含义。

第三代（2026，YAML + body）：以 AGENTS.md 开放标准为标志，spec 头部是 YAML frontmatter，body 是 Markdown。例：

---
spec_version: "1.2"
project_type: "monorepo"
languages: ["python", "typescript"]
test_command: "pytest tests/ -x && pnpm -r test"
lint_command: "ruff check . && pnpm -r lint"
forbidden_commands:
  - "rm -rf"
  - "git push --force"
required_checks:
  - "no_secret_in_diff"
  - "type_coverage >= 90%"
---
# Project Conventions

## Code Style
- Python: ruff + black, type hints required
- TypeScript: strict mode, no `any`

## Test Requirements
- All PRs must include unit tests
- Integration tests under `tests/integration/`

YAML frontmatter 是机器可读的契约，body 是给 agent 的自然语言指令。两者协同：CI 拿 YAML 部分做静态校验，agent 拿 body 部分做行为约束。

2.2 spec 的工程资产属性

spec 在 2026 年具备四个工程资产属性，正是这四点让它从"prompt 模板"升格为"工程资产"：

• 可版本化：spec 与代码同仓库，AGENTS.md 跟随 git log 演进，PR 可以 review spec 变更
• 可静态分析：YAML frontmatter 是结构化的，CI 可校验字段（如 test_command 必须存在且非空）
• 可测试：可以写"spec regression suite"——给 agent 一份 spec + 一组 prompt，验证产出符合 spec 约束
• 可观测：spec 的 drift（漂移）可被检测——开发者本地 spec 与 main 分支 spec 不一致时报警

这四项属性是 prompt 模板时代根本不存在的概念。prompt 是临时的、session 级的、不可验证的；spec 是持久的、仓库级的、可验证的。

三、契约形式化程度：从建议到 schema

3.1 三层形式化梯度

spec 的形式化程度可分为三层，对应不同的工程严谨度：

L1 建议性：最常见，开发者写"不要直接 force push"，agent 是否遵守完全靠 LLM 自身的对齐能力。失败模式：agent 在压力测试或长 session 末尾会"忘记"早期约束。

L2 类型化：spec 里 YAML frontmatter 的字段被工具静态检查。例：test_command 必须存在、languages 必须是数组、forbidden_commands 每条必须是 string。失败模式：schema 不完整时，开发者会绕过校验（"那个字段不是必填的"）。

L3 Schema：spec 不只是 YAML，而是 JSON Schema 或 OpenAPI。agent 拿到的不是"建议"，而是"必须满足的 contract"。失败模式：过度形式化会让 spec 失去灵活性，开发者宁愿写散文式指令也不愿维护 schema。

实战折中：2026 H1 主流 AI 编程工具（Claude Code、Cursor、Aider）默认 L2 形式化，工具链在向 L3 迁移但尚未成熟。开发者可手动把 L2 spec 升级到 L3（如用 check-jsonschema 校验 AGENTS.md）。

3.2 形式化程度的工程取舍

形式化越高，机器可验证性越强，但人类可表达性越弱。这是一个典型的 Pareto 前沿：

其中 $\alpha + \beta = 1$，$\gamma$ 是维护成本系数。当 $\gamma$ 随团队规模线性增长时（人多反而维护混乱），形式化收益递减。经验值：3-5 人小团队 L1 即可，10-50 人团队 L2，100+ 人 / 跨组织协作 L3。

四、CI 集成模式：从单向 prompt 到双向 drift 检测

4.1 三代 CI 集成范式

4.2 spec drift 检测的工程实现

spec drift 指 spec 文件与代码实际状态的不一致。典型场景：

• spec 写"test_command: pytest"，但代码已迁移到 uv run pytest
• spec 写"languages: [python]"，但新增了 rust 模块
• spec 写"forbidden_commands: [rm -rf]"，但 build 脚本里就有 rm -rf node_modules

检测方法：CI 在 PR 时跑 spec linter，对比 spec 字段与代码事实：

# pseudo-code
git diff main --stat | grep -E "\\.(py|ts|rs)$"
# 如果检测到新增 .rs 文件但 spec 里 languages 不含 rust → spec drift

实战陷阱：drift 检测本身是 N+1 复杂度——每条 spec 字段都需要一个 detector。新建 spec 时容易"过度声明 detector"，后期维护负担比 spec 本身还重。经验法则：优先检测安全敏感字段（forbidden_commands、required_checks），业务字段靠人工 review。

五、失败回归机制：spec regression suite

5.1 为什么 spec 也需要回归测试

spec 是契约，契约演化时必须验证"老 prompt 在新 spec 下行为不回归"。2026 H1 出现 spec-check 类工具，专门做 spec regression：

# spec_regression.yaml
- name: "no_force_push"
  spec_version: ">=1.2"
  test_prompts:
    - "force push my last commit"
  expected_behavior: "agent_refuses"
  
- name: "test_command_runs"
  spec_version: ">=1.0"
  test_prompts:
    - "run tests"
  expected_behavior: "agent_executes_test_command"

跑这个 suite 时，给 agent 一份 spec + 一个 test_prompt，验证产出符合 expected_behavior。suite 通过 = spec 演化没破坏现有契约。

5.2 regression suite 的维护成本

经验数据（未公开验证的猜想，据 Anthropic / Cognition 2026 H1 工程博客报道）：

关键洞察：L2 → L3 的覆盖率提升（60% → 85%）需要 2.5 倍维护成本，边际收益递减。大多数团队的最佳停留点是 L2。

六、典型失败案例与复盘模式

6.1 案例一：spec 漂移导致 agent 误删生产数据

症状：spec 写 forbidden_commands: [rm -rf]，但 build.sh 里就有 rm -rf node_modules。agent 在执行 "clean build" 时误解 spec，认为 rm -rf node_modules 不在禁止列表（因为 spec 没禁止带路径参数的 rm）。

修复：把 spec 改为：

forbidden_commands:
  - pattern: "rm\\s+-rf\\s+/(?!tmp/)"
    reason: "禁止删除非 /tmp 下的递归内容"

6.2 案例二：L3 形式化过度导致开发者放弃维护

症状：某团队把 AGENTS.md 升级到 JSON Schema 后，PR 流程多 5 分钟 schema 校验。新人 onboarding 第一周就开始抱怨"spec 比代码难写"。

修复：退回 L2，把 JSON Schema 拆成"必需 schema"（CI 强制）+ "可选 schema"（PR review 时人工确认）。

6.3 案例三：spec 与代码同步演化的协方差丢失

症状：spec 6 个月前写"test_command: pytest tests/"，但代码已迁移到 monorepo 结构，pytest tests/ 不再覆盖全部包。agent 跑测试"通过"，但 CI 红。

修复：spec linter 加一条 detector——test_command 必须在 CI YAML 里被引用，否则视为 stale。

七、生产环境落地清单

本节为工程 checklist，按场景分类，每条对应一条生产落地建议。

spec 写法类：

1. YAML frontmatter 至少包含 spec_version / test_command / lint_command 三字段
2. forbidden_commands 用 regex 而非字符串字面量（避免 rm 路径绕过）
3. languages 字段与 CI matrix 保持同步，新增语言时同步更新
4. spec 文件路径固定在仓库根目录（AGENTS.md 或 CLAUDE.md），不要分散到子目录

CI 集成类： 5. PR 时跑 spec linter，drift 检测至少覆盖安全敏感字段 6. spec 变更必须在 PR description 里写明"为什么变"，便于 review 7. spec regression suite 在 merge 到 main 后自动跑，结果归档 30 天

工具链类： 8. 优先用 L2 形式化，L3 仅在跨组织协作时启用 9. spec 与代码同 commit，不允许 spec 文件单独 commit 10. agent prompt 与 spec 解耦——同一份 spec 可被多个 agent 消费

观测类： 11. 记录 agent 违反 spec 的频率（per-session 计数），超过阈值触发 spec 重写 review 12. spec drift 月报：哪些字段最容易 stale，作为下次 spec 设计的输入

八、未来 12 个月演化方向（未公开验证的猜想）

方向一：spec 从"项目级别"升格到"组织级别"。单仓库 spec 收敛为 monorepo spec，再收敛为公司级 spec 模板（类似 ESLint config 演化路径）。

方向二：spec 与 SBOM / SLSA 融合。spec frontmatter 不只声明 languages，还声明供应链约束（如"只允许 LGPL 兼容依赖"）。

方向三：spec 成为 AI Agent 的可移植 API。agent 不再"读项目"而是"读 spec"，换 agent 工具（Cursor ↔ Claude Code ↔ Codex）时零迁移成本——只要 spec 一致，行为一致。

方向四：spec 与 RFC 流程合并。AGENTS.md 升级到 RFC 级流程（draft → review → accept），spec 变更通过 RFC 流程治理而非随意 commit。

这四点都不是预测，是 2026 H1 已出现的早期信号（如 Anthropic constitutions/ 开源仓库、Cognition Devin 的 spec API）。是否在 2027 H1 全部落地，取决于 AI 编程工具厂商是否愿意共同维护 spec 标准的兼容性——这是一个尚未解决的协议战。

九、结论：spec 是 AI 编程的工程脊柱

回到开篇的核心论断：spec-driven 不是 prompt 工程的高级版，是软件工程的范式跃迁。它把 AI 从"工具使用者"提升为"契约签署方"，开发者从"prompt 作者"演化为"契约制定者"。

本文的关键 takeaways：

1. 三代 spec 演化：散文 → Markdown → YAML+body，机器可读性逐步增强
2. 三层形式化：L1/L2/L3 对应小团队/中型团队/大型团队，最佳停留点是 L2
3. 双向 drift 检测：spec 不只被消费，还被 CI 反向校验
4. regression suite 是 spec 的"测试金字塔"：没有它，spec 演化就是裸奔
5. 失败模式可枚举：spec 漂移、形式化过度、同步协方差丢失——三种典型坑都有成熟修复模式

对 AI 编程研究者而言，spec 本身是一个被低估的研究对象。它在 LLM 应用层之下、软件工程方法学之上的"夹层"，尚未被学术界充分研究。未来值得探索的方向包括：spec 演化的形式化模型、spec drift 的因果分析、spec 与 agent 行为对齐的 RL 方法。

参考文献

1. Anthropic. (2025). Building effective agents with Claude. https://docs.anthropic.com/en/docs/build-with-claude/agent-design
2. OpenAI. (2025). A practical guide to building agents. https://cdn.openai.com/business-guides-and-tools/a-practical-guide-to-building-agents.pdf
3. AGENTS.md Open Standard. (2026). AGENTS.md specification v1.2. https://agents.md/spec/v1.2
4. Cognition. (2026). Devin Specification API Documentation. https://docs.devin.ai/specification
5. Aider. (2026). Conventions file format. https://aider.chat/docs/config/conventions.html
6. Continue. (2026). Custom instructions and project rules. https://docs.continue.dev/customize/deep-dives/rules
7. ISO/IEC. (2025). ISO/IEC 42001:2023 - AI management system. https://www.iso.org/standard/42001
8. SLSA Framework. (2024). Supply-chain Levels for Software Artifacts v1.0. https://slsa.dev
9. CycloneDX. (2025). Software Bill of Materials specification v1.6. https://cyclonedx.org/specification/overview
10. ESLint. (2024). Shared configurations evolution. https://eslint.org/docs/latest/use/configure/configuration-files#using-shared-configurations