前言¶

在 React + TypeScript 项目里，常见痛点是数据获取写法不统一（有的在组件里 fetch，有的堆 isLoading 分支）、目录按技术层而不是按业务功能拆分、以及路由和重型组件未做懒加载导致打包体积膨胀。团队往往靠 Code Review 口头约定，Agent 辅助写码时也容易回到「能跑就行」的默认习惯。

下面介绍 SkillHub 上的 frontend-dev-guidelines（坐标 @org-02qudk26/frontend-dev-guidelines）。它把 Suspense 优先的数据获取、基于功能的目录、TanStack Router、MUI v7 样式和严格 TypeScript 等约定写进一份可被 Agent 读取的 SKILL.md，让生成与重构代码时有同一套「必须如何写」的约束，而不只是风格建议。

这是什么¶

frontend-dev-guidelines 是面向现代 React + TypeScript 应用的、有主见（opinionated）的前端开发标准 Skill。发布者为智雨科技，来源标注为 enterprise，当前版本 1.0.0，分类为 dev-programming，标签 requires_api_key=false（安装与使用不依赖 API Key）。

SkillHub 页面显示：评分 100000，下载 2063 次（以 SkillHub 展示为准）。官方入口：

• SkillHub 展示页：https://www.skillhub.cn/skills/org-02qudk26/frontend-dev-guidelines
• API 坐标页：https://api.skillhub.cn/org-02qudk26/frontend-dev-guidelines

核心功能¶

以下内容均来自该 Skill 包内的 SKILL.md 与元数据描述，是其要求 Agent 在写前端代码时遵循的要点。

架构与数据获取¶

• Suspense 为默认：优先使用 useSuspenseQuery；避免 isLoading 条件分支和提前返回 spinner；依赖 Suspense 边界处理加载态。
• 懒加载：路由、功能入口、数据网格/图表/编辑器等重型 UI 使用 React.lazy，并包裹 <SuspenseLoader>。
• 基于功能的组织：领域逻辑放在 features/；可复用原语放在 components/；禁止跨功能随意耦合。
• API 层：每个功能在 api/ 中隔离请求；禁止在组件内内联 fetch/axios；路由中不使用 /api/ 前缀。

路由、样式与 TypeScript¶

• TanStack Router：文件夹路由；懒加载路由组件；通过 loader 提供面包屑等元数据。
• MUI v7：较短组件内联 sx；较大样式抽到 {Component}.styles.ts；网格使用 v7 的 size={{ xs, md }} 语法。
• TypeScript：严格模式；禁止 any；显式返回类型；使用 import type；类型与功能就近放置。

FFCI 与检查清单¶

Skill 定义 前端可行性与复杂度指数（FFCI）：从架构契合度、复杂度、性能风险、可复用性、维护成本等维度打分，用公式 FFCI = (架构契合度 + 可复用性 + 性能) − (复杂度 + 维护成本) 评估是否应继续实现或需要拆分重构。收尾前要求 FFCI ≥ 6，并核对 Suspense、功能边界、懒加载与类型等项。

导入别名（Skill 内约定）¶

与其他 Skill 的衔接¶

文档中说明可与 frontend-design、page-cro、analytics-tracking、backend-dev-guidelines、error-tracking 等 Skill 配合，分别对应视觉、转化、埋点、API 契约与可观测性；具体是否安装取决于你的项目与其他 Skill 是否已在环境中启用。

安装与启用¶

Skill 基于通用 SKILL.md 格式。SkillHub 官方给出的安装指引是：让 Agent 参照 SkillHub 安装文档，安装坐标 @org-02qudk26/frontend-dev-guidelines。

若本机已安装 skillhub CLI，可先检查版本，再安装到当前 Agent 的 skills 目录（必须使用 --dir，否则默认装到 ./skills/ 可能不会被 Agent 加载）：

command -v skillhub && skillhub --version

未安装 CLI 时，安装文档提供一键脚本（完整安装或仅 CLI）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

安装本 Skill：

skillhub install frontend-dev-guidelines --namespace org-02qudk26 --dir <你的 Agent skills 目录>

常见 Agent 的 skills 路径（摘自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

也可将提示词发给 AI：「请根据 https://skillhub.cn/install/skillhub.md，安装 @org-02qudk26/frontend-dev-guidelines。」安装后需按你所用客户端说明重启或刷新，以便加载新 Skill。

典型用法¶

启用后，在创建组件/页面、加功能、改数据获取、配路由、用 MUI 样式或做性能与重构审查时，Agent 应读取本 Skill 并按其清单执行。下面两段来自官方 SKILL.md，可直接对照项目结构复现。

懒加载重型组件：

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

组件树中需配合 <SuspenseLoader> 包裹。

TanStack Router 文件路由示例：

export const Route = createFileRoute('/my-route/')({
  component: MyPage,
  loader: () => ({ crumb: 'My Route' }),
});

数据获取与组件结构（节选）： 使用 useSuspenseQuery、功能级 featureApi、MUI Box/Paper，处理函数用 useCallback，底部默认导出——完整模板见 Skill 内「规范组件模板」一节。

官方 README 还用三条文字场景说明适用方向（复杂报表页、大图表首屏、跨 feature 状态耦合），属于文档内的说明素材，而非第三方用户反馈。

适用场景与注意¶

适合：

• 技术栈接近 Skill 假设的仓库：React、TypeScript、TanStack Query（Suspense）、TanStack Router、MUI v7。
• 希望 Agent 写码时统一 Suspense 数据流、features/ 分层和性能相关默认值，而不是每次临时约定。
• 需要与后端契约、设计、埋点等其它 enterprise Skill 对齐的长期维护型前端代码库。

注意：

• 规范有主见且偏严格（例如禁止 any、禁止组件内直接 fetch、用户反馈限定 useMuiSnackbar）。若项目使用其它 UI 库、路由或数据层，需要人工裁剪或不要全盘套用。
• 导入别名与目录结构（features/{name}/api|components|hooks|...、routes/）是 Skill 内的目标结构；迁入存量项目时要分步对齐，避免一次性大改。
• FFCI 与检查清单面向 Agent 自检；团队仍应保留人工 Review，尤其在边界条件与业务规则上。
• SkillHub 统计（评分、下载量）会随时间变化，以页面实时展示为准。

结尾¶

frontend-dev-guidelines 把 React + TypeScript 前端里关于 Suspense 数据获取、功能分层、路由懒加载、MUI v7 与 TypeScript 纪律等约定固化成 Agent 可执行的 Skill，适合希望在 AI 辅助开发下仍保持生产级一致性的团队。安装与详情见 SkillHub：https://www.skillhub.cn/skills/org-02qudk26/frontend-dev-guidelines ，坐标页：https://api.skillhub.cn/org-02qudk26/frontend-dev-guidelines 。