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

面向 Vue 2.7 + Rsbuild + Element/bi-eleme 技术栈的前端项目组共享配置仓库。包含 Claude Code 规则集、自定义技能、OpenSpec 工作流和 MCP 配置教程。

复制到目标项目后，Claude Code 会自动加载 .claude/；MCP 由项目成员按 mcp.md 自行维护。

1.0.3 更新内容

• 可靠发布：移除失效的同步钩子；打包前自动校验必要文件并运行测试。
• 安全更新：基于上次模板快照进行三方合并；使用 update --prune 可安全清理未被成员修改的废弃模板文件。
• 本地状态隔离：CLI 自动忽略 manifest、模板快照与 .mcp.json，避免将本地状态提交到业务仓库。
• MCP 自行维护：CLI 不再分发、合并或更新 .mcp.json；成员仅按 mcp.md 在本地配置。
• 模板去项目化：移除历史 OpenSpec 归档及个人规则中的项目私有工具和页面约定。
• 文档对齐：更新命令数量、hooks 职责与安装说明，使其与当前 CLI 行为一致。

目录结构总览

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

.claude/ —— Claude Code 配置目录

.claude/
├── CLAUDE.md                  # 主入口,强制查阅索引(自动加载)
├── settings.json              # Claude Code hooks 设置
├── commands/opsx/             # 13 个 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 斜杠命令(13 个)

| 命令 | 作用 | | -------------------- | ----------------------------------------------- | | /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 工件 | | /opsx:coding | 编排复杂变更的计划、开发、审查与验证闭环 |

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 —— 与除 /opsx:coding 外的工作流命令对应，提供工件流程细节。

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 —— 项目 hooks 设置

项目级 Claude Code 设置，目前配置 SessionStart 与 UserPromptSubmit hooks。

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 —— 项目成员自行维护

CLI 不会创建、复制、合并或更新 .mcp.json。如项目需要 MCP，请由成员在项目根目录单独创建（放进 .claude/ 会被忽略），Claude Code 启动时会自动加载。

⚠️ .mcp.json 可能含有 token。请由项目成员将其加入目标项目的 .gitignore，不要提交到仓库。

mcp.md —— MCP 配置教程

面向新人的 Figma MCP 与 YApi MCP 手动配置流程（截图步骤、token 获取方式）。按教程创建的 .mcp.json 仅保留在本地。

.gitignore —— git 忽略规则

CLI 会自动向目标项目的 .gitignore 追加以下仅本地维护的文件，已存在时不会重复添加：

.claude/.claude-config-manifest.json
.claude/.claude-config-bases/
.mcp.json

快速使用

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

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

npx @zw-team/claude-config init

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

• 文件不存在 → 直接复制
• 内容相同 → 跳过
• 内容不同 → 以“上次安装的模板快照”为共同祖先自动三方合并；只有模板和项目成员同时改到同一段时才保留 <<<<<<< 冲突标记，由成员手动解决
• .mcp.json → CLI 不创建、不合并、不更新；由项目成员自行维护

更新配置

npx @zw-team/claude-config update

按 .claude/.claude-config-manifest.json 记录的变体重新同步；每次同步都会保存最新模板快照到 .claude/.claude-config-bases/，供下一次三方合并使用。有冲突时手动解决标记即可。

若需要清理模板新版已移除的文件，显式执行：

npx @zw-team/claude-config update --prune

--prune 只删除与上次模板快照完全一致的文件；成员改过或无法确认来源的文件会保留并提示。

方式二：手动复制

# 1. 拷贝三项配置
cp -R .claude /path/to/target-project/
cp -R openspec /path/to/target-project/
cp mcp.md /path/to/target-project/

复制后必改的占位符

| 文件 | 占位符 | 改为 | | ----------------------------------------- | ------------------------------------------------------------- | ------------------------ | | .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 请按 mcp.md 在本项目单独配置，并确保本地 .mcp.json 不提交到仓库。

技术栈定位

• 框架: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