mc-skills/catalog

Fork 0

mc-skills 52efc07510 catalog: 更新 2026-04-07 11:44

2026-04-07 11:44:56 +08:00

5.6 KiB

Raw Blame History

FSD前端架构设计技能

前端架构 Feature-Sliced Design Codex React 代码组织

Codex 的 Feature-Sliced Design 技能（v2.1）

本技能帮助 Codex 将 Feature-Sliced Design（FSD）v2.1 架构方法论应用于前端项目。

v2.1 新增内容

核心更新：**"页面优先"**方法。

在需要复用之前，将代码保留在使用它的地方。
从 pages 和 widgets 开始；仅在真正复用时才提取到 features 或 entities。
提升内聚性，简化重构，加快开发速度。

本技能包含的内容

6 个活跃 FSD 层（app、pages、widgets、features、entities、shared）的完整指南
v2.1 新增："页面优先"代码放置策略
v2.1 新增：实体间跨导入的公共 API（@x 符号）
v2.1 新增：shared 中感知应用的代码
层/切片/片段的组织规则
公共 API 模式与最佳实践
React、Redux、React Query 和 Next.js 示例
需要避免的反模式（包括过早提取）
从 v2.0 迁移到 v2.1 的策略
正确放置代码的决策框架
Steiger 架构 lint 工具集成

安装

为 Codex 本地安装

创建自定义技能目录：
```
mkdir -p ~/.codex/skills
```

复制为单个技能文件：

cp SKILL.md ~/.codex/skills/feature-sliced-design.md

或复制为技能文件夹：

mkdir -p ~/.codex/skills/feature-sliced-design
cp SKILL.md ~/.codex/skills/feature-sliced-design/
cp -r agents ~/.codex/skills/feature-sliced-design/

替代方法

将 feature-sliced-design-skill 文件夹放置在项目根目录，并指定 Codex 使用它。

使用方式

在以下情况下，该技能将自动触发：

提及"FSD"、"Feature-Sliced Design"或"feature sliced"
创建新的前端结构
重构现有代码
讨论架构或代码组织方式
询问某段代码应该放在哪里
解决跨导入或依赖问题
拆解功能或组件

使用示例

示例 1：创建新功能（v2.1 方式）

用户："创建一个个人资料编辑表单"
Codex：我将把它放在 pages/profile/，因为它只在这个页面使用。
       如果之后需要复用，我们可以将其移动到 features/。

示例 2：使用页面优先方式重构

用户："我在 features/ 中有一个 UserProfile 组件，但它只在一个页面上使用"
Codex：在 v2.1 中，它应该移回 pages/。features 应包含可复用的交互逻辑。

示例 3：项目初始化

用户："帮我搭建一个使用 FSD v2.1 的新 React 项目"
Codex：[创建结构、配置路径别名、解释页面优先原则]

示例 4：跨导入

用户："实体 User 需要引用 Order"
Codex：使用 @x 符号在实体之间进行显式跨导入。

v2.1 核心概念

页面优先方法

1. 从 pages/ 开始，将代码保留在使用它的位置附近。
2. 仅在真正复用时才提取到 features/entities。
3. 不要预测未来的复用需求；等待真实的重复出现。

层结构

app/        <- 应用初始化
pages/      <- 包含自身逻辑的页面
widgets/    <- 包含自身逻辑的复合 UI 块
features/   <- 可复用的业务交互
entities/   <- 可复用的业务实体
shared/     <- 基础设施与感知应用的共享代码

注意：processes/ 层在 v2.1 中已废弃。

导入规则

模块只能从更低层级导入：

features/ -> entities/、shared/
entities/ 不得从 features/ 导入

公共 API

每个切片应通过 index.ts 暴露公共 API：

// features/auth/index.ts
export { LoginForm } from './ui/LoginForm';
export { useAuth } from './model/useAuth';

典型项目结构

src/
├── app/
├── pages/
├── widgets/
├── features/
├── entities/
└── shared/

支持的技术栈

React
Vue
Angular
Svelte
Next.js
Redux / Redux Toolkit
React Query
MobX
TypeScript
Vite
Create React App

附加工具

Steiger——FSD 架构 lint 工具

Steiger 是验证 FSD 规则的官方工具：

npm install -D @feature-sliced/steiger
npx steiger src

检查内容包括：

导入规则违反
公共 API 使用情况
跨导入违规
层结构一致性

资源

从 FSD v2.0 迁移到 v2.1

迁移是非破坏性的，可以逐步进行：

审查现有代码。
将页面专属逻辑移回 pages/。
将 widget 专属逻辑保留在 widgets/。
在 features/ 和 entities/ 中只保留真正可复用的逻辑。
在 shared 中更新基础设施和应用级常量。
移除已废弃的 processes/ 用法。

故障排查

技能未激活

确认文件/文件夹位于预期的技能目录中。
确认命名正确。
重启 Codex。

不确定代码应放在哪里

询问 Codex："在 FSD 中，[代码描述] 应该放在哪里？"

导入规则违反

该技能应能识别违规并提出修复方案。

许可证

本技能基于 Feature-Sliced Design 官方文档，可自由使用。

重要：本技能遵循 FSD v2.1 和"页面优先"方法。请将其视为实用指南，而非一成不变的规则。

黄金法则（v2.1）：从 pages/widgets 开始；仅当真正的复用需求出现时，才提取到 features/entities。

5.6 KiB Raw Blame History Unescape Escape