vercel-react-best-practices 리뷰

AI 스킬 설치 순위에서 vercel-react-best-practices가 10위에 올라와 있었습니다. 버셀 엔지니어링이 쓰는 React·Next.js 성능 지침을 스킬로 만든 거라고 적혀 있더군요.

소개에 규칙 70개라는 숫자가 붙어 있었습니다. 솔직히 첫 반응은 "누가 저걸 다 읽나"였어요. 성능 체크리스트는 길수록 안 보게 되니까요.

그런데 이건 사람이 읽으라고 만든 게 아니라 AI에게 읽히려고 만든 물건이었습니다. 그러면 70개라는 길이가 단점이 아닐 수도 있겠다 싶어서, 저장소를 받아 안을 세어봤습니다.

skills.sh 공개 페이지입니다. 설치 명령, 규칙 개요, 적용 범위가 여기 정리돼 있습니다. 캡처는 2026년 8월 26일.

세어보니 진짜 70개였습니다

저장소의 rules/ 폴더에는 파일이 72개 있었습니다. 그중 둘은 규칙이 아니라 _sections.md와 _template.md였어요. 빼면 정확히 70개예요.

전체를 한 파일로 합친 AGENTS.md도 따로 있는데, 108,212자에 ### 제목이 70개였습니다. 두 방식으로 세어도 숫자가 맞더군요.

소개에 적힌 숫자와 파일 개수가 맞는 자료를 오랜만에 봤습니다. 별것 아닌 것 같지만, 문서만 고치고 데이터는 안 늘리거나 그 반대인 경우가 흔하거든요.

중요한 묶음일수록 규칙이 적었습니다

세면서 예상 밖이었던 게 여기입니다.

규칙은 8개 묶음으로 나뉘어 있고 각 묶음에 우선순위가 매겨져 있습니다. 1번이 네트워크 워터폴 제거, 2번이 번들 크기이고 둘 다 CRITICAL입니다.

그런데 그 두 묶음에 든 규칙이 각각 6개씩, 합쳐서 12개뿐이었습니다. 전체의 17%예요. 반대로 규칙이 가장 많은 리렌더링(15개)과 자바스크립트(14개)는 우선순위가 5번과 7번입니다.

위에서 아래로 우선순위 순입니다. 제일 급한 두 줄이 제일 짧습니다.

규칙이 많은 곳이 중요한 곳이 아니라는 뜻입니다. 리렌더링이나 반복문 최적화는 쓸 거리가 많아서 규칙이 많고, 워터폴은 고칠 게 몇 개 없어서 짧습니다. 짧은 쪽이 효과가 커요.

성능 작업을 하다 보면 눈에 보이는 코드부터 손대게 됩니다. 반복문 하나 줄이는 동안 화면 뒤에서는 API 세 개가 차례로 기다리고 있을 수 있고요. 이 문서가 개수와 순서를 분리해 둔 게 그 함정을 피하게 해줍니다.

영향도가 문장이 아니라 필드로 박혀 있습니다

규칙 파일을 하나 열어봤습니다. 맨 위가 이렇게 생겼어요.

---
title: Prevent Waterfall Chains in API Routes
impact: CRITICAL
impactDescription: 2-10× improvement
tags: api-routes, server-actions, waterfalls, parallelization
---

impact가 본문 설명이 아니라 프론트매터 값입니다. 산문으로 "이건 꽤 중요하다"라고 쓰면 읽는 쪽이 해석해야 하는데, 값으로 넣어두면 그냥 거를 수 있습니다.

규칙 70개의 impact를 세어보니 이렇게 나왔어요.

여기서 하나 더 걸렸습니다. 묶음 우선순위로는 CRITICAL이 12개인데, 규칙 단위로 세면 8개입니다. 묶음이 CRITICAL이어도 그 안의 개별 규칙은 아닐 수 있다는 뜻이에요. 축이 두 개인 셈입니다.

본문 구조도 형식이 잡혀 있었습니다. 잘못된 코드 예시 69개, 고친 코드 예시 70개. 거의 모든 규칙이 나쁜 코드와 고친 코드를 짝으로 들고 있습니다. 코드블록만 174개였어요. _template.md라는 서식 파일이 따로 있는 걸 보면 이 형식을 일부러 고정한 것 같습니다.

이 방식이 AI에게 읽히는 자료의 조건에 가까워 보입니다. "성능 좋게 짜줘"라고 한 줄 던지는 것보다, 영향도 값을 주고 나쁜 예와 고친 예를 나란히 주는 편이 결과를 확인하기 쉬우니까요. 다만 이건 제가 파일 구조를 보고 든 생각이고, 문서에 그렇게 적혀 있는 건 아닙니다.

쓰지 말아야 할 때는 거의 안 적혀 있습니다

기대했던 게 하나 더 있었는데 이건 빗나갔습니다.

성능 규칙은 늘 상황을 타거든요. 메모이제이션을 붙이면 대부분 빨라지지만 어떤 코드는 오히려 느려지고요. 그래서 "이럴 땐 쓰지 마라"가 규칙마다 붙어 있을 줄 알았습니다.

전체에서 찾아보니 When NOT 2건, Exception 1건, Trade-off 1건이었습니다. 70개 중 네 군데예요.

수치가 붙은 경우도 많지 않았어요. impactDescription에 2-10× improvement처럼 배수가 적힌 건 다섯 군데였고, 나머지는 등급만 있습니다.

등급으로 순서는 정할 수 있지만 적용을 멈출 지점은 안 나옵니다. AI가 이걸 들고 코드를 고치면 대체로 맞게 고치겠지만, 안 고쳐도 될 곳까지 건드릴 여지가 남아 보입니다. 마지막 확인은 결국 사람이 네트워크 탭에서 해야 할 것 같아요.

카페24에는 그대로 못 옮깁니다

저희가 하는 일은 카페24 스마트디자인 쪽이라 React가 아닙니다. Promise.all이나 동적 임포트 코드를 복사해 붙일 수는 없습니다.

병목을 같은 무게로 보지 않고 순서를 매긴다는 것이 이 자료의 뼈대입니다.

가져올 수 있는 건 의심하는 순서입니다. 상품·재고·추천 API가 서로 결과를 안 쓰는데도 차례로 기다리고 있는지, 첫 화면에 리뷰 위젯이나 관리자용 차트까지 실려 있는지. 이 둘이 규칙 12개짜리 CRITICAL 묶음이 말하는 것이고, 스택과 무관하게 확인할 수 있는 항목입니다.

반대로 리렌더링 15개는 React의 렌더링 모델을 전제로 한 규칙이라 옮길 게 별로 없고요.

직접 붙여봐야 알 것 같은 것

여기까지가 저장소를 받아서 세어보고 파일 몇 개를 열어본 범위입니다. 이 스킬을 실제로 붙여서 코드를 고치게 해보지는 않았습니다.

그래서 이런 건 모릅니다. 70개를 다 들고 있을 때 AI가 우선순위대로 움직이는지, 아니면 눈에 먼저 띄는 규칙부터 적용하는지. 예외 조건이 네 군데뿐인데 안 고쳐도 될 코드를 얼마나 건드리는지. 고친 뒤에 실제로 빨라졌는지를 어떻게 확인시킬지도요.

다음에 React 쪽 화면 작업을 할 일이 생기면 한번 붙여보고 싶습니다. 붙이고 나서 네트워크 탭이 어떻게 달라지는지 보면 위 질문 중 몇 개는 답이 나올 것 같아요.

지금까지 건진 건 규칙 70개가 아니라 앞의 12개가 짧다는 사실입니다.