在OpenSpec（一个面向 AI Agent 的规格驱动开发框架，由 Fission-AI 开发）的项目中，openspec/config.yaml扮演着整个项目的“世界观”和“全局标准层”的角色。
简单来说，AI 编码助手（如 Claude Code、Cursor、Windsurf 等）在执行任何具体任务前，都会先读取这个文件，以确保编写的代码符合你团队的架构规范，而不需要你每次在 Prompt 里重复长篇大论。
以下是openspec/config.yaml的核心作用以及各字段的具体使用方式：
核心使用场景
- 注入项目上下文 (Context Injection)：告诉 AI 你的技术栈（如 TypeScript, React, Next.js 等）、架构模式和领域知识，让 AI 具备“全局视野”。
- 定义全局规则 (Global Rules)：为不同的设计阶段或产物（如提案 proposal、设计 design、任务 tasks）注入硬性校验规则。
- 免去 CLI 繁琐参数 (CLI Default)：配置后无需在每次执行 OpenSpec 命令时都手动输入
--schema参数。
配置文件结构解析
一个典型的openspec/config.yaml通常包含以下四个核心字段：
# 1. 声明工作流使用的 Schema 模板schema:spec-driven# 2. 可选：配置规约文件的存放路径（默认是 openspec/specs）specsPath:openspec/specs# 3. 项目的全局上下文（AI 的“世界观”）context:|技术栈: Next.js (App Router), TypeScript, Tailwind CSS, Prisma, PostgreSQL API 风格: RESTful API，所有接口使用 Zod 进行入参校验 测试框架: Jest + React Testing Library，强调集成测试 编码规范: 严格遵守 Backwards Compatibility（向后兼容），不破坏现有公共 API。# 4. 针对不同工序（Artifacts）的特定审查规则rules:proposal:-"必须包含回滚计划（Rollback Plan）。"-"必须明确识别受影响的跨职能团队。"design:-"如果是数据库变更，必须提供对应的 Prisma Schema 修改预览。"tasks:-"必须包含跨平台兼容性验证的任务 checklist。"字段详细说明
schema(必需)
指定 OpenSpec 使用的流程模版，默认通常是spec-driven。AI 会根据这里指定的 schema 去找对应的生命周期命令（如/opsx:new,/opsx:apply）。specsPath(可选)
如果你不想把所有的规格书都放在默认的openspec/specs目录下，可以通过此字段自定义（例如改成docs/specs）。context(核心)
这里使用的是 YAML 的多行字符串语法（|）。这是 AI 执行任何操作时的隐式前置 prompt。在这里写清楚技术栈和业务背景后，AI 之后产出的代码或设计就会天然契合你的项目，大大减少 Token 的无效消耗和幻觉。rules(精准控制)
用于控制开发生命周期中各个产物的质量门禁。比如你可以规定在proposal（提案阶段）AI 必须输出回滚计划；在tasks（任务清单阶段）必须加入自动化测试的步骤。
与其他.md规则文件的区别
在日常使用中，很多开发者容易混淆openspec/config.yaml与 AI 助手自身的规则文件（如 Cursor 的AGENTS.md/.cursorrules或 Claude Code 的CLAUDE.md）。GitHub Issue 中官方及社区给出的区分标准是：
- **
AGENTS.md/CLAUDE.md**：用于规范 AI 的基本编码行为（例如：“绝对不要使用 useEffect”、“所有的 import 必须使用绝对路径”）。- **OpenSpec 的
config.yaml**：用于规范业务与工程的规约策划（例如：“在规划本任务的 Artifact 产物时，必须包含跨平台兼容性的验证任务”）。
如何生成与生效
- 初始化自动创建：当你在项目根目录运行
openspec init时，脚手架工具会自动在openspec/目录下生成这个文件（通常是一个带有注释示例的骨架）。 - AI 自动读取：当你通过集成了 OpenSpec 的 AI 助手使用命令（如执行
/opsx:continue或openspec propose）时，OpenSpec 框架会在后台自动解析该 YAML 文件的内容，并将其作为 System Prompt 的一部分无感地喂给大模型。
