Spec-Driven Development 实战：用 spec-kit 将 OpenAPI/AsyncAPI 契约嵌入 CI 流水线

在传统开发流程中，API 规格文档往往沦为「一次性」产物：团队在项目初期编写 OpenAPI 或 AsyncAPI 规范，随后将其束之高阁，任由代码与文档渐行渐远。GitHub 官方推出的 spec-kit 正是为了打破这一困局 —— 它将规格文档从静态参考提升为可执行的开发契约，让「文档即代码、契约即测试」成为工程闭环中的真实环节。

核心哲学：规格即执行

Spec-Driven Development（SDD）的核心理念在于「规格优先」：在编写任何实现代码之前，先用结构化的方式定义「做什么」与「为什么做」，而非「用什么技术做」。spec-kit 作为这一方法论的官方工具链，通过一系列命令行接口与 AI 编码代理深度集成，将规格驱动贯彻到从初始化到实现的完整生命周期。

spec-kit 的工作流由五个核心阶段构成：Constitution（原则制定）→ Specify（规格定义）→ Plan（技术规划）→ Tasks（任务拆解）→ Implement（执行实现）。每个阶段都会生成对应的工件文件，这些文件不仅是人类可读的文档，更是 AI 代理执行时的约束与校验基准。

安装 spec-kit 非常简单，通过 uv 或 pipx 即可完成：

# 持久化安装（推荐）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 或使用 pipx
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z

# 初始化项目（选择 AI 代理集成）
specify init my-project --integration copilot

初始化后，项目中会生成 .specify 目录结构，其中包含 memory/constitution.md（治理原则）、specs/（功能规格）、templates/（模板配置）等关键目录。

CI 流水线中的契约守卫

spec-kit 的真正威力在于与 CI/CD 系统的深度集成。通过社区扩展 CI Guard，团队可以在每次代码提交时自动验证规格文档与实现代码的一致性，防止契约漂移。

关键的 CI 检查点包括：

规格存在性验证：确保每次功能开发都伴随着有效的规格文档，避免「先写代码后补文档」的随意开发模式。

契约漂移检测：通过比对 spec.md 与实际实现的端点、数据模型，发现并报告任何偏离规格的行为。

合并阻断策略：当规格验证失败时，阻止代码合并到主分支，确保只有通过规格检查的代码才能进入下游流程。

一个典型的 CI 配置文件示例：

# .github/workflows/spec-compliance.yml
name: Spec Compliance Check

on:
  pull_request:
    branches: [main]

jobs:
  spec-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Specify CLI
        run: uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
      - name: Run CI Guard
        run: specify extension add ci-guard && specify run ci-guard

扩展生态：从规格到落地的完整链路

spec-kit 的强大之处还在于其丰富的社区扩展生态。目前社区已贡献超过 100 个扩展，涵盖文档生成、代码审查、流程编排、外部集成等多个维度。与 CI 流水线直接相关的扩展包括：

Spec Changelog：自动从规格的 git 历史生成变更日志，确保发布说明与实际功能变更保持同步。

Spec Validate：在 /speckit.implement 执行前进行强制校验，确保规格满足最低可理解性标准。

Spec Sync：检测规格与实现之间的漂移，并提供 AI 辅助的修复建议。

API Evolve：专门针对 API 契约演进的扩展，支持 breaking-change 检测、语义化版本强制执行以及生命周期门控。

对于团队使用 OpenAPI 进行 REST API 开发、或使用 AsyncAPI 进行异步消息契约定义，spec-kit 的 Plan 阶段会生成 contracts/api-spec.json 和 contracts/signalr-spec.md 等契约文件，这些文件可以无缝对接到现有的 API 验证工具链中。

工程闭环参数

要让 spec-kit 在团队中真正发挥作用，以下关键参数值得在项目启动时明确：

规格粒度阈值：单个规格文件的行数建议控制在 300 行以内，超出时应拆分为多个子规格。这既能保证 AI 代理的理解准确度，也便于在 Code Review 时进行增量审查。

阶段通过条件：在进入下一阶段前，当前阶段的工件必须满足基础检查。建议配置为：Specify → 至少 3 个用户故事完成；Plan → 数据模型与 API 契约文件已生成；Tasks → 依赖图无循环；Implement → 所有自动化测试通过且规格覆盖率达到 85% 以上。

AI 代理上下文管理：spec-kit 通过 .specify/memory/ 目录管理项目级别的上下文，团队应定期审查 constitution.md 确保其与当前项目目标一致，避免随着项目演进出现原则与实践脱节的情况。

spec-kit 代表的是一种开发范式的转变 —— 从「代码主导」到「规格主导」。它不只是一个工具，更是一套让团队在 AI 辅助开发时代保持一致性与可追溯性的工程实践。当规格文档不再是事后的补全，而是事前的约束与执行的基准时，团队协作的效率与软件质量都将获得质的提升。

资料来源：GitHub Spec Kit 官方仓库 (github.com/github/spec-kit)

web