English version: 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 架构进行增量扩展，避免推翻重写。