在 OpenSpec（一个面向 AI Agent 的规格驱动开发框架，由 Fission-AI 开发）的项目中，openspec/config.yaml 扮演着整个项目的“世界观”和“全局标准层”的角色。

简单来说，AI 编码助手（如 Claude Code、Cursor、Windsurf 等）在执行任何具体任务前，都会先读取这个文件，以确保编写的代码符合你团队的架构规范，而不需要你每次在 Prompt 里重复长篇大论。

以下是 openspec/config.yaml 的核心作用以及各字段的具体使用方式：

核心使用场景

1. 注入项目上下文 (Context Injection)：告诉 AI 你的技术栈（如 TypeScript, React, Next.js 等）、架构模式和领域知识，让 AI 具备“全局视野”。
2. 定义全局规则 (Global Rules)：为不同的设计阶段或产物（如提案 proposal、设计 design、任务 tasks）注入硬性校验规则。
3. 免去 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 产物时，必须包含跨平台兼容性的验证任务”）。

如何生成与生效

1. 初始化自动创建：当你在项目根目录运行 openspec init 时，脚手架工具会自动在 openspec/ 目录下生成这个文件（通常是一个带有注释示例的骨架）。
2. AI 自动读取：当你通过集成了 OpenSpec 的 AI 助手使用命令（如执行 /opsx:continue 或 openspec propose）时，OpenSpec 框架会在后台自动解析该 YAML 文件的内容，并将其作为 System Prompt 的一部分无感地喂给大模型。