feature-arch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feature-Based Architecture Best Practices

基于功能的架构最佳实践

Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 42 rules across 8 categories, prioritized by impact from critical (directory structure, imports) to incremental (naming conventions).

这是一份用于按功能组织React应用的全面架构指南，支持独立团队进行可扩展开发。包含8个类别共42条规则，按影响程度从关键（目录结构、导入）到增量（命名规范）排序。

When to Apply

适用场景

Reference these guidelines when:

Creating new features or modules
Organizing project directory structure
Setting up import rules and boundaries
Implementing data fetching patterns
Composing components from multiple features
Reviewing code for architecture violations

在以下场景中参考本指南：

创建新功能或模块
整理项目目录结构
设置导入规则与边界
实现数据获取模式
组合来自多个功能的组件
评审代码以检查架构违规情况

Rule Categories by Priority

按优先级划分的规则类别


struct-
import-
bound-
fquery-
fcomp-
fstate-
test-
name-

Priority	Category	Impact	Prefix
1	Directory Structure	CRITICAL	`struct-`
2	Import & Dependencies	CRITICAL	`import-`
3	Module Boundaries	HIGH	`bound-`
4	Data Fetching	HIGH	`fquery-`
5	Component Organization	MEDIUM-HIGH	`fcomp-`
6	State Management	MEDIUM	`fstate-`
7	Testing Strategy	MEDIUM	`test-`
8	Naming Conventions	LOW	`name-`


struct-
import-
bound-
fquery-
fcomp-
fstate-
test-
name-

优先级	类别	影响程度	前缀
1	目录结构	关键	`struct-`
2	导入与依赖	关键	`import-`
3	模块边界	高	`bound-`
4	数据获取	高	`fquery-`
5	组件组织	中高	`fcomp-`
6	状态管理	中	`fstate-`
7	测试策略	中	`test-`
8	命名规范	低	`name-`

Quick Reference

快速参考

1. Directory Structure (CRITICAL)

1. 目录结构（关键）

```
struct-feature-folders
```
- Organize by feature, not technical type
```
struct-feature-self-contained
```
- Make features self-contained
```
struct-shared-layer
```
- Use shared layer for truly generic code only
```
struct-flat-hierarchy
```
- Keep directory hierarchy flat
```
struct-optional-segments
```
- Include only necessary segments
```
struct-app-layer
```
- Separate app layer from features

```
struct-feature-folders
```
- 按功能而非技术类型组织代码
```
struct-feature-self-contained
```
- 确保功能具备自包含性
```
struct-shared-layer
```
- 仅将真正通用的代码放入共享层
```
struct-flat-hierarchy
```
- 保持目录层级扁平化
```
struct-optional-segments
```
- 仅保留必要的目录段
```
struct-app-layer
```
- 将应用层与功能层分离

2. Import & Dependencies (CRITICAL)

2. 导入与依赖（关键）

```
import-unidirectional-flow
```
- Enforce unidirectional import flow
```
import-no-cross-feature
```
- Prohibit cross-feature imports
```
import-public-api
```
- Export through public API only
```
import-avoid-barrel-files
```
- Avoid deep barrel file re-exports
```
import-path-aliases
```
- Use consistent path aliases
```
import-type-only
```
- Use type-only imports for types

```
import-unidirectional-flow
```
- 强制单向导入流程
```
import-no-cross-feature
```
- 禁止跨功能导入
```
import-public-api
```
- 仅通过公共API导出
```
import-avoid-barrel-files
```
- 避免深层桶文件重导出
```
import-path-aliases
```
- 使用一致的路径别名
```
import-type-only
```
- 对类型使用仅类型导入

3. Module Boundaries (HIGH)

3. 模块边界（高）

```
bound-feature-isolation
```
- Enforce feature isolation
```
bound-interface-contracts
```
- Define explicit interface contracts
```
bound-feature-scoped-routing
```
- Scope routing to feature concerns
```
bound-minimize-shared-state
```
- Minimize shared state between features
```
bound-event-based-communication
```
- Use events for cross-feature communication
```
bound-feature-size
```
- Keep features appropriately sized

```
bound-feature-isolation
```
- 强制功能隔离
```
bound-interface-contracts
```
- 定义明确的接口契约
```
bound-feature-scoped-routing
```
- 将路由限定在功能范围内
```
bound-minimize-shared-state
```
- 尽量减少功能间的共享状态
```
bound-event-based-communication
```
- 使用事件进行跨功能通信
```
bound-feature-size
```
- 保持功能的合理规模

4. Data Fetching (HIGH)

4. 数据获取（高）

```
fquery-single-responsibility
```
- Keep query functions single-purpose
```
fquery-colocate-with-feature
```
- Colocate data fetching with features
```
fquery-parallel-fetching
```
- Fetch independent data in parallel
```
fquery-avoid-n-plus-one
```
- Avoid N+1 query patterns
```
fquery-feature-scoped-keys
```
- Use feature-scoped query keys
```
fquery-server-component-fetching
```
- Fetch at server component level

```
fquery-single-responsibility
```
- 确保查询函数单一职责
```
fquery-colocate-with-feature
```
- 将数据获取与功能代码放在一起
```
fquery-parallel-fetching
```
- 并行获取独立数据
```
fquery-avoid-n-plus-one
```
- 避免N+1查询模式
```
fquery-feature-scoped-keys
```
- 使用功能限定的查询键
```
fquery-server-component-fetching
```
- 在服务器组件层进行数据获取

5. Component Organization (MEDIUM-HIGH)

5. 组件组织（中高）

```
fcomp-single-responsibility
```
- Apply single responsibility to components
```
fcomp-composition-over-props
```
- Prefer composition over prop drilling
```
fcomp-container-presentational
```
- Separate container and presentational concerns
```
fcomp-props-as-data-boundary
```
- Use props as feature boundaries
```
fcomp-colocate-styles
```
- Colocate styles with components
```
fcomp-error-boundaries
```
- Use feature-level error boundaries

```
fcomp-single-responsibility
```
- 对组件应用单一职责原则
```
fcomp-composition-over-props
```
- 优先使用组合而非属性透传
```
fcomp-container-presentational
```
- 分离容器组件与展示组件关注点
```
fcomp-props-as-data-boundary
```
- 将属性作为功能边界
```
fcomp-colocate-styles
```
- 将样式与组件放在一起
```
fcomp-error-boundaries
```
- 使用功能级别的错误边界

6. State Management (MEDIUM)

6. 状态管理（中）

```
fstate-feature-scoped-stores
```
- Scope state stores to features
```
fstate-server-state-separation
```
- Separate server state from client state
```
fstate-lift-minimally
```
- Lift state only as high as necessary
```
fstate-context-sparingly
```
- Use context sparingly for feature state
```
fstate-reset-on-unmount
```
- Reset feature state on unmount

```
fstate-feature-scoped-stores
```
- 将状态存储限定在功能范围内
```
fstate-server-state-separation
```
- 分离服务器状态与客户端状态
```
fstate-lift-minimally
```
- 仅在必要时提升状态
```
fstate-context-sparingly
```
- 谨慎使用Context管理功能状态
```
fstate-reset-on-unmount
```
- 卸载时重置功能状态

7. Testing Strategy (MEDIUM)

7. 测试策略（中）

```
test-colocate-with-feature
```
- Colocate tests with features
```
test-feature-isolation
```
- Test features in isolation
```
test-shared-utilities
```
- Create feature-specific test utilities
```
test-integration-at-app-layer
```
- Write integration tests at app layer

```
test-colocate-with-feature
```
- 将测试与功能代码放在一起
```
test-feature-isolation
```
- 对功能进行独立测试
```
test-shared-utilities
```
- 创建功能专用的测试工具
```
test-integration-at-app-layer
```
- 在应用层编写集成测试

8. Naming Conventions (LOW)

8. 命名规范（低）

```
name-feature-naming
```
- Use domain-driven feature names
```
name-file-conventions
```
- Use consistent file naming conventions
```
name-descriptive-exports
```
- Use descriptive export names

```
name-feature-naming
```
- 使用领域驱动的功能名称
```
name-file-conventions
```
- 使用一致的文件命名规范
```
name-descriptive-exports
```
- 使用具有描述性的导出名称

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules
Individual rules:
```
references/{prefix}-{slug}.md
```

阅读单个参考文件以获取详细说明和代码示例：

章节定义 - 类别结构与影响级别说明
规则模板 - 添加新规则的模板
单个规则文件：
```
references/{prefix}-{slug}.md
```

Related Skills

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

包含所有规则扩展说明的完整指南：

AGENTS.md