通过 OpenSpec + OpenCode 实践 AI Specs

前段时间写了 《万字长文讲解：团队落地 AI 辅助编程和 AI Specs 实战》，核心内容是讨论公司落地 AI 辅助编程的一些常见问题，通过使用 Kiro 引入 Spec 实现规范驱动开发，也讲解了实践过程。 不过这篇文章太长了，而且强依赖了 Kiro，对使用 Clauda Code、Cursor、OpenCode 的小伙伴来说，迁移成本太大了。

文章地址：https://www.cnblogs.com/whuanle/p/19469026

基于这个背景，所以找时间写这篇基于 OpenSpec + OpenCode 的实践教程。

《万字长文讲解：团队落地 AI 辅助编程和 AI Specs 实战》主要是讲解思路，Kiro 并不重要，本篇主要讲解实现案例、怎么从零开发出一个程序，两篇文章并不冲突，推荐先看万字长文，再看本文。

为什么说 OpenSpec + OpenCode 适合落地呢？

现在市面上的辅助编程工具非常多，以标新立异的 Clauda Code 为首，还有 Codex、 Kimi Code CLI、Roo Code 等命令行工具，以 IDE 交互方式的有 Kiro、VS Code、Cursor 等。所以 Spec 工具不能强依赖一个辅助编程工具，就像 Kiro Spec 只能在 Kiro 下使用，后续迁移到其它辅助编程工具的成本大。

OpenSpec 是纯粹的 Spec 工具，它是开源项目，由社区驱动开发，并且支持集成到 22 种工具中。

由于辅助编程工具的交互方式、智能程度、交付能力差异大，每个开发者的使用体验也不一样，适应习惯也有很大差异，所以团队内没必要限制只能使用某个工具，就像笔者喜欢多个工具同时搭配使用。而 OpenSpec 支持非常多的工具，可以同时在这些工具中开发一个项目，避免因为切换另一个工具开发代码，需要对 Spec 进行迁移。

本文选用 OpenCode 的原因，是因为 OpenCode 也是开源的，它本身支持非常多的模型，可以自定义接入各家的模型商，不像 Kiro、Cursor 要花钱买官方的套餐，所以也很适合用于案例讲解，也适合团队落地做主力工具。

接下来，将以开发一个基金实时估值程序为例，讲解如何实现 AI Specs，但是本文不会围绕团队落地去讲解原理和技术，纯粹是讲解 OpenSpec + OpenCode 怎么用。

规划项目

开发项目要有一个明确说明，不能说一句 ”我要一个基金实时估值的程序“，当然，开发个人项目，也没必要写一堆需求文档说明，因为并没有太多业务场景，开发个人项目的目的是满足个人需求，而不是专业领域业务，所以可以借助 OpenCode 的 plan 功能或 OpenSpec 的 expore 功能帮助我们生成任务规划。

虽然 AI 很强大，但是还是得想想，实现基金实时估计的程序，我需要什么功能？抄！

找一个觉得不错的程序，根据观察别人的程序，然后整理自己想要的功能。

本文写于公元 2026 年 2 月 5 号 周四，可谓是疯狂星期四，亏损了这么多。

以下是笔者手敲的一些需要。

app 定位或目标：做一个能够实时查看基金涨跌幅、估值的 app，以及可以查看当前 A股、美股、港股的行情信息。
app 有两个菜单，“刷新”、“基金”、“行情”
刷新菜单是基金管理功能：
1，能够手动添加基金代码到列表，修改持仓，支持支付宝截图后识别图片同步基金。
2，可以修改基金持仓信息或删除基金
3，界面要能够显示当前涨幅、单日收益、持有收益
4，下拉刷新数据（本身要默认自动1s刷新一次数据）
5，点击具体的基金后，跳转到 “基金” 菜单

基金功能是查看基金详细信息的：
目的是看到一个基金的各类信息，以便让我评估行情和涨跌，以便调仓。
信息显示有三个主要功能：
实时估值，要画出走向图；
业绩走势，显示历史涨跌
我的收益，显示收益信息
接着界面下面显示这个基金的持仓股票信息和份额，然后显示每个股票的实时涨跌幅

行情功能是看不同交易所和指数的：
目的是查看当前 A股、美股、港股的行情信息。
功能按一般证券app实现，该 app 是 桌面 app，不是移动 app。

有了想要做的功能后，还需要列出技术方案。

有了 AI 还需要自己想方案？

笔者认为还是要的，比如基金估值数据从哪里来？如果你自己没有主意，没有提前调研技术方案，那么 AI 自己给了一个通过网络爬取证券公司页面整理信息的方案，这个方案不仅数据十分落后，会消耗大量处理时间，还可能因为爬虫写得好、牢房吃得早。所以，有必要自己去学习、研究技术方案，评估不同技术方案的实现难度、性能、带来的风险。

不过可以利用 AI 的规划能力，大大简少技术调研和编写技术方案的时间，后面会说到。

举个例子，这个程序最重要的数据源，但是花钱买数据源是不可能的，只能白嫖。

研究了一些资料之后，笔者采用 akshare 这个开源项目，它已经内置了多种数据源和采集方案，接口非常齐全。

项目地址： https://github.com/akfamily/akshare

需要想的东西已经想好了，现在通过 tauri 创建一个项目模板，后面的开发工作都在这个项目内进行。

 npm create tauri-app@latest

设计 UI

为了避免在编写界面时花费太多时间调教 UI，反复处理细节，我们可以利用一些支持 MCP 的 UI 工具平台，使用 AI 提前设计页面，这里选择 Pencil。

在 VS Code 里面安装插件 Pencil 插件，然后根据提示使用邮箱注册账号。

Pencli 支持自动配置到多种辅助编程工具上，你可以在扩展的设置面板配置开启 MCP 功能。

重启 OpenCode 后发现已自动连接 Pencil 的 MCP 服务器。

复制 “我需要什么功能” 里面列出的需求，贴到 OpenCode 里面，使用 Plan 模式，然后开始规划设计，跟 AI 不断确认细节。

觉得设计没问题之后，将模式切换为 Build，开始真正设计页面。

在 VS Code 里面可以看到预览。

了解 OpenSpec

安装 OpenSpec 。

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

在 VSCode 安装 OpenSpecCodeExplorer 插件，便于后续维护 Spec 相关文件。

在项目里面执行 openspec init 初始化 OpenSpec 文件，绑定使用 OpenCode，设置完成后需要重启 OpenCode。

可以多选，同时在一个项目里面使用不同的工具。

OpenSpec 会跟项目创建 .openspec 目录和 AGENTS.md 文件，第一次初始化时，.openspec 目录结构比较简单，但是后面随着迭代，目录会越来越复杂。

OpenSpec 的目录结构规划说明如下：

openspec/
├── AGENTS.md               # 人工智能助手使用指南（自动生成）
├── project.md              # 项目专属上下文信息（技术栈、编码/项目规范）
├── specs/                  # 权威基准：当前已部署的功能能力
│   └── [capability]/       # 示例：用户认证、支付处理
│       ├── spec.md         # 需求说明与场景描述
│       └── design.md       # （可选）技术实现模式
├── changes/                # 提案集：正在进行中的活跃工作
│   ├── [change-name]/      # 示例：新增谷歌登录功能
│   │   ├── proposal.md     # 提案背景、核心内容与影响评估
│   │   ├── tasks.md        # 实现任务清单（检查项）
│   │   ├── design.md       # （可选）架构决策文档
│   │   └── specs/          # 增量规格说明（对权威基准的变更内容）
│       └── [capability]/
│           └── spec.md     # 包含 ## 新增/修改/移除 的需求内容
│   └── archive/            # 已完成变更的历史归档

因为关联了 OpenCode，所以 OpenCode 会在 .opencode/command 下生成一些命令文件。

按开发的阶段排序，这些命令的说明如下：

/opsx:explore 、/opsx-explore 是一样的。

为了便于理解 OpenSpec 的工作原理，可以把这些命令分为 CLI 、Command、Skill 三部分。

上面提到的 /opsx:explore 就是 Command，是跟 AI 协作的时候使用的，可以通过 Command 来引导 AI 规划和执行 Spec。

而 CLI 是管理配置或项目用的，功能比较多，但是本文使用不到，这里只列出使用说明。

Command 引导 AI 干活，而 Skill 则是告诉 AI 怎么做，具体要做什么。

体验 OpenSpec

在做了前期规划和了解 OpenSpec 后，我们正式开始进入生成 Spec 和编码的过程。

OpenSpec 强制实施严格的三阶段工作流程，以防止需求漂移，并确保 AI 助手始终与人类意图保持一致，所以开发也是按三步来走。

所谓万丈高楼平地起，做项目的第一步就是把基础架构做好，把架子搭起来，让程序有个基本的页面，所以这里我们不做具体的功能，而且规划一个 Spec 把项目先跑起来。

前面写了 “我需要什么功能” ，但是这种描述并不完善，在 AI 编码之前，要仔细思考想法，调查问题，并明确要求。所以这一步跟 OpenCode 的 plan 一样，先跟 AI 对话，逐步明确细节和步骤。

在对话框输入：

/opsx:explore 创建项目架构

/opsx:explore 后面可以不填主题，也可以直接把 “我需要什么功能” 内容写到里面，这个命令比较灵活。

其实，OpenSpec Command 的本质就是提示词，当你发出 /opsx-explore 创建项目架构 的命令时，实际上是把 opsx-explore.md 文件的内容输入做提示词了。

接着把 “我需要什么功能” 贴到对话框，让 AI 帮助你把想法变为具体的需求说明。你可以在对话中继续跟 AI 探讨明确目标，确认架构规划，然后进入下一阶段。

常见问题：上下文太多，需要新开对话怎么办。

因为需要加载很多提示词、Spec 文件还有代码，导致后面每次对话的 token 会爆炸，为了减少 token 消耗和对话性能，不得不新开一个对话，但是又怕对话上下文丢失。

基于 OpenSpec 做任务时，因为每个功能都会在 openspec/changes 目录，并且会根据任务进度在 tasks.md 里打标记，所以执行命令时指定续写某个功能即可，会自动恢复要做的事情，例如：

/opsx-continue [change-name]

第 1 阶段：创建变更 (提案)

”变更“ 指在原有需要和代码下，需要做改动。

”提案“ 指要做新的功能。

OpenSpec 要求在这个阶段，在将资源投入到 “如何” 之前，强制要求在 “做什么” 和 “为什么” 上保持一致。

这个阶段要做的事情（准确来说是 OpenSpec 会做的事情）：

1. 识别需求：新功能、重构或架构转变。
2. 脚手架：在 openspec/changes/<change-id>/ 下创建唯一目录。
3. 定义规范：为相关功能编写增量 (添加、修改、删除)。
4. 计划：创建 tasks.md 文件，将工作分解成可验证的步骤。

5. 验证（验收）：使用 openspec validation 确保提案在结构上是合理的。

执行命令开始创建 Spec：

/opsx-new
# 或者
/opsx-new {功能名称}

Spec 是不能一下子直接创建的，需要按照流程一个个创建，最后组合成一个 Spec，Spec 每个部分都由一些文件组成，后续 AI 编码时会按照这些文件完成工作。

[ ] proposal
[ ] design
[ ] specs
[ ] tasks

你可以使用 /opsx-continue 进入下一个阶段，或者参考笔者的方式，输入文字说明让 AI 自动流转步骤。

先创建 proposal：

描述这个变更的内容，我来帮你起草 proposal.md

或者输入 /opsx-continue 自动进入此步骤。

design、specs 可以一起并行工作，所以可以输入：

同时创建 design、specs

等 AI 完成任务后，openspec/changes/{功能名称} 下会创建一批文件。

当前阶段最后一步创建任务清单，规划每个环节要做的步骤和目的、验收标准。

创建任务清单

不要急着进入第二阶段，笔者建议好好研究一下 openspec/changes目录下的文件。

第二阶段：实施

这是编码阶段，AI 会根据前面创建的 Spec 去执行编码任务。

OpenSpec 的工作步骤：

1. 上下文加载：人工智能读取 proposal.md 和规范/以理解需求。
2. 执行:AI 按顺序处理 tasks.md。
3. 跟踪：任务实时标记为已完成。

前面提到，如果上下文太长，需要新开对话；或者今天偷懒不写代码，第二天写的时候忘记了进度，那么可以使用 /opsx-continue [change-name] 恢复进度。

如下图，第一阶段的四个步骤已经完成了，提示我们下一步可以使用 /opsx-apply、/opsx-archive 执行编码任务了。

/opsx-apply 按tasks.md 规划一步步实现功能，实现时无需监管。完成任务后，使用/opsx-archive 存档已完成的更改。

所以先执行 /opsx-apply ，刷一会儿抖音，等十几二十分钟，任务执行完毕后。

但是还不能直接存档，需要执行 /opsx-verify [change-name] 检查完整性、正确性和一致性，如果有问题，让 AI 接着改。

如果发现有地方完成得不好，需要调整，可以直接在当前对话中要求 AI 完善设计、修改代码。如果改动比较大，涉及到逻辑和设计的变更，则需要使用 /opsx-sync 把变更同步到 changes 里面。

第 3 阶段：归档 (集成)

这一步要使用 /opsx-archive 归档已完成的更改，也就是标记这个功能已经结束了。

一旦代码部署并验证，变更提案就不再是 “提案”，而是现实代码了，为了减少后续检索成本等，OpenSpec 会做一些操作。

1. 归档命令：运行 openspec archive <change-id>将 change 文件夹移动到 openspec/changes/archive/。
2. 规范合并: CLI 自动将规范增量 (ADDED/MODIFIED 要求) 应用于openspec/specs/ 目录。

因为 OpenSpec 没有数据，也不存数据库，所以主要是根据目录文件来判断工作状态，如果不整理文件，会导致检索时的文件内容很多，把没必要的文件也读取进去了。

openspec/specs 里面存储了程序当前的架构、功能说明等文件和信息，所以每次完成 Spec 后，都需要更新这里的文件，

基础架构搭建起来后，界面太丑了，忘记了让引入 ant design 框架了，也忘记了安装 pencli 的设计走，不过问题不大，后面创建新的 Spec 专门优化即可。当然你也可以先继续完善一些基础功能，然后才归档。

目前界面只是有个架子，功能还是不可用的，我们可以新开一个 change 按一个模块去增加功能，不要一个 change 干一堆事情，小步快跑、逐步积累。

接下来，我们可以继续使用 /opsx-expore 或 /opsx-new 逐步实现其它功能。

目前，该项目还需要实现：

• 界面按照 pencli 的设计图实现界面
• 基金管理功能
• 基金信息查看功能
• 行情功能

可以逐个创建 Spec，逐步实现功能。