Claude Code 工作流程化 OpenSpec 保姆级教程

一、前言 🚀

日常使用**Claude Code开发时，反复粘贴项目编码规范、接口约束、架构规则极大降低效率。OpenSpec** 是配套Claude Code的标准化持久提示词工具，无需本地安装，通过**npx OpenSpec** 一键拉起，支持全局/项目/临时三级配置自动加载，团队可Git共享统一代码规范，彻底告别重复输入约束文本。

本文跳过安装流程，聚焦**npx OpenSpec** 命令、配置分层、工程目录、完整实战案例、排错方案，全部代码可直接复制复用。

二、核心概念：OpenSpec三级提示词作用域 📊

2.1 三级配置文件存放位置（优先级从低到高）

1. 全局用户级（本机所有项目共用，不提交Git）
   Windows：%USERPROFILE%/.openspec/spec.global.yaml
   Mac/Linux：~/.openspec/spec.global.yaml
   适用：通用安全约束、基础注释规范、全局模型参数

2. 项目级（仓库共享，团队强制同步，核心）
   项目根目录：./.openspec.yaml
   配套规范文档：./.openspec/rules/code-standard.md
   适用：项目专属命名、接口返回、数据库映射、CR审查规则，提交Git全员生效

3. 临时会话级（单次对话，优先级最高）
   启动命令传参-p、交互内临时指令、本地临时SPEC.md
   临时规则会覆盖全局/项目配置，仅当前会话生效

2.2 配置加载优先级Mermaid流程图（带颜色）

三、npx OpenSpec核心命令大全 🔧

无需全局安装，任意项目目录直接运行**npx OpenSpec**，覆盖交互、批量任务、会话恢复、诊断排错场景。

3.1 基础启动命令

# 1. 当前目录启动交互式REPL多轮对话（日常开发首选）
npx OpenSpec

# 2. 指定项目目录启动OpenSpec
npx OpenSpec ./backend-service

# 3. 附带初始需求直接进入对话
npx OpenSpec "编写Java全局异常拦截器，统一返回Result<T>"

# 4. 非交互单次批量执行，执行完毕自动退出（CI/批量重构）
npx OpenSpec -p "重构全部Controller，严格遵循项目openspec规范"

# 5. 恢复历史会话上下文，断点续做开发任务
npx OpenSpec -r session_002

# 6. 查看完整参数文档
npx OpenSpec --help

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

进入交互终端后执行，无需重启工具：

# 查看全部内置指令
/help

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

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

# 诊断配置加载状态，排错核心命令
/doctor

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

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

四、核心：项目级OpenSpec持久规范完整配置 💡

4.1 标准工程目录结构（推荐）

your-project/
├── .openspec.yaml                # OpenSpec项目主配置（Git提交）
├── .openspec/
│   └── rules/
│       └── code-standard.md      # 持久编码规范提示词本体
├── src/
├── pom.xml / pyproject.toml
└── .gitignore

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

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

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

## AI输出强制规则
1. 输出完整可运行代码，不省略导入、配置
2. 修改代码标注变更位置+修改原因
3. 配套边界场景单元测试
4. 输出完成自动校验是否匹配本规范

4.3 步骤2：项目核心配置 .openspec.yaml

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

# 持久Spec规则配置（核心）
spec_rules:
  - file: "./.openspec/rules/code-standard.md"
    weight: 10 # 权重越高优先级越高，业务规范设最高
    description: 项目统一编码规范，代码生成/重构自动生效

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

4.4 步骤3：全局公共补充配置（本机私有）

文件路径：~/.openspec/spec.global.yaml

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

~/.openspec/global-base-rule.md 存放通用安全、注释基础约束。

4.5 配置生效校验命令

# 启动OpenSpec交互
npx OpenSpec

# 执行诊断，查看已加载的Spec规则文件列表
/doctor

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

五、完整实战案例：批量重构Controller 🛠️

场景说明

后端项目批量改造所有Controller，自动统一返回体、补充参数注释，全程自动读取OpenSpec持久规范，无需手动粘贴规则。

执行命令（项目根目录运行）

npx OpenSpec -p "遍历src/main/java/com/controller下所有Controller，统一修改返回体为Result<T>，添加入参校验注释，严格遵守项目.openspec/rules/code-standard.md全部约束"

多轮交互完整流程Mermaid

六、Git仓库最佳实践 ⚙️

必须提交至Git（团队共享统一规范）

• .openspec.yaml
• .openspec/rules/code-standard.md

必须加入.gitignore（本地缓存、私有配置不提交）

# OpenSpec 缓存与本地私有配置
.openspec/sessions/
.openspec/*.local.json

个人个性化覆盖方案

新建.openspec/settings.local.json，仅本机生效，不会提交Git，用于自定义模型、超时等参数，覆盖项目公共配置。

七、常见问题排错指南 ❌

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

1. YAML文件禁止Tab缩进，仅使用空格，缩进错误会加载失败
2. 执行npx OpenSpec → /doctor 查看加载文件清单
3. spec_rules.file 使用项目相对路径，禁止绝对路径

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

临时-p参数优先级最高，如需强制项目规范：

1. 删除-p内冲突约束文本
2. 提高.openspec.yaml中weight数值，提升规范权重

问题3：会话过长Token占用过高

交互终端执行指令压缩上下文，持久Spec规则不会丢失：

/compact

八、总结 ✨

1. OpenSpec 核心价值：项目级持久提示词，Git共享，团队统一编码标准，消除重复粘贴规范的低效操作；
2. 三级加载优先级：临时命令参数 > 项目配置 > 本机全局配置；
3. 启动统一使用**npx OpenSpec**，无需本地安装；
4. /doctor 是配置排错核心指令，快速校验规则文件是否正常加载；
5. 工程目录固定.openspec.yaml + .openspec/rules/结构，开箱即用适配Java/Python全栈项目。