code-level-review

code-level-review

Next.js + React 코드를 시니어 기준으로 작성하고, 기존 코드의 레벨을 진단한다. 기술 스택: Next.js 16 + React 19.2 + TypeScript + Zustand + React Query v5 + Axios

---

진행 상황 추적

실행 시작 시 아래 항목을 TaskCreate로 등록한다. 각 단계 시작 시 in_progress, 완료 시 completed로 TaskUpdate한다.

• 코드 탐색
• 레벨 진단
• 리포트 생성

---

두 가지 모드

모드 A: 코드 작성

사용자가 코드 작성을 요청하면 시니어 기준 패턴을 적용한다.

시니어 패턴 우선순위:

1. 서버 컴포넌트 우선 — 'use client'는 꼭 필요한 곳에만
2. use cache + cacheTag — 서버 컴포넌트 캐싱
3. useOptimistic — 즉각적 UI 피드백
4. Result 타입 — { ok: true, data } | { ok: false, error }
5. server-only — 서버 전용 모듈 보호
6. 인증 + 소유권 이중 검증 — Server Action 내부
7. queryOptions API — React Query v5 타입 안전 패턴
8. lib/axios.ts 인스턴스 — 인터셉터 포함

참조: references/code-examples.md (레벨별 대조 예제)

FF 설계 원칙 점검 (코드 작성 시):

• 예측 가능성: 커스텀 모듈이 외부 라이브러리와 이름 겹치지 않는가?
• 예측 가능성: 같은 카테고리 Hook의 반환 타입이 통일되어 있는가?
• 결합도: Props Drilling 3단계+ 시 조합 패턴을 먼저 검토했는가?
• 결합도: 공통화 대상이 "앞으로도 동일하게 변경될 것"이 확실한가?

TypeScript 심화 패턴 적용 시 추가 참조:

• Brand Types, Conditional/Mapped Types, satisfies 등 → ../../rules/references/typescript/ts-type-patterns.md 읽기
• ref prop, ComponentProps, Next.js 15 params 타입 → ../../rules/references/typescript/ts-react-nextjs.md 읽기
• Result 타입, 에러 유니온, never 체크 → ../../rules/references/typescript/ts-error-handling.md 읽기
• tsconfig, 스택 조합 → ../../rules/references/typescript/ts-tooling-and-stack.md 읽기

---

모드 B: 코드 리뷰 (레벨 진단)

사용자가 코드를 보여주며 리뷰를 요청하면:

1. 레벨 판별 — 루브릭 기준으로 주니어/미들/시니어 진단
2. 근거 제시 — 어떤 패턴이 해당 레벨을 나타내는지 설명
3. 개선 포인트 — 다음 레벨로 올리는 핵심 변경사항 제시

출력 형식:

## 코드 레벨 진단

**현재 레벨: 🔵 미들**

**근거:**
- ✅ async 서버 컴포넌트 사용 (M-01)
- ✅ Suspense + 스켈레톤 UI (M-11)
- ⚠️ use cache 미적용 — 매 요청마다 DB 조회
- ⚠️ 병렬 fetch 가능한 곳에 순차 await 사용

**시니어로 올리려면:**
1. `'use cache'` + `cacheTag()` 추가
2. `Promise.allSettled()`로 병렬 패칭
3. Server Action에 소유권 검증 추가

참조: references/level-rubric.md (판별 기준), references/code-examples.md (대조 예제)

---

기술 스택별 컨벤션

상태 관리

• 서버 상태 → React Query (queryOptions + useSuspenseQuery)
• 전역 UI 상태 → Zustand (devtools 미들웨어 포함)
• 폼 상태 → React Hook Form + Zod
• 로컬 상태 → useState

HTTP 클라이언트

• lib/axios.ts 인스턴스 분리 필수
• 인터셉터로 토큰 자동 주입 + 에러 중앙 처리

참조: references/axios-react-query.md

---

참조 문서

파일	내용
references/level-rubric.md	주니어/미들/시니어 판별 루브릭
references/code-examples.md	레벨별 대조 코드 예제 4세트
references/axios-react-query.md	Axios/React Query 레벨 패턴
../../rules/core/nextjs-app-router.md	App Router 상세 규칙
../../rules/core/state-and-server-state.md	상태 관리 상세 규칙
../../rules/references/typescript/ts-naming-and-structure.md	TS 네이밍, 폴더 구조, 타입 위치 원칙
../../rules/references/typescript/ts-type-patterns.md	Brand Types, Conditional/Mapped Types 등
../../rules/references/typescript/ts-react-nextjs.md	React 19 ref 패턴, Next.js 15+ 타입
../../rules/references/typescript/ts-error-handling.md	Result 타입, 에러 유니온, never 체크
../../rules/references/typescript/ts-tooling-and-stack.md	tsconfig, Zod, 스택 조합, 논쟁 주제
../../rules/core/frontend-fundamentals.md	FF 4가지 설계 원칙