시니어 Next.js / React / TypeScript 엔지니어
Next.js는 빠르게 변화하며 모델 메모리는 종종 오래되었습니다. 버전에 의존하는 API를 사용하기 전에 references/versions.md를 확인하세요. 설치된 next에 번들 문서(node_modules/next/dist/docs/) 또는 Next.js가 생성한 AGENTS.md가 있으면 메모리보다 이를 선호하세요.
0단계: 버전 및 규칙 감지 (항상)
bash scripts/detect_versions.sh를 읽기 전용으로 실행한 후 다음을 확인하세요:
-
package.json+ lockfile (pnpm/npm/yarn/bun) → next, react, typescript, tailwindcss, 테스트 도구; lockfile의 패키지 매니저 사용 -
next.config.*→cacheComponents,partialPrefetching,reactCompiler,experimental.* - 라우터:
app/vssrc/app/,pages/유무 (혼합 라우터),proxy.tsvs 레거시middleware.ts - 데이터 계층: ORM/SDK, 기존
lib/dal.ts또는server-only모듈, 인증 라이브러리 - 스타일링 및 UI 키트 (Tailwind 버전, CSS Modules, shadcn/ui, 디자인 토큰), 린트/포맷 (ESLint flat config vs Biome)
- 테스트: Vitest/Jest, Testing Library, Playwright; 기존 CI 스크립트
기존 규칙을 따르세요. 프로젝트가 오래된 메이저 버전에 있다면 해당 버전에서 동작하는 코드를 작성하세요.
기본값 (결정당 하나, 탈출구 제공)
| 결정 | 기본값 | 대안을 사용할 때 |
|---|---|---|
| 컴포넌트 유형 | 서버 컴포넌트 | 상태, 효과, 브라우저 API 또는 이벤트 핸들러가 필요함 → 가장 작은 리프에 "use client" |
| 캐싱 모델 (16.x) | Cache Components (cacheComponents: true, 'use cache' + cacheLife/cacheTag) | 기존 앱이 이전 모델을 사용 중이며 마이그레이션 계획이 없음. 반만 마이그레이션하지 마세요 |
| 변이(Mutations) | 서버 액션 + revalidateTag/updateTag/refresh | 다른 클라이언트가 사용하는 공개 API → 라우트 핸들러 |
| 데이터 접근 | 모든 읽기/쓰기를 인증하고 권한 부여하는 하나의 server-only 데이터 접근 계층 (DAL) | — |
| 요청 가로채기 | 리디렉션/재작성/헤더만을 위한 proxy.ts | 유일한 확인 수단으로 인증에 절대 사용하지 마세요 |
| 런타임 | Node.js (기본값) | 16.3+에는 없음: runtime = 'edge'는 더 이상 사용되지 않거나 지원되지 않음 |
| 폼 | <form action={serverAction}> + useActionState + 서버 측 스키마 검증 (zod 또는 프로젝트의 것) | 복잡한 클라이언트 전용 마법사 → 프로젝트에 이미 있는 클라이언트 폼 라이브러리 |
| 스타일링 | 프로젝트의 시스템; 새 프로젝트의 경우 Tailwind CSS v4 (CSS-first config) | — |
| 클라이언트 상태 | URL 검색 파라미터 → 서버 상태 → React 상태; 글로벌 스토어는 필요할 때만 | — |
| 메모이제이션 | 활성화된 경우 React Compiler; 그렇지 않으면 측정된 핫스팟만 메모이제이션 | — |
| 테스트 | 단위 테스트: Vitest + Testing Library; E2E 중요 흐름: Playwright | Jest가 이미 설정됨 |
워크플로우 A: 라우트 또는 기능 구축
- [ ] 0단계 완료
- [ ] 라우트 세그먼트: 필요에 따라 page.tsx, layout.tsx, loading.tsx/Suspense 경계, error.tsx, not-found.tsx
- [ ] DAL(server-only)을 통한 데이터, 서버 컴포넌트에서 await; params/searchParams는 Promise: `const { id } = await params`
- [ ] 캐시될 내용 ('use cache' + cacheLife/cacheTag)과 요청 시점 (Suspense 내부) 결정
- [ ] 서버 액션을 통한 변이: 입력 검증, 액션 내에서 권한 재확인, 태그 재검증
- [ ] 클라이언트 컴포넌트는 최소화; props는 직렬화 가능; 클라이언트 번들에 시크릿 없음 (NEXT_PUBLIC_*만 브라우저에 도달)
- [ ] 접근성: 시맨틱 요소, 레이블, 포커스 관리, 키보드 경로, 색상 대비
- [ ] 로직 테스트 + 중요 경로에 대한 E2E 테스트 하나
- [ ] 유효성 검사 루프 통과
유효성 검사 → 수정 → 반복:
pnpm exec tsc --noEmit # 또는 npm/yarn/bun 해당 명령어
pnpm lint # 프로젝트별 ESLint 또는 Biome (next lint는 16에서 제거됨)
pnpm test -- --run # Vitest
pnpm build # Cache Components / prerender 오류 포착
pnpm exec playwright test # E2E가 있을 때
<Suspense> 외부의 캐시되지 않은 데이터에 대한 next build 오류는 신호이지 노이즈가 아닙니다. 'use cache'를 추가하거나, 접근을 Suspense 경계 안으로 옮기거나, 요청 시점으로 표시하여 수정하세요.
워크플로우 B: Next.js 업그레이드 (낮은 자유도)
- [ ] references/versions.md "오래된 패턴" 및 보안 플로어 읽기
- [ ] 깨끗한 트리 커밋; 브랜치 생성
- [ ] 공식 업그레이드 도구 실행: `npx next@canary upgrade --agent=latest`
(에이전트 흐름을 사용할 수 없으면 `npx @next/codemod@canary upgrade latest`)
- [ ] next와 함께 react, react-dom 및 @types/react 업그레이드
- [ ] `runtime = 'edge'` export 제거; middleware.ts → proxy.ts로 이름 변경 (Node 런타임)
- [ ] 유효성 검사 루프; 그런 다음 인증, 리디렉션, 캐싱 및 재검증을 직접 수동 테스트
보안 우선: 설치된 버전이 versions.md의 패치된 플로어보다 낮으면 next 자체를 업그레이드하세요 (React 패키지만 패치하는 것으로는 충분하지 않습니다).
워크플로우 C: 기존 앱에 Cache Components 도입
라우트별로 마이그레이션하세요. 브랜치에서 cacheComponents (+ 16.4+에서는 partialPrefetching)를 활성화하고, next build를 실행한 후 보고된 각 경계를 수정하세요. references/caching.md를 참조하세요. 설치된 경우 Next.js next-cache-components-adoption 스킬이 메커니즘을 자세히 다루므로 이 스킬과 함께 사용하세요.
인증 및 보안 규칙
- DAL과 모든 서버 액션 및 라우트 핸들러에서 권한을 부여하세요. 프록시/미들웨어 확인은 낙관적 리디렉션일 뿐입니다. CVE-2025-29927은 미들웨어의 헤더 기반 우회가 가능함을 보여주었습니다.
- 서버 액션은 공개 HTTP 엔드포인트입니다: 입력을 검증하고, 세션을 확인하고, 소유권을 확인하세요.
- 시크릿이나 DB 접근이 있는 모듈에는
server-only를 import하세요; 클라이언트 컴포넌트에는 DTO(필요한 필드만)를 반환하세요. - 자세한 내용:
references/data-and-auth.md.
디자인 또는 목업에서 구현
- 디자인 인벤토리 작성: 토큰(색상, 서체 척도, 간격, 반경), 컴포넌트, 상태(호버, 포커스, 비활성화, 로딩, 빈 상태, 오류), 중단점.
- 먼저 프로젝트의 기존 토큰과 컴포넌트에 매핑하고, 일회성 값이 아닌 테마에 새 토큰을 추가하세요.
- 먼저 정적 서버 컴포넌트 마크업을 구축한 다음 리프에서 상호작용성을 추가하세요.
- 320px, 태블릿 및 데스크톱 너비에서 확인하세요. 키보드 및 스크린 리더 레이블을 확인하세요.
prefers-reduced-motion을 존중하세요. - 브라우저 도구 또는 Playwright를 사용할 수 있으면 스크린샷을 찍고 목업과 비교하고 간격과 타이포그래피가 일치할 때까지 반복하세요.
리뷰 모드
references/review-checklist.md를 사용하세요. 각 발견 사항을 차단기 / 수정해야 함 / 사소한 으로 파일:줄, 문제 및 구체적인 코드 수정과 함께 보고하세요. 발견 사항을 심각도 순으로 정렬하세요. 차단기에는 프록시에서만 인증, 클라이언트 번들에 시크릿 도달, 검증되지 않은 서버 액션 입력, 취약한 next 버전, 공유 'use cache' 범위 내의 사용자별 데이터가 포함됩니다.
참고 자료 맵
references/versions.md: 버전, 보안 플로어, 오래된 패턴, 확인 노트references/data-and-auth.md: DAL 패턴, 서버 액션 템플릿, 세션 처리references/caching.md: Cache Components 규칙, ensureStatic, navigation()/prefetch()references/review-checklist.md: 영향 기준 순위 규칙