2026년 1월 14일, Vercel에서 react-best-practices를 공개했다. 10년 이상의 React와 Next.js 최적화 지식을 구조화된 저장소에 담았으며, AI 에이전트와 LLM에 최적화되어 있다고 한다. 이 시리즈에서는 해당 프로젝트를 하나하나 톺아보려고 한다.

주요 특징

8개 카테고리, 45개의 규칙: 성능 최적화 가이드라인이 체계적으로 분류됨
영향도 기반 우선순위: 각 규칙에 CRITICAL부터 LOW까지 영향도가 매겨져 있음
AI 에이전트 최적화: 자동화된 리팩토링과 코드 생성에 활용 가능

프로젝트 구조

react-best-practices는 vercel-labs/agent-skills 저장소 내의 하위 폴더로 존재한다:

vercel-labs/agent-skills/
└── react-best-practices/
    ├── rules/           # 개별 규칙 파일들 (*.md)
    ├── AGENTS.md        # 컴파일된 최종 출력물 (AI 에이전트가 읽는 파일)
    ├── README.md        # 기여자를 위한 가이드
    ├── SKILL.md         # 스킬 설치 시 복사되는 파일
    └── metadata.json    # 버전, 조직, 설명 등 메타데이터

파일	역할
`rules/`	개별 규칙 파일들이 담긴 폴더. `pnpm build` 시 `AGENTS.md`로 컴파일됨
`AGENTS.md`	모든 규칙이 합쳐진 최종 파일. AI 에이전트가 실제로 참조하는 파일
`README.md`	프로젝트 기여자를 위한 개발 가이드
`SKILL.md`	`npx add-skill` 실행 시 사용자 프로젝트에 복사되는 스킬 정의 파일
`metadata.json`	스킬의 버전, 이름, 설명 등 메타 정보

설치 방법

npx add-skill vercel-labs/agent-skills

프로젝트 내부에서 위 명령어를 실행하면 대화형 인터페이스가 나타나며, 다음을 선택할 수 있다:

어느 에이전트에 적용할 것인지
어떤 스킬을 선택할 것인지
프로젝트 범위 (로컬/글로벌)

설치 경로

설치 시 각 에이전트의 skills 디렉토리에 SKILL.md 파일이 복사된다:

Agent	Project Path	Global Path
Claude Code	`.claude/skills/`	`~/.claude/skills/`
Cursor	`.cursor/skills/`	`~/.cursor/skills/`
Codex	`.codex/skills/`	`~/.codex/skills/`
OpenCode	`.opencode/skill/`	`~/.config/opencode/skill/`

Skills는 설치되면 자동으로 사용 가능해진다. 에이전트가 관련 작업을 감지하면 해당 skill을 활용한다

README 톺아보기

📌 README가 의미하는 것

이 README는 react-best-practices 프로젝트에 기여하려는 개발자를 위한 문서입니다. 일반 사용자와 기여자의 사용 방법이 다르므로 구분해서 이해해야 합니다.

구분	명령어	대상	설명
사용자	`npx add-skill vercel-labs/agent-skills`	스킬을 설치하려는 일반 개발자	프로젝트에 스킬을 추가하여 AI 에이전트가 React 최적화 규칙을 활용하도록 함
기여자	`pnpm install` → `pnpm build`	프로젝트에 기여하려는 개발자	저장소를 클론한 후 로컬에서 규칙을 수정하거나 새로운 규칙을 추가할 때 사용

주요 섹션 해석

Structure: 프로젝트의 디렉토리 구조. rules/ 폴더에 개별 규칙 파일이 있고, pnpm build 실행 시 이들이 AGENTS.md로 컴파일됨
Getting Started: 기여자가 로컬 개발 환경을 설정하는 방법
Creating a New Rule: 새로운 최적화 규칙을 추가하는 방법. prefix로 카테고리를 구분함
Rule File Structure: 규칙 파일의 필수 형식. frontmatter와 Incorrect/Correct 예시 포함 필요
Impact Levels: 규칙의 영향도 수준. CRITICAL부터 LOW까지 우선순위를 표시
Scripts: 빌드, 검증, 테스트 추출 등 개발에 사용되는 npm 스크립트들

아래는 react-best-practices 저장소의 README 번역본입니다.

React Best Practices

agents와 LLM에 최적화된 React Best Practices를 생성하고 유지 관리하기 위한 구조화된 repository입니다.

Structure (구조)

rules/           - 개별 rule 파일들 (rule당 하나의 파일)
  _sections.md   - Section 메타데이터 (titles, impacts, descriptions)
  _template.md   - 새 rule 생성을 위한 템플릿
  area-description.md - 개별 rule 파일들
 
src/             - Build scripts와 유틸리티
metadata.json    - 문서 메타데이터 (version, organization, abstract)
AGENTS.md        - 컴파일된 출력물 (자동 생성)
test-cases.json  - LLM 평가를 위한 테스트 케이스 (자동 생성)

Getting Started (시작하기)

dependencies 설치:

pnpm install

rules로부터 AGENTS.md build:

pnpm build

rule 파일 검증:

pnpm validate

테스트 케이스 추출:

pnpm extract-tests

Creating a New Rule (새 Rule 생성하기)

rules/_template.md를 rules/area-description.md로 복사
적절한 area prefix 선택:

Prefix	Section	설명
`async-`	Section 1	Waterfalls 제거
`bundle-`	Section 2	Bundle Size 최적화
`server-`	Section 3	Server-Side 성능
`client-`	Section 4	Client-Side Data Fetching
`rerender-`	Section 5	Re-render 최적화
`rendering-`	Section 6	Rendering 성능
`js-`	Section 7	JavaScript 성능
`advanced-`	Section 8	Advanced Patterns

frontmatter와 content 작성
설명이 포함된 명확한 examples 작성
pnpm build를 실행하여 AGENTS.md와 test-cases.json 재생성

Rule File Structure (Rule 파일 구조)

각 rule 파일은 다음 구조를 따라야 합니다:

---
title: Rule 제목
impact: MEDIUM
impactDescription: 선택적 설명
tags: tag1, tag2, tag3
---
 
## Rule 제목
 
rule과 그것이 중요한 이유에 대한 간략한 설명.
 
**Incorrect (무엇이 잘못되었는지 설명):**
 
\`\`\`typescript // 나쁜 코드 예시 \`\`\`
 
**Correct (무엇이 올바른지 설명):**
 
\`\`\`typescript // 좋은 코드 예시 \`\`\`
 
examples 이후 선택적 설명 텍스트. Reference: 링크

File Naming Convention (파일 명명 규칙)

_로 시작하는 파일은 특수 파일 (build에서 제외)
Rule 파일: area-description.md (예: async-parallel.md)
Section은 filename prefix로부터 자동 추론
Rules는 각 section 내에서 title 기준 알파벳순 정렬
IDs (예: 1.1, 1.2)는 build 과정에서 자동 생성

Impact Levels (영향도 수준)

Level	설명
`CRITICAL`	최고 우선순위, 주요 성능 향상
`HIGH`	상당한 성능 개선
`MEDIUM-HIGH`	중상위 수준의 개선
`MEDIUM`	중간 수준의 성능 개선
`LOW-MEDIUM`	중하위 수준의 개선
`LOW`	점진적 개선

Scripts

명령어	설명
`pnpm build`	rules를 AGENTS.md로 컴파일
`pnpm validate`	모든 rule 파일 검증
`pnpm extract-tests`	LLM 평가용 테스트 케이스 추출
`pnpm dev`	build와 validate 실행

Contributing (기여하기)

rules를 추가하거나 수정할 때:

section에 맞는 올바른 filename prefix 사용
_template.md 구조 따르기
설명이 포함된 명확한 bad/good examples 포함
적절한 tags 추가
pnpm build를 실행하여 AGENTS.md와 test-cases.json 재생성
Rules는 title 기준으로 자동 정렬됨 - 번호 관리 불필요!