Shu Ding (소프트웨어 엔지니어)
Andrew Qu (Vercel 소프트웨어 총괄)
2026년 1월 14일
우리는 10년 이상의 React 및 Next.js 최적화 지식을 react-best-practices에 캡슐화했습니다. 이는 AI 에이전트와 LLM(대형 언어 모델)을 위해 최적화된 구조화된 저장소입니다.
React 성능 작업은 대개, 말 그대로 반응적(reactive)입니다. 릴리스가 나가고, 앱이 느려지면, 팀은 증상을 쫓기 시작합니다. 이는 비용이 많이 들며, 엉뚱한 것을 최적화하기 쉽습니다.
우리는 10년 넘게 프로덕션 코드베이스 전반에서 동일한 근본 원인들을 보았습니다:
- 실수로 순차적이 된 비동기 작업
- 시간이 지남에 따라 커지는 대규모 클라이언트 번들
- 필요 이상으로 렌더링되는 컴포넌트
여기서 "이유"는 간단합니다: 이것들은 미시적인 최적화(micro-optimizations)가 아닙니다. 이것들은 대기 시간, 버벅거림, 그리고 모든 사용자 세션에 영향을 미치는 반복적인 비용으로 나타납니다.
그래서 우리는 이러한 문제들을 더 쉽게 발견하고 더 빠르게 수정하기 위해 이 React 모범 사례 프레임워크를 구성했습니다.
핵심 아이디어: 순서 (The core idea: ordering)
대부분의 성능 작업은 스택의 너무 낮은 곳에서 시작하기 때문에 실패합니다.
요청 워터폴(waterfall)이 600ms의 대기 시간을 추가한다면, useMemo 호출이 얼마나 최적화되었는지는 중요하지 않습니다. 모든 페이지에 300KB의 추가 JavaScript를 전송한다면, 루프에서 몇 마이크로초를 줄이는 것은 중요하지 않을 것입니다.
성능 작업은 또한 복리로 작용합니다. 오늘 배포한 작은 회귀(regression)는 누군가가 그 부채를 갚을 때까지 모든 세션에 대한 장기적인 세금이 됩니다.
따라서 프레임워크는 대개 실제 지표를 가장 먼저 움직이는 두 가지 수정 사항으로 시작합니다:
- 워터폴 제거
- 번들 크기 축소
그런 다음 서버 측 성능, 클라이언트 측 가져오기(fetching), 그리고 리렌더링 최적화로 넘어갑니다.
여기에는 8개 카테고리에 걸친 40개 이상의 규칙이 포함되어 있으며, 영향도에 따라 치명적(CRITICAL - 워터폴 제거, 번들 크기 축소)인 것부터 점진적(incremental - 고급 패턴)인 것까지 순서가 매겨져 있습니다.
그 외 내용물은? (What else is inside?)
이 저장소는 8가지 성능 카테고리를 다룹니다:
- 비동기 워터폴 제거
- 번들 크기 최적화
- 서버 측 성능
- 클라이언트 측 데이터 가져오기
- 리렌더링 최적화
- 렌더링 성능
- 고급 패턴
- JavaScript 성능
각 규칙에는 수정의 우선순위를 정하는 데 도움을 주기 위한 영향도 등급(CRITICAL에서 LOW까지)과, 무엇이 문제이고 어떻게 고치는지 보여주는 코드 예제가 포함되어 있습니다.
예를 들어, 다음은 사용되지 않는 코드를 차단하는 일반적인 패턴입니다:
잘못된 예 (두 분기 모두 차단):
올바른 예 (필요할 때만 차단):
개별 규칙 파일들은 AGENTS.md라는 단일 문서로 컴파일되며, 이는 당신의 에이전트가 코드를 검토하거나 최적화를 제안할 때 쿼리할 수 있는 문서입니다. 이는 리팩토링을 수행하는 AI 에이전트를 포함하여 일관되게 따라 할 수 있도록 설계되었으므로, 팀은 대규모 코드베이스 전체에 걸쳐 동일한 결정을 적용할 수 있습니다.
이 모범 사례들이 수집된 방법 (How these practices were collected)
이것들은 이론적인 것이 아닙니다. 이것들은 프로덕션 코드베이스에서의 실제 성능 작업에서 나온 것입니다.
몇 가지 예시입니다:
- 루프 반복 결합하기: 한 채팅 페이지가 동일한 메시지 목록을 여덟 번이나 따로 스캔하고 있었습니다. 우리는 이를 한 번의 패스로 결합했고, 이는 수천 개의 메시지가 있을 때 합산되어 효과가 큽니다.
- Awaits 병렬화하기: 한 API가 다음 데이터베이스 호출을 시작하기 전에 이전 호출이 끝나기를 기다리고 있었는데, 서로 의존하지 않음에도 그랬습니다. 이것들을 동시에 실행함으로써 전체 대기 시간을 절반으로 줄였습니다.
- 폰트 폴백(fallbacks) 조정하기: 커스텀 폰트가 로드되기 전에 시스템 폰트를 사용할 때 헤드라인이 비좁아 보였습니다. 자간(letter-spacing)을 조정하여 폴백이 깨져 보이는 대신 의도된 것처럼 보이게 만들었습니다.
당신의 코딩 에이전트에서 react-best-practices 사용하기 (Using react-best-practices in your coding agent)
이 모범 사례들은 또한 Opencode, Codex, Claude Code, Cursor 및 기타 코딩 에이전트에 설치되는 '에이전트 스킬(Agent Skills)'로도 패키징되어 있습니다. 당신의 에이전트가 연쇄적인 useEffect 호출이나 무거운 클라이언트 측 import를 발견하면, 이 패턴들을 참조하여 수정 사항을 제안할 수 있습니다.
react-best-practices 저장소를 확인해 보세요.
