OpenSpec第六节:AI工具集成

前言

前几课我们学习了OpenSpec的核心概念、工作流程和规范编写。这一课我们将学习如何将OpenSpec与各种AI编程工具集成，包括Cursor、Claude Code等主流工具。通过熟练使用这些集成功能，您可以显著提升开发效率。

Cursor与OpenSpec集成

Cursor是目前最流行的AI代码编辑器之一，OpenSpec原生支持Cursor的斜杠命令。

初始化配置

在使用Cursor之前，需要先配置OpenSpec：

# 初始化OpenSpec并配置Cursor支持openspec init --tools cursor

初始化过程会自动创建以下文件：

.cursor/└── rules/└── openspec-propose.md└── openspec-apply.md└── openspec-archive.md└── openspec-new.md

Cursor斜杠命令

在Cursor中，使用以下斜杠命令：

/openspec-propose — 创建提案

/openspec-propose Add user authentication

AI会自动创建变更文件夹和所有必要的文档。

/openspec-apply — 实施代码

/openspec-apply

AI会按照tasks.md中的任务清单逐项实施。

/openspec-archive — 归档变更

/openspec-archive

AI会归档当前变更并更新规范库。

/openspec-new — 快速创建

/openspec-new feature-name

快速创建一个新的变更，适用于简单场景。

Cursor配置示例

您可以自定义Cursor的OpenSpec规则。在.cursor/rules/目录下编辑相应的规则文件：

# openspec-propose.md## 用途当用户输入/openspec-propose时，创建新的变更提案。## 执行步骤1. 解析用户的需求描述2. 生成唯一的变更ID（kebab-case格式）3. 创建变更文件夹结构4. 生成proposal.md5. 生成specs/目录下的规范文件6. 生成design.md（如果需要）7. 生成tasks.md## 注意事项- 变更ID使用动词开头，如add-、update-、remove-- 规范使用GIVEN-WHEN-THEN格式- 任务清单中的每个任务应该有明确的验收标准

Claude Code与OpenSpec集成

Claude Code是Anthropic推出的AI编程助手，与OpenSpec集成可以实现更智能的开发体验。

初始化配置

# 初始化OpenSpec并配置Claude Code支持openspec init --tools claude

初始化会创建以下文件：

.claude/└── commands/└── opsx-propose.md└── opsx-apply.md└── opsx-archive.md

Claude Code斜杠命令

Claude Code使用冒号格式的斜杠命令。

/opsx:propose

/opsx:propose Add dark mode

或使用更详细的描述：

/opsx:propose "我要添加暗黑模式功能，包括主题切换按钮、CSS变量定义、localStorage持久化"

/opsx:apply

AI会读取当前的变更任务清单，逐项实施。

/opsx:archive

归档当前变更并更新规范库。

/opsx:ff — 快速推进

/opsx:ff add-new-feature

一次性创建所有工件（proposal.md、design.md、tasks.md、specs/）。

/opsx:verify — 验证实现

/opsx:verify

验证当前实现是否符合规范文档。

/opsx:explore — 探索规范

/opsx:explore

在不修改代码的情况下，探索和分析现有规范。

Claude Code配置示例

# opsx-propose.md# OpenSpec Proposal CommandThis command creates a new OpenSpec change proposal.## UsageType `/opsx:propose [description]` to create a new change.## Behavior1. Parse the user's request description2. Generate a unique change ID3. Create the change directory structure4. Generate proposal.md with: - Why: The reason for the change - What: The scope of the change - Impact: Affected components5. Generate specs/*.md with detailed requirements6. Generate design.md if needed7. Generate tasks.md with implementation checklist## Output- openspec/changes/[change-id]/ - proposal.md - design.md - tasks.md - specs/[capability]/spec.md## Guidelines- Use clear, specific descriptions- Include acceptance criteria- Break down complex features

其他AI工具集成

OpenSpec支持20多种AI编程工具，以下是一些常用工具的配置方法。

GitHub Copilot

初始化配置：

openspec init --tools copilot

Copilot会在.github/prompts/目录下创建规则文件。

斜杠命令格式：

/openspec-propose/openspec-apply/openspec-archive

Amazon Q Developer

初始化配置：

openspec init --tools amazon-q

斜杠命令格式：

@openspec-propose@openspec-apply@openspec-archive

Windsurf

初始化配置：

openspec init --tools windsurf

Cline

Cline需要在.clinerules/目录下创建规则文件：

.clinerules/└── openspec.rules

跨工具协作

OpenSpec的设计允许不同团队成员使用不同的AI工具，同时共享相同的规范。

AGENTS.md兼容性

初始化时创建的AGENTS.md文件包含了所有AI工具的指令，确保不同工具能够理解相同的规范格式。

工具切换

当团队成员切换到不同的AI工具时，运行：

openspec update

这会重新生成所有工具的配置文件。

协作示例

假设团队中有使用Cursor的开发者和使用Claude Code的开发者：

1.开发者A（使用Cursor）创建了一个变更提案

2.开发者B（使用Claude Code）可以继续这个变更的实施

3.两个工具使用相同的规范文件，工作流程无缝衔接

AI助手指令优化

您可以通过修改AGENTS.md文件来自定义AI助手的行为。

项目上下文设置

编辑openspec/project.md文件，添加项目特定的上下文：

# Project Context## Tech Stack- Frontend: React + TypeScript- Backend: Node.js + Express- Database: PostgreSQL- Styling: Tailwind CSS## Code Conventions- 组件名使用PascalCase- 函数名使用camelCase- 常量使用UPPER_SNAKE_CASE- 使用TypeScript严格模式## Architecture- 组件化设计- 前后端分离- RESTful API设计- 响应式设计原则## Testing- Vitest for unit tests- Playwright for e2e tests- 覆盖率要求 > 80%

自定义规则

您可以在config.yaml中添加自定义规则：

# openspec/config.yamlproject: name: "my-project" version: "1.0.0"workflow: auto_validate: true require_review: true archive_on_complete: truerules: proposal: include_rollback_plan: true identify_affected_teams: true specs: use_given_when_then: true require_acceptance_criteria: true tasks: max_task_duration: "2h" require_verification: true

高级集成技巧

1. 自动验证

在config.yaml中配置自动验证：

workflow: auto_validate: true validate_on_apply: true

这样每次apply前都会自动验证规范格式。

2. 提交前检查

使用Git hooks在提交前自动验证：

# .git/hooks/pre-commit#!/bin/bashopenspec validate --strict

3. CI/CD集成

在GitHub Actions中集成OpenSpec验证：

# .github/workflows/openspec.ymlname: OpenSpec Validationon: pull_request: paths: - 'openspec/**'jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install OpenSpec run: npm install -g @fission-ai/openspec@latest - name: Validate changes run: | for change in $(openspec list --format json | jq -r '.active_changes[]'); do openspec validate "$change" --strict done

常见问题解答

Q1：AI工具没有显示斜杠命令怎么办？

首先确认已经执行了openspec init，然后重启AI编辑器。如果还不行，执行openspec update重新生成指令文件。

Q2：不同工具的命令格式不同怎么办？

OpenSpec会自动处理不同工具的命令格式差异。您只需要记住当前使用的工具的命令格式即可。

Q3：可以在多个项目中共享配置吗？

可以，但建议每个项目有独立的配置文件，以便根据项目特点进行定制。

Q4：如何自定义AI助手的行为？

编辑openspec/AGENTS.md文件，添加自定义指令。您可以指定AI助手在特定情况下的行为模式。

练习题

4.在Cursor中初始化OpenSpec配置。

5.使用Cursor的/openspec-propose创建一个测试变更。

6.使用Cursor的/openspec-apply实施这个变更。

7.在Claude Code中初始化OpenSpec配置。

8.查看两个工具生成的配置文件，了解它们的差异。

9.配置一个CI/CD workflow，集成OpenSpec验证。

下节预告

下一课我们将学习：

·OpenSpec团队协作指南

·多人协作工作流程

·版本控制与规范管理

·代码审查与规范审查

请在微信客户端打开