📒 멘토링

4회차 🗓️ 26.03.17

🤖 AI & 생산성

PR을 단순한 코드 제출이 아니라, 하나의 문서이자 히스토리 기록으로 남긴다는 관점으로 작성하는 것이 좋다.

• PR 설명은 상세할수록 좋다.
• 변경 이유 / 설계 의도 / 트레이드오프를 기록한다.
• 공통 컴포넌트의 경우 작성자가 셀프 리뷰 코멘트를 남겨 의도를 설명하는 것을 권장
• AI를 활용한 PR 리뷰 작성도 적극적으로 시도해보기 → 반복 작업을 줄이고 생산성을 높일 수 있음

🌳 Git Worktree

• 브랜치를 병렬로 관리할 수 있음
• 후가공때 병렬로 간단한 작업 처리하기에 아주 용이하다고 한다.
• Git Worktree로 여러 피처 동시에 개발하기 | AI 코딩 시대의 필수 스킬

🔐 Next.js 인증 및 데이터 페칭

Fetcher를 클라이언트 / 서버로 분리하는 패턴을 추천

• ClientSideFetcher → Axios 기반
• ServerSideFetcher → fetch 기반

권장 아키텍처

Token Service (독립)
   ↓
Fetcher
   ↓
API 함수

토큰 관리를 별도 서비스로 분리하고, Fetcher가 토큰 서비스를 통해 토큰을 받아 API를 호출하는 구조.

• 독립된 토큰 서비스: 토큰 관리 로직을 별도로 분리하여 Fetcher → API 호출 구조로 연결
• 쿠키 사용 권장: localStorage는 서버에서 접근할 수 없기 때문에 Next.js 환경에서는 쿠키 기반 인증이 유리하다.
• next/headers, js-cookie 같은 라이브러리를 활용 가능

🧩 서버 컴포넌트(RSC)의 특성과 주의점

• 컴포넌트 포함 규칙: 서버 컴포넌트는 클라이언트 컴포넌트를 포함할 수 있지만, 반대는 불가능
• 스냅샷의 함정: 서버 컴포넌트는 항상 최신 값을 보는 것이 아니라 요청 시점의 상태를 기준으로 렌더링된다.
• next/headers의 cookies 값도 snapshot이다 → 실시간 변경 대응 시 주의 필요

🔎 찾아보기

• Claude Serena, Ghostty
• DIP (Dependency Inversion Principle): 의존성 역전 원칙. 토큰 서비스 등을 구현할 때 상위 모듈이 하위 모듈에 의존하지 않게 설계하는 방법
• ISP (Interface Segregation Principle): 인터페이스 분리 원칙. 사용하지 않는 메서드에 의존하지 않도록 인터페이스를 작게 쪼개는 원칙
• next/headers에 의존하지 않는 토큰 관리 구조

5회차 🗓️ 26.03.20

🧩 SOLID / 추상 레이어

• 복잡한 로직은 추상 레이어로 숨긴다.
• 사용하는 쪽에서는 내부 구현을 몰라도 되게 만든다.
• 서비스 계층은 가능한 순수 함수 형태로 유지하는 것이 좋다.

추상 레이어 의미
복잡한 로직을 밖에서 알 필요 없게 숨기는 구조. 사용하는 쪽에서는 인터페이스만 알면 된다.

🔐 인증 — 토큰 서비스 분리

토큰 관리 로직은 전역 상태가 아니라 독립된 서비스 레이어로 분리하는 것이 좋다.
지양해야 할 패턴 - 전역 상태에 토큰 저장

• 라이브러리 옵션: js-cookie / iron-session / 직접 구현
• localStorage는 서버에서 접근 불가 → Next.js 환경에서는 쿠키 기반 인증이 유리

⚡ useSyncExternalStore

쿠키 / 세션 / 외부 저장소 값을 읽을 때 사용. React 상태가 아닌 외부 저장소를 안전하게 구독할 수 있다.

const token = useSyncExternalStore(
  TokenService.subscribe,
  TokenService.getSnapshot,
);

• 비동기 타이밍 문제 방지
• 외부 저장소 구독 가능
• concurrent 환경 대응

🔎 찾아보기

• SOLID 원칙
• 추상 레이어

Q CI 타입 체크 단계에서 발생한 오류와 관련해, 현재 해결 방향이 적절한지 여쭤보고 싶어 질문드립니다.

[상황 - Github Actions]
CI에서 tsc --noEmit 실행 시 PNG import에 대해 Cannot find module 'png' 오류가 발생했습니다.
로컬에서는 동일 코드가 정상 동작하는데, GitHub Actions의 type-check 단계에서만 실패하고 있습니다.

[현재 적용한 해결한 방법 - Github 적용 코드]
src/types/images.d.ts를 추가해 이미지 모듈 declaration 정의 했고,
tsconfig.json의 include에 next-env.d.ts 명시하니 CI 타입체크가 통과했습니다.

[고민되는 점]
Next.js는 next build 과정에서 .next/types 관련 타입 파일을 생성하고 next-env.d.ts가 이를 참조하는 구조로 이해하고 있습니다. 따라서 CI처럼 tsc --noEmit만 단독으로 실행되는 환경에서는 로컬과 타입 환경이 달라져서 위와 같은 문제가 발생한 것으로 생각했습니다.

주강사님께서 CI 순서를 build → type-check로 변경하는 방법도 제안해 주셨는데, 개인적으로는 타입 에러가 있는데 빌드 과정을 거칠 필요가 없으니 type-check → build 순서가 더 자연스럽지 않을까?"라고 생각했습니다.

해결한 방법처럼, 이미지 모듈 타입을 직접 선언해서 기존 CI 순서를 유지하는 방식이 맞는지
Next.js의 동작 방식에 맞춰 빌드를 먼저 거치는 것이 더 일반적인지 판단이 어려워 질문드립니다.

[궁금한 점]

Q. 현재처럼 .d.ts로 이미지 모듈 declaration을 수동으로 추가하는 방식이 Next.js 프로젝트에서도 일반적으로 권장되는 방향인지 궁금합니다.
A. type.d.ts는 많이 쓴다. 외부 SDK 연결 시에도 자주 사용.
Q. 만약 build → type-check 순서로 변경한다면, 단순 타입 오류 확인을 위해 매번 빌드를 먼저 수행하는게 비효율적이지 않은지 궁금합니다.
A. build → type-check도 실제로 쓰는 패턴.
Next.js 프로젝트에서 빌드를 먼저 돌린 경우도 있었다고 하셨다.

1. 여러 사람이 소스를 오염시킬 확률을 줄이기 위해
2. 빌드 실패를 Actions로 체킹하는 것 자체가 비용이기 때문

하지만, 단순 타입 오류 확인을 위해 매번 빌드를 먼저 수행하는 건 비효율적이긴 하다고 하셨다.

Q. 찾아보니 Next.js 15.5부터 지원하는 next typegen 명령어를 사용하면 전체 빌드 없이 타입 파일만 생성할 수 있다고 합니다. CI 환경에서는 next typegen → tsc --noEmit → next build 같은 흐름으로 구성하는 것이 적절할지 궁금합니다.
A. 처음 들어본 방식이라 찾아보았는데, 적용해봐도 좋을 것 같다고 의견 주심

6회차 🗓️ 26.03.23

📚 멘토님 공유 자료

프로젝트 진행 중 멘토님이 공유해주신 자료 및 기술 참고 링크 정리

🧠 Dev Insight

• AI가 주니어 개발자를 쓸모없게 만들고 있다 ↗
• AI 시대에도 프로그래밍을 배워야 하는가

🏗 Architecture / Structure

• FSD 관점으로 바라보는 코드 경계 찾기
• Feature-Sliced Design Docs

🏗 Design System Architecture

• 플랫폼 팀 없는 오픈 소스 기반의 디자인 시스템 구축 회고

📄 Documentation / Visualization

• Mermaid ↗

🧪 Testing

• Playwright MCP로 E2E 테스트 자동화하기

🎨 Component / Design System

• 당신2 9하던 Storybook
• Radix UI vs Base UI

📦 Libraries / Tools

• nuqs - URL을 통한 상태 관리 라이브러리
• ↳ nuqs 라이브러리 딥하게 파헤치기

📘 Next.js / React Notes

• Next.js 프로젝트에 TypeScript 타입 체크 설정하기: 놓치기 쉬운 필수 설정
• useSyncExternalStore
• next.js 에서 static asset 사용하기 (public vs src)