Qwen Code + OpenSpec 实战指南：AI 驱动开发的从安装到落地

1. 安装 Qwen Code

1.1 基本信息

GitHub：https://github.com/QwenLM/qwen-code
中文官网：https://qwenlm.github.io/qwen-code-docs/zh/users/overview/

核心功能

从描述构建功能：用简单语言告诉 Qwen Code 想构建的内容，它会制定计划、编写代码并确保正常运行。
调试和修复问题：描述 bug 或粘贴错误信息，Qwen Code 会分析代码库、识别问题并修复。
导航任何代码库：询问团队代码库相关问题，获得答案；维护项目结构感知，可从网络获取最新信息，通过 MCP 拉取 Google Drive、Figma、Slack 等外部数据。
自动化繁琐任务：修复 lint 问题、解决合并冲突、编写发布说明等，可通过单个命令在开发机器或 CI 中自动执行。

1.2 安装步骤

第一步：全局安装 CLI

bash 复制代码

npm install -g @qwen-code/qwen-code@latest

第二步：配置 Qwen Code

支持两种认证方式（公司电脑无法使用 Qwen OAuth，需用第二种）：

Qwen OAuth（免费）：浏览器登录 qwen.ai 账户。
OpenAI 兼容 API：使用 API 密钥（OpenAI 或兼容提供商/端点）。

配置时需输入：

API key：大语言模型供应商的密钥
Base URL：大语言供应商提供的模型地址
Model：大语言模型的名称

1.2 支持 Agent Skill

Agent Skill 将专业知识打包为可发现能力，含 SKILL.md（模型加载指令）及可选支持文件（脚本、模板）。

启动方式

1. 通过 CLI 标志

bash 复制代码

qwen --experimental-skills

2. 通过 settings.json

添加到 ~/.qwen/settings.json 或项目的 .qwen/settings.json：

json 复制代码

{
  "tools": {
    "experimental": {
      "skills": true
    }
  }
}

其他说明

存储位置 ：~/.qwen/skills/
运行命令 ：/skills <skill-name>

2. 安装 OpenSpec

2.1 基本信息

GitHub：https://github.com/Fission-AI/OpenSpec

主流开源 SDD 工具对比

特性维度	SpecKit	OpenSpec	BMAD
核心理念	"规范即代码源"，开发者维护规范，代码由 AI 生成	"规范锚定"，规范作为长期资产贯穿 AI 辅助开发	"规范优先"，规范是人类与 AI 代理沟通的"单一事实来源"
核心主张	四阶段流程（Specify->Plan->Tasks->Implement）将意图转代码	轻量级流程引擎，规范驱动开发注入现有代码库	定义智能体行为、交互和工具使用编排
工作流	严格线性流程	轻量级、非侵入式流程引擎	基础方法框架，需自行实现协作逻辑
AI 工具兼容性	深度集成 GitHub Copilot，兼容差	支持 Claude Code、Cursor、Copilot 等十几种工具	基础构件，需大量自行集成
项目适配性	零到一（Zero to One）项目	无缝融入现有项目，不改变开发习惯	提供基础构件，需大量自行实现

OpenSpec 核心流程

复制代码

┌────────────────────┐
│ Draft Change       │
│ Proposal           │
└────────┬───────────┘
         │ share intent with your AI
         ▼
┌────────────────────┐
│ Review & Align     │
│ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘                          │
         │ approved plan                        │
         ▼                                      │
┌────────────────────┐                          │
│ Implement Tasks    │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘

流程步骤：

起草变更提案（捕获规范更新意图）。
与 AI 助手审核提案至共识。
实施引用已批准规范的 task（AI 写代码）。
归档变更，将批准的更新合并回源规范。

2.2 安装步骤

前置条件

Node.js ≥ 20.19.0（通过 node --version 检查版本）。

第一步：全局安装 CLI

bash 复制代码

# 安装
npm install -g @fission-ai/openspec@latest

# 确认安装
openspec --version

第二步：项目中初始化 OpenSpec

bash 复制代码

# 进入项目目录
cd my-project

# 运行初始化
openspec init

初始化过程：

提示选择原生支持的 AI 工具（Claude Code、CodeBuddy 等），其他 agent 依赖共享存根 AGENTS.md。
自动配置所选工具的斜杠命令，在项目根写入受管理的交接 AGENTS.md。
创建 openspec/ 目录，结构如下：
复制代码
```
openspec
 - AGENTS.md
 - project.md
```

project.md可参考：一个AI编码的项目规范约束（project规范）

第三步：检查状态

bash 复制代码

openspec list  # 验证设置状态，查看当前活跃变更提案

初始化后，主流 AI 工具可直接使用 /openspec 相关命令。

2.3 配置 Qwen Code

执行 openspec init 选择 AI 模型时选 qwen-code，会在当前目录创建 .qwen 目录，含三个配置文件：

复制代码

.qwen
  - commands
     - openspec-apply.toml
     - openspec-archive.toml
     - openspec-proposal.toml

3. AI 编码实践

3.1 配置 OpenSpec 项目约束文件

openspec init 后生成：

AGENTS.md：定义 AI 模型 agent 的引导。
project.md：定义项目规范约束（可由 AI 生成）。

3.2 创建变更（五步骤）

1. 起草提案

启动 qwen-code（qwen 或 qwen --experimental-skills），提交变更请求：

bash 复制代码

/openspec-proposal 构建一个业务场景agent注册中心生成注册表，提供新增、编辑和查询功能，一个业务场景只有一个生效的智能

生成目录结构：

复制代码

openspec
  - changes
     - 对应变更名称  （AI 创建的名称）
        - design.md     （提案设计）
        - proposal.md  （变更提案）
        - tasks.md       （完成任务所需任务）

2. 核实与审核

检查变更是否正确创建并审查提案：

bash 复制代码

$ openspec list                             # 确认变更文件夹存在
$ openspec validate add-profile-filters     # 验证规范格式
$ openspec show add-profile-filters         # 审查提案、任务和规范差异

3. 检查与完善

若 AI 理解偏差或提案不符需求，可：

与 AI 多轮交流修正提案设计。
手动修改 design.md、proposal.md 等文档。

4. 实施任务

文档完善后，执行实施：

bash 复制代码

/openspec-apply 指定开始实施的任务

5. 归档变更

验证无误后归档：

bash 复制代码

/openspec-archive 指定归档的变更

一键三连，让我的信心像气球一样膨胀！