728188325/frontend-admin-architecture-skill

前端后台架构 Skill

这个 skill 用于创建或规范化前端后台管理系统，支持：

• React + TypeScript
• Vue 3 + TypeScript

它负责选择对应框架规范，生成目标项目的 docs/architecture.md 和 AGENTS.md，并在用户要求时创建基础项目骨架。

内置资源

按用户选择的框架读取对应资源，不要把另一套框架内容写入目标项目。

React：

• references/react/architecture.md
• assets/AGENTS.react.template.md

Vue：

• references/vue/architecture.md
• assets/AGENTS.vue.template.md

通用项目治理文档：

• assets/docs/ai-interaction.md
• assets/docs/karpathy-guidelines.md
• assets/docs/ui-style.md
• assets/docs/ui-quality.md
• assets/docs/design-tokens.md
• assets/docs/code-style.md
• assets/docs/security.md
• assets/docs/comments.md
• assets/docs/verification.md
• assets/docs/git-commit.md
• assets/docs/knowledge-capture.md

默认工作流

第 1 步：确认范围

如果用户没有提供项目路径，先询问项目路径。

如果用户没有说明目标框架，先判断目标路径是否已有项目：

• 如果存在 package.json，读取 dependencies 和 devDependencies。
• 出现 react 或 react-dom 时，识别为 React + TypeScript。
• 出现 vue 或 @vitejs/plugin-vue 时，识别为 Vue 3 + TypeScript。
• 如果 package.json 不存在，再查看 vite.config.* 中的框架插件线索。
• 如果同时出现 React 和 Vue，或无法判断，再询问用户。

需要询问时使用：

请选择项目框架：
1. React + TypeScript
2. Vue 3 + TypeScript

如果用户没有说明“只生成文档”还是“同时创建项目骨架”，用一个简短问题确认。

如果用户要创建或脚手架项目，必须在创建文件、执行脚手架命令、安装依赖前确认以下决策。除非用户明确说“默认方案”、“按默认配置”、“不用问直接默认”或等价表达，否则不要把“新建项目”、“创建项目”、“新建在桌面”、“继续”等表述理解为采用默认方案。

缺少系统 UI 风格、布局风格、登录认证或依赖安装选择时，先停止执行并用一个简短问题覆盖缺失选项。系统 UI 风格必须优先询问一次，但允许用户选择“暂不指定”；用户未选择或未编写自定义风格时，不要替用户预设具体视觉风格。

1. 请选择系统 UI 风格。系统 UI 风格只描述视觉语言、信息密度和交互气质，不等同于布局风格；如果用户暂不选择，则 docs/ui-style.md 保持待补充：
   • 经典稳重型：浅色背景、低饱和主色、清晰表格和表单，适合通用企业后台。
   • 极简清爽型：留白更充足、边框和阴影更克制，适合轻量 SaaS 和低复杂度管理端。
   • 数据密集型：紧凑表格、高信息密度、弱装饰，适合运营、报表、BI、数据管理类后台。
   • SaaS 工作台型：工作区感更强，强调概览、快捷入口和多租户/多项目切换，适合 B2B 产品。
   • 科技深色型：深色背景、高对比数据状态、适度科技感，适合监控、安全、运维和大屏相关系统。
   • 金融严谨型：克制配色、强表格、明确风险和金额状态，适合财务、结算、风控类后台。
   • 政企规范型：蓝白基调、层级清晰、表单和审批链路规范，适合政企、OA、审批系统。
   • 内容运营型：重视素材预览、批量操作、状态标签和审核流，适合 CMS、内容和营销运营后台。
   • 工具效率型：强调快捷操作、分栏面板、键盘友好和配置效率，适合工具型或配置型后台。
   • 轻量门户型：顶部导航、模块入口清晰、页面复杂度低，适合模块较少的内部系统。
   • 自定义：用户用自然语言描述期望的视觉风格、参考产品或设计要求。
   • 暂不指定：不写入具体风格，保留 docs/ui-style.md 待补充。
2. 请选择布局风格：
   • 经典后台布局：左侧菜单 + 顶部栏 + 内容区 + 标签页。适合菜单层级较多、传统管理后台，作为默认布局。
   • 顶部导航型：顶部横向主导航 + 内容区。适合模块较少、层级较浅、希望页面更开阔的轻量后台。
   • 混合导航型：顶部一级业务域 + 左侧二级菜单 + 内容区。适合多业务域后台，例如订单、财务、系统、内容等模块并存的项目。
   • 图标窄栏型：左侧窄图标栏 + 展开菜单或二级面板 + 内容区。适合工具型后台和希望节省横向空间的现代 SaaS。
   • 工作台型：顶部产品栏 + 组织/项目切换 + 左侧可折叠菜单 + 内容区。适合多租户、多项目、组织切换频繁的 B2B 系统。
   • 不预设布局：只保留基础路由和页面容器。适合后续由业务或设计稿决定布局。
3. 是否包含基础登录认证。若启用基础登录认证，登录页必须遵守已选择的系统 UI 风格；若系统 UI 风格暂不指定，则使用 UI 组件库默认中性风格。
4. 是否立即安装依赖并运行验证。
5. 是否采用默认方案：不预设系统 UI 风格 + 经典后台布局 + 基础登录认证 + 不立即安装依赖。

只有当用户明确采用默认方案时，使用这些默认值：

• 包管理器：pnpm。
• 登录认证：默认包含基础 token 登录骨架。
• 布局：默认包含经典后台布局。
• 系统 UI 风格：默认不预设；docs/ui-style.md 保持待补充，由后续业务或设计要求补齐。
• 依赖安装：默认不执行 pnpm install、pnpm add、pnpm dev、pnpm lint、pnpm typecheck、pnpm build，只写入依赖声明、项目文件和后续命令。
• React 默认栈：Vite、React、TypeScript、Ant Design、React Router、Axios、TanStack Query、Zustand。
• Vue 默认栈：Vite、Vue 3、TypeScript、Composition API、<script setup lang="ts">、Vue Router、Pinia、Axios、Element Plus、VueUse。
• 权限、Mock、i18n、图表、监控、部署、OpenAPI 代码生成：不默认实现，需要时再引入。

第 2 步：读取对应规范

写入文件前，按框架读取对应架构文档：

• React 读取 references/react/architecture.md
• Vue 读取 references/vue/architecture.md

将它作为以下内容的依据：

• 技术栈
• 目录结构
• 模块边界
• 公共组件边界
• API 和类型放置规则
• 状态管理规则
• 编码规范
• 工程质量工具
• 测试策略

第 3 步：写入项目文档

在目标项目中创建或更新：

docs/architecture.md
docs/ai-interaction.md
docs/karpathy-guidelines.md
docs/ui-style.md
docs/ui-quality.md
docs/design-tokens.md
docs/code-style.md
docs/security.md
docs/comments.md
docs/verification.md
docs/git-commit.md
docs/knowledge-capture.md
AGENTS.md

写入 docs/architecture.md 时，只描述目标项目后续开发要遵守的架构规范。不要把 skill 工作流程、向用户提问的话术、初始化决策过程写进目标项目文档。

写入其他 docs/*.md 时，使用 assets/docs/ 下的通用治理文档作为基础。它们用于描述 AI 交互、Karpathy 指南、UI 风格记录、UI 质量与创意边界、设计变量、代码风格、安全与数据、注释、验证、Git 提交和规则沉淀。除 docs/ui-style.md 需要记录用户明确选择或自定义的系统 UI 风格外，不写具体业务项目的临时决策。

如果用户选择或跳过了基础登录认证、布局风格等可选能力，生成的 docs/architecture.md 要与实际选择一致：

• 已选择的能力：保留对应架构规则和预期文件。
• 已跳过的能力：只保留边界说明，明确除非未来需求引入，否则不预创建相关目录和文件。
• 布局风格：只写入当前选择的布局目录、组件职责和状态边界；不要把所有布局候选项都写进目标项目文档，除非用户明确要求保留布局对比。

写入 docs/ui-style.md 时：

• 用户选择十种内置系统 UI 风格之一：写入风格名称、适用场景和对应描述。
• 用户选择自定义：整理用户原话为清晰的系统 UI 风格要求，避免扩写成用户没有确认的视觉方案。
• 用户选择暂不指定，或没有提供自定义描述：保留 assets/docs/ui-style.md 的待补充状态。
• 不要把全部系统 UI 风格候选项写进目标项目文档，除非用户明确要求保留对比。
• 如果创建了登录页、布局壳、首页工作台、基础列表页或状态页，这些界面必须以当前系统 UI 风格为视觉依据；系统 UI 风格暂不指定时，使用对应 UI 组件库默认中性风格，不额外创造视觉主题。

写入 docs/ui-quality.md 时：

• 使用 assets/docs/ui-quality.md 作为稳定 UI 输出的质量底线。
• 明确创造性可以体现在视觉语言、token、登录页、工作台、空状态、轻量动效和组件组合方式；布局壳、标签页、菜单、表格、表单、分页、弹窗、登录链路必须稳定正确。
• 创建项目骨架时，登录页、布局壳、工作台和基础列表页必须按 docs/ui-quality.md 的验收清单实现。

写入 AGENTS.md 时：

• React 使用 assets/AGENTS.react.template.md。
• Vue 使用 assets/AGENTS.vue.template.md。
• AGENTS.md 只作为项目级 AI 协作入口，列出必读文档、优先级、框架关键边界和冲突处理方式；不要把所有细则堆回 AGENTS.md。
• 如果目标项目已有 AGENTS.md，不要静默覆盖；先读取，再优先追加一个指向 docs/architecture.md 的前端后台架构章节。
• 如果需要整体替换，先询问用户。
• 如果目标项目已有同名 docs/*.md 专项规范，先读取现有内容；除非用户明确要求覆盖，否则只补充缺失文档或提示用户确认合并策略。

第 4 步：创建项目结构

只有在用户要求实现或创建项目骨架时，才创建代码文件。

创建命令按用户选择的框架执行，不要同时执行两条命令。

除非用户明确要求立即安装依赖并运行验证，否则不要执行：

pnpm install
pnpm add <package>
pnpm dev
pnpm lint
pnpm typecheck
pnpm build
pnpm test:run

未安装依赖时，只修改 package.json 的 dependencies、devDependencies 和 scripts，并在完成后告诉用户下一步手动执行哪些命令。

React：

pnpm create vite <project-name> --template react-ts

Vue：

pnpm create vite <project-name> --template vue-ts

React 业务模块使用：

src/modules/<business-domain>/<business-module>/
  pages/
  components/
  api/
  hooks/
  types/
  constants/

Vue 业务模块使用：

src/modules/<business-domain>/<business-module>/
  views/
  components/
  api/
  hooks/
  types/
  constants/

Vue 项目统一使用 hooks/ 命名可复用组合逻辑目录，不使用 composables/ 目录；实现仍采用 Composition API，hook 文件导出 useXxx 函数。

第 5 步：说明使用方式

创建文档或项目结构后，告诉用户：

可以在新的 Codex/Agent 会话中这样调用：

$frontend-admin-architecture 我想新建一个 Vue 3 + TypeScript 企业后台管理系统，请按规范初始化项目

或者：

使用 frontend-admin-architecture，帮我为当前 React 项目生成 docs/ 规范文档和 AGENTS.md，并按规范创建目录结构。

同时说明：

• 新成员应将 frontend-admin-architecture 文件夹复制到自己的 .agents/skills/ 目录。
• 安装后重启 Codex，或打开新的 Codex 会话。
• 后续开发任务建议这样开头：“请先阅读 AGENTS.md，并按任务类型读取 docs/ 下的专项规范，严格按项目规范开发。”

创建项目指导

如果用户要求创建实际项目：

1. 使用对应 Vite 模板创建项目。
2. 按所选框架写入或合并 package.json 依赖声明和 scripts。
3. 创建 docs/architecture.md 和通用专项规范文档。
4. 创建或更新 AGENTS.md。
5. 创建目录结构。
6. 根据用户选择的系统 UI 风格写入或保留 docs/ui-style.md，并写入 docs/ui-quality.md 作为 UI 输出质量底线。
7. 先完成稳定可用的路由、布局壳、菜单、标签页、登录链路、列表页、表单和状态流，再做视觉风格增强。
8. 根据用户选择的布局和登录认证选项添加最小应用骨架；如果创建登录页或布局壳，必须让它们遵守已选择的系统 UI 风格和 docs/ui-quality.md。
9. 配置 scripts 和工程工具。
10. 如果用户选择立即安装依赖并验证，再执行安装、启动、验证和浏览器视觉检查。
11. 如果用户未选择立即安装依赖，最后提示用户自行执行：

• pnpm install
• pnpm dev
• pnpm lint
• pnpm typecheck
• pnpm build

用户明确要求立即安装依赖并验证时，运行：

pnpm install
pnpm lint
pnpm typecheck
pnpm build

如果项目配置了测试，也运行：

pnpm test:run

如果当前环境允许启动页面和浏览器检查，还必须打开登录页、工作台和基础列表页做视觉验收，重点检查：

• 菜单、顶部栏、标签页、面包屑、内容区没有遮挡、错位和漂浮。
• 主题风格在登录页、布局壳、表格、表单、弹窗和状态标签上保持一致。
• 在项目主力桌面宽度下文本不溢出、按钮不挤压、内容宽度合理；没有项目约定时优先检查 1440px 和 1920px。
• 浏览器控制台没有运行时报错。

如果具体版本很重要，安装前使用 npm view <package> version 查询当前版本。前端包版本变化很快，不要长期依赖旧版本号。

边界

默认不要过度建设。

除非用户明确要求，不要默认添加：

• RBAC 实现
• Mock server
• i18n
• 图表
• monitoring SDK
• Docker
• Nginx
• CI/CD
• OpenAPI code generation

保留扩展边界，但保持初始项目轻量。