Claude Code 工作流程化 OpenSpec 保姆级教程文章目录Claude Code 工作流程化 OpenSpec 保姆级教程一、前言 二、核心概念OpenSpec三级提示词作用域 2.1 三级配置文件存放位置优先级从低到高2.2 配置加载优先级Mermaid流程图带颜色三、npx OpenSpec核心命令大全 3.1 基础启动命令3.2 REPL交互内置斜杠指令输入/唤起四、核心项目级OpenSpec持久规范完整配置 4.1 标准工程目录结构推荐4.2 步骤1编写规范文档 .openspec/rules/code-standard.md4.3 步骤2项目核心配置 .openspec.yaml4.4 步骤3全局公共补充配置本机私有4.5 配置生效校验命令五、完整实战案例批量重构Controller ️场景说明执行命令项目根目录运行多轮交互完整流程Mermaid六、Git仓库最佳实践 ⚙️必须提交至Git团队共享统一规范必须加入.gitignore本地缓存、私有配置不提交个人个性化覆盖方案七、常见问题排错指南 ❌问题1Spec编码规范未自动加载问题2临时参数覆盖项目规范问题3会话过长Token占用过高八、总结 ✨一、前言 日常使用**Claude Code开发时反复粘贴项目编码规范、接口约束、架构规则极大降低效率。OpenSpec** 是配套Claude Code的标准化持久提示词工具无需本地安装通过**npx OpenSpec** 一键拉起支持全局/项目/临时三级配置自动加载团队可Git共享统一代码规范彻底告别重复输入约束文本。本文跳过安装流程聚焦**npx OpenSpec** 命令、配置分层、工程目录、完整实战案例、排错方案全部代码可直接复制复用。二、核心概念OpenSpec三级提示词作用域 2.1 三级配置文件存放位置优先级从低到高全局用户级本机所有项目共用不提交GitWindows%USERPROFILE%/.openspec/spec.global.yamlMac/Linux~/.openspec/spec.global.yaml适用通用安全约束、基础注释规范、全局模型参数项目级仓库共享团队强制同步核心项目根目录./.openspec.yaml配套规范文档./.openspec/rules/code-standard.md适用项目专属命名、接口返回、数据库映射、CR审查规则提交Git全员生效临时会话级单次对话优先级最高启动命令传参-p、交互内临时指令、本地临时SPEC.md临时规则会覆盖全局/项目配置仅当前会话生效2.2 配置加载优先级Mermaid流程图带颜色执行 npx OpenSpec读取临时参数 -p/-r加载项目 .openspec.yaml加载全局 ~/.openspec/spec.global.yaml合并所有持久Spec规则携带完整规范发起Claude请求优先级临时 项目 全局三、npx OpenSpec核心命令大全 无需全局安装任意项目目录直接运行**npx OpenSpec**覆盖交互、批量任务、会话恢复、诊断排错场景。3.1 基础启动命令# 1. 当前目录启动交互式REPL多轮对话日常开发首选npx OpenSpec# 2. 指定项目目录启动OpenSpecnpx OpenSpec ./backend-service# 3. 附带初始需求直接进入对话npx OpenSpec编写Java全局异常拦截器统一返回ResultT# 4. 非交互单次批量执行执行完毕自动退出CI/批量重构npx OpenSpec-p重构全部Controller严格遵循项目openspec规范# 5. 恢复历史会话上下文断点续做开发任务npx OpenSpec-rsession_002# 6. 查看完整参数文档npx OpenSpec--help3.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 └── .gitignore4.2 步骤1编写规范文档.openspec/rules/code-standard.md# 项目强制OpenSpec编码规范自动注入上下文 ## Java后端约束 1. 包名全小写类名大驼峰UpperCamelCase方法/变量小驼峰lowerCamelCase 2. 所有接口统一返回ResultT固定字段code、msg、data 3. 公有类、接口、方法必须添加JavaDoc注释 4. 统一抛出自定义GlobalException禁止原生RuntimeException 5. 数据库下划线命名实体驼峰MyBatis自动映射 ## Python约束 1. 遵循PEP8行宽1204空格缩进 2. 函数强制Type Hints类型注解 3. 工具函数添加多行文档字符串 4. 禁用全局变量优先依赖注入 ## AI输出强制规则 1. 输出完整可运行代码不省略导入、配置 2. 修改代码标注变更位置修改原因 3. 配套边界场景单元测试 4. 输出完成自动校验是否匹配本规范4.3 步骤2项目核心配置.openspec.yaml# OpenSpec项目级配置提交Git团队共享model:astron-code-latesttimeout:60000# 持久Spec规则配置核心spec_rules:-file:./.openspec/rules/code-standard.mdweight:10# 权重越高优先级越高业务规范设最高description:项目统一编码规范代码生成/重构自动生效# 权限管控可选permissions:allow:-Bash(git diff*)-Bash(git status)-Bash(mvn test)deny:-Read(.env*)# 禁止读取密钥环境文件4.4 步骤3全局公共补充配置本机私有文件路径~/.openspec/spec.global.yaml# 本机全局通用规则不提交Gitspec_rules:-file:~/.openspec/global-base-rule.mdweight: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统一修改返回体为ResultT添加入参校验注释严格遵守项目.openspec/rules/code-standard.md全部约束多轮交互完整流程Mermaidcd 项目根目录npx OpenSpec启动交互自动加载.openspec.yaml code-standard.md输入需求新增用户登录接口AI生成代码自动匹配Spec规范输入 /clear 清空对话上下文新增需求创建用户Mapper持久Spec规范持续生效不受/clear影响六、Git仓库最佳实践 ⚙️必须提交至Git团队共享统一规范.openspec.yaml.openspec/rules/code-standard.md必须加入.gitignore本地缓存、私有配置不提交# OpenSpec 缓存与本地私有配置 .openspec/sessions/ .openspec/*.local.json个人个性化覆盖方案新建.openspec/settings.local.json仅本机生效不会提交Git用于自定义模型、超时等参数覆盖项目公共配置。七、常见问题排错指南 ❌问题1Spec编码规范未自动加载YAML文件禁止Tab缩进仅使用空格缩进错误会加载失败执行npx OpenSpec→/doctor查看加载文件清单spec_rules.file使用项目相对路径禁止绝对路径问题2临时参数覆盖项目规范临时-p参数优先级最高如需强制项目规范删除-p内冲突约束文本提高.openspec.yaml中weight数值提升规范权重问题3会话过长Token占用过高交互终端执行指令压缩上下文持久Spec规则不会丢失/compact八、总结 ✨OpenSpec核心价值项目级持久提示词Git共享团队统一编码标准消除重复粘贴规范的低效操作三级加载优先级临时命令参数 项目配置 本机全局配置启动统一使用**npx OpenSpec**无需本地安装/doctor是配置排错核心指令快速校验规则文件是否正常加载工程目录固定.openspec.yaml .openspec/rules/结构开箱即用适配Java/Python全栈项目。