用 OpenSpec 和 CodeBuddy 搭建 AI Native 研发流程

AI Coding 很容易被用成“高级自动补全”：工程师在对话框里描述需求，AI 生成一段代码，工程师复制、运行、报错、再追问。这个循环看起来省了敲代码的时间，但项目一复杂，问题就会暴露出来：

• AI 不理解项目架构，容易写出和现有代码风格不一致的实现。
• 需求、设计、代码、测试分散在不同工具里，上下文靠人工搬运。
• 每个人和 AI 的协作方式不同，输出质量取决于提示词水平。
• 文档写完就失效，新人维护系统时只能反向阅读代码。

AI Native 研发不是让 AI 随意改代码，也不是取消工程师的责任，而是把“写代码”这件事变成一条可规划、可审查、可追踪的流水线。人的工作从手工实现转向定义需求、审查方案、控制风险和决定是否合入；AI 则负责按规范执行编码、补测试、同步文档。

这里的“0 人工 Coding”更准确地说，是不再由人直接手写大量业务代码。工程师仍然要做决策、审批和质量把关。

AI 辅助编码的结构性问题

单点使用 AI 写代码时，效率上限通常不高。根因不是模型能力不够，而是协作链路没有工程化。

要解决这些问题，不能只靠“写更好的提示词”。更合理的做法是把需求、设计、任务拆解、代码生成、验证和归档统一到一套规范里。

OpenSpec + CodeBuddy 的核心思路

可以把 OpenSpec 理解成一份“研发契约”。它既能让人审查，也能让 AI 执行。

CodeBuddy 则是执行入口。工程师通过 CodeBuddy 发起规划、编码、审计和归档指令，AI 根据 OpenSpec 中的规范文件完成具体工作。

整体链路如下：

flowchart LR
    A[需求或 Bug] --> B[/opsx:propose 生成变更规划]
    B --> C[人工审查 proposal/design/tasks/specs]
    C --> D[/opsx:apply 按任务清单编码]
    D --> E[测试与 /opsx:verify 审计]
    E --> F[提交 MR 合并请求]
    F --> G[/opsx:archive 归档规范]
    G --> H[openspec/specs 活文档]
    H --> B

这条链路有一个关键点：AI 不直接根据一句模糊需求写业务代码，而是先生成一组可审查的规划文件。人审查通过后，AI 再按任务清单执行。

人的角色也随之变化。

这种模式下，工程师的主要职责不是“替 AI 修一堆代码”，而是让 AI 拿到足够清晰的规范，并在关键节点拦住错误。

OpenSpec 的项目结构

OpenSpec 会在项目中维护一套规范目录。一个典型结构如下：

项目根目录/
└── openspec/
    ├── config.yaml              # 项目配置：技术栈、规范风格、业务背景
    ├── specs/                   # 已归档规范：系统当前能力的活文档
    │   └── user-permission/
    │       └── spec.md
    └── changes/                 # 进行中的变更
        └── add-user-permission/
            ├── proposal.md      # 为什么做、做什么
            ├── design.md        # 怎么做、架构决策是什么
            ├── tasks.md         # 可执行任务清单
            └── specs/           # 本次变更带来的规范增量

其中最重要的是两个目录：

changes/ 里的内容通过评审后会被归档进 specs/。这样，文档不是额外维护的 Wiki，而是研发流程的一部分。

三个核心指令：propose、apply、archive

/opsx:propose：先形成规划，再开始编码

大段业务代码不适合直接让 AI 写。正确入口是先生成规划文件：

/opsx:propose 新增用户权限控制模块，支持角色绑定、权限校验和接口拦截

执行后，AI 会在 openspec/changes/[变更名]/ 下生成一组文件。

tasks.md 建议控制在 15 项以内。任务过多时，AI 需要同时记住大量上下文，更容易遗漏约束或生成前后不一致的代码。复杂需求应该拆成多个原子变更。

一个简化的 tasks.md 可以长这样：

# Tasks

- [ ] 新增权限数据模型和迁移脚本
- [ ] 实现角色与权限绑定接口
- [ ] 实现权限校验中间件
- [ ] 为管理端接口接入权限校验
- [ ] 补充单元测试和接口测试
- [ ] 更新权限模块规范说明

/opsx:apply：按图施工

规划通过审查后，执行：

/opsx:apply add-user-permission

AI 会读取当前变更目录中的 proposal.md、design.md、tasks.md 和 specs/，并结合项目里的已归档规范进行编码。它不再依赖一句临时提示词，而是依据完整上下文跨文件修改代码。

执行过程中，AI 会逐项处理 tasks.md，完成后把对应任务打勾：

- [x] 新增权限数据模型和迁移脚本
- [x] 实现角色与权限绑定接口
- [ ] 实现权限校验中间件

工程师在这个阶段的重点是代码评审，而不是接管所有实现细节。评审时要重点看：

• 是否严格遵守 design.md 的设计约束。
• 是否实现了 specs/ 中描述的行为。
• 是否引入了项目没有使用的依赖。
• 是否破坏现有接口兼容性。
• 测试是否覆盖主要分支和异常场景。

/opsx:archive：让规范跟着代码一起演进

Merge Request（MR，合并请求）通过后，执行：

/opsx:archive add-user-permission

归档会把本次变更中的规范增量合并到 openspec/specs/，并清理 changes/ 下的草稿。之后 AI 再处理相关需求时，会自动把这些已归档规范作为系统现状来理解。

这一步解决的是“文档失效”问题。规范不再是上线前写一次的静态材料，而是每次变更完成后自动沉淀的项目记忆。

更完整的六步研发流

核心三步适合描述主干流程，但实际团队协同时通常还需要审查、验证和 MR 门禁。

flowchart TD
    A[创建变更 /opsx:propose] --> B[审查规划文件]
    B --> C{涉及前端页面?}
    C -- 是 --> D[补充原型图或页面链接到 design.md]
    C -- 否 --> E[执行 /opsx:apply]
    D --> E
    E --> F[运行测试与 /opsx:verify]
    F --> G[提交 MR]
    G --> H[人工审查代码 + 规划文档]
    H --> I{通过?}
    I -- 否 --> B
    I -- 是 --> J[/opsx:archive 归档规范]

前端页面开发要多一个原型审查节点。因为 proposal.md 和 design.md 能说明“做什么”和“怎么做”，但 UI（User Interface，用户界面）还需要回答“长什么样”。把原型截图、设计稿链接或交互说明补进 design.md，AI 生成页面时才有稳定参照。

让 AI 理解项目的三类上下文

流程本身只能保证动作顺序，不能保证 AI 了解项目。要让 AI 写出“符合当前项目”的代码，还需要三类上下文。

flowchart LR
    A[知识库] --> D[CodeBuddy 中的 AI]
    B[MCP 工具连接] --> D
    C[Skills 技能包] --> D
    D --> E[按项目规范生成代码]

可以用一句话概括：

• 知识库让 AI 知道项目是什么。
• MCP 让 AI 连接团队工具。
• Skills 让 AI 掌握团队的标准做法。

知识库：AI 的项目记忆

知识可以分成两层。

常见知识分类如下：

openspec/specs/ 应该承担“系统当前行为”的唯一事实源角色。外部知识库适合补充背景，但不应该替代归档规范。

MCP：AI 的工具连接层

MCP（Model Context Protocol，模型上下文协议）可以让 AI 访问外部工具，减少人工复制粘贴。

没有 MCP 时，工程师需要先打开需求平台，理解内容，再把信息转述给 AI。接入 MCP 后，AI 可以直接读取原始需求，减少信息损耗。

Skills：团队 SOP 的可执行封装

Skills 可以理解成 AI 可调用的技能包。一个 Skill 不只是提示词，它应该包含：

• 什么时候触发。
• 要按什么步骤执行。
• 需要哪些脚本和模板。
• 遇到失败如何降级。
• 哪些文件不能提交。
• 如何检查版本和更新。

一个高质量 Skill 的价值在于：团队经验写一次，所有人都能按同一套流程使用。

openspec-installer：一个生产级 Skill 的结构

新项目接入 OpenSpec 时，如果靠人工操作，通常要处理这些事情：

1. 检查 Node.js 版本。
2. 安装 OpenSpec CLI（Command Line Interface，命令行界面）。
3. 在项目根目录执行初始化。
4. 补全 openspec/config.yaml。
5. 配置 MCP 服务。
6. 安装项目需要的 Skills。
7. 建立知识库目录。
8. 检查 Skill 版本。

这些步骤适合封装成 openspec-installer。使用时可以提供一个团队内的安装入口，例如：

curl -fsSL https://skills.example.com/openspec-installer/install.sh | bash

地址应替换为团队真实的 Skill 仓库或分发服务。

一个完整的 Skill 目录可以这样组织：

openspec-installer/
├── SKILL.md                         # 核心 SOP，告诉 AI 何时触发、如何执行
├── version.json                     # 版本元数据和 changelog
├── scripts/
│   ├── INSTALL_MAC_LINUX.sh         # macOS/Linux 自动安装
│   ├── INSTALL_WINDOWS.ps1          # Windows 自动安装
│   ├── install_skills.sh            # 批量安装项目 Skills
│   ├── check-skill-updates.sh       # 检查 Skills 更新
│   └── self_update.sh               # Skill 自更新
└── templates/
    ├── mcp-servers.json             # MCP 配置模板
    ├── skill-bundle.json            # 默认 Skill 套装
    └── openspec-config-awareness.md # Bridge Rule 模板

这个结构说明，Skill 不是一段安装脚本，而是一套包含 SOP、脚本、配置模板和版本策略的小型系统。

SKILL.md：AI 的执行蓝图

SKILL.md 的 front matter 应该同时服务于人和 AI：人能看懂能力边界，AI 能根据描述判断什么时候该触发。

---
name: openspec-installer
description: 项目初始化工具。自动安装 OpenSpec 开发环境，配置 MCP 服务，批量安装 Skill，创建项目知识库目录，生成 OpenSpec 索引文件，检查 Skill 版本更新。当用户提到安装 OpenSpec、配置 OpenSpec 环境、初始化项目或 openspec init 时使用此 Skill。
version: 0.4.3
module: openspec-installer
tags: [openspec, setup, installation, initialization, mcp, skills]
---

SOP（Standard Operating Procedure，标准作业流程）可以拆成这些步骤：

幂等性非常重要。安装中断后再次执行，脚本不应该重复污染环境，也不应该覆盖用户已经确认过的配置。

Skill 设计里的三个关键决策

Bridge Rule：打通 config.yaml 到 AI 的链路

OpenSpec 的 config.yaml 可以放项目规则，例如：

rules:
  archive:
    - 归档前必须确认 MR 已创建并通过评审
    - 归档后必须更新 INDEX.md 索引
  coding:
    - 新增接口必须包含单元测试
    - 禁止引入未在 package.json 中声明的依赖

但有一个容易忽视的问题：AI 不一定知道每次执行 OpenSpec 操作前都要读取这个文件。

解决办法是在安装时生成一个 Bridge Rule，放到 CodeBuddy 的规则目录中：

mkdir -p .codebuddy/rules

cp "$SKILL_DIR/templates/openspec-config-awareness.md" \
   ".codebuddy/rules/openspec-config-awareness.md"

Bridge Rule 不复制 config.yaml 里的具体规则，只告诉 AI：

---
alwaysApply: true
---

执行 OpenSpec 相关操作前，必须读取 openspec/config.yaml。
如果 config.yaml 中存在 rules 字段，需要把对应规则作为当前操作的约束。

这里的重点是 alwaysApply: true。如果让 AI 自行判断是否加载规则，复杂任务里可能漏掉。Bridge Rule 的内容很短，常驻上下文成本低，却能保证 config.yaml 成为稳定入口。

Token 交互：放在对话层，不放在 bash 脚本里

MCP 服务通常需要 PAT（Personal Access Token，个人访问令牌）。直觉上可以在 bash 脚本里写：

read -p "请输入 Token: " token

但很多 AI 执行命令的环境是非 TTY（终端交互设备），read -p 可能直接挂起，导致安装流程卡住。

更稳妥的方式是把 Token 交互写进 SKILL.md 的 SOP，让 AI 在对话中询问用户：

配置 MCP 服务需要个人访问令牌。
请前往团队 Token 申请页面创建 Token，并粘贴到当前对话。
如果暂时不配置，请回复“跳过”。

拿到 Token 后，再用脚本替换模板中的占位符：

import json
from pathlib import Path

token = "<user_token>"
template = json.loads(Path("templates/mcp-servers.json").read_text())

for server in template.get("mcpServers", {}).values():
    env = server.setdefault("env", {})
    for key, value in env.items():
        if value == "<your_token>":
            env[key] = token

Path(".mcp.json").write_text(
    json.dumps(template, indent=2, ensure_ascii=False)
)

在写入 .mcp.json 前，还应该无条件把它加入 .gitignore，防止 Token 被误提交：

touch .gitignore

if grep -qxF ".mcp.json" .gitignore; then
  echo "[INFO] .gitignore 已包含 .mcp.json"
else
  echo ".mcp.json" >> .gitignore
  echo "[INFO] 已将 .mcp.json 加入 .gitignore"
fi

即使用户选择跳过 Token 配置，这个安全步骤也应该执行，因为用户之后可能手动创建 .mcp.json。

版本检查：辅助功能不能阻塞核心安装

Skill 自身也会迭代。安装时可以检查远端版本，但版本检查失败不应该影响 OpenSpec 初始化。

一个可靠策略是三级降级：

flowchart TD
    A[检查远端版本] --> B{MCP 可用?}
    B -- 是 --> C[通过 MCP 读取 version.json]
    B -- 否 --> D{本地是 Git 仓库?}
    D -- 是 --> E[读取本地 version.json 或浅克隆查询]
    D -- 否 --> F[静默跳过版本检查]
    C --> G[比较版本并提示更新]
    E --> G
    F --> H[继续安装核心环境]
    G --> H

脚本可以通过环境变量接收 AI 使用 MCP 查询到的远端版本：

if [[ -n "${MCP_REMOTE_VERSION:-}" ]]; then
  remote_version="$MCP_REMOTE_VERSION"
  echo "[INFO] 使用 MCP 查询到的远端版本: $remote_version"
elif command -v git >/dev/null 2>&1; then
  echo "[INFO] 尝试通过 Git 查询版本"
  # git clone --depth 1 ... 或读取本地 version.json
else
  echo "[WARN] 无法检查远端版本，跳过"
fi

设计原则很简单：安装 OpenSpec 环境是核心目标，版本提示只是辅助能力。辅助能力失败时，流程继续往前走。

version.json：给人看，也给脚本用

version.json 不只是一个版本号。它可以同时记录仓库位置、Skill 路径和变更说明：

{
  "version": "0.4.3",
  "name": "openspec-installer",
  "description": "项目初始化工具，安装 OpenSpec 环境、配置 MCP 服务、批量安装 Skill",
  "release_date": "2026-03-20",
  "git_repo": "git@example.com:team/skills.git",
  "skill_path": "skills/common/openspec-installer",
  "changelog": {
    "0.4.3": "更新 Bridge Rule 为 alwaysApply: true，确保 OpenSpec 操作稳定读取 config.yaml",
    "0.4.2": "新增 OpenSpec 配置感知 Bridge Rule",
    "0.4.1": "优化版本同步和兜底 SOP",
    "0.4.0": "新增归档后索引自动更新规则",
    "0.3.0": "新增归档前 MR 检查规则",
    "0.2.0": "新增 MCP 配置与 Skill 批量安装"
  }
}

自更新脚本可以解析这个文件，比较本地和远端版本，并展示从当前版本到目标版本之间的变更内容。这样团队成员不需要手动追踪 Skill 更新，也能知道升级带来了什么。

skill-bundle.json：项目默认技能套装

不同项目需要的 Skills 不应该靠新人记忆。可以用一个清单文件描述默认安装项：

{
  "skills": [
    {
      "name": "atomic",
      "type": "local",
      "centerPath": "product/atomic"
    },
    {
      "name": "operation-template",
      "type": "local",
      "centerPath": "product/operation-template"
    },
    {
      "name": "bug-fix",
      "type": "local",
      "centerPath": "engineering/bug-fix"
    }
  ]
}

install_skills.sh 读取清单后批量安装。新项目初始化和新人接入时，只需要执行 installer，不需要再询问“这个项目还要装哪些技能包”。

上手配置流程

安装 OpenSpec 初始化 Skill

把安装地址替换成团队自己的 Skill 分发地址：

curl -fsSL https://skills.example.com/openspec-installer/install.sh | bash

让 CodeBuddy 初始化项目

在项目根目录打开 CodeBuddy CLI 或 IDE 插件，输入：

帮我初始化 OpenSpec 项目

AI 应完成这些动作：

1. 检测 Node.js 环境。
2. 安装 @fission-ai/openspec@latest。
3. 执行 openspec init。
4. 创建 openspec/ 目录。
5. 引导补全 config.yaml。
6. 配置 MCP 和默认 Skills。

补全 config.yaml

config.yaml 是 AI 编码时的重要约束，应认真填写。

project:
  name: order-service
  description: 电商订单管理系统
  stack:
    language: TypeScript
    framework: NestJS
    database: PostgreSQL
  style:
    lint: ESLint Standard
    test: Jest

rules:
  coding:
    - 新增接口必须包含单元测试
    - Controller 只做参数校验和调用编排，业务逻辑放在 Service
    - 禁止直接拼接 SQL
  archive:
    - 归档前必须确认 MR 已通过评审
    - 归档后必须更新模块索引

配置越清楚，AI 后续生成代码时越不容易偏离项目习惯。

CLI 和 IDE 的分工

CodeBuddy CLI 和 IDE 插件适合承担不同职责。

推荐做法是：CLI 负责主流程，IDE 负责审查和局部调整。

前后端多项目联动

如果一个需求同时涉及前端和后端，可以在父目录启动 CodeBuddy CLI，让 AI 同时看到多个仓库。

my-fullstack-workspace/
├── web-frontend/
│   ├── openspec/
│   └── src/
└── api-backend/
    ├── openspec/
    └── src/

在父目录执行：

/opsx:propose 新增订单列表查询能力：后端提供分页查询 API，前端提供筛选表单和表格展示

AI 可以在一次规划中同时拆出后端 API、前端调用、数据类型、测试和联调任务。需要注意的是，跨仓库变更更容易失控，tasks.md 更要保持小粒度，必要时拆成后端 Change 和前端 Change。

扩展指令速查

核心指令足够覆盖大多数场景。复杂需求可以启用扩展工作流：

openspec config profile
# 选择 Workflows only，并启用 new、ff、continue、verify 等扩展命令

/opsx:explore 应只用于讨论和沉淀文档，不应该修改代码。它适合需求模糊、边界不清或技术方案需要比较时使用。

团队协同规则

原子化变更

规范即文档

openspec/specs/ 应作为系统行为的活文档。绕过 OpenSpec 直接手写大量核心逻辑，会导致规范和代码重新脱节。

MR 审查要同时看代码和规划文档

AI Native 研发里的代码评审不能只看 diff，还要对照规划文件。

常见坑和处理方式

一套可落地的判断标准

AI Native 研发是否真正建立起来，可以用几个问题检查：

AI Native 研发的关键不是“让 AI 多写一点代码”，而是建立一套机器能执行、人能审查、团队能复用的工程流程。OpenSpec 提供规范载体，CodeBuddy 提供执行入口，MCP 打通工具上下文，Skills 固化团队经验。四者组合起来，AI 才能从临时打字员变成稳定的研发执行者。