---
title: React Best Practices
description: 面向代理与 LLM 优化创建和维护 React 最佳实践的规范化仓库
---

# React 最佳实践

面向代理与 LLM 优化创建和维护 React 最佳实践的规范化仓库。

## 结构

- `rules/` — 单条规则文件（每条规则一个文件）
  - `_sections.md` — 章节元数据（标题、影响等级、描述）
  - `_template.md` — 创建新规则的模板
  - `area-description.md` — 单条规则文件
- `src/` — 构建脚本与工具
- `metadata.json` — 文档元数据（版本、组织、摘要）
- __`AGENTS.md`__ — 编译后输出文件（自动生成）
- __`test-cases.json`__ — 供 LLM 评估用的测试用例（自动生成）

## 快速开始

1. 安装依赖：
   ```bash
   pnpm install
   ```

2. 从规则构建 AGENTS.md：
   ```bash
   pnpm build
   ```

3. 校验规则文件：
   ```bash
   pnpm validate
   ```

4. 提取测试用例：
   ```bash
   pnpm extract-tests
   ```

## 创建新规则

1. 将 `rules/_template.md` 复制为 `rules/area-description.md`
2. 选择对应的区域前缀：
   - `async-` — 消除瀑布请求（第 1 节）
   - `bundle-` — 包体积优化（第 2 节）
   - `server-` — 服务端性能（第 3 节）
   - `client-` — 客户端数据获取（第 4 节）
   - `rerender-` — 重渲染优化（第 5 节）
   - `rendering-` — 渲染性能（第 6 节）
   - `js-` — JavaScript 性能（第 7 节）
   - `advanced-` — 高级模式（第 8 节）
3. 填写 frontmatter 和正文内容
4. 确保提供清晰的示例并附带说明
5. 运行 `pnpm build` 重新生成 AGENTS.md 和 test-cases.json

## 规则文件结构

每条规则文件应遵循以下结构：

```markdown
---
title: 规则标题
impact: MEDIUM
impactDescription: 可选描述
tags: tag1, tag2, tag3
---

## 规则标题

关于该规则的简要说明以及它为何重要。

**不正确（问题描述）：**

```typescript
// 反面代码示例
```

**正确（正确做法描述）：**

```typescript
// 正面代码示例
```

示例之后的可选说明文字。

参考链接：[Link](https://example.com)

## 文件命名约定

- 以 `_` 开头的文件为特殊文件（不参与构建）
- 规则文件格式：`area-description.md`（例如 `async-parallel.md`）
- 章节根据文件名前缀自动推断
- 每条规则在各章节内按标题字母顺序排序
- 编号（如 1.1、1.2）在构建时自动生成

## 影响等级

- `CRITICAL` — 最高优先级，显著性能提升
- `HIGH` — 大幅性能改进
- `MEDIUM-HIGH` — 中高收益
- `MEDIUM` — 中等性能改进
- `LOW-MEDIUM` — 中低收益
- `LOW` — 渐进式改进

## 脚本

- `pnpm build` — 将规则编译为 AGENTS.md
- `pnpm validate` — 校验所有规则文件
- `pnpm extract-tests` — 提取供 LLM 评估用的测试用例
- `pnpm dev` — 构建并校验

## 贡献指南

添加或修改规则时：

1. 为你的章节使用正确的文件名前缀
2. 遵循 `_template.md` 的结构
3. 包含清晰的反面/正面示例并附带说明
4. 添加适当的标签
5. 运行 `pnpm build` 重新生成 AGENTS.md 和 test-cases.json
6. 规则按标题自动排序——无需手动管理编号！

## 致谢

最初由 [@shuding](https://x.com/shuding) 在 [Vercel](https://vercel.com) 创建。