企业官网建设流程全解析

• 前端
• 教程

导读

本文以仓库中 .agents/skills/vercel-react-best-practices/README.md 为骨架，深入剖析这套由 Vercel Engineering 维护的 React/Next.js 性能优化规则库：它如何用"一条规则一个 Markdown 文件 + 构建脚本"的方式组织知识，如何通过pnpm命令链编译出可供 Agent 与 LLM 直接消费的AGENTS.md与测试用例，以及贡献者应遵循的命名、模板与影响等级约定。读完本文，你将掌握这套规则库的目录职责、新增规则的标准流程、规则文件结构与自动化编号机制，并能对照仓库内 69 条真实规则理解其错误/正确示例的写作范式。

一、项目定位：为 Agent 与 LLM 设计的最佳实践规则库

README 开篇即给出了核心定位："A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs"——这是一个面向 AI Agent 与 LLM 的结构化 React 最佳实践仓库，而非普通的文档站点。

从仓库结构可以印证这一设计意图：该技能位于 .agents/skills/vercel-react-best-practices/，与仓库内其他技能（如 next-best-practices、tailwind-css-patterns 等）并列，说明它是作为Agent 技能（Skill）被注入工作流的。配套的 SKILL.md 元数据中声明：This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns，即在编写、审查、重构 React/Next.js 代码时触发引用。

编译产物的消费对象也印证了这一点：AGENTS.md 开头明确写道：

This document is mainly for agents and LLMs to follow when maintaining, generating, or refactoring React and Next.js codebases. Humans may also find it useful, but guidance here is optimized for automation and consistency by AI-assisted workflows.

核心思路可以概括为一条流水线：规则作者把性能优化知识拆成一条条带元数据（frontmatter）的规则文件 → 构建脚本编译为单一AGENTS.md与test-cases.json→ Agent/LLM 在维护或重构代码时整体引用。每条规则都包含"错误写法 vs 正确写法"的对照与影响等级，便于自动化重构时直接套用。

二、仓库结构与目录职责

README 的 Structure 一节定义了完整的目录布局，结合当前仓库快照可以逐项核对：

实际核对当前快照：rules/ 目录下除两个_开头的特殊文件外，共包含 69 条规则文件（async-、bundle-、server-、client-、rerender-、rendering-、js-、advanced-八类前缀），AGENTS.md 为 3000 余行的编译汇总文档，metadata.json 记录了version: 1.0.0、organization: Vercel Engineering、date: January 2026与摘要。README 中提到的src/构建脚本目录与test-cases.json产物在当前提交快照中尚不存在，属于通过pnpm脚本构建/生成的部分。

metadata.json 的摘要准确概括了内容形态：

Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns).

三、快速开始：一条命令链完成安装、构建与校验

README 的 Getting Started 给出四个步骤，均在仓库根目录执行：

# 1. 安装依赖（仓库使用 pnpm，根目录存在 pnpm-lock.yaml 与 pnpm-workspace.yaml） pnpm install # 2. 从规则编译出 AGENTS.md（以及 test-cases.json） pnpm build # 3. 校验所有规则文件（frontmatter 字段、结构合法性等） pnpm validate # 4. 抽取测试用例，用于 LLM 评估 pnpm extract-tests

这条命令链的核心在于：规则源文件（rules/）是唯一人工维护的输入，AGENTS.md与test-cases.json都是可再生成的产物。因此贡献规则后只需重新pnpm build，编译文档与评测数据会自动刷新，无需手工维护编号或目录。

四、新增一条规则的标准流程

README 的 Creating a New Rule 一节定义了五步标准流程：

1. 将rules/_template.md复制为rules/area-description.md（例如async-parallel.md）；
2. 依据所属章节选择正确的区域前缀（area prefix）；
3. 填写 frontmatter 与正文内容；
4. 确保提供带解释的清晰示例（错误/正确对照）；
5. 运行pnpm build重新生成AGENTS.md与test-cases.json。

其中第 2 步的八类前缀由 rules/_sections.md 统一定义，优先级从高到低为：

前缀选择是规则归属章节的唯一依据——构建时章节（Section）由文件名前缀自动推断，这也是"文件名约定"能够自动化的前提。

五、规则文件结构：frontmatter 元数据 + 正反对照示例

每条规则文件都遵循 rules/_template.md 定义的结构：先是 YAML 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()

Optional explanatory text after examples.

Reference: Link to documentation or resource

四个 frontmatter 字段各有明确语义： - `title`：规则标题，构建后按标题字母序参与自动排序； - `impact`：影响等级，取值限定在六档（见第七节）； - `impactDescription`：可选的影响量化描述，例如 `2-10× improvement`、`200-800ms import cost`； - `tags`：逗号分隔的标签，便于检索与归类。 正文部分采用**固定的"错误/正确"对照格式**——`**Incorrect**` 给出反例并解释问题所在，`**Correct**` 给出修复后的写法，末尾可附补充说明与 `Reference` 链接。 以实际规则文件 [rules/async-parallel.md](https://link.gitcode.com/i/1869eb13b37b645a9b6bd325673ad028) 为例，可以看到该模板的完整落地： ```markdown --- title: Promise.all() for Independent Operations impact: CRITICAL impactDescription: 2-10× improvement tags: async, parallelization, promises, waterfalls --- ## Promise.all() for Independent Operations When async operations have no interdependencies, execute them concurrently using `Promise.all()`. **Incorrect (sequential execution, 3 round trips):** ```typescript const user = await fetchUser() const posts = await fetchPosts() const comments = await fetchComments()

Correct (parallel execution, 1 round trip):

const [user, posts, comments] = await Promise.all([ fetchUser(), fetchPosts(), fetchComments() ])

这条规则的写法完全符合模板：`impact: CRITICAL` 配 `2-10× improvement` 的量化描述，正反对照一目了然，构建后自动获得章节 ID 1.5（见第六节）。 --- ## 六、文件名约定与自动编号机制 README 的 File Naming Convention 一节详细规定了命名规则： - **`_` 开头的文件是特殊文件**，构建时被排除（如 `_sections.md`、`_template.md`）； - **规则文件采用 `area-description.md` 命名**，例如 `async-parallel.md`、`bundle-barrel-imports.md`； - **章节由文件名前缀自动推断**，无需在文件内声明章节； - **规则在各自章节内按标题字母序自动排序**； - **ID（如 1.1、1.2）在构建时自动生成**，贡献者完全不需要手动管理编号。 自动编号的效果可以直接在编译产物 [AGENTS.md](https://link.gitcode.com/i/188e7efb7cdbf12f2146bd6c5a723688#L23-L28) 的目录中看到： ```markdown ## Table of Contents 1. Eliminating Waterfalls — CRITICAL - 1.1 Check Cheap Conditions Before Async Flags - 1.2 Defer Await Until Needed - 1.3 Dependency-Based Parallelization - 1.4 Prevent Waterfall Chains in API Routes - 1.5 Promise.all() for Independent Operations - 1.6 Strategic Suspense Boundaries

同一章节内 ID 的先后顺序由构建脚本按标题排序生成，这解释了 README 中"Rules are automatically sorted by title - no need to manage numbers!"的维护承诺——新增或删除规则都不会破坏既有编号体系。

七、影响等级体系：六档优先级

README 的 Impact Levels 一节定义了六个影响等级，用于指导自动化重构时"先做哪条"：

等级与章节的对应关系（摘自 rules/_sections.md）：消除瀑布流与包体积优化被列为CRITICAL，服务端性能为HIGH，客户端取数为MEDIUM-HIGH，重渲染与渲染性能为MEDIUM，JS 微优化为LOW-MEDIUM，进阶模式为LOW。这种分级让 Agent 在面对大型代码库时能够按"收益递减"的顺序逐条套用规则。

八、脚本工作流：四个命令的职责

README 的 Scripts 一节汇总了全部脚本命令：

工作流闭环是：编辑规则 →pnpm dev校验并编译 → 检查生成的AGENTS.md目录与内容 → 提交。由于编号与排序均由构建自动完成，人工审查只需关注规则本身的正确性。

九、贡献指南与维护约定

README 的 Contributing 一节为新增或修改规则列出了六条约定：

1. 为自己的章节使用正确的文件名前缀；
2. 遵循_template.md的结构；
3. 提供清晰的 bad/good 示例并附解释；
4. 添加合适的 tags；
5. 运行pnpm build重新生成AGENTS.md与test-cases.json；
6. 规则按标题自动排序，无需手动管理编号。

Acknowledgments 一节说明该仓库最初由 Vercel 工程师 @shuding 创建，许可证为 MIT（见 SKILL.md frontmatter 中的license: MIT）。

十、代表性规则速览：深入规则库内部

为了让前文的模板结构更有实感，下面从 69 条规则中节选几条典型规则，展示其错误/正确对照的实战写法（均为仓库内真实内容）：

10.1 服务端组件并行取数：server-parallel-fetching（CRITICAL）

React Server Components 在组件树内是串行执行的，若在父组件中先await再渲染子组件，就会形成服务端瀑布流。rules/server-parallel-fetching.md 给出的正确做法是把取数下沉到各自组件内：

async function Header() { const data = await fetchHeader() return <div>{data}</div> } async function Sidebar() { const items = await fetchSidebarItems() return <nav>{items.map(renderItem)}</nav> } export default function Page() { return ( <div> <Header /> <Sidebar /> </div> ) }

Header 与 Sidebar 的取数从此并行发生，而不是 Sidebar 干等 Page 的数据。配套规则 rules/server-parallel-nested-fetching.md 进一步处理嵌套取数：把依赖链getChat → getUser放进每个 item 自己的 Promise 链中，避免单个慢请求阻塞其余 99 条数据。

10.2 包体积：避免 barrel 文件导入bundle-barrel-imports（CRITICAL）

rules/bundle-barrel-imports.md 指出：barrel 文件（如index.js中的export * from './module'）会一次性引入数千个模块，流行的图标/组件库入口可达上万次 re-export，仅 import 一项在部分 React 包上就要消耗 200-800ms，同时拖慢开发与生产冷启动。规则给出的推荐解法是使用 Next.js 的optimizePackageImports在构建期自动改写：

// next.config.js module.exports = { experimental: { optimizePackageImports: ['lucide-react', '@mui/material'] } }

源码保持不变，既保留 TypeScript 类型与编辑器补全，又消除了 barrel import 成本；非 Next.js 项目则改为直接路径导入（如@mui/material/Button），并提醒注意部分库深层导入路径不提供.d.ts的类型警告。

10.3 每请求去重：React.cache()server-cache-react（MEDIUM）

rules/server-cache-react.md 演示了React.cache()对认证、数据库查询等非 fetch 异步操作的单请求去重，并指出一个容易踩的坑：React.cache()用浅比较（Object.is）判定缓存命中，内联对象每次调用都会生成新引用导致永远 miss：

// 错误：每次调用都生成新对象，永远缓存未命中 const getUser = cache(async (params: { uid: number }) => { return await db.user.findUnique({ where: { id: params.uid } }) }) getUser({ uid: 1 }) getUser({ uid: 1 }) // Cache miss, runs query again // 正确：基础类型按值比较，可命中缓存 const getUser = cache(async (uid: number) => { return await db.user.findUnique({ where: { id: uid } }) }) getUser(1) getUser(1) // Cache hit

10.4 重渲染：useDeferredValue保输入响应rerender-use-deferred-value（MEDIUM）

rules/rerender-use-deferred-value.md 处理"输入触发昂贵派生渲染"的场景：用useDeferredValue让结果列表落后于输入，React 优先处理输入更新、空闲时再渲染昂贵结果：

function Search({ items }: { items: Item[] }) { const [query, setQuery] = useState('') const deferredQuery = useDeferredValue(query) const filtered = useMemo( () => items.filter(item => fuzzyMatch(item, deferredQuery)), [items, deferredQuery] ) const isStale = query !== deferredQuery return ( <> <input value={query} onChange={e => setQuery(e.target.value)} /> <div style={{ opacity: isStale ? 0.7 : 1 }}> <ResultsList results={filtered} /> </div> </> ) }

规则特别提示：昂贵计算必须用useMemo包裹并以延迟值为依赖，否则每次渲染仍会执行。同样属于重渲染类别的还有 rules/rerender-lazy-state-init.md（useState(() => expensiveInit())惰性初始化）与 rules/rerender-functional-setstate.md（函数式setState消除陈旧闭包、生成稳定回调）。

10.5 渲染性能：CSScontent-visibilityrendering-content-visibility（HIGH）

rules/rendering-content-visibility.md 针对超长列表，用一行 CSS 让浏览器跳过屏外元素的布局与绘制：

.message-item { content-visibility: auto; contain-intrinsic-size: 0 80px; }

规则给出的量化结论是：对于 1000 条消息，浏览器可跳过约 990 条屏外项的 layout/paint，初始渲染约快 10 倍。

结语：这套规则库如何被 Agent 消费

综合仓库内各文件可以还原出完整的消费链路：Agent 首先读取 SKILL.md 的技能声明与快速索引，判断当前任务（编写/审查/重构 React/Next.js 代码）应触发的规则类别；随后从 rules/ 下读取具体规则文件获取详细代码对照，或直接引用编译后的 AGENTS.md 完整文档；构建时生成的test-cases.json则用于对 LLM 的重构效果做量化评估。而这一切的上游，正是 README 定义的"规则文件 + 模板 + 前缀 + 影响等级 + 自动编号"这套低维护成本的贡献体系——人工只需写好一条条带 frontmatter 的 Markdown 规则，其余编译、排序、编号与测试抽取全部交给pnpm脚本完成。

• 前端
• 教程