React로 앱을 만들다 보면 이런 상황을 마주칩니다. 컴포넌트는 잘 동작하는데 어딘가 느립니다. Lighthouse 점수는 낮고, 처음 페이지가 뜨는 데 오래 걸립니다. Claude Code에 “성능 최적화해줘”라고 해봐도 돌아오는 답변은 항상 비슷합니다. React.memo 써라, useCallback 써라 — 알고는 있지만 이 코드에 정확히 어떻게 적용해야 하는지는 여전히 막막합니다.

문제는 AI 에이전트가 React 성능 최적화 원칙을 모르는 게 아닙니다. Vercel 수준의 체계화된 우선순위 기준이 없어서입니다. 워터폴 제거가 번들 최적화보다 먼저인지, server-cache-react와 server-cache-lru 중 어느 상황에 무엇을 써야 하는지 — 이런 판단 기준이 없으면 에이전트도 일반론만 이야기합니다.

vercel-react-best-practices 스킬은 이 간극을 메웁니다. Vercel이 실제 프로덕션 경험을 바탕으로 정리한 69개 규칙을 에이전트에 직접 주입해서, 코드를 짤 때마다 자동으로 이 기준이 적용되도록 합니다.

vercel-react-best-practices란?

vercel-react-best-practices는 Vercel Labs가 공식 배포한 React·Next.js 성능 최적화 스킬입니다. 2026년 1월 19일 처음 등록된 이후 현재 주간 설치 수 295,500회, GitHub Stars 24,700개를 기록하고 있습니다.

스킬 하나에 69개 규칙이 담겨 있습니다. 규칙마다 왜 중요한지, 잘못된 예시, 올바른 예시가 함께 포함되어 있어서 에이전트가 단순히 규칙 이름만 아는 게 아니라 실제 코드에 어떻게 적용해야 하는지까지 이해합니다.

69개 규칙, 8개 카테고리

Vercel은 규칙들을 임팩트 순서대로 정리했습니다. 우선순위가 높은 것부터 먼저 적용하도록 설계되어 있습니다.

우선순위	카테고리	임팩트	규칙 접두어
1	워터폴 제거	CRITICAL	async-
2	번들 크기 최적화	CRITICAL	bundle-
3	서버 사이드 성능	HIGH	server-
4	클라이언트 데이터 페칭	MEDIUM-HIGH	client-
5	리렌더링 최적화	MEDIUM	rerender-
6	렌더링 성능	MEDIUM	rendering-
7	자바스크립트 성능	LOW-MEDIUM	js-
8	고급 패턴	LOW	advanced-

워터폴과 번들이 CRITICAL로 분류된 이유는 사용자가 체감하는 로딩 속도에 직접 영향을 주기 때문입니다. 리렌더링 최적화는 중요하지만 워터폴보다는 나중에 챙겨야 합니다.

이 스킬이 해결하는 문제

에이전트가 규칙 코드(async-parallel, bundle-barrel-imports)를 구체적으로 언급하기 때문에 어떤 기준을 적용했는지 추적할 수 있습니다.

설치 방법

터미널을 열고 아래 명령어를 실행합니다. 프로젝트 폴더 위치와 무관하게 어디서든 실행할 수 있습니다.

# Claude Code에 전역 설치 (모든 프로젝트에서 사용 가능)
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -g -a claude-code

# 현재 프로젝트에만 설치
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -a claude-code

-g 옵션은 “글로벌(global)“의 약자로, 한 번 설치하면 이후 모든 프로젝트에서 자동으로 이 스킬이 활성화됩니다. React·Next.js 프로젝트를 여러 개 운영하고 있다면 -g를 붙이는 편이 편합니다.

다른 에이전트를 사용하신다면:

# Cursor에 설치
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -a cursor

# Codex(OpenAI)에 설치
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -a codex

# Gemini CLI에 설치
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -a gemini-cli

실전 데모: 이렇게 써보세요

설치 후 Claude Code에서 React 컴포넌트를 작성하거나 리뷰를 요청하면 됩니다. 별도 명령어가 필요 없습니다. 에이전트가 알아서 규칙을 참조합니다.

예시 1: 데이터 페칭 코드 리뷰

"이 컴포넌트 성능 문제 있으면 알려줘"

// 이런 코드를 붙여넣으면
async function Dashboard() {
  const user = await fetchUser();
  const posts = await fetchPosts();
  const stats = await fetchStats();
  return <div>...</div>;
}

에이전트 응답:

async-parallel 규칙: fetchUser, fetchPosts, fetchStats가 순차적으로
실행되고 있습니다. 세 요청은 서로 독립적이므로 동시에 실행할 수 있습니다.

수정 방법:
const [user, posts, stats] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchStats()
]);

이 변경만으로 세 요청 중 가장 느린 하나의 시간만 기다리게 됩니다.
세 요청이 각각 200ms라면 기존 600ms → 200ms로 단축됩니다.

예시 2: 새 컴포넌트 작성

"상품 목록 컴포넌트 만들어줘. 상품이 100개 이상일 수 있어"

에이전트가 자동으로 적용하는 규칙들:

• rendering-content-visibility: 뷰포트 밖 아이템에 content-visibility: auto 적용
• bundle-dynamic-imports: 상세 모달처럼 무거운 컴포넌트는 next/dynamic으로 지연 로드
• rerender-memo: 리스트 아이템 컴포넌트를 메모이제이션

// 스킬이 없을 때 — 기본 구현
export function ProductList({ products }) {
  return (
    <div>
      {products.map(p => <ProductCard key={p.id} product={p} />)}
    </div>
  );
}

// 스킬이 있을 때 — 규칙 적용 버전
const ProductDetail = dynamic(() => import('./ProductDetail'), { ssr: false });

const ProductCard = memo(function ProductCard({ product }) {
  return <div style={{ contentVisibility: 'auto' }}>...</div>;
});

export function ProductList({ products }) {
  return (
    <div>
      {products.map(p => <ProductCard key={p.id} product={p} />)}
    </div>
  );
}

내부 동작 원리

이 스킬이 설치되면 에이전트의 컨텍스트에 69개 규칙이 주입됩니다. 각 규칙은 별도 파일(rules/async-parallel.md 등)로 관리되며, 에이전트가 코드를 분석할 때 해당 규칙들을 참조 기준으로 삼습니다.

규칙 파일 하나의 구조는 이렇습니다:

rules/async-parallel.md
├── 왜 중요한지 (원인 설명)
├── 잘못된 코드 예시 + 무엇이 문제인지
├── 올바른 코드 예시 + 왜 좋은지
└── 추가 컨텍스트와 참고 자료

에이전트가 규칙 이름(async-parallel)을 명시적으로 언급하는 이유도 여기 있습니다. 내가 무슨 기준으로 피드백하는지 추적 가능하게 설계된 것입니다.

스킬이 사용하는 도구

이 스킬은 별도 외부 API나 도구를 호출하지 않습니다. 규칙 텍스트를 에이전트 컨텍스트에 주입하는 것이 전부입니다. 따라서 인터넷 연결이 없어도 설치 후에는 오프라인에서 동작합니다.

이럴 때 쓰세요 / 이럴 때는 안 맞아요

잘 맞는 상황	덜 맞는 상황
React·Next.js 컴포넌트를 새로 작성할 때	Vue, Svelte, Angular 프로젝트
기존 코드 성능 리뷰를 요청할 때	백엔드 API 서버만 작업할 때
번들 크기가 너무 크다는 피드백을 받았을 때	이미 최적화가 잘 된 성숙한 프로젝트
리팩토링 방향을 잡고 싶을 때	성능보다 빠른 기능 구현이 우선일 때
Next.js App Router로 마이그레이션할 때	React Native 앱 (웹 최적화 규칙 일부 미적용)

Vercel Labs의 다른 스킬들

vercel-labs/agent-skills 레포에는 React 외에도 여러 스킬이 있습니다.

# 전체 목록 확인
npx skills add vercel-labs/agent-skills --list

주요 스킬들:

• web-design-guidelines — 접근성, 레이아웃, 타이포그래피 등 웹 디자인 체크리스트
• deploy-to-vercel — Vercel 배포 설정 자동화 가이드
• vercel-react-best-practices — 지금 이 스킬

같은 레포의 스킬을 한 번에 설치하려면:

npx skills add vercel-labs/agent-skills

자주 묻는 질문 (FAQ)

Q1: vercel-react-best-practices 스킬은 유료인가요?

npx skills add로 설치되는 스킬 자체는 GitHub에 공개된 텍스트 파일입니다. 완전 무료입니다. 이 스킬은 외부 API를 호출하지 않으므로 추가 비용이 발생하지 않습니다.

Q2: Next.js가 아닌 React 프로젝트에도 쓸 수 있나요?

네. 69개 규칙 중 일부는 Next.js 전용(server-cache-react, server-after-nonblocking 등)이지만, 워터폴 제거·번들 최적화·리렌더링 최적화 규칙들은 Create React App이나 Vite 기반 프로젝트에서도 동일하게 적용됩니다.

Q3: 스킬 설치 후 에이전트를 재시작해야 하나요?

Claude Code 기준으로, 설치 후 새 세션을 시작하면 자동 적용됩니다. 현재 열린 세션에 즉시 적용하려면 /reload 명령을 실행합니다. Cursor는 IDE를 재시작하면 됩니다.

Q4: 69개 규칙을 다 외워야 하나요?

전혀 아닙니다. 스킬을 설치하면 에이전트가 규칙을 참조하기 때문에 사용자가 기억할 필요가 없습니다. 에이전트가 규칙 이름을 언급하면 그때 해당 규칙이 무엇인지 물어보면 됩니다.

---