【OpenSpec完整教程】一篇吃透Claude Code配套OpenSpec｜从安装、三级持久提示词到项目实战

一、前言 🚀

OpenSpec 是适配 Claude Code CLI 的标准化持久提示词工程工具，核心解决重复粘贴编码规范、团队AI代码标准不统一、多项目配置隔离的痛点。
工具基于Node.js发布，全局npm一键安装，支持三级配置作用域自动加载、Git团队共享、批量代码重构、会话持久复用。
本文完整覆盖安装、配置分层、核心命令、项目规范落地、排错实战，所有代码可直接复制运行。

二、一键全局安装 OpenSpec 📦

官方指定安装命令，不可省略，终端执行：

# 全局安装最新版OpenSpec
npm install -g @fission-ai/openspec@latest

# 验证安装是否成功
openspec --version

# 更新工具版本
npm update -g @fission-ai/openspec

安装完成后，终端全局可用 openspec 指令，无需额外配置环境变量。

三、核心概念：三级提示词作用域（优先级分层）📊

3.1 三级配置文件存放路径

完全对齐Claude Code配置逻辑，三层隔离，互不干扰：

1. 全局用户级（本机所有项目，不提交Git）
   Windows：%USERPROFILE%/.openspec/cli.config.yaml
   Mac/Linux：~/.openspec/cli.config.yaml
   适用：公司通用基础编码约束、全局模型参数、安全通用规则
2. 项目级（仓库共享，强制推荐）
   项目根目录：./.openspec.config.yaml
   配套规范文档：./.openspec/rules/coding-standard.md
   适用：项目专属命名、注释、架构、CR审查规则，提交Git全员生效
3. 临时会话级（单次对话，优先级最高）
   交互传参 openspec -p、本地临时SPEC.md、会话内手动输入
   临时内容会覆盖全局/项目配置，仅当前会话生效

3.2 配置加载流程Mermaid流程图（带颜色标识）

优先级规则：临时会话参数 > 项目配置 > 全局配置
项目配置可提交Git，团队克隆仓库自动复用统一编码规范。

四、OpenSpec 核心终端命令大全 🔧

4.1 基础启动命令

终端命令	功能说明	实战场景
openspec	当前目录启动交互式REPL多轮对话	日常迭代、持续代码重构
openspec ./backend-demo	指定项目目录启动工具	多工程快速切换
openspec "编写Python统一异常工具类"	携带初始需求直接进入对话	快速单任务开发
openspec -p "批量重构所有Controller，遵循项目规范"	非交互单次执行，结束自动退出	CI流水线、批量自动化处理
openspec -r spec_session_002	恢复历史会话上下文	中断任务续做
openspec --help	查看全部参数文档	遗忘参数快速查阅

示例单次批量重构命令：

openspec -p "遍历src/main/java下所有接口，统一返回Result<T>，严格遵循.openspec/rules/coding-standard.md规范"

4.2 REPL交互内置斜杠指令（输入/唤起）

进入openspec交互终端后可执行：

# 查看全部内置指令
/help

# 清空当前对话上下文（持久规范不会丢失）
/clear

# 压缩超长会话，减少Token消耗
/compact

# 诊断配置文件加载状态（排错核心指令）
/doctor

# 切换Claude模型：opus/sonnet/haiku
/model opus

# 查看本次会话Token消耗与费用
/cost

五、项目级持久编码规范完整配置（核心实战）💡

需求：将Java/Python编码规范持久写入配置，启动OpenSpec自动注入上下文，团队Git共享，无需重复粘贴规范。

5.1 标准工程目录结构

your-project/
├── .openspec.config.yaml       # OpenSpec项目主配置文件
├── .openspec/
│   └── rules/
│       └── coding-standard.md  # 完整编码规范提示词本体
├── src/
├── pom.xml / pyproject.toml
└── .gitignore

5.2 步骤1：编写规范文档 .openspec/rules/coding-standard.md

# 项目强制编码规范（OpenSpec自动注入上下文）
## 1 Java后端规范
1. 包名全小写，类名大驼峰UpperCamelCase，方法/变量小驼峰lowerCamelCase
2. 所有接口统一返回Result<T>结构体，固定字段code、msg、data
3. 公有类、方法、枚举必须补充完整JavaDoc注释
4. 统一抛项目自定义GlobalException，禁止直接抛出RuntimeException
5. 数据库下划线命名，实体驼峰，MyBatis自动映射

## 2 Python规范
1. 严格遵循PEP8，行宽120，4空格缩进
2. 函数强制添加Type Hints类型注解
3. 工具函数增加多行文档字符串""" """
4. 禁用全局变量，优先依赖注入

## 3 OpenSpec代码输出约束
1. 输出完整可运行代码，不省略导入、配置片段
2. 修改代码标注变更位置，附带修改原因说明
3. 自动生成单元测试，覆盖边界异常场景
4. 代码生成完成后校验是否匹配本规范

5.3 步骤2：项目配置文件 .openspec.config.yaml

# OpenSpec项目级配置，提交Git团队共享
model: astron-code-latest
timeout: 60000

# 持久提示词加载配置（核心）
project_prompts:
  - file: "./.openspec/rules/coding-standard.md"
    weight: 10  # 权重越高，约束优先级越高，规范建议设最高权重
    description: 项目统一编码规范，所有代码生成/重构自动生效

# 权限控制（可选）
permissions:
  allow:
    - Bash(git diff *)
    - Bash(git status)
    - Bash(npm run test)
  deny:
    - Read(.env*) # 禁止读取密钥环境文件

5.4 步骤3：全局通用补充配置（本机私有）

文件路径：~/.openspec/cli.config.yaml

# 本机全局通用配置，不提交Git
project_prompts:
  - file: "~/.openspec/global-base-rule.md"
    weight: 5

~/.openspec/global-base-rule.md 存放通用安全、基础注释约束，所有项目默认加载。

5.5 配置生效校验排错命令

# 进入项目根目录启动交互终端
openspec

# 执行诊断命令，查看已加载的规范文件列表
/doctor

输出日志中出现 ./.openspec/rules/coding-standard.md 即代表自动加载成功。

六、完整实战案例：批量重构后端Controller 🛠️

场景

后端项目统一改造所有Controller，自动适配项目持久编码规范，无需手动粘贴规则。

1. 提前完成上文 .openspec.config.yaml + coding-standard.md 配置
2. 终端进入项目根目录，执行单次非交互批量重构：

openspec -p "遍历src/main/java/com/controller全部Controller文件，统一修改返回体为Result<T>，新增参数校验注释，完全遵循项目coding-standard.md编码规范"

多轮交互完整流程Mermaid图

七、Git仓库团队协作最佳实践 ⚙️

7.1 必须提交到Git的文件

• .openspec.config.yaml
• .openspec/rules/coding-standard.md
  团队成员克隆仓库后，直接执行openspec自动加载统一规范，新人零配置。

7.2 必须忽略的缓存文件（添加至.gitignore）

# OpenSpec 会话缓存、本地个性化配置忽略
.openspec/sessions/
.openspec/*.local.json

7.3 本地个性化覆盖方案

新建 .openspec/settings.local.json，仅本机生效，不提交Git，用于覆盖模型、超时等个人参数。

八、常见问题排错指南 ❌

问题1：编码规范未自动加载

1. YAML严格使用空格缩进，禁止Tab制表符；
2. 执行 openspec → /doctor 查看加载文件清单；
3. project_prompts.file 使用项目相对路径，禁止绝对路径。

问题2：临时参数覆盖项目规范

临时-p参数优先级最高，如需强制使用项目规范：删除-p内冲突约束，或提高yaml中weight权重数值。

问题3：会话过长Token占用爆炸

交互终端执行 /compact 压缩对话上下文，持久提示词不会被压缩丢失。

九、总结 ✨

1. OpenSpec 采用npm全局安装 npm install -g @fission-ai/openspec@latest，适配Claude Code CLI；
2. 三层配置优先级：临时会话 > 项目级配置 > 本机全局配置；
3. 项目级 .openspec.config.yaml + rules/ 方案支持Git团队共享，一次性配置永久生效；
4. /doctor 是配置排错核心指令，批量重构使用 openspec -p 实现自动化编码；
5. 搭配Mermaid流程图清晰梳理加载链路，彻底解决每次对话重复粘贴编码规范的低效问题。