前端项目规则与开发规范模板

面向 Vue 2.7 + Rsbuild + Element/bi-eleme 技术栈的前端项目组共享配置仓库。包含 Claude Code 规则集、自定义技能(skills)、OpenSpec 工作流、MCP 服务器注册四套配置。

复制到目标项目后,Claude Code 会自动加载 .claude/ 与 .mcp.json,无需额外初始化。

目录结构总览

.
├── .claude/                # Claude Code 配置(规则、技能、命令、钩子、设置)
├── openspec/               # OpenSpec 工作流目录(提案/设计/规格/任务)
├── docs/                   # 过程产物(brainstorming 设计文档、实施计划等)
├── .mcp.json               # 项目级 MCP server 注册(4 个 server)
├── mcp.md                  # MCP 配置教程(Figma / YApi)
├── .gitignore              # git 忽略规则
└── README.md               # 本文件

.claude/ —— Claude Code 配置目录

.claude/
├── CLAUDE.md                  # 主入口,强制查阅索引(自动加载)
├── settings.json              # 权限白名单与项目设置
├── commands/opsx/             # 12 个 OpenSpec 斜杠命令
├── hooks/                     # git/工作流钩子脚本
├── rules/                     # 常驻规则(自动加载,每次会话载入上下文)
├── rules_details/             # 详细规范(不自动加载,按需 Read)
├── skills/                    # 自定义技能
└── worktrees/                 # git worktree 工作区(执行 EnterWorktree 时使用)

CLAUDE.md —— 行为准则与强制查阅索引

每次会话自动加载。包含:

• 强制查阅规则表:触发条件命中时,必须先 Read 对应 rules_details/ 文档再动手,禁止凭记忆写代码
• 5 阶段工作流:/opsx:explore → /opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive
• 编码行为准则:思考优先、简单优先、美准修改、目标驱动执行

rules/ —— 常驻规则(全部自动加载)

| 文件 | 作用 | | --------------- | ----------------------------------------------------------------------------------------- | | 1-base.md | 协作流程、项目背景、技术栈(Vue 2.7 / Rsbuild / bi-eleme)、src/ 目录与别名 | | user_rules.md | 个人偏好、常用全局方法速记($formatNumberWithCommas / $deepCopy / $tosUploadData 等) |

rules_details/ —— 详细规范(按需 Read,不自动加载)

| 文件 | 触发条件 | | --------------------------- | -------------------------------------------------------------------------------------------------- | | coding-standards.md | 命名 / SCSS / BEM / 样式覆盖 / 表单 rules | | api-requests.md | 调接口 / loading / status_code 判断 / 认证 / 金额展示 | | components.md | BiDrawer / BiTable / BiForm / BiFormItem / BiSearchBlock / BiBlock / BiDatePicker / BiCustomColumn | | page-structure.md | 新建主页面(列表页:搜索区+表格区) / $AccessReport.report | | tools.md | this.$xxx 全局方法 / @/utils / 文件上传 / 复制 / 防抖节流 | | openspec.md | 走 /opsx:* 任一阶段 / 写 OpenSpec proposal/design/specs/tasks | | yapi.md | 调 YApi 接口文档 / 切换业务线 Token | | bi-component-reference.md | BiTable / BiSearchBlock 等组件的完整参数参考 | | rules-readme.md | 规则目录加载机制说明、与 rules/ 分工原因 |

为什么分两层:rules/ 自动加载会持续占用上下文 token,rules_details/ 按需 Read 可省 75%+ 常驻成本。

commands/opsx/ —— OpenSpec 斜杠命令(12 个)

| 命令 | 作用 | | -------------------- | ----------------------------------------------- | | /opsx:explore | 探索模式:旧代码调研、需求澄清 | | /opsx:new | 新建变更(手动控制) | | /opsx:propose | 一步建档:生成 proposal + specs + design + tasks | | /opsx:continue | 继续创建下一个工件 | | /opsx:ff | 快进:快速创建所有工件 | | /opsx:apply | 按 tasks.md 逐任务实现 | | /opsx:verify | 全量验证:代码与工件对齐 | | /opsx:archive | 归档:同步 spec、记录 CHANGELOG | | /opsx:sync | 同步 delta spec 到主目录 | | /opsx:bulk-archive | 批量归档多个变更 | | /opsx:onboard | 引导式入门 | | /opsx:writeback | 同步对话中的需求变更到 OpenSpec 工件 |

hooks/ —— 钩子脚本

| 文件 | 作用 | | ------------------------ | ------------------------- | | openspec-sync-check.sh | OpenSpec 工件同步检查钩子 |

skills/ —— 自定义技能(18 个)

OpenSpec 工作流套件(12 个):openspec-apply-change / openspec-archive-change / openspec-bulk-archive-change / openspec-continue-change / openspec-explore / openspec-ff-change / openspec-new-change / openspec-onboard / openspec-propose / openspec-sync-specs / openspec-verify-change / openspec-writeback —— 与 commands/opsx/ 一一对应,提供工作流实现细节

OpenSpec 增强技能(2 个):

| Skill | 作用 | | --------------------- | ------------------------------------------------------------------------------------------------- | | opsx-coding | 复杂 OpenSpec 变更的编码闭环编排(plan/worktree/分阶段开发/Code Review/验证) | | opsx-review-summary | 从 change 产物生成技术评审总结 review.md,支持 PC 后台/小程序/H5 移动端多场景模板,面向后端/测试/TL |

工具技能(4 个):

| Skill | 作用 | | ------------------- | -------------------------------------------------------------------------- | | git-commit | 分析 git diff 生成 Conventional Commits 格式提交信息并提交 | | image-auto-upload | 图片上传阿里云 OSS 并返回 CDN 地址,支持 Figma 转码自动上传和手动批量上传 | | ui-style-fixer | 根据 Figma 设计图 + UI 修改意见截图,精确修改 Vue/React 组件样式 | | yapi | 从 YApi 平台提取接口文档,自动生成 markdown 文档和接口方法代码 |

worktrees/ —— git worktree 工作区

执行 EnterWorktree 时,Claude Code 会在此目录创建临时 worktree,实现任务隔离。退出时按选择保留或清理。

settings.json —— 项目权限与设置

项目级 Claude Code 设置,包含工具权限白名单等配置。

openspec/ —— 规格驱动开发(spec-driven)工作流

openspec/
├── README.md         # 工作流使用说明(命令、目录约定、工件规范)
├── config.yaml       # 项目上下文 + per-artifact 书写规则注入
├── CHANGELOG.md      # 归档后的变更记录(日期、变更名、描述)
├── changes/          # 进行中的变更工件(proposal/design/specs/tasks)
└── specs/            # 归档后的长期能力规格(spec-driven 主目录)

工作流:新需求 → /opsx:explore 或 brainstorming → /opsx:propose 一步建档 → /opsx:apply 逐任务实现 → /opsx:verify 全量验证 → /opsx:archive 归档。详见 openspec/README.md。

.mcp.json —— 项目级 MCP server 注册

位置:必须放在项目根目录(放进 .claude/ 会被忽略)。Claude Code 启动时自动加载。

当前注册的 4 个 server:

| Server | 作用 | | --------------------- | -------------------------------- | | sequential-thinking | 链式推理工具 | | context7 | 第三方库文档实时查询 | | yapi | YApi 接口文档提取(需 YAPI_TOKEN) | | Figma | Figma 设计稿读取(HTTPS MCP) |

⚠️ 安全提示:.mcp.json 中含明文 token,已加入 .gitignore 禁止 git 跟踪。复制到新项目时需重新填入自己的 token。

mcp.md —— MCP 配置教程

面向新人的 Figma MCP 与 YApi MCP 手动配置流程(截图步骤、token 获取方式)。与 .mcp.json 互补:mcp.md 教怎么配,.mcp.json 是配好的结果。

.gitignore —— git 忽略规则

.DS_Store
node_modules/
.idea
.omc/

快速使用

方式一：CLI 一键安装（推荐）

在你的前端项目根目录执行：

npx @maoxiya/claude-config init

CLI 会自动检测当前项目技术栈并推荐配置版本（release = 传统 Vue2，wujie = wujie + React），你确认后一键复制 .claude/、openspec/、mcp.md、.mcp.json 到当前项目。

• 文件不存在 → 直接复制
• 内容相同 → 跳过
• 内容不同 → 自动 git merge，冲突处保留 <<<<<<< 标记由你手动解决
• .mcp.json → 保留你已填好的 server/token，仅追加你缺少的 server

更新配置

npx @maoxiya/claude-config update

按 .claude/.claude-config-manifest.json 记录的变体重新同步；有冲突时用 git merge 手动解决。

方式二：手动复制

# 1. 拷贝四套配置
cp -R .claude /path/to/target-project/
cp .mcp.json /path/to/target-project/   # 注意:含 token,目标项目也应加入 .gitignore
cp -R openspec /path/to/target-project/
cp mcp.md /path/to/target-project/

复制后必改的占位符

| 文件 | 占位符 | 改为 | | ----------------------------------------- | ------------------------------------------------------------- | ------------------------ | | .mcp.json | YAPI_TOKEN | 目标项目自己的 token | | .claude/rules_details/api-requests.md | https://your-login.example.com / your-project.example.com | 目标项目实际域名 | | .claude/rules_details/page-structure.md | 两个 <!-- 示意图位置 --> 注释 | 目标项目主页面设计稿截图 | | .claude/rules/1-base.md 项目背景段 | 通用描述 | 目标项目实际业务定位 | | openspec/config.yaml 顶部 | 项目名描述 | 目标项目名 |

启用配置

复制完成后,在目标项目根目录启动 Claude Code,即自动加载所有规则。首次进入会话时,Claude 会读取 .claude/CLAUDE.md 与 .claude/rules/ 下全部文件。MCP server 在 Claude Code 启动时初始化(若有报错请重启会话)。

技术栈定位

• 框架:Vue 2.7 + vue-router 3.x + vuex 3.x
• 构建:Rsbuild(非 Vue CLI),入口 src/main.js
• UI 组件库:bi-eleme / bi-element-ui(基于 element-ui 的业务封装)
• 样式:SCSS + scoped + 全局变量注入(global.scss / mixin.scss);未使用 Tailwind
• 请求:axios,统一封装在 src/utils/request.js
• 包管理:pnpm(优先) > npm
• 路径别名:@ / @src → src

不同技术栈的项目组(如 Vue 3、React、Vite)需要相应调整 rules_details/ 中的组件示例与构建配置描述。

superpowers 安装方法

打开新终端，启动 Claude Code 后运行以下命令：

/plugin install superpowers@claude-plugins-official