用途:在 OpenSpec 中分两层管理配置。项目级配置位于 openspec/config.yaml,用于提供项目专属上下文与规则;全局 CLI 配置通过 openspec config 子命令管理用户级设置。
适用时机:需要为项目补充上下文以提高 AI 产物质量;为特定产物设置规则(如 specs 必须使用 Given/When/Then);更改项目默认 schema;管理全局 CLI 设置(遥测、编辑器等)。
前提:项目已初始化 OpenSpec。
项目配置字段:schema 为新变更的默认 schema;context 为注入所有产物指令的项目上下文,上限 50KB;rules 为按产物 ID 组织的规则对象。示例结构包含 schema、context(技术栈、API 约定、测试、风格)以及 proposal、specs、design 的规则列表。
工作方式:schema 优先级从高到低为 CLI 参数、变更元数据、项目配置、默认 spec-driven。context 以 project-context 标签前置到每个产物的指令;rules 仅对匹配产物生效,以 project-rules 标签置于 context 之后。spec-driven schema 的产物 ID 包括 proposal、specs、design、tasks。
全局 CLI 配置命令:openspec config list、openspec config get <key>、openspec config set <key> <value>、openspec config unset <key>、openspec config reset --all --yes、openspec config edit、openspec config path。常见设置如关闭遥测 openspec config set telemetry.enabled false、设置用户名 openspec config set user.name "My Name" --string。
输出:包含项目上下文与规则的 openspec/config.yaml,通过上下文注入改善 AI 产物质量。后续可开始使用 openspec-new 或 openspec-explore,或用 openspec-schema 创建自定义 schema 并在配置中设为默认。
限制与排错:规则中出现未知产物 ID 时,需核对 ID 与 schema 是否一致;配置未生效时,确认文件位于 openspec/config.yaml(非 .yml)并检查 YAML 语法;上下文超限时需精简或外链文档(上限 50KB)。