企业官网建设流程全解析

• AI 应用
• 媒体生成
• 前端
• AI Agent
• AI 技能

本文围绕开源仓库.agents/skills/vercel-react-best-practices中的规则模板文件 rules/_template.md 展开，系统讲解如何基于该模板编写一条结构规范、示例清晰、可被自动构建与校验的性能优化规则。读者将掌握模板的 frontmatter 字段语义、八类规则分区与文件名前缀体系、六档 impact 级别、Incorrect/Correct 示例的写作规范，以及pnpm build/pnpm validate等构建管线的工作方式，可直接在本仓库或其他 React/Next.js 项目中实践规则作者工作流。

一、这套规则体系的定位：为 Agent 而生的性能规范库

vercel-react-best-practices是一套由 Vercel Engineering 维护、面向 AI Agent 与 LLM 的 React/Next.js 性能优化指南。从 SKILL.md 的描述看，它"在编写、审查或重构 React/Next.js 代码时应被使用"，共包含 70 条规则、8 个分类，按影响程度（impact）排序，以指导自动化重构与代码生成。其元数据（metadata.json）记录了版本 1.0.0、组织为 Vercel Engineering、日期 2026 年 1 月，并声明"每一条规则都包含详细解释、对比错误与正确实现的真实示例，以及具体的影响指标，用于指导自动化重构和代码生成"。

该技能在仓库中的文件布局如下：

• rules/：单条规则文件（每条一个文件），其中_sections.md保存分区元数据（标题、影响、描述），_template.md是创建新规则用的模板，_开头的文件不参与构建；
• metadata.json：文档元数据（版本、组织、摘要）；
• AGENTS.md：构建生成的完整编译输出（所有规则展开后的总文档，共 3800 余行）；
• README.md：使用说明与规则作者指南。

其中_template.md是整个规则库的"写作骨架"——所有规则文件都从它复制而来。理解这个模板，就等于理解了整个规则库的创作规范。

二、模板整体结构：四段式规则文件

模板全文仅 28 行，却定义了规则文件的标准形态，可概括为"frontmatter 元数据 + 四段正文"：

--- title: Rule Title Here impact: MEDIUM impactDescription: Optional description of impact (e.g., "20-50% improvement") tags: tag1, tag2 --- ## Rule Title Here **Impact: MEDIUM (optional impact description)** Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications. **Incorrect (description of what's wrong):** ```typescript // Bad code example here const bad = example()

Correct (description of what's right):

// Good code example here const good = example()

Reference: Link to documentation or resource

其中 frontmatter 是 YAML 格式的元数据头，正文则固定包含 Impact 声明、规则说明、错误示例、正确示例、参考链接五个组成部分。下面逐一拆解每个字段的写法与取值规范。 ## 三、frontmatter 字段详解 frontmatter 是机器可读的规则元数据，构建脚本会依据它生成目录、排序和汇总。四个字段分别承担不同职责： ### 1. `title` 规则标题，要求用"动作 + 对象"的祈使句式概括规则核心，便于在目录中快速检索。仓库内真实规则标题示例： - [async-parallel.md](https://link.gitcode.com/i/2e20992c963495700463b38dc70bae84)：`Promise.all() for Independent Operations` - [rerender-memo.md](https://link.gitcode.com/i/5c8bb1c66dcfb9912400564e430a2c1a)：`Extract to Memoized Components` - [bundle-barrel-imports.md](https://link.gitcode.com/i/d0a6087acfc4d77bf6c10e2b7ef9617a)：`Avoid Barrel File Imports` 标题应同时出现在 frontmatter 和正文 H2 中，两者保持一致（见模板第 2 行与第 8 行）。 ### 2. `impact` 规则的影响等级，取值限定在六个级别之一：`CRITICAL`、`HIGH`、`MEDIUM-HIGH`、`MEDIUM`、`LOW-MEDIUM`、`LOW`。它决定规则在优先级排序中的位置，是构建与检索的关键字段。级别语义在 [README.md](https://link.gitcode.com/i/3c3a1675c4c334bb09cc7564f846a939) 中定义如下： | 级别 | 语义 | |------|------| | CRITICAL | 最高优先级，带来主要性能收益 | | HIGH | 显著的性能提升 | | MEDIUM-HIGH | 中高收益 | | MEDIUM | 中等性能改进 | | LOW-MEDIUM | 中低收益 | | LOW | 渐进式改进 | 值得注意的是，同一分类内的规则 impact 也可以不同。例如同属 `async-` 分区的规则中，[async-parallel.md](https://link.gitcode.com/i/2e20992c963495700463b38dc70bae84) 标记为 `CRITICAL`（影响描述为 2-10 倍提升），而 [async-cheap-condition-before-await.md](https://link.gitcode.com/i/cc425044fb568693808eac08b5d5b11a) 标记为 `HIGH`（影响描述为"当同步守卫已失败时避免不必要的异步工作"）。这说明 impact 描述的是**该条规则单独实施时**的收益量级，而非所属分类的整体权重。 ### 3. `impactDescription` 对影响的可选量化说明，建议给出可验证的收益描述（如 "20-50% improvement"、"2-10× improvement"）。仓库内真实取值包括： - [bundle-barrel-imports.md](https://link.gitcode.com/i/d0a6087acfc4d77bf6c10e2b7ef9617a)：`200-800ms import cost, slow builds` - [async-parallel.md](https://link.gitcode.com/i/2e20992c963495700463b38dc70bae84)：`2-10× improvement` - [rerender-memo.md](https://link.gitcode.com/i/5c8bb1c66dcfb9912400564e430a2c1a)：`enables early returns` 它随 `impact` 一起展示在正文第一行，帮助读者快速判断这条规则值不值得投入改造。 ### 4. `tags` 逗号分隔的标签列表，用于跨分类检索与语义归类。示例：[async-parallel.md](https://link.gitcode.com/i/2e20992c963495700463b38dc70bae84) 使用 `async, parallelization, promises, waterfalls`，[rerender-memo.md](https://link.gitcode.com/i/5c8bb1c66dcfb9912400564e430a2c1a) 使用 `rerender, memo, useMemo, optimization`。标签应覆盖规则所属分类、核心 API 与关键概念词，便于 Agent 按关键词命中。 ## 四、正文五要素：从 Impact 到 Reference ### 1. Impact 声明行 正文第一行以 **加粗的 Impact 声明** 开头，格式为 `**Impact: 级别 (影响描述)**`，与 frontmatter 中的 `impact` / `impactDescription` 保持同步。它既是给人类读者的速览，也是构建脚本进行排序的依据。 ### 2. 规则说明 模板要求"清晰简洁地解释规则及其重要性，说明性能影响"。仓库内规则的说明普遍采用"问题背景 + 反例危害 + 正例收益"的三段式写法。例如 [async-cheap-condition-before-await.md](https://link.gitcode.com/i/cc425044fb568693808eac08b5d5b11a) 先定义适用场景（"分支中同时使用 `await` 获取 flag 和**廉价的同步条件**时，应先评估同步条件"），再解释原因（"否则即使复合条件永远不可能成立，你也要为异步调用付费"），最后补充边界（"如果同步条件本身昂贵、依赖 flag，或必须按固定顺序执行副作用，则保持原有顺序"）。 ### 3. Incorrect / Correct 双示例 模板的核心约束是**每条规则必须同时提供错误与正确两份代码示例**，这是整库规则的统一写作范式。示例要求： - **Incorrect**：给出"看起来合理但存在性能问题"的代码，并附一句问题描述； - **Correct**：给出改造后的代码，并附一句正确做法说明； - 两份示例应形成同场景下的直接对比，让 Agent 能识别出可自动化的改写模式。 以 [async-parallel.md](https://link.gitcode.com/i/2e20992c963495700463b38dc70bae84) 为例，它用"3 次串行网络往返"对比"1 次并行往返"来说明 `Promise.all()` 的价值： ```typescript // Incorrect：串行执行，3 次往返 const user = await fetchUser() const posts = await fetchPosts() const comments = await fetchComments() // Correct：并行执行，1 次往返 const [user, posts, comments] = await Promise.all([ fetchUser(), fetchPosts(), fetchComments() ])

rerender-memo.md 则展示了组件级重构的对比：错误写法在loading时仍用useMemo计算头像，正确写法把头像提取为memo包裹的UserAvatar子组件，从而在 loading 分支提前返回、跳过计算。该文件末尾还附带了适用性说明：若项目已启用 React Compiler，手写memo()/useMemo()就不再必要——这体现了规则作者对"何时不适用"的边界意识。

4. Reference 参考链接

模板最后要求给出参考文档或资源链接。仓库内规则引用过 Next.js 官方博客的包导入优化文章、react.dev、nextjs.org、SWR 官网等权威资料（见 metadata.json 的 references 列表）。在编写规则时，建议将参考链接放在示例之后，便于读者和 Agent 回溯原始依据。

五、创建一条新规则的完整工作流

README.md 给出了创建新规则的六步流程，与本仓库内 70 条规则的生成方式完全一致：

1. 复制模板：将rules/_template.md复制为rules/分区-描述.md（如async-parallel.md）；
2. 选择分区前缀：根据规则所属分类选用八种前缀之一（见下表）；
3. 填写 frontmatter 与正文：按第三、四节所述规则补全四个元数据字段和正文五要素；
4. 确保示例清晰且带解释：Incorrect/Correct 各一份，并说明对错原因；
5. 运行pnpm build：重新生成编译输出AGENTS.md与test-cases.json；
6. 运行pnpm validate：校验所有规则文件格式合规。

八类分区与文件名前缀

规则按性能主题划分为 8 个分类，每个分类有固定的文件名前缀与优先级权重（数据来自 SKILL.md 与 _sections.md）：

_sections.md对每个分类都给出了一句"为什么重要"的说明，例如第 1 类："Waterfall 是第一大性能杀手，每次串行 await 都会叠加完整的网络延迟，消除它们收益最大"；第 2 类："减小初始包体积可以改善 TTI（可交互时间）与 LCP（最大内容绘制）"。

六、文件名规范与自动构建管线

模板所在的规则库对文件名有严格约束，理解这些约束才能写出"可被构建系统正确收录"的规则：

• _开头的文件是特殊文件，不参与构建：_template.md和_sections.md即属此类——模板不会被当成规则编入AGENTS.md；
• 规则文件命名：分区前缀-描述.md，如async-parallel.md、bundle-barrel-imports.md；分类由文件名前缀自动推断，无需在 frontmatter 中重复声明；
• 排序与编号：构建时每个分区内的规则按标题字母排序，编号（如 1.1、1.2）在构建过程中自动生成，作者不需要手动管理序号；
• 构建产物：pnpm build将全部规则编译为完整的 AGENTS.md（即文首所述 3800 余行的总文档）并生成test-cases.json（用于 LLM 评估的测试用例）；pnpm validate校验全部规则文件；pnpm extract-tests抽取测试用例；pnpm dev等价于 build + validate。

仓库内编译产物 AGENTS.md 展示了这套管线的实际输出形态：包含目录（按 8 个分区编号 1.1～8.4）、每条规则的影响声明、以及规则间相互引用的链接（如async-cheap-condition-before-await自述为async-defer-await针对flag && cheapCondition场景的特化）。这证明模板结构完全能支撑大规模、机器可读的规则文档组织。

七、模板在实际项目中的落地：本仓库的前端实践

这套规则技能被引入本仓库，服务于 web/ 目录下基于 Vite + React + TypeScript + Ant Design + Tailwind + Zustand 构建的前端画布应用。从根目录 AGENTS.md 的前端规范可以看到，模板所代表的性能理念已经渗透到项目编码规范中：

• 包体积规则（bundle-barrel-imports）的对应实践：项目规范明确"UI 图标优先使用lucide-react或项目已经使用的 Ant Design 图标"。而 bundle-barrel-imports.md 恰好指出lucide-react等图标库的 barrel 入口可能包含上万个 re-export，直接import { Check } from 'lucide-react'会产生数百毫秒的导入成本——两者结合意味着：在仓库前端开发中选用图标时，应留意"从库入口导入 vs 从深路径导入"的取舍，或在构建层启用包导入优化；
• 渲染与重渲染规则的应用场景：画布页面（web/src/pages/canvas/、web/src/components/canvas/）存在大量高频更新的节点组件，rerender-与rendering-分区中关于memo、useMemo、避免组件内定义组件、条件渲染用三元表达式等规则，正是这类交互密集界面的优化依据；
• 数据获取规则的应用场景：项目规范规定"外部服务请求统一放在web/src/services/api/，由浏览器前端直连"，async-分区关于Promise.all()并行化、Suspense 边界、先检查廉价条件再 await 的规则，可直接指导这些 API 调用层的并发编排。

也就是说，_template.md不只是仓库内一个孤立的模板文件——它是整个前端性能规范体系的生产工具，仓库中的 70 条规则全部经由它产出，并反向约束着 web/ 前端的编码质量。

八、编写高质量规则的四条准则

综合模板要求与仓库内真实规则的写法，可以提炼出四条作者准则：

1. 示例必须成对且同场景：Incorrect 与 Correct 应改写同一段代码，差异点只在于性能关键改动，方便 Agent 学习自动化的前后差异；
2. 说明要讲清"为什么"：模板要求的"brief explanation"不是复述代码，而是解释性能机理（如"每次串行 await 都会叠加完整网络延迟"），并尽量给出可量化的影响描述；
3. 标注适用边界与例外：如async-cheap-condition-before-await提示"若同步条件昂贵、依赖 flag 或需固定副作用顺序则保持原序"，rerender-memo提示 React Compiler 启用时无需手写 memo——边界说明让规则在自动化应用中不易误伤；
4. 元数据与正文保持同步：frontmatter 的 title 与正文 H2 一致、impact 与 Impact 声明行一致、标签覆盖检索关键词，这是构建与检索可靠性的前提。

结语

rules/_template.md以最精简的 28 行定义了 Vercel React Best Practices 规则库的完整写作契约：frontmatter 承载机器可读的元数据，四段正文承载人可读的讲解与示例，双示例结构则让性能优化模式可以被 Agent 直接识别和自动改写。理解并善用这个模板，意味着你既能产出符合规范的新规则，也能借助pnpm build/pnpm validate管线将其纳入自动化的性能治理闭环——无论是本仓库的画布前端，还是任何 React/Next.js 项目，这套"模板 + 分区 + 级别 + 构建"的规则工程方法论都值得直接复用。

• AI 应用
• 媒体生成
• 前端
• AI Agent
• AI 技能