团队 AI 编码配置模板

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

除三个前端变体外，另提供 openspec 变体：与技术栈无关的纯 OpenSpec 流程，同时支持 Claude Code 与 Codex（详见「openspec 变体」一节）。

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

更新日志

1.2.1（2026-09-23）

• 文档：补齐 1.1.0 / 1.1.1 / 1.2.0 更新日志，修正 commands/opsx 数量描述（13 → 14）。

1.2.0（2026-09-23）

• 新增 openspec 变体：技术栈无关的纯 OpenSpec 流程，适用于后端、脚本、CLI 工具、类库与纯文档仓库；只保留治理层（openspec/config.yaml + rules_details/openspec.md），不携带任何技术栈规则。
• 双宿主支持：新增 AGENTS.md（Codex 入口）与 .codex/hooks.json（项目级 hooks）；hooks 脚本支持 --codex，输出 Codex 需要的 JSON 信封。
• 上游产物改为现场生成：11 个 /opsx:* 命令与技能不再随模板分发，改由 scripts/setup-openspec.sh 调用 openspec init 生成，避免与上游版本漂移。
• 安装器代装宿主：init 会检测 Claude Code 与 Codex，缺失时逐个询问是否代装，随后生成命令与技能；--tools claude,codex 可显式指定目标宿主。
• 变体推荐扩展：无 vue / react 依赖，或仓库没有 package.json 时，推荐 openspec 变体。
• 护栏测试：新增测试断言 openspec 变体目录不出现技术栈关键词。
• 文档：README 新增「openspec 变体」章节；仓库根目录新增 VARIANTS.md，说明四个变体的定位、差异与使用方法。

1.1.1（2026-09-22）

• 打包修复：发布包排除 .omc 会话状态与 upload-history.md 测试残留；新增 package/.npmignore 收紧发布内容。

1.1.0（2026-09-22）

• 新增 react 变体：面向独立 React 应用（不跑无界微前端），rules_details/ 采用 common/ + react/ 分层，openspec/config.yaml 同步换成 React 技术栈描述。
• 新增 /opsx:coding-matt：配套 opsx-coding-matt 技能，三个前端变体均可用；走 mattpocock-skills，不依赖 Superpowers。
• 修复变体推荐与死链。

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/             # 14 个 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 斜杠命令(14 个)

| 命令 | 作用 | | -------------------- | ----------------------------------------------- | | /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 | 编排复杂变更的计划、开发、审查与验证闭环 | | /opsx:coding-matt | 同上，但改用 Mattpocock skills 驱动（不依赖 superpowers）|

hooks/ —— 钩子脚本

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

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

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 增强技能(3 个):

| Skill | 作用 | | --------------------- | ------------------------------------------------------------------------------------------------- | | opsx-coding | 复杂 OpenSpec 变更的编码闭环编排(plan/worktree/分阶段开发/Code Review/验证) | | opsx-coding-matt | 同上闭环，但把 superpowers skill 全部换成 Mattpocock skills 或内联规则 | | 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 会自动检测当前项目技术栈并推荐配置版本，你确认后一键复制 .claude/、openspec/、mcp.md 到当前项目。

| 变体 | 适用项目 | 推荐条件（package.json 依赖） | rules_details/ 布局 | | --- | --- | --- | --- | | wujie | wujie 微前端（Vue2 主应用 + React 子应用） | 有 wujie* 依赖，或 react 与 vue 并存 | common/ + react/ + vue/ | | react | 独立 React 应用（无微前端） | 有 react、无 vue、无 wujie | common/ + react/ | | release | 传统 Vue2 主应用 | 其余情况（含纯 Vue2） | 扁平（Vue 规则直接放根） | | openspec | 任意项目（后端 / 脚本 / 文档 / 前端均可） | 无 vue、无 react 依赖，或仓库没有 package.json | 仅 openspec.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

/opsx:coding 与 /opsx:coding-matt 怎么选

两条命令的边界、阶段顺序、checkpoint、停止条件完全一致，区别只在底层调用哪套 skill。

| 阶段 | /opsx:coding | /opsx:coding-matt | | --- | --- | --- | | 写 plan | superpowers:writing-plans | 内联规则，直接写 | | worktree | superpowers:using-git-worktrees | 内联 git 命令 | | 分阶段开发 | superpowers:subagent-driven-development | 内联派单表 + mattpocock-skills:tdd | | Code Review | superpowers:requesting-code-review | mattpocock-skills:code-review（Standards / Spec 双轴并行） | | 处理 review 反馈 | superpowers:receiving-code-review | 内联规则 | | 完成前验证 | superpowers:verification-before-completion | 内联规则 |

前置依赖

/plugin install mattpocock-skills@claude-plugins-official

/opsx:coding-matt 不需要 superpowers。

两者共用 plan 目录 docs/superpowers/plans/，所以同一个变更可以今天用一条命令起、明天用另一条命令接着跑。

三点行为差异需要知道

1. seam 一次性确认：mattpocock-skills:tdd 规定「未确认的 seam 不许写测试」，所以 /opsx:coding-matt 在 Plan Ready checkpoint 就把整个变更的测试 seam 一次问完，而不是每个 phase 打断一次。项目没有测试框架时记为 none，全程跳过 tdd（不会为了普通 UI/业务修复临时引入测试框架）。
2. review 需要固定基点：phase 级 review 用该 phase 起点 SHA，最终聚合 review 用变更起点 SHA，两个 SHA 都记在 plan 文件里。
3. review 不降级：mattpocock-skills:code-review 不可用时直接停并提示安装插件，不会退回 general-purpose agent —— 避免「看起来跑过双轴 review、实际只跑了泛化 agent」的假阳性。

Spec 来源：review 的 Spec 轴直接读 openspec/changes/<name>/ 下的 proposal / design / specs / tasks，不使用 .scratch/ 票池，也不需要跑 setup-matt-pocock-skills。

未采用 mattpocock-skills:implement：它会自动跑全量测试套件、自动跑 code review、自动 commit 到当前分支，与本配置「验证与 Code Review 仅由用户显式触发」的规则冲突。

openspec 变体 —— 技术栈无关的纯 OpenSpec 流程

openspec 变体从 release 变体抽取而来，只保留 OpenSpec 工作流本身，删掉全部技术栈绑定内容。适用于后端仓库、脚本仓库、纯文档仓库，或任何不想绑定前端规则的项目。

它包含什么

| 内容 | 说明 | | --------------------------------------------- | ---------------------------------------------------------------------------------------- | | openspec/config.yaml | 治理事实源：context: 是待填写占位骨架，rules: 是技术栈无关的工件规则与流程门卫。 | | openspec/README.md | 流程总览与命令清单。 | | .claude/CLAUDE.md / AGENTS.md | 双宿主入口，薄指针：只写「何时必须走 OpenSpec + 五阶段入口」。 | | .claude/rules_details/openspec.md | 操作细则：/opsx:coding 阶段流程、派单策略、plan 与 tasks 的分工。 | | .claude/hooks/ + settings.json | openspec-sync-check.sh（即时同步提醒）、check-superpowers.sh（宿主自适应检测）。 | | .codex/hooks.json | Codex 侧项目级 hooks，复用 .claude/hooks/ 下同一份脚本。 | | .claude/commands/opsx/ + .claude/skills/ | 团队自研的三个扩展：/opsx:coding、/opsx:coding-matt、/opsx:writeback。 | | scripts/setup-openspec.sh | 调用上游 openspec init 生成其余命令与技能。 |

它不包含什么

• 不 vendored 上游产物：/opsx:explore、/opsx:propose 等 11 个命令与对应技能由上游 openspec CLI 现场生成，避免版本漂移。
• 不含任何技术栈内容：仓库内有一条测试断言该变体目录不出现 vue / react / rsbuild / antd / tailwind 等技术栈关键词。
• 不含 opsx-review-summary：评审总结的场景模板（PC 后台 / 小程序 / H5）属业务形态绑定，不在本变体范围内。

安装流程

npx @zw-team/claude-config init   # 选择「openspec 版本」

安装器会依次执行：

1. 复制变体文件（.claude/、openspec/、AGENTS.md、scripts/）。
2. 检测宿主：Claude Code（claude）与 Codex（codex）。
3. 未安装的宿主逐个询问是否代装；同意后按项目包管理器（pnpm / yarn / npm）执行全局安装。
4. 调用 openspec init --tools <已装宿主> 生成命令与技能。
5. 提示填写 openspec/config.yaml 的 context: 段。

跳过宿主检测、直接指定生成目标：

npx @zw-team/claude-config init --tools claude,codex

前置依赖

| 依赖 | 用途 | 安装 | | ------------------- | ------------------------------- | ------------------------------------------------------------------------------------- | | openspec CLI | 硬前提，命令与技能由它生成 | npm i -g @fission-ai/openspec | | Superpowers | 仅 /opsx:coding 需要 | Claude Code：/plugin install superpowers@claude-plugins-official；Codex：装到 ~/.agents/skills/ | | mattpocock-skills | 仅 /opsx:coding-matt 需要 | /plugin install mattpocock-skills@claude-plugins-official |

只用 /opsx:apply 的话，除 openspec CLI 外无任何外部依赖。

双宿主差异

| | Claude Code | Codex | | ---------------- | --------------------------------- | ------------------------------------------------------------ | | 入口文件 | .claude/CLAUDE.md | AGENTS.md | | 命令落点 | <项目>/.claude/commands/opsx/*.md | ~/.codex/prompts/opsx-*.md（全局，不随仓库分发） | | 技能落点 | <项目>/.claude/skills/ | <项目>/.codex/skills/ |

规则内容两侧完全一致，差异只在命令的触发方式。

安装后要做的两件事

1. 填写 openspec/config.yaml 的 context: 段（产品与技术栈、目录约定），填完删掉占位提示块。
2. 上游版本升级后重新生成命令与技能：bash scripts/setup-openspec.sh。

更新

update 只做文件同步；命令与技能请在更新后重跑一次生成脚本：

npx @zw-team/claude-config update
bash scripts/setup-openspec.sh

react 变体与 wujie 变体的差异

react 变体从 wujie 变体派生，面向独立 React 应用（不跑在无界微前端容器里）。相对 wujie 做了这些去耦合：

移除

• rules_details/vue/（6 个 Vue2 规则文件）——纯 React 项目不需要
• rules_details/react/wujie-integration.md（微前端通信规范）

改写

| 文件 | 改动 | | --- | --- | | openspec/config.yaml | context: 段从 Vue 2.7 + bi-element-ui 换成 React 19 + antd 6 + Tailwind；design/验证规则同步换成 React 表述 | | .claude/CLAUDE.md | 删掉「按包分流总闸」与 Vue2 强制查阅表，合并为单一 React 查阅表；路径从 packages/react/src/ 改为 src/ | | .claude/rules/1-base.md | 项目背景从「Vue2 主应用 + React 子应用 monorepo」改为单包 React 应用 | | rules_details/react/react-base.md | 去掉微前端行、wujie-props、assetPrefix: '/micro/'、Vue2 包别名陷阱 | | rules_details/react/react-store-router.md | 删掉「是否参与无界同步」列与 syncWujieProps() 说明 | | rules_details/react/react-api-requests.md | 去掉 resolveApiBaseURL() 的无界 origin 解析 | | rules_details/common/backend-business-contract.md | 去掉 Vue2/React 双包对照，只留 React 写法 | | skills/ui-style-fixer/ | 从 Vue 2 + Element UI + ::v-deep 改写为 React + antd + CSS Modules :global() + Tailwind |

注意：react 变体的技术栈描述来自 wujie 变体里 React 子应用的真实配置（React 19 / antd 6 / Zustand 5 / react-router 7 / Tailwind 3.4）。如果你的 React 项目栈不同（例如用 Vite 而非 Rsbuild、用 Redux 而非 Zustand），装完后需要按实际情况调整 rules_details/react/react-base.md 与 openspec/config.yaml 的 context: 段。