catalog/repos/aiko-atami--fsd.md

# 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 本地安装

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

2. 复制为单个技能文件：
   ```bash
   cp SKILL.md ~/.codex/skills/feature-sliced-design.md
   ```

3. 或复制为技能文件夹：
   ```bash
   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：
```typescript
// features/auth/index.ts
export { LoginForm } from './ui/LoginForm';
export { useAuth } from './model/useAuth';
```

## 典型项目结构

```text
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](https://github.com/feature-sliced/steiger) 是验证 FSD 规则的官方工具：

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

检查内容包括：
- 导入规则违反
- 公共 API 使用情况
- 跨导入违规
- 层结构一致性

## 资源

- [FSD 官方文档](https://feature-sliced.design/)
- [FSD 文档仓库](https://github.com/feature-sliced/documentation)
- [Steiger lint 工具](https://github.com/feature-sliced/steiger)
- [FSD 示例](https://feature-sliced.design/examples)

## 从 FSD v2.0 迁移到 v2.1

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

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

## 故障排查

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

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

### 导入规则违反
该技能应能识别违规并提出修复方案。

## 许可证

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

---

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

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