文章目录 OpenSpec 基本概念 什么是 OpenSpec 常用命令 典型执行路径 环境准备 Node.js 安装配置 OpenSpec 安装与初始化 Claude Code 安装与配置 命令行方式 VS Code插件 GPTs API CC-Switch OpenSpec 效果测试 测试用例 指标分析（主观评估） OpenSpec 使用体验 OpenSpec 基本概念 什么是 OpenSpe…
OpenSpec 用规范先行、提案驱动、文件化管理，让 AI 编程从 '模糊对话' 走向 '可控工程'，核心是提质量、降返工、可追溯、易协作。
| 流程阶段 | 对应文件/操作 | 状态标识 |
|---|---|---|
| 创建提案 | proposal.md | 📝 待启动 |
| 实现变更 | apply.md | 🔧 进行中 |
| 归档完成 | archive.md | 📦 已完成 |
| 完成部署 | specs 更新 | 🚀 已上线 |
| 1.x 命令 | 用途 | 旧版 0.x 命令 |
|---|---|---|
/opsx-explore | 自由思考，只读模式，不写代码。允许在动手前理清思路，可衔接 opsx-new。 | |
/opsx-new | 创建一个新变更。 | /openspec:proposal |
/opsx-continue | 创建下一个产物：proposal、specs、design、tasks | /openspec:proposal |
/opsx-ff | Fast-Forward，按依赖顺序一次性生成四个产物。适合需求明确的场景。 | /openspec:proposal |
/opsx-apply | 实现 tasks.md 里的任务。 | /openspec:apply |
/opsx-verify | 检查代码和规范是否一致。 | |
/opsx-sync | 预览规格合并。 | |
/opsx-archive | 完成并归档变更。 | /openspec:archive |
/opsx-bulk-archive | 批量归档多个变更。 |
# 场景1：简单明确需求: /opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive # 场景2：需求表达不出来: /opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply ──► /opsx:archive
| 环境类别 | 具体配置 | 备注 |
|---|---|---|
| 运行环境 | Node.js v24.14.0 | |
| 编辑器 | Claude Code 2.1.63 | 命令行形式 |
| SDD | OpenSpec 1.2.0 | |
| 模型 | claude-opus-4-5-20251101 | |
| 配置管理 | CC-Switch v3.11.1 | |
| 中转服务 | GPTs API |
# 下载安装包wget https://nodejs.org/dist/v24.14.0/node-v24.14.0-linux-x64.tar.xz # 解压tar-xvf node-v24.14.0-linux-x64.tar.xz # 移动到/usr/local安装mv node-v24.14.0-linux-x64 /usr/local/node-v24.14.0-linux-x64 cd /usr/local/node-v24.14.0-linux-x64 # 建立软链接ln-s /usr/local/node-v24.14.0-linux-x64/bin/node /usr/local/bin/node ln-s /usr/local/node-v24.14.0-linux-x64/bin/npm /usr/local/bin/npm # 配置环境变量vim /etc/profile # 添加如下内容exportNODE_HOME=/usr/local/node-v24.14.0-linux-x64 exportPATH=$PATH:$NODE_HOME/bin exportNODE_PATH=$NODE_HOME/lib/node_modules # 使环境变量生效source /etc/profile # 查看版本号验证安装结果node-vnpm-v
安装
# 安装npminstall-g @fission-ai/openspec@latest # 查看版本号检查是否安装成功 openspec --version
项目初始化
cd your-project openspec init
执行初始化后进入欢迎界面
Welcome to OpenSpec A lightweight spec-driven framework ████ This setup will configure: ██ ██ • Agent Skills for AI tools ░░ ████ ░░ • /opsx:* slash commands ░░ ████ ░░ ░░ ████ ░░ Quick start after setup: ██ ██ /opsx:new Create a change ████ /opsx:continue Next artifact /opsx:apply Implement tasks Press Enter to select tools...
选择编程工具（Claude Code）
? Select tools to set up (24 available) Selected: Claude Code Search: [type to filter] ↑↓ navigate • Space toggle • Backspace remove • Enter confirm ○ Amazon Q Developer ○ Antigravity ○ Auggie (Augment CLI) › ◉ Claude Code (selected) ○ Cline ○ Codex ○ CodeBuddy Code (CLI) ○ Continue ○ CoStrict ○ Crush ○ Cursor ○ Factory Droid ○ Gemini CLI ○ GitHub Copilot ○ iFlow (1/2)
生成openspec目录结构
# tree -a .claude openspec .claude ├── commands │ └── opsx │ ├── apply.md │ ├── archive.md │ ├── explore.md │ └── propose.md └── skills ├── openspec-apply-change │ └── SKILL.md ├── openspec-archive-change │ └── SKILL.md ├── openspec-explore │ └── SKILL.md └── openspec-propose └── SKILL.md openspec ├── changes │ └── archive ├── config.yaml └── specs
Claude Code 官方文档：https://code.claude.com/docs/en/overview
# 官方脚本安装curl-fsSL https://claude.ai/install.sh |bash# 或通过npm全局安装npminstall-g @anthropic-ai/claude-code
安装完成后终端提示：
Setting up Claude Code... ✔ Claude Code successfully installed! Version: 2.1.63 Location: ~/.local/bin/claude Next: Run claude --help to get started ⚠ Setup notes: • Native installation exists but ~/.local/bin is not in your PATH. Run: echo'export PATH="$HOME/.local/bin:$PATH"'>> ~/.bashrc &&source ~/.bashrc ✅ Installation complete!
补充配置环境变量
echo'export PATH="$HOME/.local/bin:$PATH"'>> ~/.bashrc &&source ~/.bashrc
验证安装与启动
# 验证版本 claude --version# 启动 claude
启动后配置（主题选择）
Welcome to Claude Code v2.1.63 ………………………………………………………………………………………………………………………………………………………… * █████▓▓░ * ███▓░ ░░ ░░░░░░ ███▓░ ░░░ ░░░░░░░░░░ ███▓░ ░░░░░░░░░░░░░░░░░░░ * ██▓░░ ▓ ░▓▓███▓▓░ * ░░░░ ░░░░░░░░ ░░░░░░░░░░░░░░░░ █████████ * ██▄█████▄██ * █████████ * …………………█ █ █ █……………………………………………………………………………………………………………… Let's get started. Choose the text style that looks best with your terminal To change this later, run /theme ❯ 1. Dark mode ✔ 2. Light mode 3. Dark mode (colorblind-friendly)4. Light mode (colorblind-friendly)5. Dark mode (ANSI colors only)6. Light mode (ANSI colors only) ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 1functiongreet(){2 - console.log("Hello, World!");2 + console.log("Hello, Claude!");3} ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ Syntax theme: Monokai Extended (ctrl+t to disable)
登录方式选择
Welcome to Claude Code v2.1.63 ………………………………………………………………………………………………………………………………………………………… * █████▓▓░ * ███▓░ ░░ ░░░░░░ ███▓░ ░░░ ░░░░░░░░░░ ███▓░ ░░░░░░░░░░░░░░░░░░░ * ██▓░░ ▓ ░▓▓███▓▓░ * ░░░░ ░░░░░░░░ ░░░░░░░░░░░░░░░░ █████████ * ██▄█████▄██ * █████████ * …………………█ █ █ █……………………………………………………………………………………………………………… Claude Code can be used with your Claude subscription or billed based on API usage through your Console account. Select login method: ❯ 1. Claude account with subscription · Pro, Max, Team, or Enterprise 2. Anthropic Console account · API usage billing 3. 3rd-party platform · Amazon Bedrock, Microsoft Foundry, or Vertex AI
登录成功后即可正常使用 Claude Code
╭─── Claude Code v2.1.63 ────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ Tips for getting started │ │ Welcome back Yao! │ Run /init to create a CLAUDE.md file with instructions for Claude │ │ │ ───────────────────────────────────────────────────────────────── │ │ │ Recent activity │ │ ▐▛███▜▌ │ No recent activity │ │ ▝▜█████▛▘ │ │ │ ▘▘ ▝▝ │ │ │ Sonnet 4.6 · API Usage Billing · Yao's Individual │ │ │ Org │ │ │ ~/workspace/FinQuery │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── ❯ Try "write a test for <filepath>" ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── ? for shortcuts
插件市场中搜索'Claude Code for VS Code'进行安装
如无法直连Claude官方服务，可选择中转服务：https://gptsapi.net/
需将各 AI 模型的官方 API 地址替换为 GPTs API 地址：
https://api.openai.com → https://api.gptsapi.nethttps://api.anthropic.com → https://api.gptsapi.nethttps://generativelanguage.googleapis.com → https://api.gptsapi.net调用示例：
curl https://api.gptsapi.net/v1/messages \-H"Content-Type: application/json"\-H"x-api-key: sk-pTp7b3e8164015c23d53138c77a3511683b25d7b7b1G5Y87"\-H"anthropic-version: 2023-06-01"\-d'{ "model": "claude-opus-4-5-20251101", "max_tokens": 1000, "messages": [ { "role": "user", "content": "Hello, who are you" } ] }'
安装 CC-switch 主要是为了方便切换各大模型厂商的API，下载地址：https://github.com/farion1231/cc-switch/releases
配置步骤：添加 Claude 模型供应商，将 API Key、请求地址、主模型替换为 GPTs API 提供的配置。
选取部分有代表性场景记录如下：
| 场景 | 用例 | 期望 | 实际 | 效果 |
|---|---|---|---|---|
| 绿地新项目（从零开始） | 开发Scheme Linking模块 | 功能完整好，代码和设计一致性高 | 和设计还是有不小差距，多处不符合预期，主要表现在：DDL写死在代码里没有用知识库、向量化文本时组装规则不合理导致噪声过大、复杂SQL生成质量差等问题。需要人工阅读AI生成代码，手动优化，浪费很多时间。 | 不满意 |
| 棕地老项目（核心场景） | 优化输入预检机制，只处理财务数据相关问句，对不相干问题返回友好的引导提示 | 精准匹配老项目代码规范， 生成的spec贴合现有项目风格，不污染老代码 | validate检出原有代码隐藏格式错误3处，新增代码无错误；apply后无需大量调整，直接适配老项目环境，未出现兼容性问题。 | 较好 |
| 数据库能力 | 复杂SQL执行报错，分析原因并优化 | 修复MySQL版本导致的兼容问题；优化SQL，禁用多层CTE、窗口函数 | 未能考虑到版本兼容性；没有找到正确优化方向，一直在原有SQL上反复修改细节。 | 一般 |
| 代码注释 | 系统性完善项目代码注释，指定多个Java类 | 注释遵循Java编程规范，使用Javadoc格式，清晰易懂 | 过渡设计，除注释外擅自添加了架构图和流程说明，大量浪费Token。 | 一般 |
| 单元测试 | 生成指定模块的单元测试 | case设计合理，覆盖所有场景，能自动执行 | 比较好，未通过case能自动调整 | 较好 |
| 多人协同 | 模拟多人协同， 2人同时修改不同模块 | 提交Git无核心代码冲突；变更记录清晰，可明确区分两人操作 | 可基于各自spec生成代码，无互相干扰，Java代码冲突率较低，但是在执行归档同步主Spec时经常冲突。 | 较好 |
| 跨项目需求 | 跨项目需求 | 找出多个代码仓库里和本需求相关的修改点，无遗漏 | 把多仓库放在一个目录里，性能很差，也没有找全 | 不满意 |
以下纯属主观印象：
| 指标 | 数据 |
|---|---|
| 对话轮次 | 简单需求<50次；复杂需求150 ~ 500次 |
| Token消耗 | 简单需求<100M；复杂需求>500M |
| 需求对齐耗时 | 除了和产品经理沟通，还要让AI理解，耗时增加了 |
| 功能开发耗时 | 有提升，具体多少不明确，需要多个对照组验证 |
| 代码Review耗时 | 交给AI，原汤化原食 |
| 代码质量打分 | 85分 |
| 代码初次执行成功率 | 80%，大多数情况可以自动修改 |
| 返工率 | 10%，特殊场景下生成代码完全不可用 |
优点
不足
感想
迷茫
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online