@kood/claude-code 0.4.1 → 0.5.0

package/templates/.claude/skills/nextjs-react-best-practices/AGENTS.md

@@ -1,44 +1,23 @@
-# Next.js React Best Practices
+# Next.js React 베스트 프랙티스
 
 **Version 1.0.0**
 Vercel Engineering
 January 2026
 
-> **Note:**
-> 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.
+> **참고:**
+> 이 문서는 주로 에이전트와 LLM이 React 및 Next.js 코드베이스를 유지보수, 생성, 리팩토링할 때 따르기 위한 것입니다. 사람도 유용하게 사용할 수 있지만, AI 지원 워크플로의 자동화 및 일관성을 위해 최적화되어 있습니다.
 
 ---
 
-<communication>
+## 요약
 
-## User Communication Protocol
-
-**CRITICAL: Always communicate with the user in Korean (한국어).**
-
-This applies to:
-- Questions and clarifications
-- Progress updates and summaries
-- Explaining decisions and trade-offs
-- Reporting errors or blockers
-
-Internal processing and code comments remain in English. Only user-facing messages must be in Korean.
-
-</communication>
-
----
-
-## Abstract
-
-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). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+AI 에이전트와 LLM을 위한 React 및 Next.js 애플리케이션 종합 성능 최적화 가이드. 8개 카테고리에 걸쳐 40개 이상의 규칙을 포함하며, 영향도별로 우선순위를 매겼습니다 (critical: waterfall 제거, 번들 크기 감소 → incremental: 고급 패턴). 각 규칙은 자동 리팩토링 및 코드 생성을 위한 상세한 설명, 올바른 구현 대 잘못된 구현을 비교하는 실제 예시, 구체적인 영향 지표를 포함합니다.
 
 ---
 
 <instructions>
 
-## Document Usage Instructions
+## 문서 사용 지침
 
 @rules/async-defer-await.md
 @rules/async-parallel.md
@@ -92,18 +71,18 @@ Comprehensive performance optimization guide for React and Next.js applications,
 
 <categories>
 
-## Categories by Priority
+## 카테고리별 우선순위
 
-| Priority | Category | Impact | Description |
-|----------|----------|--------|-------------|
-| 1 | Eliminating Waterfalls | **CRITICAL** | Convert sequential awaits to parallel. Biggest gains |
-| 2 | Bundle Size Optimization | **CRITICAL** | Improve TTI and LCP. Faster initial loads |
-| 3 | Server-Side Performance | HIGH | Eliminate server-side waterfalls, reduce response times |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH | Automatic deduplication, efficient data fetching |
-| 5 | Re-render Optimization | MEDIUM | Minimize unnecessary re-renders, improve UI responsiveness |
-| 6 | Rendering Performance | MEDIUM | Optimize browser rendering work |
-| 7 | JavaScript Performance | LOW-MEDIUM | Hot path micro-optimizations |
-| 8 | Advanced Patterns | LOW | Advanced implementation patterns for specific cases |
+| 우선순위 | 카테고리 | 영향도 | 설명 |
+|---------|---------|--------|------|
+| 1 | Waterfall 제거 | **CRITICAL** | 순차 await를 병렬로 전환. 가장 큰 성능 향상 제공 |
+| 2 | 번들 크기 최적화 | **CRITICAL** | TTI와 LCP 개선. 초기 로딩 속도 향상 |
+| 3 | 서버 사이드 성능 | HIGH | 서버 사이드 waterfall 제거, 응답 시간 단축 |
+| 4 | 클라이언트 데이터 페칭 | MEDIUM-HIGH | 자동 중복 제거, 효율적 데이터 페칭 |
+| 5 | Re-render 최적화 | MEDIUM | 불필요한 re-render 최소화, UI 반응성 향상 |
+| 6 | 렌더링 성능 | MEDIUM | 브라우저 렌더링 작업 최적화 |
+| 7 | JavaScript 성능 | LOW-MEDIUM | Hot path 마이크로 최적화 |
+| 8 | 고급 패턴 | LOW | 특정 케이스용 고급 구현 패턴 |
 
 </categories>
 
@@ -111,19 +90,19 @@ Comprehensive performance optimization guide for React and Next.js applications,
 
 <critical_patterns>
 
-## 1. Eliminating Waterfalls (CRITICAL)
+## 1. Waterfall 제거 (CRITICAL)
 
-Waterfalls are the #1 performance killer. Each sequential await adds full network latency.
+Waterfall은 가장 큰 성능 저해 요소입니다. 순차 await는 전체 네트워크 지연을 추가합니다.
 
-### Parallel Execution
+### 병렬 실행
 
 ```typescript
-// ❌ Sequential execution (3 round trips)
+// ❌ 순차 실행 (3번 왕복)
 const user = await fetchUser()
 const posts = await fetchPosts()
 const comments = await fetchComments()
 
-// ✅ Parallel execution (1 round trip)
+// ✅ 병렬 실행 (1번 왕복)
 const [user, posts, comments] = await Promise.all([
   fetchUser(),
   fetchPosts(),
@@ -131,17 +110,17 @@ const [user, posts, comments] = await Promise.all([
 ])
 ```
 
-### Dependency-Based Parallelization
+### 의존성 기반 병렬화
 
 ```typescript
-// ❌ profile waits for config unnecessarily
+// ❌ profile이 config을 불필요하게 대기
 const [user, config] = await Promise.all([
   fetchUser(),
   fetchConfig()
 ])
 const profile = await fetchProfile(user.id)
 
-// ✅ config and profile run in parallel with better-all
+// ✅ better-all로 최대 병렬화
 import { all } from 'better-all'
 
 const { user, config, profile } = await all({
@@ -153,10 +132,10 @@ const { user, config, profile } = await all({
 })
 ```
 
-### Suspense Boundaries
+### Suspense 경계
 
 ```tsx
-// ❌ Entire layout blocked by data fetching
+// ❌ 전체 레이아웃이 데이터 대기
 async function Page() {
   const data = await fetchData()
   return (
@@ -169,7 +148,7 @@ async function Page() {
   )
 }
 
-// ✅ Wrapper shows immediately, data streams in
+// ✅ 래퍼는 즉시 표시, 데이터는 스트리밍
 function Page() {
   return (
     <div>
@@ -195,20 +174,20 @@ async function DataDisplay() {
 
 <bundle_optimization>
 
-## 2. Bundle Size Optimization (CRITICAL)
+## 2. 번들 크기 최적화 (CRITICAL)
 
-### Avoid Barrel File Imports
+### Barrel Import 회피
 
 ```tsx
-// ❌ Import entire library (1583 modules, ~2.8s)
+// ❌ 전체 라이브러리 import (1583개 모듈, ~2.8초)
 import { Check, X, Menu } from 'lucide-react'
 
-// ✅ Direct imports (3 modules only)
+// ✅ 직접 import (3개 모듈만)
 import Check from 'lucide-react/dist/esm/icons/check'
 import X from 'lucide-react/dist/esm/icons/x'
 import Menu from 'lucide-react/dist/esm/icons/menu'
 
-// ✅ Next.js 13.5+ auto-optimization
+// ✅ Next.js 13.5+ 자동 최적화
 // next.config.js
 module.exports = {
   experimental: {
@@ -217,19 +196,19 @@ module.exports = {
 }
 ```
 
-Affected libraries: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`
+영향 받는 라이브러리: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`
 
-### Dynamic Imports
+### Dynamic Import
 
 ```tsx
-// ❌ Monaco bundled with main chunk (~300KB)
+// ❌ Monaco가 메인 청크에 포함 (~300KB)
 import { MonacoEditor } from './monaco-editor'
 
 function CodePanel({ code }: { code: string }) {
   return <MonacoEditor value={code} />
 }
 
-// ✅ Monaco loads on demand
+// ✅ Monaco는 필요시 로드
 import dynamic from 'next/dynamic'
 
 const MonacoEditor = dynamic(
@@ -248,9 +227,9 @@ function CodePanel({ code }: { code: string }) {
 
 <server_performance>
 
-## 3. Server-Side Performance (HIGH)
+## 3. 서버 사이드 성능 (HIGH)
 
-### React.cache() - Per-Request Deduplication
+### React.cache() - 요청별 중복 제거
 
 ```typescript
 import { cache } from 'react'
@@ -261,17 +240,17 @@ export const getCurrentUser = cache(async () => {
   return await db.user.findUnique({ where: { id: session.user.id } })
 })
 
-// Within single request, multiple calls execute query only once
+// 단일 요청 내에서 여러 번 호출해도 쿼리는 1번만 실행
 ```
 
-### LRU Cache - Cross-Request Caching
+### LRU 캐시 - 요청 간 캐싱
 
 ```typescript
 import { LRUCache } from 'lru-cache'
 
 const cache = new LRUCache<string, any>({
   max: 1000,
-  ttl: 5 * 60 * 1000  // 5 minutes
+  ttl: 5 * 60 * 1000  // 5분
 })
 
 export async function getUser(id: string) {
@@ -283,25 +262,25 @@ export async function getUser(id: string) {
   return user
 }
 
-// Request 1: DB query, result cached
-// Request 2: cache hit, no DB query
+// 요청 1: DB 쿼리, 결과 캐싱
+// 요청 2: 캐시 히트, DB 쿼리 없음
 ```
 
-### Minimize Serialization at RSC Boundaries
+### RSC 경계에서 직렬화 최소화
 
 ```tsx
-// ❌ Serializes all 50 fields
+// ❌ 50개 필드 모두 직렬화
 async function Page() {
-  const user = await fetchUser()  // 50 fields
+  const user = await fetchUser()  // 50개 필드
   return <Profile user={user} />
 }
 
 'use client'
 function Profile({ user }: { user: User }) {
-  return <div>{user.name}</div>  // uses 1 field
+  return <div>{user.name}</div>  // 1개 필드만 사용
 }
 
-// ✅ Serializes only 1 field
+// ✅ 1개 필드만 직렬화
 async function Page() {
   const user = await fetchUser()
   return <Profile name={user.name} />
@@ -313,7 +292,7 @@ function Profile({ name }: { name: string }) {
 }
 ```
 
-### after() for Non-Blocking Operations
+### after()로 비차단 작업
 
 ```tsx
 import { after } from 'next/server'
@@ -321,7 +300,7 @@ import { after } from 'next/server'
 export async function POST(request: Request) {
   await updateDatabase(request)
 
-  // Log after response is sent
+  // 응답 전송 후 로깅
   after(async () => {
     const userAgent = (await headers()).get('user-agent') || 'unknown'
     logUserAction({ userAgent })
@@ -340,14 +319,14 @@ export async function POST(request: Request) {
 
 <client_data_fetching>
 
-## 4. Client-Side Data Fetching (MEDIUM-HIGH)
+## 4. 클라이언트 데이터 페칭 (MEDIUM-HIGH)
 
-### SWR for Automatic Deduplication
+### SWR로 자동 중복 제거
 
 ```tsx
 import useSWR from 'swr'
 
-// ❌ No deduplication, each instance fetches
+// ❌ 중복 제거 없음, 각 인스턴스가 fetch
 function UserList() {
   const [users, setUsers] = useState([])
   useEffect(() => {
@@ -357,7 +336,7 @@ function UserList() {
   }, [])
 }
 
-// ✅ Multiple instances share one request
+// ✅ 여러 인스턴스가 하나의 요청 공유
 function UserList() {
   const { data: users } = useSWR('/api/users', fetcher)
 }
@@ -369,57 +348,57 @@ function UserList() {
 
 <rerender_optimization>
 
-## 5. Re-render Optimization (MEDIUM)
+## 5. Re-render 최적화 (MEDIUM)
 
-### Functional setState
+### 함수형 setState
 
 ```tsx
-// ❌ items as dependency, recreated every time
+// ❌ items가 의존성, 매번 재생성
 function TodoList() {
   const [items, setItems] = useState(initialItems)
 
   const addItems = useCallback((newItems: Item[]) => {
     setItems([...items, ...newItems])
-  }, [items])  // Recreated on items change
+  }, [items])  // items 변경마다 재생성
 }
 
-// ✅ Stable callback, never recreated
+// ✅ 안정적 콜백, 재생성 없음
 function TodoList() {
   const [items, setItems] = useState(initialItems)
 
   const addItems = useCallback((newItems: Item[]) => {
     setItems(curr => [...curr, ...newItems])
-  }, [])  // No dependencies, always uses latest state
+  }, [])  // 의존성 없음, 항상 최신 상태 사용
 }
 ```
 
-### Lazy State Initialization
+### Lazy 상태 초기화
 
 ```tsx
-// ❌ Runs on every render
+// ❌ 매 렌더마다 실행
 function FilteredList({ items }: { items: Item[] }) {
   const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
   const [query, setQuery] = useState('')
 }
 
-// ✅ Runs only on initial render
+// ✅ 초기 렌더 시에만 실행
 function FilteredList({ items }: { items: Item[] }) {
   const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
   const [query, setQuery] = useState('')
 }
 ```
 
-### Subscribe to Derived State
+### 파생 상태 구독
 
 ```tsx
-// ❌ Re-renders on every pixel change
+// ❌ 픽셀 변경마다 re-render
 function Sidebar() {
-  const width = useWindowWidth()  // continuous updates
+  const width = useWindowWidth()  // 연속 업데이트
   const isMobile = width < 768
   return <nav className={isMobile ? 'mobile' : 'desktop'}>
 }
 
-// ✅ Re-renders only when boolean changes
+// ✅ boolean 변경 시에만 re-render
 function Sidebar() {
   const isMobile = useMediaQuery('(max-width: 767px)')
   return <nav className={isMobile ? 'mobile' : 'desktop'}>
@@ -432,12 +411,12 @@ function Sidebar() {
 
 <rendering_performance>
 
-## 6. Rendering Performance (MEDIUM)
+## 6. 렌더링 성능 (MEDIUM)
 
-### Animate SVG Wrapper
+### SVG 래퍼 애니메이션
 
 ```tsx
-// ❌ Animating SVG directly - no hardware acceleration
+// ❌ SVG 직접 애니메이션 - 하드웨어 가속 없음
 function LoadingSpinner() {
   return (
     <svg className="animate-spin" width="24" height="24">
@@ -446,7 +425,7 @@ function LoadingSpinner() {
   )
 }
 
-// ✅ Animating wrapper div - hardware accelerated
+// ✅ 래퍼 div 애니메이션 - 하드웨어 가속
 function LoadingSpinner() {
   return (
     <div className="animate-spin">
@@ -461,7 +440,7 @@ function LoadingSpinner() {
 ### content-visibility
 
 ```css
-/* Long list optimization */
+/* 긴 리스트 최적화 */
 .message-item {
   content-visibility: auto;
   contain-intrinsic-size: 0 80px;
@@ -483,30 +462,30 @@ function MessageList({ messages }: { messages: Message[] }) {
 }
 ```
 
-For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render)
+1000개 메시지 기준, 브라우저가 ~990개 오프스크린 항목의 레이아웃/페인트 스킵 (초기 렌더 10배 빠름)
 
-### Prevent Hydration Mismatch
+### Hydration 불일치 방지
 
 ```tsx
-// ❌ SSR failure
+// ❌ SSR 실패
 function ThemeWrapper({ children }: { children: ReactNode }) {
-  const theme = localStorage.getItem('theme') || 'light'  // localStorage undefined on server
+  const theme = localStorage.getItem('theme') || 'light'  // localStorage는 서버에서 undefined
   return <div className={theme}>{children}</div>
 }
 
-// ❌ Flickering
+// ❌ 깜빡임
 function ThemeWrapper({ children }: { children: ReactNode }) {
   const [theme, setTheme] = useState('light')
 
   useEffect(() => {
     const stored = localStorage.getItem('theme')
-    if (stored) setTheme(stored)  // Runs after hydration → flicker
+    if (stored) setTheme(stored)  // hydration 후 실행 → 깜빡임
   }, [])
 
   return <div className={theme}>{children}</div>
 }
 
-// ✅ No flicker, no hydration mismatch
+// ✅ 깜빡임 없음, hydration 불일치 없음
 function ThemeWrapper({ children }: { children: ReactNode }) {
   return (
     <>
@@ -535,9 +514,9 @@ function ThemeWrapper({ children }: { children: ReactNode }) {
 
 <javascript_performance>
 
-## 7. JavaScript Performance (LOW-MEDIUM)
+## 7. JavaScript 성능 (LOW-MEDIUM)
 
-### Build Index Maps for Repeated Lookups
+### 반복 조회용 Map
 
 ```typescript
 // ❌ O(n) per lookup
@@ -560,15 +539,15 @@ function processOrders(orders: Order[], users: User[]) {
 
 1000 orders × 1000 users: 1M ops → 2K ops
 
-### Early Length Check for Array Comparisons
+### 배열 비교 시 길이 체크
 
 ```typescript
-// ❌ Always runs expensive comparison
+// ❌ 항상 비싼 비교 실행
 function hasChanges(current: string[], original: string[]) {
   return current.sort().join() !== original.sort().join()
 }
 
-// ✅ O(1) length check first
+// ✅ O(1) 길이 체크 먼저
 function hasChanges(current: string[], original: string[]) {
   if (current.length !== original.length) return true
 
@@ -581,10 +560,10 @@ function hasChanges(current: string[], original: string[]) {
 }
 ```
 
-### Use toSorted() for Immutability
+### toSorted()로 불변성 유지
 
 ```typescript
-// ❌ Mutates original array
+// ❌ 원본 배열 변경
 function UserList({ users }: { users: User[] }) {
   const sorted = useMemo(
     () => users.sort((a, b) => a.name.localeCompare(b.name)),
@@ -592,7 +571,7 @@ function UserList({ users }: { users: User[] }) {
   )
 }
 
-// ✅ Creates new array
+// ✅ 새 배열 생성
 function UserList({ users }: { users: User[] }) {
   const sorted = useMemo(
     () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
@@ -607,9 +586,9 @@ function UserList({ users }: { users: User[] }) {
 
 <advanced_patterns>
 
-## 8. Advanced Patterns (LOW)
+## 8. 고급 패턴 (LOW)
 
-### useLatest for Stable Callback Refs
+### useLatest로 안정적 콜백
 
 ```typescript
 function useLatest<T>(value: T) {
@@ -622,7 +601,7 @@ function useLatest<T>(value: T) {
 ```
 
 ```tsx
-// ❌ Effect re-runs on every callback change
+// ❌ effect가 콜백 변경마다 재실행
 function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
   const [query, setQuery] = useState('')
 
@@ -632,7 +611,7 @@ function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
   }, [query, onSearch])
 }
 
-// ✅ Stable effect, fresh callback
+// ✅ 안정적 effect, 최신 콜백
 function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
   const [query, setQuery] = useState('')
   const onSearchRef = useLatest(onSearch)
@@ -650,14 +629,14 @@ function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
 
 <references>
 
-## References
+## 참고 자료
 
 1. [React](https://react.dev)
 2. [Next.js](https://nextjs.org)
 3. [SWR](https://swr.vercel.app)
 4. [better-all](https://github.com/shuding/better-all)
 5. [node-lru-cache](https://github.com/isaacs/node-lru-cache)
-6. [Next.js Package Import Optimization](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
-7. [Vercel Dashboard Twice as Fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+6. [Next.js Package Import 최적화](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [Vercel Dashboard 2배 빠르게](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
 
 </references>