一、OpenSpec 是什么

OpenSpec 是由 Fission‑AI 团队开源的 AI‑原生规范驱动开发（Spec‑Driven Development, SDD）框架 + CLI 工具，核心口号：先对齐规格，再写代码（Align before code）。

• 定位：给 AI 编程助手（Claude Code、Cursor、Copilot ,opencode等）配一套结构化需求契约，防止需求跑偏、幻觉、上下文丢失。
• 形态：本地目录 + Markdown 文件 + 一套 /opsx: 斜杠命令，无云端依赖、无需 API Key、完全 Git 友好。
• 开源：MIT 协议，GitHub 34.9k+ Stars，Node.js 20+ 运行。

二、解决的核心痛点

• 需求散在聊天记录里，会话一丢就找不到。
• AI 理解偏差，代码反复返工。
• 文档与代码脱节，技术债务累积。
• 多人协作时，变更不可追溯、难以审查。

三、核心设计：双文件夹模型

所有配置都在项目根目录的 openspec/ 下：

plaintext

openspec/
├── specs/          # 系统当前生效的规范（Source of Truth，事实来源）
└── changes/         # 正在进行的变更提案（每个功能一个子目录）

• specs/：已确认的需求、设计、约束，归档后自动合并至此。
• changes/：每个变更独立目录，含 proposal.md、specs/、design.md、tasks.md，并行开发互不干扰

四、两套工作流（Core vs Expanded）

• 默认（core）：只有 /opsx:propose、/opsx:apply、/opsx:archive 等少数几个 “一步到位” 的命令，适合快速开发。
• 扩展（expanded）：多了 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard 这些细粒度命令，适合需要精细控制流程的场景。
• openspec config profile + openspec update：就是把 CLI 从默认的 core 切换成 expanded（或自定义），让 AI 能识别并使用这些额外命令。

1）Core（默认，极简快流）

适合小需求、快速开发，3 个核心命令：

• /opsx:propose <name>：一键生成变更目录 + 所有规划产物（相当于 new + ff）
• /opsx:apply：按 tasks.md 实现代码
• /opsx:archive：归档完成的变更
• /opsx:explore：纯思考，不产生产物

流程：

plaintext

/opsx:propose → /opsx:apply → /opsx:archive

2. Expanded（扩展，细粒度控制）

在 core 基础上，多出这些命令（需要手动开启）：

• /opsx:new <name>：只创建空的 change 目录，不生成任何 spec
• /opsx:continue：逐步生成下一个产物（每次一个，适合边想边做）
• /opsx:ff（fast-forward）：一次性生成所有规划产物（直接跳到可实现状态）
• /opsx:verify：实现后做完整性、一致性检查
• /opsx:bulk-archive：批量归档多个变更（适合大项目批量收尾）
• /opsx:onboard：给存量项目做 SDD 冷启动引导

流程：

plaintext

/opsx:new → /opsx:continue 或 /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

五、如何切换工作流（你之前问的）

默认只启用 Core，要使用 Expanded 需两步：

1. 选 Profile（配置）

运行

openspec config profile

交互式勾选 new/continue/ff/verify/bulk-archive/onboard。

2. 生效（更新项目文件）

bash

运行

openspec update

重生成 AGENTS.md、CLAUDE.md、命令定义，AI 即可识别扩展命令。

六、核心价值总结

• ✅ 可控：需求文档化，AI 按 “图纸” 施工，减少幻觉。
• ✅ 可追溯：每次变更留痕，归档后自动入规范，便于审计。
• ✅ 轻量：纯本地文件，无侵入，存量项目可逐步接入。
• ✅ 兼容：支持 20+ AI 工具，不锁定厂商。

七、典型使用场景

• 新功能开发：先写规格再编码，一次通过。
• 复杂重构：分阶段设计、审核、实现，降低风险。
• 多人协作：变更独立提案，评审通过后再合并。
• 存量项目治理：用 /opsx:onboard 快速补全规范。

八、OPSX Slash 命令

在 AI 编码助手的对话界面中调用（如 Claude Code、Cursor、Windsurf）

默认快速路径（CORE PROFILE）

/opsx:propose创建变更并一键生成规划产物

/opsx:explore在提交变更前思考和探索想法

/opsx:apply实现变更中的任务

/opsx:archive归档已完成的变更

扩展工作流命令（自定义选择）

/opsx:new创建新变更脚手架

/opsx:continue按依赖顺序创建下一个产物

/opsx:ff快进：一次创建所有规划产物

/opsx:verify验证实现是否与产物匹配

/opsx:sync将 Delta 规范合并到主规范

/opsx:bulk-archive批量归档多个变更

/opsx:onboard引导式完整工作流教程

/opsx:propose

深入理解 OpenSpec

1.1 OpenSpec 是什么？

OpenSpec 是一个轻量级规范驱动开发框架，专为 AI 编码助手时代设计。它通过建立「人机对齐」的规范层，让开发者和 AI 在编写代码之前先达成共识。

核心定位

OpenSpec 不是取代 AI 编码助手，而是增强它们的可控性和可预测性。它让 AI 从「被动响应聊天历史」转变为「主动遵循结构化规范」。

维度	传统 AI 编码	OPENSPEC 增强
需求来源	聊天历史（易丢失、难追溯）	结构化规范文件（可版本控制）
实现过程	一次性生成，难以迭代	任务驱动，可暂停、可恢复
变更管理	无记录，难以审计	Delta 机制，完整审计轨迹
团队协作	依赖个人 prompt 技巧	标准化工作流，经验可复用

1.2 为什么需要 OpenSpec？

AI 编码助手（如 Claude Code、Cursor、Copilot，opencode）的普及带来了三个核心痛点：

痛点一：AI 幻觉与偏离

需求只存在于聊天中，AI 容易「忘记」上下文或产生幻觉。长对话后，AI 可能偏离最初意图，实现出完全不符合预期的功能。

痛点二：迭代成本高

没有结构化记录，每次修改都需要重新描述上下文。复杂功能的迭代开发变成「从头再来」，效率极低。

痛点三：团队协作难

个人 prompt 技巧无法复用，团队成员的 AI 协作质量参差不齐。缺乏统一的工作流程和质量标准。

OpenSpec 的解决方案

01规范先行

在编码前通过 Proposal 明确意图、通过 Specs 定义行为契约、通过 Design 确定技术方案

02任务驱动

Tasks 文件作为实现清单，AI 按任务逐项执行，可随时暂停和恢复，进度可追踪

03Delta 机制

变更以增量方式记录（ADDED/MODIFIED/REMOVED），完美适配存量项目改造场景

1.3 核心架构解析

理解 OpenSpec 的架构设计，是高效使用它的基础。

OpenSpec 目录结构

openspec/
├── specs/                    # 【权威基准】系统当前行为的完整描述
│   ├── auth/
│   │   └── spec.md           # 认证模块规范
│   ├── payments/
│   │   └── spec.md           # 支付模块规范
│   └── ui/
│       └── spec.md           # UI 行为规范
│
├── changes/                  # 【变更工作区】正在进行的修改
│   ├── add-dark-mode/        # 变更文件夹（每个变更独立）
│   │   ├── proposal.md       # 提案：为什么做、做什么
│   │   ├── specs/            # Delta 规范：正在变化的部分
│   │   │   └── ui/
│   │   │       └── spec.md   # ADDED/MODIFIED/REMOVED 格式
│   │   ├── design.md         # 设计：如何实现
│   │   ├── tasks.md          # 任务：具体实现步骤
│   │   └── .openspec.yaml    # 变更元数据
│   │
│   └── archive/              # 【历史归档】已完成的变更
│       └── 2025-01-24-add-auth/
│
├── schemas/                  # 【可选】自定义工作流 Schema
│   └── my-workflow/
│       ├── schema.yaml
│       └── templates/
│
└── config.yaml               # 项目配置（上下文、规则等）

架构设计哲学
specs/ 与 changes/ 的分离是 OpenSpec 的核心设计。这确保了：① 主规范始终保持稳定 ② 多个变更可并行进行而不冲突 ③ 归档时 Delta 能干净合并回主规范

1.4 产物（Artifact）体系详解

OpenSpec 的产物体系遵循「渐进式明确」原则，每个产物为下一个提供上下文。

Proposal（提案）

职责：回答「为什么做」和「做什么」

• Intent（意图）：解决什么问题
• Scope（范围）：包含/不包含什么
• Approach（方案）：高层次的实现思路

💡 Proposal 是与 AI 对齐的第一步，确保你们对「做什么」有共识

Specs（规范）

职责：定义系统的行为契约

• Requirements：系统必须具备的行为
• Scenarios：可验证的具体场景（Given/When/Then）
• Delta 格式：ADDED / MODIFIED / REMOVED

💡 Specs 是行为契约，不是实现细节。关注「系统做什么」而非「代码怎么写」

Design（设计）

职责：回答「如何实现」

• Technical Approach：技术方案概述
• Architecture Decisions：关键决策及理由
• Data Flow：数据流和组件交互

💡 Design 记录架构决策的「为什么」，方便后续维护和回溯

Tasks（任务）

职责：具体的实现步骤清单

• 分组编号：按模块分组，层级编号（1.1, 1.2...）
• 复选框：- [ ] 未完成 / - [x] 已完成
• 可追踪：AI 按任务执行，进度实时可见

💡 Tasks 是 AI 实现代码的「导航图」，粒度要适中（一个任务 ≈ 一次提交）

产物依赖关系图

OpenSpec 最佳实践

2.1 工作流选择策略

OpenSpec 提供两种主要工作流，选择合适的工作流能显著提升效率。

推荐

Core 快速路径

/opsx:propose → /opsx:apply → /opsx:archive

适用场景：

• 需求明确的中小型功能
• Bug 修复和小型优化
• 时间紧迫需要快速交付
• 个人项目或快速原型

优势：一条命令生成所有产物，最小化仪式感

精细控制

Expanded 扩展路径

/opsx:new → /opsx:continue/ff → /opsx:apply → /opsx:verify → /opsx:archive

适用场景：

• 复杂功能开发（跨模块、跨团队）
• 需求不明确，需要探索
• 需要逐步审查每个产物
• 团队协作项目

优势：每个产物可单独创建和审查，控制粒度更细

工作流选择决策树

选择指南

你能在 30 秒内描述清楚「做什么」吗？
├── 是 → 需求明确
│   ├── 功能复杂度高（>10 个任务）？
│   │   ├── 是 → 使用 Expanded（/opsx:new + /opsx:ff）
│   │   └── 否 → 使用 Core（/opsx:propose）
│   └── 需要团队审查？
│       ├── 是 → 使用 Expanded（/opsx:continue 逐步审查）
│       └── 否 → 使用 Core（/opsx:propose）
│
└── 否 → 需求不明确
    └── 先使用 /opsx:explore 探索，然后选择合适路径

2.2 变更命名规范

好的命名让 openspec list 一目了然，也方便日后追溯。

模式	示例	适用场景
add-<feature>	add-dark-mode、add-export-csv	新增功能
fix-<issue>	fix-login-redirect、fix-memory-leak	Bug 修复
refactor-<module>	refactor-auth-service	代码重构
optimize-<target>	optimize-query-performance	性能优化
update-<component>	update-react-18	依赖更新
implement-<spec>	implement-2fa	实现某个规范

命名原则：动词-名词格式，kebab-case 连字符分隔，具体描述意图。避免使用 feature-1、update、wip 等模糊命名。

.3 高质量规范编写

规范是 OpenSpec 的核心，写好规范是提高 AI 实现质量的关键。

✅ 好的规范示例

# Auth 规范

## 目的
用户身份验证和会话管理。

## 需求

### 需求：JWT 令牌认证
系统 SHALL 在登录成功时颁发 JWT 令牌。

#### 场景：有效凭据登录
- GIVEN 用户具有有效的邮箱和密码
- WHEN 用户提交登录表单
- THEN 系统返回包含 accessToken 和 refreshToken 的响应
- AND accessToken 有效期为 15 分钟
- AND refreshToken 有效期为 7 天
- AND 用户被重定向到 dashboard 页面

#### 场景：无效凭据登录
- GIVEN 用户提交无效的邮箱或密码
- WHEN 用户提交登录表单
- THEN 系统返回 401 状态码
- AND 响应包含 "Invalid credentials" 错误信息
- AND 不颁发任何令牌

❌ 避免的写法

反例：过于实现细节

# 不好的规范 - 包含实现细节

### 需求：登录功能
使用 bcrypt 比较密码，用 jsonwebtoken 库生成 JWT。
在 UserController.login() 方法中实现，
调用 AuthService.validatePassword() 验证...

⚠️

规范 ≠ 实现计划
规范描述「系统应该做什么」（行为契约），不是「代码怎么写」（实现细节）。内部类名、库选择、代码结构应该放在 design.md 中。

2.4 Delta 规范高级用法

Delta 机制是 OpenSpec 适配「存量项目改造」的核心能力。

ADDED：新增需求

## ADDED Requirements

### 需求：双因素认证
系统 MUST 支持基于 TOTP 的双因素认证。

#### 场景：启用 2FA
- GIVEN 用户未启用 2FA
- WHEN 用户在设置页面启用 2FA
- THEN 显示二维码供 Authenticator App 扫描
- AND 用户需输入验证码确认激活

归档效果：追加到主规范末尾

MODIFIED：修改现有需求

示例

## MODIFIED Requirements

### 需求：会话过期时间
系统 MUST 在 15 分钟不活动后使会话过期。
（之前：30 分钟）

#### 场景：空闲超时
- GIVEN 已认证的会话
- WHEN 15 分钟内无任何操作
- THEN 会话被作废
- AND 用户需重新登录

归档效果：替换主规范中同名需求

REMOVED：删除需求

示例

## REMOVED Requirements

### 需求：记住我功能
（因支持 2FA 而废弃。用户应在每次会话重新认证。）

归档效果：从主规范中删除该需求

2.5 项目配置最佳实践

合理的 config.yaml 配置能显著提升 AI 产物质量。

openspec/config.yaml — 推荐配置模板复制

schema: spec-driven

# 项目上下文 - AI 生成产物时会参考这些信息
context: |
  # 项目概述
  项目名称：MyApp
  项目类型：Web 应用
  
  # 技术栈
  前端：React 18 + TypeScript + Tailwind CSS
  后端：Node.js + Express + PostgreSQL
  测试：Jest + React Testing Library
  
  # 代码规范
  - 使用 ESLint + Prettier 进行代码格式化
  - 组件使用函数式组件 + Hooks
  - API 遵循 RESTful 设计
  - 所有公共 API 需保持向后兼容
  
  # 分支策略
  - main: 生产分支
  - develop: 开发分支
  - feature/*: 功能分支

# 每产物规则 - 针对特定产物的额外指导
rules:
  proposal:
    - 必须包含回滚计划
    - 说明对现有功能的影响
    - 列出需要协调的团队
  specs:
    - 使用 Given/When/Then 格式编写场景
    - 优先引用现有模式，避免重复发明
    - 包含边界条件和异常场景
  design:
    - 说明关键技术决策的理由
    - 列出受影响的文件和模块
    - 考虑性能和安全影响
  tasks:
    - 任务粒度适中（每个任务约 1-2 小时工作量）
    - 按模块分组，使用层级编号
    - 包含必要的测试任务

PART 3

从零开始实践

通过完整案例掌握 OpenSpec 工作流

通过完整案例掌握 OpenSpec 工作流

3.1 环境准备

1 安装 OpenSpec

bash复制

# 使用 npm 全局安装（推荐）
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

2 初始化项目

bash复制

# 进入项目目录
cd your-project

# 交互式初始化（推荐）
openspec init

# 或非交互式，指定 AI 工具
 openspec init --tools opencode --force --profile custom jettodata-auth

3配置项目上下文（可选但推荐）

bash复制

# 编辑配置文件，添加项目上下文
# 参考上一节的配置模板
vim openspec/config.yaml

3.2 完整案例：为应用添加暗色模式

让我们通过一个完整案例，体验 OpenSpec 的工作流。

PHASE 1 启动变更

在 AI 编码助手的对话窗口中输入：

AI 对话复制

/opsx:propose add-dark-mode

我想为应用添加暗色模式功能，包括：
1. 在设置页面添加主题切换开关
2. 支持检测系统偏好（跟随系统）
3. 用户选择持久化到 localStorage
4. 所有页面即时切换，无需刷新

AI 将创建：

• openspec/changes/add-dark-mode/proposal.md — 提案文档
• openspec/changes/add-dark-mode/specs/ui/spec.md — Delta 规范
• openspec/changes/add-dark-mode/design.md — 设计文档
• openspec/changes/add-dark-mode/tasks.md — 任务清单

PHASE 2 审查产物（重要！）

在执行实现前，花几分钟审查 AI 生成的产物：

bash — 查看产物复制

# 列出当前变更
openspec list

# 查看变更详情
openspec show add-dark-mode

# 或使用交互式仪表板
openspec view

审查清单：

• ☐ Proposal：意图和范围是否准确？
• ☐ Specs：场景是否覆盖了主要用例和边界情况？
• ☐ Design：技术方案是否合理？
• ☐ Tasks：任务拆分是否合理？粒度是否适中？

Pro Tip：如果发现产物有问题，直接告诉 AI 修改即可，如：「请把 tasks.md 中的第 2 组任务拆分得更细一些」

PHASE 3 实现代码

AI 对话复制

/opsx:apply add-dark-mode

AI 将按照 tasks.md 中的清单逐项实现：

✓ 1.1 创建 ThemeContext

✓ 1.2 添加 CSS 自定义属性

✓ 1.3 实现 localStorage 持久化

→ 2.1 创建 ThemeToggle 组件（进行中）

○ 2.2 添加到设置页面

○ 3.1 定义暗色调色板

💡

可以随时暂停
实现过程中如果需要暂停（下班、开会等），直接停止即可。下次继续时，AI 会从未完成的任务继续执行。

PHASE 4 验证实现（推荐）

AI 对话复制

/opsx:verify

AI 将检查实现是否与产物一致：

• Completeness：所有任务是否完成？所有需求是否实现？
• Correctness：实现是否符合规范意图？
• Coherence：代码是否反映了设计决策？

PHASE 5 归档变更

AI 对话复制

/opsx:archive

归档过程会：

1. 将 Delta 规范合并到 openspec/specs/ui/spec.md
2. 将变更文件夹移动到 openspec/changes/archive/2026-xx-xx-add-dark-mode/
3. 保留完整的产物作为审计轨迹

3.3 CLI 常用命令速查

命令	用途	示例
openspec list	列出所有活动变更	openspec list --json
openspec show	查看变更/规范详情	openspec show add-dark-mode
openspec view	交互式仪表板	openspec view
openspec validate	验证产物格式	openspec validate --all
openspec status	查看产物完成状态	openspec status --change add-dark-mode
openspec archive	归档变更（CLI 方式）	openspec archive add-dark-mode -y
openspec update	更新 AI 工具配置	openspec update
openspec config profile	配置工作流 profile	openspec config profile core

https://radebit.github.io/OpenSpec-Docs-zh/#installation

案例： openspee+opencode

第一步：初始化

openspec init --tools opencode --force --profile  custom  jettotest

第二步：
 

[root@localhost jettotest]# tree openspec/
openspec/
├── changes
├── config.yaml
├── refs
│   ├── 01-context.md
│   └── 02-tech-stack.md
└── specs


[root@localhost jettotest]# cat openspec/config.yaml 
schema: spec-driven
context: |
  - refs/01-context.md
  - refs/02-tech-stack.md
rules:
  proposal:
    - 必须使用**简体中文**
  specs:
    - 必须使用**简体中文**
  design:
    - 必须使用**简体中文**
  tasks:
    - 必须使用**简体中文**


[root@localhost jettotest]# cat openspec/refs/01-context.md 
# 上下线文
创建和删除rm 先关操作先询问我  ask me
[root@localhost jettotest]# cat openspec/refs/02-tech-stack.md 
# 技术栈规范
- 后端：python语言
- 所有后端代码必须放在 wubo-python-be/ 目录下
- 所有前端代码必须放在 wubo-python-fe/ 目录下
- 前端：vue3
- 数据库：sqlit

注意openspec不支持include import先关属性在config.yaml全局入口文件

但是在config.yaml还能refs/01-xxx  02-xxx呢 那不是opespec的功劳而是opencode的功劳

观察确实读取了refs下面的01 02 相关约束文件

[root@localhost openspec]# tree
.
├── config.yaml
└── schemas
    └── jettech
        ├── schema.yaml
        └── templates
            ├── design.md
            ├── mock.json
            ├── openapi.yaml
            ├── proposal.md
            ├── specs
            │   └── spec.md
            └── tasks.md

4 directories, 8 files

分析一下：config.yaml，schema.yaml以及templates之间关系

1.config.yaml: 有context，rules

2.schema.yaml：有
artifacts:
  - id: proposal
    generates: proposal.md
    description: 
    template: proposal.md
    instruction: 
    requires: []
分析一下执行逻辑最后文档形成都参考了什么

 

总前置核心定位（先分清两大文件职责边界）

1. openspec/config.yaml：项目运行层配置（可变、业务层、AI 执行细则） 由使用者自定义，存放当前项目的技术栈、全局标准、每个产物专属强制规则；AI 生成文档 / 代码时优先读取此文件约束。 原生固定顶层字段仅两个：context、rules + 顶层标识 schema: xxx

2. openspec/schemas/jettech/schema.yaml：体系元模型层（稳定、标准链路、不可随意改动） 定义整套 SDD 工作流有哪些产出物、文件生成关系、上下游依赖、绑定哪个模板、交付校验入口apply； 核心节点 artifacts 是整套工作流的目录骨架，只定义「有什么阶段、阶段之间谁依赖谁」，不写任何业务强制细则。

一、config.yaml 完整结构、context /rules 各自作用

1. 顶层标识 schema: jettech

作用：绑定当前项目使用哪一套元模型（对应 schemas/jettech/schema.yaml），OpenSpec 工具通过该值找到对应的 schema 元文件，建立「配置 - 标准体系」关联。

2. context 字段（纯多行文本块，官网原生设计）

作用

全局共享上下文信息，所有产物通用信息统一存放，给 AI 提供项目全局背景、全局统一标准，所有阶段（proposal/specs/openapi...）生成时都会读取。 适合存放：

• 项目名称、项目类型、完整技术栈
• 全局统一语法 / 命名规范（kebab-case、MUST/SHALL、WHEN/THEN、破坏性变更标记）
• Git 分支策略、迭代目录 / 归档目录路径规则
• tasks 固定分组顺序
• apply 交付全局校验流程、prism mock 校验要求

核心特点

1. 全局唯一一处定义，全链路复用，不用在每个产物重复抄写；
2. 偏向背景描述、通用标准、环境目录、分支规范，不拆分逐条数组；
3. instruction、rules 里可以引用 context 中约定的标准，不用重复定义。

和 artifacts.instruction 的关系

• context 是全局公共知识库；
• artifacts.instruction 只是描述「这个文档是干嘛的」轻量化一句话；
• AI 在执行 instruction 描述的动作时，会同步读取 context 里的全局约束作为底层通用规则。

举例： schema.proposal.instruction 只说「输出立项业务清单」，但怎么命名能力、哪些模块受影响、破坏性怎么标记，全部取自 config.context。

3. rules 字段（键值对象，每个 key 对应一个 artifact id，值为字符串数组）

作用

分产物专属强约束，针对单一阶段的精细化强制校验规则，只对当前产物生效，是 AI 生成时的逐条执行检查项。 rules.proposal 仅约束 proposal.md；rules.specs 仅约束 specs 文档，互不干扰。 适合存放：

• 文档内部固定标题、段落强制要求
• 字段渲染、模板加载强制规则（openapi 必须加载完整模板、禁止复用旧文件）
• 禁止行为（spec 不能只写 json 不写字段定义、proposal 不能写代码）
• 产物产出校验阻断规则（不合规则阻断下一阶段生成）

核心特点

1. 按阶段隔离，规则互不污染；
2. 数组逐条校验，机器可逐条识别拦截；
3. 优先级高于 context：同一内容如果 context 是通用描述，rules 是该产物专属细化强制要求。

和 artifacts.instruction 的关系

1. artifacts.instruction：目标描述层（做什么、产出价值，极简一句话）
2. config.rules[产物id]：执行约束层（怎么做、不能做什么、必须遵守哪些细节，逐条强制规则）
3. 执行顺序：AI 先看 instruction 理解文档定位，再严格按 rules 逐条落地校验，同时遵循 context 全局标准。

直观逻辑链路

AI 生成 proposal.md：

1. 读取 schema.artifacts.proposal.instruction → 知道这个文件是立项提案，只写业务范围；
2. 读取 config.context → 知道能力要 kebab-case、破坏性变更要标记、分支目录规范；
3. 读取 config.rules.proposal → 逐条校验：不能写代码、必须标注 be/fe 模块、不能新增清单外能力； 三层结合输出合规文档。

二、schema.yaml 中 artifacts 整体结构 & 内部字段详解

artifacts 总作用

定义整套 SDD 工作流所有产出阶段清单，是 OpenSpec 的工作流元数据骨架，回答三个问题：

1. 有哪些工作阶段？proposal /specs/openapi /mock/design /tasks
2. 每个阶段生成什么文件？generates
3. 阶段之间依赖关系？必须先生成谁才能做当前阶段 requires

artifacts 单条节点所有原生字段（官网标准，无自定义扩展）

yaml

- id: proposal               # 阶段唯一标识，和 config.rules 键一一对应
  generates: proposal.md     # 当前阶段最终产出文件/目录
  description: 迭代立项提案，定义业务能力、变更范围与影响边界 # 阶段简短说明
  template: proposal.md      # 绑定openspec模板目录下的模板文件
  instruction: 轻量化一句话描述该文档核心产出目标 # 仅定位，无细分强制规则
  requires: []                # 前置依赖阶段id，必须先生成依赖产物才可执行当前阶段

逐个字段解释

1. id 唯一标识，关键关联桥梁：

   • 与 config.rules 的 key 完全匹配（rules.proposal 对应 id: proposal）；
   • requires 内填写其他 artifact 的 id，定义串行工作流顺序； apply 流程依赖 tasks 也是通过 id 识别阶段。

2. generates 声明该阶段执行后输出的文件 / 目录路径，工具用于识别产物、归档、校验文件是否存在。

3. template 绑定 schemas/jettech/templates/ 下的空白模板，AI 生成时以此文件为基底填充内容。

4. instruction（重点，区分于 config.rules）

   官方原生定位

   仅一句话概括该产物的核心定位与产出目标，轻量化、无分点细则、无强制校验规则。 只回答：这个文档在工作流里承担什么角色，解决什么问题。

   禁止放入内容（和 config.rules 明确分割）

   • 不能写多条分点强制规范；
   • 不能写字段渲染、语法约束、阻断校验逻辑；
   • 不能写全局命名、场景句式标准； 以上全部交给 config.context + config.rules。

   和 config.rules/context 完整协作关系

   表格

   层级	文件位置	承载内容	作用
   顶层定位	schema.artifacts[X].instruction	一句话：文档是什么、用来干嘛	给 AI 明确产出目标、业务定位
   全局通用标准	config.context	项目全局统一规范、技术栈、目录分支	所有阶段共享底层通用约束
   阶段细分强制规则	config.rules[X]	当前产物逐条执行校验细则	AI 生成时逐条校验、违规阻断

   执行逻辑示例（specs）

   1. schema.specs.instruction：知道 spec 是可测试需求规格，给 openapi 和任务提供依据；
   2. config.context：全局统一场景必须 WHEN/THEN、约束词只能 MUST/SHALL；
   3. config.rules.specs：强制标题格式、每条需求必须带场景、场景必须输出完整字段定义； 三层叠加，先定目标，再套全局标准，最后用专属细则强制落地。

5. requires 定义串行工作流依赖，实现 SDD 固定顺序：

   • specs requires [proposal] → 必须先完成提案，才能生成需求规格；
   • openapi requires [specs] → 需求规格完成后才能生成接口契约； 工具会自动控制生成顺序，禁止跳阶段，是串行工作流的核心依赖控制字段。

schema.apply 补充（和 artifacts 配套）

yaml

apply:
  requires: [tasks]
  tracks: tasks.md
  instruction: 执行全链路交付一致性校验，校验通过后完成迭代归档；仅修改tasks任务勾选状态，不会自动提交、推送代码仓库。

• requires：交付校验必须等 tasks 任务文件生成完毕；
• tracks：以 tasks.md 作为交付验收跟踪载体；
• instruction：仅描述 apply 整体动作，完整校验细则放在 config.context，不堆在 schema

三、整体完整联动链路（从头到尾串联所有关系）

场景：AI 执行生成 specs 需求规格文档

1. 工具读取顶层绑定 config.yaml -> schema: jettech，找到 schemas/jettech/schema.yaml；
2. 在 schema.artifacts 匹配 id=specs 节点： a. 读取 instruction：明确 spec 是可测试需求规格，作为接口和任务依据； b. 读取 generates：输出 specs / 能力名 /spec.md； c. 读取 template：使用 templates/specs/spec.md 空白模板； d. 读取 requires=[proposal]：校验提案文件已生成，不允许跳流程；
3. 读取 config.yaml 全局上下文 context： 拿到全局标准：kebab 命名、WHEN/THEN 句式、破坏性变更标记规范；
4. 读取 config.rules.specs 数组逐条约束： 强制目录名匹配提案、存量需求必须复制基线、场景必须输出字段定义、不合规则阻断 openapi 生成；
5. AI 融合三层信息生成文档： 以 template 为骨架，按 instruction 确定文档定位，遵循 context 全局标准，逐条校验 rules 所有强制要求，产出合规 spec.md。

核心区分总结（一句话分清边界，杜绝混淆）

1. schema.yaml.artifacts[X].instruction：只讲「这个文件是做什么的」（定位层，极简）
2. config.context：全局通用规矩，所有阶段共用（全局标准层）
3. config.rules.X：当前文件必须遵守的一条条硬性校验细则（阶段专属执行层） 三者互不重叠、各司其职，完全遵循 OpenSpec 官方示例分层设计，不新增任何工具不识别的自定义属性。