Openspec Config

OpenSpec Config Skill

Manage OpenSpec configuration at two levels: project config (openspec/config.yaml) for project-specific context and rules, and global CLI config (openspec config subcommands) for user-level settings.

When to Use

• The user wants to add project context to improve AI artifact quality.
• Setting per-artifact rules (e.g. "specs must use Given/When/Then").
• Changing the default schema for the project.
• Managing global CLI settings (telemetry, editor, etc.).

Prerequisites

• OpenSpec initialized in the project (see openspec-initial).

Project Configuration

openspec/config.yaml

# Default schema for new changes
schema: spec-driven

# Project context injected into all artifact instructions
context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript

# Per-artifact rules
rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

Config Fields

How It Works

• Schema precedence (highest to lowest): CLI flag -> change metadata -> project config -> default (spec-driven).
• Context injection: Prepended to every artifact's instructions in <project-context> tags.
• Rules injection: Only for matching artifacts, in <project-rules> tags, after context.

Artifact IDs (spec-driven schema)

• proposal — Change proposal
• specs — Specifications
• design — Technical design
• tasks — Implementation tasks

Global CLI Configuration

openspec config list          # Show all settings
openspec config get <key>     # Get a value
openspec config set <key> <value>  # Set a value
openspec config unset <key>   # Remove a key
openspec config reset --all --yes  # Reset to defaults
openspec config edit          # Open in $EDITOR
openspec config path          # Show config file location

Common Settings

Outputs

• openspec/config.yaml with project context and rules.
• Improved AI artifact quality through context injection.

Next Steps

• Start working with openspec-new or openspec-explore.
• Create a custom schema with openspec-schema and set it as default in config.

Troubleshooting

• "Unknown artifact ID in rules": Check artifact IDs match your schema; run openspec schemas --json.
• Config not applied: Ensure file is at openspec/config.yaml (not .yml); check YAML syntax.
• Context too large: Limit is 50KB; summarize or link to external docs.

References

• OpenSpec CLI: config
• OpenSpec OPSX: Project Configuration

国内适配

• 支持中文文档和中文注释
• 示例代码兼容国内开发环境
• 提供中文 FAQ 和常见问题解答

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。