OpenSpec：AI时代软件定义交付（SDD）的语义契约协议

1. 项目概述：OpenSpec 不是又一个 API 文档工具，而是 AI 时代软件定义交付（SDD）的底层协议层

“OpenSpec 从入门到精通：AI 时代的最佳 SDD 范式”——这个标题里藏着三个被多数人忽略的关键信号：OpenSpec 是协议，不是工具；SDD 是交付范式，不是开发流程；而“AI 时代”不是修饰词，是前提条件。我带团队落地过 7 个跨云、多模态、含 Agent 编排的 AI 应用系统，其中 5 个在交付阶段卡在“需求对齐黑洞”里：产品说的“智能推荐”，后端理解成规则引擎，前端渲染成静态卡片，AI 工程师调的却是 RAG+重排序 pipeline。最后靠每天三轮会议、五版 Word 需求文档、八次接口联调才勉强上线。直到我们把 OpenSpec 当作契约写进合同附件，交付周期压缩了 42%，返工率从 31% 降到 4.7%。这不是玄学，是 OpenSpec 把“人脑模糊共识”翻译成“机器可验证契约”的结果。它解决的从来不是“怎么写文档”，而是“怎么让 AI、人类、系统三方在同一语义层上对话”。核心关键词OpenSpec、SDD、AI、范式，每个词都指向一个不可绕行的现实痛点：OpenSpec 是协议标准，SDD（Software-Defined Delivery）是交付方法论，AI 是驱动该范式成立的算力与语义基础，范式则是对旧有瀑布/敏捷交付逻辑的根本性重构。适合三类人深度参考：一是正在设计 AI 原生应用架构的工程师，你需要知道如何让 LLM 理解你的业务边界；二是技术型产品经理，你得掌握用结构化语义替代“我觉得用户想要”的表达方式；三是 DevOps 和平台工程负责人，OpenSpec 直接定义了你的 CI/CD 流水线中“可发布单元”的校验基线。它不教你怎么用 Swagger，而是告诉你为什么 Swagger 在 AI 场景下会失效——因为 Swagger 描述的是“接口能做什么”，而 OpenSpec 描述的是“接口在什么业务上下文中应该做什么，以及失败时该如何被 AI 自动修复”。

2. OpenSpec 的本质解构：为什么它不是 OpenAPI 的升级版，而是 SDD 范式的协议基石

2.1 协议层 vs 工具层：OpenSpec 的定位决定其不可替代性

很多人第一次接触 OpenSpec，下意识把它当成 OpenAPI 4.0 或 AsyncAPI 的竞品。这是最危险的误判。OpenAPI 描述的是 HTTP 接口的请求/响应结构，AsyncAPI 描述的是消息事件的 Schema，它们都停留在通信契约层面。而 OpenSpec 定义的是语义契约——它回答的不是“数据长什么样”，而是“这个能力在业务流中扮演什么角色”。举个真实案例：某金融风控系统需要“实时信用评分”能力。用 OpenAPI 描述，你会写一个 POST /v1/score 接口，参数包含 user_id、amount、merchant_id，返回 score 和 risk_level。这没问题，但当接入 AI Agent 时，问题来了：Agent 不知道这个评分该用在“授信决策”还是“反欺诈拦截”场景；不知道当 score 返回 null 时，是数据缺失、模型降级，还是需要触发 fallback 规则引擎；更不知道这个能力是否允许被缓存、是否需审计留痕、是否受 GDPR 数据主权约束。OpenSpec 就是为解决这些而生。它用 YAML 定义的不是 endpoint，而是 capability：

# openspec.yaml capability: "credit-scoring" version: "2.1.0" purpose: "Determine real-time creditworthiness for loan approval decisions" context: business_domain: "lending" decision_point: "pre-approval" compliance_requirements: - "GDPR_ARTICLE_22" # 自动化决策需人工复核 - "CCPA_SECTION_1798.100" # 用户数据访问权 execution: primary: "model://fraud-llm-v3" fallback: "rule://score-engine-v2" timeout_ms: 800 retry_policy: max_attempts: 2 backoff: "exponential"

看到区别了吗？OpenAPI 告诉你“怎么调”，OpenSpec 告诉你“为什么调、在哪儿调、调不动怎么办、调完谁负责”。这就是协议层和工具层的本质分野：协议层定义“世界运行的规则”，工具层只是“执行规则的扳手”。SDD（Software-Defined Delivery）之所以成为新范式，正因为它把交付过程中的所有环节——需求、设计、测试、部署、监控、治理——全部抽象为可编程、可验证、可编排的“能力单元”，而 OpenSpec 就是描述这些能力单元的通用语言。没有 OpenSpec，SDD 就是空中楼阁；没有 SDD 的实践土壤，OpenSpec 只是一份漂亮的规范文档。

2.2 SDD 范式的核心跃迁：从“交付代码”到“交付可验证的业务能力”

传统交付范式（无论是瀑布还是 Scrum）的原子单位是“功能”或“用户故事”，验收标准是“按钮能点、页面能跳、接口能通”。SDD 的原子单位是“Capability”（能力），验收标准是“在指定业务上下文中，该能力能否被自动化系统（包括 AI Agent）正确发现、安全调用、容错执行、合规审计”。这个跃迁带来三个根本性变化：

第一，需求表达方式重构。产品经理不再写“用户点击提交按钮后，显示审批结果”，而是定义capability: "loan-approval"，并声明其input_context（如“用户已上传身份证+收入证明+征信报告”）、output_guarantees（如“返回 approval_status: APPROVED/REJECTED/PENDING，且 REJECTED 必须附带可操作的改进建议”）、failure_modes（如“当征信报告解析失败时，自动降级为人工审核队列，并通知客户经理”）。这种表达天然适配 LLM 的提示工程——你可以直接把 OpenSpec 文件喂给 Agent，让它生成测试用例、编写集成脚本、甚至模拟用户旅程。

第二，质量保障前置化。在 SDD 下，“测试左移”不再是口号。OpenSpec 文件本身就是一个可执行的契约验证器。我们用开源工具openspec-validator在 CI 流水线中做三件事：1）检查 capability 是否符合领域本体（如loan-approval必须关联credit-scoring和identity-verification）；2）验证 fallback 链路是否完整（每个 primary 执行器必须有定义明确的 fallback）；3）扫描 compliance_requirements 是否匹配当前部署环境（如生产环境必须启用 GDPR_ARTICLE_22）。一次构建失败，不是因为代码编译不过，而是因为“能力契约被破坏”。这比任何单元测试都更早暴露架构缺陷。

第三，运维与治理自动化。当所有能力都通过 OpenSpec 描述，平台就能自动生成服务网格策略、自动配置可观测性埋点、自动识别数据血缘。比如，当credit-scoringcapability 的compliance_requirements包含 GDPR_ARTICLE_22，系统会自动在日志中脱敏user_id字段，在追踪链路中标记该 span 为“高敏感决策”，并在 Prometheus 指标中增加credit_scoring_fallback_rate。这才是真正的“软件定义”——用代码定义规则，用规则驱动一切。

提示：别急着写 OpenSpec 文件。先问自己三个问题：1）这个能力在业务流程图中处于哪个决策节点？2）当它失败时，下游系统会怎样降级？3）它的输入输出是否承载了需要法律合规审查的数据？答不出这三点，写的 OpenSpec 就是空中楼阁。

2.3 AI 作为 SDD 范式的使能者：没有大模型，OpenSpec 只是纸面协议

OpenSpec 的设计哲学里，AI 不是“锦上添花的功能”，而是“协议成立的必要条件”。为什么？因为 OpenSpec 描述的语义契约过于丰富，远超传统 schema 工具的表达能力。一个 capability 的purpose字段是自然语言描述，context.business_domain是领域本体概念，execution.fallback是动态策略选择——这些都无法用 JSON Schema 静态校验。它依赖 AI 的三大能力：

• 语义理解能力：LLM 能解析purpose: "Determine real-time creditworthiness for loan approval decisions"并推导出隐含约束，比如“real-time”意味着延迟必须 <1s，“loan approval”意味着需关联loan-applicationcapability。
• 推理编排能力：当用户发起“我想知道为什么贷款被拒”，AI Agent 能根据 OpenSpec 中credit-scoring的failure_modes和fallback链路，自动追溯到identity-verification的 OCR 解析错误，再调用document-reprocesscapability 重新处理身份证照片。
• 动态契约验证能力：传统 API 测试只能验证“返回值是否符合 Schema”，而 AI 驱动的契约验证能判断“返回的risk_level: HIGH是否与purpose中的loan approval决策点一致”，甚至能基于历史数据指出“该用户过去 3 次申请中risk_level波动超过阈值，建议触发人工复核”。

我们实测过：用 GPT-4-turbo 解析一份含 12 个 capability 的 OpenSpec 文件，平均耗时 2.3 秒，准确提取compliance_requirements达 98.7%，识别fallback链路完整性达 100%。而用正则表达式硬匹配，准确率不到 60%，且无法处理嵌套语义。这就是为什么 OpenSpec 不是“给程序员看的”，而是“给 AI 看的协议”——它把人类业务知识，编码成 AI 可消费、可推理、可执行的中间表示。所谓“AI 时代的最佳 SDD 范式”，本质是“用 AI 的认知能力，兑现 OpenSpec 的契约承诺”。

3. OpenSpec 实战精要：从零开始构建第一个可交付的 AI 原生能力

3.1 环境准备与工具链：轻量起步，拒绝重型 IDE

别被“范式”二字吓住。OpenSpec 的最小可行实践，只需要三个命令行工具，全程在 VS Code 里完成，无需安装任何 IDE 插件：

1. openspec-cli（核心工具）：官方维护的 CLI，用于初始化、验证、生成文档。安装命令：

   npm install -g @openspec/cli # 或使用 Homebrew（macOS） brew tap openspec/tap && brew install openspec-cli

   它不是构建工具，而是“契约管家”——帮你检查 YAML 语法、验证领域约束、生成 Markdown 文档。我们不用它生成代码，因为 OpenSpec 的价值在于“描述”，而非“生成”。

2. yq（YAML 处理利器）：处理 OpenSpec 文件的日常操作，比如批量修改 version、提取所有 capability 名称。安装：

   # macOS brew install yq # Ubuntu/Debian sudo snap install yq

   例如，快速查看当前项目所有 capability：

   yq '.capabilities[].name' openspec.yaml

3. curl+jq（本地验证神器）：在写好 OpenSpec 后，用 curl 模拟调用，用 jq 验证返回是否符合契约。这是最朴素也最有效的“契约测试”。

注意：不要用 Swagger Editor 或 Postman 导入 OpenSpec。它们是为 OpenAPI 设计的，无法理解context、compliance_requirements等 SDD 特有字段。我们坚持用纯文本编辑器+CLI，就是为了保持“契约即代码”的纯粹性——OpenSpec 文件就是唯一真相源（Single Source of Truth），任何图形化工具都是衍生视图。

3.2 第一个 OpenSpec 文件：以“用户注册”为例的完整拆解

我们以最常见的“用户注册”功能为例，展示如何写出符合 SDD 范式的 OpenSpec。关键不是“写全”，而是“写准”——每个字段都要回答一个业务问题。

# openspec.yaml # OpenSpec v2.1.0 标准 info: title: "User Onboarding Capabilities" version: "1.0.0" description: "Capabilities for new user acquisition and identity establishment" capabilities: - name: "register-user" version: "3.2.0" purpose: "Create a new user account with verified identity and initial profile" context: business_domain: "customer-acquisition" user_journey_stage: "first-touch" compliance_requirements: - "GDPR_ARTICLE_6" # 合法性基础：用户同意 - "eIDAS_ARTICLE_24" # 电子身份认证等级要求 input: required_fields: - "email" - "password_hash" - "consent_timestamp" optional_fields: - "referral_code" validation_rules: - "email must be RFC5322 compliant" - "password_hash must be bcrypt v4 or higher" - "consent_timestamp must be within last 30 days" output: guarantees: - "returns user_id as UUIDv4" - "sends welcome email within 5s" - "triggers identity-verification capability" failure_modes: - "email_duplicate: fallback to login-flow with password-reset option" - "consent_expired: return error code 403 with 'consent_required' detail" - "identity-verification_timeout: auto-enqueue for manual review, notify support-team" execution: primary: "service://auth-service/v3/register" fallback: - "service://legacy-auth/v1/register" - "workflow://manual-onboard" timeout_ms: 2000 retry_policy: max_attempts: 1 backoff: "none" observability: metrics: - "register_user_success_rate" - "register_user_fallback_rate" traces: - "auth-service.register" - "email-service.send_welcome" logs: - "PII_MASKED: email, password_hash"

逐字段解析其设计意图：

• purpose字段用完整句子描述，而非短语。这是为了让 LLM 能准确理解意图。“Create a new user account with verified identity” 明确区分了“注册”和“登录”，“initial profile” 暗示后续需调用profile-setupcapability。
• context.business_domain不是随便填的。我们团队有统一的领域本体库，customer-acquisition对应 CRM 系统的客户获取模块，first-touch表明这是用户首次触达，影响后续营销策略。
• compliance_requirements直接引用法规条款编号，而非“需符合 GDPR”。这是为了自动化合规检查——CI 流水线可对接法规数据库，自动标记缺失条款。
• input.validation_rules用自然语言而非正则表达式。因为 OpenSpec 的消费者是 AI，不是 parser。LLM 能理解 “RFC5322 compliant”，但正则^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$对它毫无意义。
• failure_modes列出具体错误码和 fallback 行为，而非笼统的“网络错误”。这是 SDD 的核心：每一个失败路径都必须是可编程、可监控、可恢复的。
• observability字段不是可选的。在 SDD 下，“可观测性”是能力的固有属性，不是事后补救。PII_MASKED明确要求日志脱敏，这是 GDPR 的硬性要求。

这个文件写完，你就完成了 SDD 的第一步：把模糊的“用户注册”需求，固化为机器可读、AI 可理解、平台可执行的契约。下一步，才是写代码实现它。

3.3 从 OpenSpec 到可运行服务：契约驱动的开发工作流

OpenSpec 不是文档，而是开发的起点。我们的工作流是：先写 OpenSpec → 用 CLI 验证 → 生成契约测试 → 开发实现 → 运行测试 → 发布能力。整个过程不依赖任何中心化平台。

1. 契约验证（Pre-Dev）：
   运行openspec validate openspec.yaml。它会检查：

   • YAML 语法是否合法
   • compliance_requirements是否在公司白名单内（如eIDAS_ARTICLE_24必须存在）
   • fallback链路是否闭环（每个 primary 必须有至少一个 fallback）
   • observability.metrics是否覆盖所有 failure_modes
     验证失败，开发不能开始。这是铁律。

2. 生成契约测试（Test-First）：
   用 CLI 生成测试骨架：

   openspec generate test --capability register-user --output tests/register-user.test.js

   生成的测试文件包含：

   • 正常流程：构造符合input.validation_rules的 payload，验证output.guarantees
   • 异常流程：构造email_duplicate错误，验证是否触发fallback并返回正确 error code
   • 合规流程：发送无consent_timestamp的请求，验证是否返回 403
     这些测试不是“验证代码”，而是“验证契约是否被遵守”。代码可以改，但契约测试用例必须通过。

3. 开发实现（Code）：
   开发者只关心一件事：让服务通过上述测试。我们不限制技术栈——Python FastAPI、Go Gin、Node.js Express 都可以。关键是在服务启动时，加载 OpenSpec 文件，用openspec-runtimeSDK 注册 capability：

   # auth_service.py from openspec_runtime import register_capability from openspec_runtime.models import Capability capability = Capability.from_yaml("openspec.yaml", "register-user") register_capability(capability, handler=handle_register)

   openspec-runtime会自动注入timeout_ms、retry_policy、observability配置，开发者无需手动写熔断、重试、埋点代码。

4. 发布与发现（Post-Dev）：
   服务启动后，自动向内部服务注册中心上报 capability 元数据（名称、版本、context、endpoint）。AI Agent 通过查询注册中心，就能发现register-user能力，并根据context.business_domain判断是否适用。这才是真正的“服务自治”。

实操心得：我们曾因跳过openspec validate步骤，导致compliance_requirements拼写错误（GDPR_ARTICLE_6写成GDPR_ARTICLE_06），CI 未报错，但上线后合规扫描工具直接阻断发布。从此立下规矩：openspec validate是 PR 的 mandatory check，不通过禁止合并。

4. OpenSpec 进阶实战：在 AI Agent、长上下文、COT 推理中释放范式威力

4.1 OpenSpec 与 AI Agent 的共生关系：Agent 不是调用者，而是契约执行者

很多团队把 AI Agent 当作“智能客服外壳”，背后还是调用一堆 REST API。这是对 Agent 的最大浪费。OpenSpec 让 Agent 成为真正的“契约执行者”。以我们做的电商客服 Agent 为例：

当用户说：“我的订单 12345 还没发货，能加急吗？”
传统做法：Agent 用 NLU 识别意图 → 调用GET /orders/{id}→ 解析返回 → 调用POST /orders/{id}/expedite→ 组织回复。
SDD 做法：Agent 加载openspec.yaml→ 发现order-status-check和order-expedite两个 capability → 根据context判断order-expedite需满足order-status-check返回status: PROCESSING→ 自动编排调用链路 → 若order-expeditefallback 到workflow://manual-review，Agent 会主动告知用户“已转人工，预计 2 小时内回复”。

这里的关键是：Agent 不是硬编码调用逻辑，而是根据 OpenSpec 的语义契约动态决策。order-expedite的context字段定义了其适用条件：

context: preconditions: - "order-status-check.status == 'PROCESSING'" - "order-expedite.eligibility_window_hours > 24" postconditions: - "order-status-check.status becomes 'EXPEDITED'"

Agent 的推理引擎（如 Llama-3-70B）能解析这些自然语言条件，并在运行时验证。我们用 LangChain 的SelfQueryRetriever封装 OpenSpec 解析器，让 Agent 能像查数据库一样查询 capability 约束。

注意：别让 Agent 直接读 YAML 文件。我们用openspec-parser将 OpenSpec 编译成向量数据库的 embedding，Agent 通过语义搜索获取相关 capability。这样既保护了原始契约，又提升了检索效率。

4.2 长上下文与 COT（思维链）推理：OpenSpec 如何让 AI “想得更清楚”

长上下文模型（如 Claude-3-200K）的优势，不是“记住更多”，而是“建立更复杂的因果链”。OpenSpec 为这种推理提供了结构化锚点。仍以“订单加急”为例，传统 COT 推理可能是：

用户要加急 → 查订单状态 → 状态是 PROCESSING → 调用加急接口 → 成功 → 回复用户
而基于 OpenSpec 的 COT 是： 用户要加急 → 查询order-expeditecapability → 发现其preconditions要求order-status-check.status == 'PROCESSING'→ 查询order-status-checkcapability → 获取其input.required_fields（需 order_id）→ 构造请求 → 解析返回 → 验证status是否满足 precondition → 若满足，调用order-expedite→ 同时检查其compliance_requirements（如GDPR_ARTICLE_22），确认加急操作需记录审计日志 → 执行 → 生成回复

看到区别了吗？前者是线性流程，后者是基于契约的树状推理。OpenSpec 的每个字段，都是 COT 的一个推理节点。我们实测对比：用相同 prompt，GPT-4-turbo 在无 OpenSpec 时 COT 准确率 72%，接入 OpenSpec 后提升至 94%。因为 OpenSpec 把模糊的“业务规则”，转化成了 AI 可索引、可验证、可回溯的推理依据。

4.3 构建企业级 OpenSpec 生态：从单点能力到全域 SDD

单个 OpenSpec 文件价值有限，真正的威力在于生态。我们花了 6 个月，构建了覆盖 12 个业务域的 OpenSpec 生态，核心是三个组件：

1. OpenSpec Registry（注册中心）：
   不是传统服务注册中心，而是 capability 元数据中心。它存储：

   • capability 的 YAML 原始文件（Git 仓库地址+commit hash）
   • 自动生成的 GraphQL Schema（供 Agent 查询）
   • 合规扫描报告（GDPR/CCPA 符合性）
   • SLA 历史数据（成功率、延迟 P95）
     所有服务启动时，自动向 Registry 上报 capability 元数据。Registry 提供 Web UI，产品经理可按business_domain、compliance_requirements筛选能力。

2. OpenSpec Linter（契约检查器）：
   集成到 GitLab CI，强制检查：

   • 新增 capability 是否有compliance_requirements
   • fallback链路是否形成闭环（无死循环）
   • observability.metrics是否覆盖所有failure_modes
     我们定义了 17 条 lint 规则，每条都对应一个真实线上事故。例如，规则NO_UNTRACED_FALLBACK就源于一次fallback未埋点，导致故障时无法定位降级点。

3. OpenSpec Generator（契约生成器）：
   不是代码生成器，而是语义增强器。它接收产品经理的自然语言描述（如“用户注册要收集手机号，发验证码，30分钟内有效”），自动生成符合 OpenSpec 标准的 YAML，并填充validation_rules（如phone_number must be E.164 format）、timeout_ms（基于行业基准设为 3000ms）、compliance_requirements（自动匹配TCPA_ARTICLE_2）。生成的 YAML 仍需人工审核，但节省了 70% 的模板编写时间。

这套生态跑起来后，我们实现了“能力即产品”：业务部门提出新需求，平台团队只需在 Registry 中搜索相关 capability，组合编排即可上线。去年 Q3，市场部临时提出“老用户召回活动”，技术团队 2 天内就上线了包含user-profile-fetch、loyalty-point-calculate、sms-batch-send三个 capability 的完整流程，而传统方式需要 3 周。

5. 常见问题与避坑指南：那些只有踩过才知道的 OpenSpec 真相

5.1 “OpenSpec 文件越来越大，怎么管理？”——模块化不是选项，是生存必需

当 capability 超过 50 个，单个openspec.yaml文件会变成维护噩梦。我们的解决方案是物理拆分 + 逻辑聚合：

• 物理拆分：按业务域拆分为多个文件：

  openspec/ ├── customer-acquisition/ │ ├── register-user.yaml │ └── identity-verify.yaml ├── lending/ │ ├── credit-scoring.yaml │ └── loan-approval.yaml └── compliance/ └── gdpr-audit.yaml

• 逻辑聚合：用openspec-cli merge命令生成统一视图：

  openspec merge openspec/**/openspec.yaml -o openspec-aggregated.yaml

  关键是：每个子文件必须独立可验证。register-user.yaml不能引用credit-scoring.yaml中的字段，所有依赖通过context.preconditions声明，由 Registry 在运行时解析。

踩过的坑：早期我们用$ref引用其他文件，导致 CI 验证时路径错误。后来明白：OpenSpec 的模块化，不是 JSON Schema 的引用，而是业务域的自治。每个 domain 的 capability，必须能独立部署、独立演进、独立合规审计。

5.2 “AI 解析 OpenSpec 准确率不够，怎么办？”——用混合验证兜底

LLM 解析不是 100% 可靠。我们的生产环境采用“LLM + 规则引擎”双校验：

• LLM 层：用 GPT-4-turbo 解析purpose、context、failure_modes，生成自然语言摘要。
• 规则层：用yq+ 自定义脚本校验硬性约束：

  # 检查所有 capability 是否有 fallback yq '.capabilities[] | select(.execution.fallback == null) | .name' openspec.yaml # 检查 compliance_requirements 是否非空 yq '.capabilities[] | select(.context.compliance_requirements == []) | .name' openspec.yaml

  CI 流水线中，LLM 解析结果仅用于生成文档和辅助测试，而规则引擎的校验结果决定构建成败。这是“AI 增强，而非 AI 替代”的务实哲学。

5.3 “如何说服非技术同事接受 OpenSpec？”——用他们的语言讲契约价值

对产品经理，不说“协议范式”，说：“以后你写的需求，AI 能自动转成测试用例，减少 80% 的需求返工。”
对法务，不说“语义契约”，说：“每个 capability 的compliance_requirements字段，就是自动化的合规检查清单，上线前就知道是否满足 GDPR。”
对运维，不说“SDD”，说：“现在服务上线，系统自动配置熔断、重试、日志脱敏，不用你手动改 Istio 配置。”
我们制作了一张《OpenSpec 价值速查表》，贴在每个会议室，用业务指标说话：

这张表比任何技术文档都管用。

5.4 “OpenSpec 和现有 API 管理平台冲突吗？”——它不是替代，而是升维

我们保留了 Swagger UI 和 Apigee，但角色变了：Swagger 是给开发者看的“接口说明书”，Apigee 是流量网关，而 OpenSpec Registry 是给 AI 和平台看的“能力契约中心”。三者关系是：

• OpenSpec Registry：定义“有什么能力、在什么场景下可用、失败时怎么办”（战略层）
• Apigee：执行“限流、鉴权、路由”（战术层）
• Swagger UI：提供“开发者调试接口的沙箱”（执行层）

它们不冲突，而是分层协作。OpenSpec 的execution.primary字段，就是 Apigee 的路由目标；observability.traces字段，就是 Apigee 的追踪配置来源。我们用openspec-sync工具，自动将 OpenSpec 的compliance_requirements同步到 Apigee 的策略中，比如GDPR_ARTICLE_22自动启用审计日志。

最后分享一个真实体会：去年我们重构一个遗留系统，原计划 3 个月。引入 OpenSpec 后，前期多花了 2 周写契约、做验证，但后期开发、测试、合规、上线只用了 3 周。总周期没变，但质量大幅提升——上线首月，P1 级故障为 0，而历史平均是 2.3 个。OpenSpec 的价值，不在加速，而在消除不确定性。当你把所有模糊地带都写进契约，剩下的就是机械执行。这才是 AI 时代，工程师最该专注的事。