【OpenSpec完整教程】一篇吃透Claude Code配套OpenSpec从安装、三级持久提示词到项目实战文章目录【OpenSpec完整教程】一篇吃透Claude Code配套OpenSpec从安装、三级持久提示词到项目实战一、前言 二、一键全局安装 OpenSpec 三、核心概念三级提示词作用域优先级分层3.1 三级配置文件存放路径3.2 配置加载流程Mermaid流程图带颜色标识四、OpenSpec 核心终端命令大全 4.1 基础启动命令4.2 REPL交互内置斜杠指令输入/唤起五、项目级持久编码规范完整配置核心实战5.1 标准工程目录结构5.2 步骤1编写规范文档 .openspec/rules/coding-standard.md5.3 步骤2项目配置文件 .openspec.config.yaml5.4 步骤3全局通用补充配置本机私有5.5 配置生效校验排错命令六、完整实战案例批量重构后端Controller ️场景多轮交互完整流程Mermaid图七、Git仓库团队协作最佳实践 ⚙️7.1 必须提交到Git的文件7.2 必须忽略的缓存文件添加至.gitignore7.3 本地个性化覆盖方案八、常见问题排错指南 ❌问题1编码规范未自动加载问题2临时参数覆盖项目规范问题3会话过长Token占用爆炸九、总结 ✨一、前言 OpenSpec是适配Claude Code CLI的标准化持久提示词工程工具核心解决重复粘贴编码规范、团队AI代码标准不统一、多项目配置隔离的痛点。工具基于Node.js发布全局npm一键安装支持三级配置作用域自动加载、Git团队共享、批量代码重构、会话持久复用。本文完整覆盖安装、配置分层、核心命令、项目规范落地、排错实战所有代码可直接复制运行。二、一键全局安装 OpenSpec 官方指定安装命令不可省略终端执行# 全局安装最新版OpenSpecnpminstall-gfission-ai/openspeclatest# 验证安装是否成功openspec--version# 更新工具版本npmupdate-gfission-ai/openspec安装完成后终端全局可用openspec指令无需额外配置环境变量。三、核心概念三级提示词作用域优先级分层3.1 三级配置文件存放路径完全对齐Claude Code配置逻辑三层隔离互不干扰全局用户级本机所有项目不提交GitWindows%USERPROFILE%/.openspec/cli.config.yamlMac/Linux~/.openspec/cli.config.yaml适用公司通用基础编码约束、全局模型参数、安全通用规则项目级仓库共享强制推荐项目根目录./.openspec.config.yaml配套规范文档./.openspec/rules/coding-standard.md适用项目专属命名、注释、架构、CR审查规则提交Git全员生效临时会话级单次对话优先级最高交互传参openspec -p、本地临时SPEC.md、会话内手动输入临时内容会覆盖全局/项目配置仅当前会话生效3.2 配置加载流程Mermaid流程图带颜色标识执行 openspec 启动工具读取临时参数 -p/-r加载项目 .openspec.config.yaml加载全局 ~/.openspec/cli.config.yaml拼接全部持久提示词注入请求上下文调用Claude Code生成/重构代码优先级规则临时会话参数 项目配置 全局配置项目配置可提交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下所有接口统一返回ResultT严格遵循.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 └── .gitignore5.2 步骤1编写规范文档.openspec/rules/coding-standard.md# 项目强制编码规范OpenSpec自动注入上下文 ## 1 Java后端规范 1. 包名全小写类名大驼峰UpperCamelCase方法/变量小驼峰lowerCamelCase 2. 所有接口统一返回ResultT结构体固定字段code、msg、data 3. 公有类、方法、枚举必须补充完整JavaDoc注释 4. 统一抛项目自定义GlobalException禁止直接抛出RuntimeException 5. 数据库下划线命名实体驼峰MyBatis自动映射 ## 2 Python规范 1. 严格遵循PEP8行宽1204空格缩进 2. 函数强制添加Type Hints类型注解 3. 工具函数增加多行文档字符串 4. 禁用全局变量优先依赖注入 ## 3 OpenSpec代码输出约束 1. 输出完整可运行代码不省略导入、配置片段 2. 修改代码标注变更位置附带修改原因说明 3. 自动生成单元测试覆盖边界异常场景 4. 代码生成完成后校验是否匹配本规范5.3 步骤2项目配置文件.openspec.config.yaml# OpenSpec项目级配置提交Git团队共享model:astron-code-latesttimeout:60000# 持久提示词加载配置核心project_prompts:-file:./.openspec/rules/coding-standard.mdweight:10# 权重越高约束优先级越高规范建议设最高权重description:项目统一编码规范所有代码生成/重构自动生效# 权限控制可选permissions:allow:-Bash(git diff*)-Bash(git status)-Bash(npm run test)deny:-Read(.env*)# 禁止读取密钥环境文件5.4 步骤3全局通用补充配置本机私有文件路径~/.openspec/cli.config.yaml# 本机全局通用配置不提交Gitproject_prompts:-file:~/.openspec/global-base-rule.mdweight:5~/.openspec/global-base-rule.md存放通用安全、基础注释约束所有项目默认加载。5.5 配置生效校验排错命令# 进入项目根目录启动交互终端openspec# 执行诊断命令查看已加载的规范文件列表/doctor输出日志中出现./.openspec/rules/coding-standard.md即代表自动加载成功。六、完整实战案例批量重构后端Controller ️场景后端项目统一改造所有Controller自动适配项目持久编码规范无需手动粘贴规则。提前完成上文.openspec.config.yamlcoding-standard.md配置终端进入项目根目录执行单次非交互批量重构openspec-p遍历src/main/java/com/controller全部Controller文件统一修改返回体为ResultT新增参数校验注释完全遵循项目coding-standard.md编码规范多轮交互完整流程Mermaid图cd 项目根目录openspec 启动工具自动加载项目.openspec配置与规范文档输入需求新增用户登录接口AI输出代码自动匹配规范Result返回、JavaDoc、自定义异常clear清空对话上下文输入新需求新增用户Mapper持久规范持续生效无需重复粘贴七、Git仓库团队协作最佳实践 ⚙️7.1 必须提交到Git的文件.openspec.config.yaml.openspec/rules/coding-standard.md团队成员克隆仓库后直接执行openspec自动加载统一规范新人零配置。7.2 必须忽略的缓存文件添加至.gitignore# OpenSpec 会话缓存、本地个性化配置忽略 .openspec/sessions/ .openspec/*.local.json7.3 本地个性化覆盖方案新建.openspec/settings.local.json仅本机生效不提交Git用于覆盖模型、超时等个人参数。八、常见问题排错指南 ❌问题1编码规范未自动加载YAML严格使用空格缩进禁止Tab制表符执行openspec→/doctor查看加载文件清单project_prompts.file使用项目相对路径禁止绝对路径。问题2临时参数覆盖项目规范临时-p参数优先级最高如需强制使用项目规范删除-p内冲突约束或提高yaml中weight权重数值。问题3会话过长Token占用爆炸交互终端执行/compact压缩对话上下文持久提示词不会被压缩丢失。九、总结 ✨OpenSpec采用npm全局安装npm install -g fission-ai/openspeclatest适配Claude Code CLI三层配置优先级临时会话 项目级配置 本机全局配置项目级.openspec.config.yaml rules/方案支持Git团队共享一次性配置永久生效/doctor是配置排错核心指令批量重构使用openspec -p实现自动化编码搭配Mermaid流程图清晰梳理加载链路彻底解决每次对话重复粘贴编码规范的低效问题。
