跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
编程语言Node.jsAI

OpenSpec 实战指南：在 Cursor 中落地 AI 原生开发工作流

综述由AI生成OpenSpec 是一款基于规范驱动开发（SDD）理念的 AI 辅助开发工具，旨在将 AI 从编码助手升级为工程合作伙伴。 OpenSpec 在 Cursor IDE 中的安装与初始化流程，解析了 CLI 命令行工具与 AI Agent 的协作架构，阐述了 Delta Specs 与 Main Specs 的双重规格系统机制，并详细说明了从探索、定义、执行到归档的标准工作流。通过规范化的文档资产沉淀，OpenSpec 帮助开发者实现可追溯的决策历史和可控的 AI 生成代码，提升开发效率与质量。

剑仙发布于 2026/4/5更新于 2026/5/2129 浏览
OpenSpec 实战指南：在 Cursor 中落地 AI 原生开发工作流

OpenSpec 实战指南：在 Cursor 中落地 AI 原生开发工作流

OpenSpec 是规范驱动开发（SDD）在 Cursor IDE 中的实践方案，旨在将 AI 从编码助手升级为工程合作伙伴。

0. 安装和初始化

安装要求：Node.js >= 20.19.0

npm install -g @fission-ai/openspec@latest
openspec --version

装好后可以查看版本，输出版本号说明安装成功。注意 1.0.0 之后的版本命令已更新，请使用新命令。

选择你的工程目录，打开终端输入 openspec init 初始化目录。

初始化界面

在初始化向导中选择 Cursor IDE。

选择 IDE

确认后显示如下：

确认结果

至此，项目初始化完成。

1. 核心架构解密：CLI 与 Agent 的关系

在 OpenSpec 中，经常看到两类命令：openspec ... 和 /opsx:...。理解它们的底层关系，是掌握这套系统的关键。

1.1 角色定义
  • CLI (openspec ...) —— '机械臂'
    • 本质：底层的命令行工具（类似于 Git 或 NPM）。
    • 能力：只懂文件操作。负责创建文件夹、移动文件、验证 JSON 格式、合并文档。没有智能，不理解业务，只听死命令。
    • 运行位置：Terminal（终端）。
  • Agent (/opsx:...) —— '大脑'
    • 本质：Cursor 的 AI 代理脚本（Prompt Chain）。
    • 能力：拥有智能。负责思考架构、编写文档、生成代码。
    • 运行位置：Chat（对话框）。
1.2 底层调用关系

Agent 是 CLI 的'驾驶员'。

当你输入 /opsx:new "login" 时，实际上发生了一连串的连锁反应：

  1. Agent 思考：AI 先分析你的意图，决定需要创建一个名为 login 的变更。
  • Agent 调用 CLI：AI 在后台默默执行了终端命令 openspec new change "login"。
  • CLI 执行：CLI 在硬盘上创建了目录结构。
  • Agent 接管：AI 看到目录创建好了，开始引导你：'好了，文件夹建好了，我们来写 Proposal 吧…'。

    • 结论：你（用户）指挥 Agent，Agent 指挥 CLI。Agent 封装了繁琐的 CLI 操作，让你专注于业务逻辑。

    2. 双重规格系统：Delta Specs vs. Main Specs

    这是 OpenSpec 最精妙的设计之一。你会发现有两个地方存放 spec.md，它们看似相同，实则作用完全不同。

    2.1 位置对比
    • 位置 A (Delta Specs): openspec/changes/<change-name>/specs/...
    • 位置 B (Main Specs): openspec/specs/...
    2.2 深度解析
    特性Delta Specs (位置 A)Main Specs (位置 B)
    中文名变更规格 (拟议)主规格 (真理之源)
    状态Draft (草稿/拟议中)Live (生效中/已发布)
    含义'我希望系统变成什么样''系统现在是什么样'
    生命周期随变更创建，归档即消失 (合并)永久存在，随项目演进
    Git 类比Feature Branch (功能分支)Main Branch (主分支)
    作用指导 AI 完成本次开发任务指导 AI 理解现有系统能力，帮助新成员上手
    2.3 数据流向
    1. 开发时：你在 changes/ 下编写 Delta Specs。此时，它可能与 Main Specs 冲突（因为你要修改现有功能）。
    2. 归档时 (/opsx:archive)：CLI 会自动将 Delta Specs 合并 (Merge) 到 Main Specs 中。
    3. 完成后：changes/ 文件夹被移走，specs/ 文件夹更新为最新状态。

    3. 标准工作流 (The Workflow)

    第一阶段：思考 (Thinking)
    • 指令：/opsx:explore
    • 作用：自由探索，分析代码，不产生文件。
    第二阶段：定义 (Defining)
    • 指令：
      • /opsx:new "任务名" (新手向，一步步引导)
      • /opsx:ff "任务名" (老手向，Fast-Forward，一次性生成)
    • 产出工件：
      1. Proposal: Why & What (意图)。
      2. Specs (Delta): 具体的、可测试的需求 (WHEN…THEN…)。
      3. Design: 技术选型、架构决策。
      4. Tasks: 执行清单。
    第三阶段：执行 (Executing)
    • 指令：/opsx:apply "任务名"
    • 作用：AI 读取 tasks.md，自动写代码。
    • 技巧：中断后使用 /opsx:continue "任务名" 恢复。
    第四阶段：完成 (Finishing)
    • 指令：/opsx:archive "任务名"
    • 作用：
      1. 验证任务完成度。
      2. 将 Delta Specs 合并进 Main Specs。
      3. 将变更文件夹移入 archive/ 目录作为历史记录。

    4. 最佳实践与 FAQ

    4.1 并行开发与'暂停'
    • 场景：正在做 feature-A，突然要修 bug-B。
    • 操作流：
      1. git stash (保护 feature-A 的半成品代码)。
      2. /opsx:ff "bug-B" (创建修复任务)。
      3. /opsx:apply -> /opsx:archive (修复并归档)。
      4. git stash pop (恢复现场)。
      5. /opsx:continue "feature-A" (继续之前的任务)。
    4.2 为什么不用 Cursor CLI 命令行？
    • Cursor CLI：适合'盲写'和自动化执行，但缺乏全局视图。
    • Cursor IDE：OpenSpec 产生大量文档，IDE 的文件树、分屏对比和 Diff 视图能让你更好地进行决策和审查 (Review)。
    • 建议：在 IDE 里做规划和 Review，享受掌控感。
    4.3 什么时候该用什么命令？
    • 90% 的时间：用 /opsx:... (Agent 命令)。让 AI 帮你干活。
    • 10% 的时间：用 openspec ... (CLI 命令)。通常用于查看状态 (openspec status) 或手动强制归档。

    5. 总结

    OpenSpec 的本质是将'隐性的思维过程'转化为'显性的文档资产'。

    • 它让 AI 不再是'黑盒'，而是可控的'白盒'。
    • 它让你的项目不再只有代码，还有完整的决策历史 (archive/) 和功能说明书 (specs/)。

    目录

    1. OpenSpec 实战指南：在 Cursor 中落地 AI 原生开发工作流
    2. 0. 安装和初始化
    3. 1. 核心架构解密：CLI 与 Agent 的关系
    4. 1.1 角色定义
    5. 1.2 底层调用关系
    6. 2. 双重规格系统：Delta Specs vs. Main Specs
    7. 2.1 位置对比
    8. 2.2 深度解析
    9. 2.3 数据流向
    10. 3. 标准工作流 (The Workflow)
    11. 第一阶段：思考 (Thinking)
    12. 第二阶段：定义 (Defining)
    13. 第三阶段：执行 (Executing)
    14. 第四阶段：完成 (Finishing)
    15. 4. 最佳实践与 FAQ
    16. 4.1 并行开发与“暂停”
    17. 4.2 为什么不用 Cursor CLI 命令行？
    18. 4.3 什么时候该用什么命令？
    19. 5. 总结
    • 💰 8折买阿里云服务器限时8折了解详情
    • Magick API 一键接入全球大模型注册送1000万token查看
    • 🤖 一键搭建Deepseek满血版了解详情
    • 一键打造专属AI 智能体了解详情
    极客日志微信公众号二维码

    微信扫一扫，关注极客日志

    微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

    更多推荐文章

    查看全部
    • 2026 年 2 月 GitHub 热门项目 Top 10（1）
    • GitHub 连接 443 端口报错及 SSL 证书配置解决方案
    • 大厂 Android 性能优化项目实战：腾讯、字节、阿里等技术解析
    • Hadoop YARN SLS 运行中常见问题及解决方案
    • 二分查找实战：旋转数组最小值与缺失数字求解
    • 文心一言：从入门到精通的完整指南
    • 机器学习：逻辑回归与线性回归的区别
    • GitHub Copilot 账号被封禁处理指南
    • 数字图像处理与 FPGA 实现：建立算法思维与硬件思维的桥梁
    • Spring Cloud 与 Dubbo 架构选型与实战对比
    • ASR 自动语音识别技术与 Whisper 模型详解
    • Win10 升级后频繁弹出 Copilot 窗口的彻底禁用方法
    • AI 大模型驱动的软件开发全流程变革：从需求到运维
    • JavaScript 中 var、let、const 的核心区别与实战应用
    • 字节 Seedance 2.0 使用指南：免费渠道与额度策略详解
    • 程序员身份认同与银行服务的定制化探索
    • 基于 Python 与 Selenium 的电商购物车自动结算脚本实现
    • Git 工作流程详解与场景选择指南
    • Python 数据科学工具链实战：NumPy、Pandas 与 Matplotlib 入门
    • 本地大模型构建知识库：Ollama + LobeChat + AnythingLLM

    相关免费在线工具

    • RSA密钥对生成器

      生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

    • Mermaid 预览与可视化编辑

      基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

    • 随机西班牙地址生成器

      随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

    • Base64 字符串编码/解码

      将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

    • Base64 文件转换器

      将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online

    • Markdown转HTML

      将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online