AI 2026年3月25日 1 分钟阅读

使用 Claude Code 与 OpenSpec：打造可预测的 AI 开发工作流

tinyash 0 条评论
claude

当强大的 AI 编码助手遇上结构化的规范框架，开发变得既快速又可预测。

什么是 OpenSpec？

OpenSpec 是 Fission-AI 推出的轻量级规范框架，核心理念：

→ fluid not rigid      （灵活而非僵化）
→ iterative not waterfall（迭代而非瀑布）
→ easy not complex     （简单而非复杂）
→ built for brownfield  （为现有项目而生）

它的核心创新在于 artifact-guided workflow（工件引导工作流）：

/opsx:propose "add-dark-mode"  → 创建规范提案
/opsx:apply                    → 执行实现任务
/opsx:archive                  → 归档完成的功能

每个功能变更都会生成结构化的文档：

  • proposal.md — 为什么要做这个改动
  • specs/ — 需求和场景
  • design.md — 技术方案
  • tasks.md — 实现清单

什么是 Claude Code？

Claude Code 是 Anthropic 推出的命令行 AI 编码助手，能够：

  • 直接操作文件系统 — 读取、创建、修改代码
  • 执行终端命令 — 运行测试、构建、安装依赖
  • 理解项目上下文 — 扫描代码库，理解架构
  • 迭代式开发 — 根据反馈持续改进

为什么要把两者结合起来？

1. 解决 AI 编码的不可预测性

AI 编码助手很强大，但如果需求只存在于聊天记录中，结果往往不可预测。OpenSpec 在编码之前建立规范层，让你和 AI 在写代码之前就对”要构建什么”达成共识。

2. 结构化 + 自动化

传统 AI 编码：
  模糊提示 → AI 猜测 → 反复修改 → 最终完成

OpenSpec + Claude Code：
  /opsx:propose → 结构化规范 → /opsx:apply → 按任务实现 → 完成

3. 保持组织性

每个功能变更都有独立的文件夹，包含完整的决策记录。新人加入项目时，可以通过 openspec/changes/ 目录快速理解每个功能的来龙去脉。

快速开始

安装 OpenSpec

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

初始化项目

cd your-project
openspec init

配置 Claude Code

确保你的 Claude Code 支持 OpenSpec 的 slash commands。大多数主流 AI 编码工具都已支持。

实战工作流

步骤 1：提出功能提案

# 在 Claude Code 中输入
/opsx:propose 添加用户认证功能

OpenSpec 会生成：

openspec/changes/add-user-auth/
├── proposal.md    # 为什么需要认证，目标是什么
├── specs/         # 登录、注册、令牌刷新等场景
├── design.md      # JWT 方案、中间件设计
└── tasks.md       # 待实现的任务清单

步骤 2：审查规范

在继续之前，花几分钟审查生成的规范文档：

  • 需求是否完整？
  • 技术方案是否合理？
  • 任务分解是否清晰？

必要时可以修改任何文档，OpenSpec 是灵活的，没有僵化的阶段限制。

步骤 3：执行实现

# 在 Claude Code 中输入
/opsx:apply

Claude Code 会按照 tasks.md 中的清单逐项实现：

✓ 1.1 创建 JWT 工具类
✓ 1.2 实现登录端点
✓ 1.3 实现注册端点
✓ 2.1 添加认证中间件
✓ 2.2 保护需要登录的路由

步骤 4：归档完成的功能

/opsx:archive

功能被归档到 openspec/changes/archive/，规范文档保留作为项目历史。

高级技巧

1. 批量处理多个功能

使用 /opsx:bulk-archive 一次性归档多个已完成的功能，保持工作区整洁。

2. 新人快速上手

/opsx:onboard

为新团队成员生成项目概览，包括所有已实现的功能和当前进行中的变更。

3. 上下文卫生

OpenSpec 受益于干净的上下文窗口。在开始实现之前：

  • 清除之前的聊天记录
  • 只保留相关的规范文档
  • 每次会话专注于一个功能

4. 模型选择

OpenSpec 在高推理能力的模型上表现最佳：

  • 规划阶段：Claude Opus 4.5 / GPT-5.2
  • 实现阶段：Claude Sonnet 4 / GPT-5.1

与其他工具对比

工具优点缺点
Spec Kit (GitHub)详尽完整重量级、阶段僵化、Python 依赖
Kiro (AWS)功能强大锁定 IDE、仅限 Claude 模型
无规范快速开始结果不可预测、难以维护
OpenSpec轻量灵活、工具无关需要学习工作流

实际案例

案例：为 Express 应用添加暗色模式

传统方式：

你：帮我加个暗色模式
AI：好的（生成一些 CSS）
你：不对，我想要系统自动切换
AI：好的（修改代码）
你：还要保存到 localStorage
AI：...（反复多次）

OpenSpec 方式：

/opsx:propose add-dark-mode
→ 生成完整的规范文档，包括：
  - 系统偏好检测
  - 手动切换开关
  - localStorage 持久化
  - CSS 变量方案

/opsx:apply
→ 按任务清单一次性实现所有功能

注意事项

⚠️ 规范是活的

OpenSpec 的规范不是僵化的合同，你可以随时更新任何文档。发现更好的方案？直接修改 design.md。

⚠️ 保持简洁

规范文档应该简洁明了，避免过度设计。一个功能通常 1-2 页文档就够了。

⚠️ 版本控制

将 openspec/ 目录纳入 Git：

git add openspec/

规范文档是项目历史的重要组成部分。

⚠️ 团队协作

团队使用时，可以通过 teams@openspec.dev 获取 Slack 频道访问权限，方便交流最佳实践。

命令速查

命令用途
/opsx:propose创建功能提案
/opsx:apply执行实现任务
/opsx:archive归档完成的功能
/opsx:new创建新变更（扩展工作流）
/opsx:continue继续中断的工作
/opsx:verify验证实现是否符合规范
/opsx:onboard生成新人指南

总结

OpenSpec + Claude Code 的组合代表了规范驱动 AI 开发的未来：

  1. 可预测的结果 — 在编码之前达成共识
  2. 完整的记录 — 每个决策都有文档
  3. 灵活的工作流 — 没有僵化的阶段限制
  4. 工具无关 — 支持 20+ AI 编码助手

开始尝试：

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
# 然后在 Claude Code 中输入：
# /opsx:propose "你的第一个功能"

相关链接

AI AI 工具

发表评论

你的邮箱地址不会被公开，带 * 的为必填项。