skillhub-088-vercel-react-best-practices
wehub-skill-sync
129 行
3.3 KiB
Markdown
129 行
3.3 KiB
Markdown
---
|
||
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) 创建。
|