OpenSpec 规范驱动开发辅助技能

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

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

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

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

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

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

本章节概述了 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) 。

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

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

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

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

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

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

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

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

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