# Openspec Assistant

> 执行 OpenSpec 规范驱动开发 (SDD) 。涵盖意图对齐、规范生成、代码实现与自动化验证。支持架构师 (写Spec/评审) 、开发 (写代码) 和 QA (写测试) 角色协同及 /opsx 指令体系。

- Skill: `forceinjection/openspec-assistant` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add forceinjection/openspec-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/forceinjection/openspec-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ForceInjection (https://skillmd.com/u/forceinjection)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/forceinjection/openspec-assistant

---

> English version: [SKILL-en.md](SKILL-en.md)

# OpenSpec 规范驱动开发辅助技能

此技能旨在帮助用户使用 OpenSpec 框架进行敏捷且高确定性的软件开发。作为 AI 编程助手，我们将严格遵循“意图 -> 规范 (Spec) -> 代码 -> 验证”的协同范式，确保 AI 生成的代码可控、可信、可维护。

## 1. 角色职责与执行流程总览

本章节在最前面对 OpenSpec 协作过程中的核心角色和整体执行流程进行全局说明，指导用户和 AI 在不同阶段的协作方式。

### 1.1 核心角色定义

为了保证开发的规范性，我们将工作流拆分为三个核心角色，他们在变更的生命周期中各司其职：

- **架构师 (Architect)**：负责“想清楚”与“最后把关”。在开发前进行意图对齐与规格定义 (生成 Spec) ；在开发后对照 Spec 进行代码评审与归档。
- **测试工程师 (QA)**：负责“验证标准”。基于 Architect 输出的 Spec ，提取业务场景并设计自动化测试用例，为开发提供明确的红绿验收基准。
- **开发工程师 (Developer)**：负责“落地实现”。严格按照 Spec 定义的模型与接口，以及 QA 提供的测试用例，进行业务逻辑的编码实现。

### 1.2 标准执行流程

一个 Change (或 Milestone) 的标准生命周期流转如下：

1. **创建与规格定义 (Architect)**：发起新变更，输出 `proposal.md`、`design.md` 和 `spec.md`。
2. **规格校验 (Architect)**：验证输出的规范文档格式是否 100% 正确。
3. **测试设计 (QA)**：根据 `spec.md` 中的场景 (Scenario) 设计并编写测试用例骨架。
4. **代码实现 (Developer)**：基于规范与测试用例进行编码，建立代码到规格的追踪映射。
5. **测试执行 (QA/Developer)**：运行测试脚本，确保所有系统行为符合预期并全绿通过。
6. **代码评审与归档 (Architect)**：严格评审代码，确认不偏离规格后合并入主基线。

## 2. 核心理念与架构

本章节概述了 OpenSpec 的底层哲学以及核心双态目录结构，作为整个开发流程的理论基础。

OpenSpec 不仅仅是一套文档格式，更是一种规范驱动开发 (Spec-Driven Development) 的工程实践。它作为上下文锚点与契约守护者，约束着代码的生成边界。

- **核心哲学**：流动而非僵化、迭代而非瀑布、简单而非复杂、兼顾存量与新建项目 (Brownfield-first) 。
- **双态管理**：
  - **Source of Truth** (`openspec/specs/`) ：系统当前真实的规格基线。所有已发布的特性都必须在此处有对应的规格定义。
  - **Proposed Changes** (`openspec/changes/<name>/`) ：进行中的变更。每个变更是一个独立的文件夹，包含 `proposal.md` (Why & What) 、`design.md` (How) 、`specs/` (Deltas) 和 `tasks.md` (Steps) 。

## 3. 角色协同与工作流详述

本章节概述了三个核心角色在不同阶段的具体职责与核心动作。

为了保证开发的规范性，我们将工作流拆分为 Architect、QA 和 Developer 三个核心角色。
有关各角色在 Change 生命周期中的详细动作指南，请读取 `references/role-workflow.md` 文件。

## 4. 核心指令体系

本章节列出了驱动 OpenSpec 流程的核心指令，包括 AI 协同指令与底层 CLI 命令。

### 4.1 AI 协同指令 (Slash Commands)

本小节展示了在支持的 AI 编辑器中推荐使用的工作流指令。

推荐使用以下指令驱动全流程：

- `/opsx:propose <description>`：提出变更并生成规范 (Architect 角色) 。
- `/opsx:apply`：根据规范实现代码与测试 (Developer & QA 角色) 。
- `/opsx:archive`：完成开发、评审代码且测试通过后，归档变更合并入主 Spec 。

### 4.2 CLI 命令速查

本小节提供了 OpenSpec 原生命令行工具的操作指引。

当需要进行底层管理或查阅 OpenSpec 原生命令行工具的操作备忘时，请读取 `references/cli-commands.md` 文件。

## 5. 交互与执行准则

本章节总结了使用 OpenSpec 技能时必须遵循的高级指导原则，以确保最佳的 AI 协同效果。

1. **上下文锚点**：在长对话中，始终将 OpenSpec 的文档 (Proposal / Design / Spec) 作为外部存储器。引用已有 Spec 进行扩展，而非重新分析上下文。
2. **契约守护者**：AI 生成的代码必须严格遵循 Spec 定义的接口契约 (Schema) ，绝不随意更改 JSON 结构或状态码 (如 400, 409) 。
3. **先规范后代码**：拒绝在没有 Spec 定义的情况下直接编写业务代码。
4. **增量演进**：在引入复杂特性 (如鉴权、持久化) 时，基于现有 Spec 架构进行增量扩展，避免推翻重写。