인수인계서 — 세션 10 (범용 코드 갈무리 ~77개 파일 추가)
작성일: 2026-02-16 이전 세션: session9
작업 요약
GitHub 커뮤니티 검증 패턴(usehooks-ts, radash, ahooks, mantine, bulletproof-react 등) 기반으로 02-reusable-code(TS/React) 및 02-reusable-code-python에 77개 파일 일괄 추가. 계획 Phase 18 전체 완료 + README/CLAUDE.md 인덱스 업데이트.
수정 파일 (~80개)
Phase 1: React 커스텀 훅 28개 (신규)
| # | 파일 | 설명 |
|---|---|---|
| 1 | 02-hooks/useLocalStorage.ts | localStorage React state 래퍼, SSR 안전, 탭 간 동기화 |
| 2 | 02-hooks/useSessionStorage.ts | sessionStorage React state 래퍼 |
| 3 | 02-hooks/useMediaQuery.ts | CSS 미디어쿼리 반응형 감지 |
| 4 | 02-hooks/useEventListener.ts | DOM 이벤트 리스너 자동 등록/해제 |
| 5 | 02-hooks/useClickOutside.ts | 요소 바깥 클릭 감지 |
| 6 | 02-hooks/useInterval.ts | setInterval React 래퍼 |
| 7 | 02-hooks/useTimeout.ts | setTimeout React 래퍼 |
| 8 | 02-hooks/useToggle.ts | boolean 상태 토글 |
| 9 | 02-hooks/useCopyToClipboard.ts | 클립보드 복사 + 상태 추적 |
| 10 | 02-hooks/usePrevious.ts | 이전 렌더 값 추적 |
| 11 | 02-hooks/useWindowSize.ts | 윈도우 크기 추적 (debounce) |
| 12 | 02-hooks/useScrollLock.ts | body 스크롤 잠금 |
| 13 | 02-hooks/useHover.ts | 요소 hover 상태 감지 |
| 14 | 02-hooks/useLongPress.ts | 길게 누르기 제스처 감지 |
| 15 | 02-hooks/useDocumentTitle.ts | 문서 제목 동적 변경 |
| 16 | 02-hooks/useScript.ts | 외부 스크립트 동적 로딩 |
| 17 | 02-hooks/useIdle.ts | 사용자 비활동 감지 |
| 18 | 02-hooks/useMouse.ts | 마우스 위치 추적 |
| 19 | 02-hooks/useWindowScroll.ts | 윈도우 스크롤 위치 추적 |
| 20 | 02-hooks/useCounter.ts | 숫자 상태 (increment/decrement/set/reset) |
| 21 | 02-hooks/useMap.ts | Map 자료구조 상태 관리 |
| 22 | 02-hooks/useSet.ts | Set 자료구조 상태 관리 |
| 23 | 02-hooks/useQueue.ts | FIFO 큐 상태 관리 |
| 24 | 02-hooks/useList.ts | 배열 상태 (push/remove/update/clear) |
| 25 | 02-hooks/useIsFirstRender.ts | 첫 렌더 여부 감지 |
| 26 | 02-hooks/useStep.ts | 스텝 진행 관리 (위자드 UI) |
| 27 | 02-hooks/useCookie.ts | 쿠키 read/write/delete |
| 28 | 02-hooks/useVisibilityChange.ts | 페이지 가시성 변경 감지 |
Phase 1: 기존 파일 편집
| # | 파일 | 변경 내용 |
|---|---|---|
| 29 | 02-hooks/index.ts | 28개 신규 훅 export 추가 (카테고리별 그룹핑) |
Phase 2: 유틸리티 함수 (신규)
| # | 파일 | 설명 |
|---|---|---|
| 30 | 03-utils/type-guards.ts | 15개 타입 가드 (isString, isNumber, isObject 등) |
| 31 | 03-utils/deep.ts | deepClone, deepEqual, deepMerge, shake, crush, construct |
| 32 | 03-utils/promise.ts | pLimit, pMap, pRetry, tryit, defer, parallel |
| 33 | 03-utils/functional.ts | pipe, compose, partial, once, negate |
| 34 | 03-utils/id.ts | nanoid, cuid, uuid |
| 35 | 03-utils/math.ts | mean, median, mode, variance, stdDev, percentile |
| 36 | 03-utils/color.ts | hexToRgb, rgbToHex, lighten, darken, contrast |
| 37 | 03-utils/event-emitter.ts | createEmitter (.on/.off/.emit + 와일드카드) |
| 38 | 03-utils/validation-schemas.ts | Zod 공통 스키마 (email, url, phone, password, pagination) |
| 39 | 03-utils/types/type-helpers.ts | DeepPartial, Prettify, StrictOmit, RequireAtLeastOne 등 |
| 40 | 03-utils/types/branded-types.ts | Brand<T,B>, UserId, Email 등 명목적 타입 |
| 41 | 03-utils/types/discriminated-unions.ts | match(), Result, exhaustiveCheck |
Phase 2: 기존 파일 편집
| # | 파일 | 변경 내용 |
|---|---|---|
| 42 | 03-utils/array.ts | +7 함수 (intersects, diff, fork, toggle, select, shift, zipToObject) |
| 43 | 03-utils/date.ts | +8 함수 (addBusinessDays, startOf, endOf, isWeekend 등) |
| 44 | 03-utils/index.ts | 신규 모듈 export 추가 |
Phase 3: 상태관리 패턴 (신규 디렉토리 11-state-patterns/)
| # | 파일 | 설명 |
|---|---|---|
| 45 | 11-state-patterns/zustand/slice-pattern.ts | 모듈러 슬라이스 패턴 |
| 46 | 11-state-patterns/zustand/persist-middleware.ts | 선택적 영속화 미들웨어 |
| 47 | 11-state-patterns/zustand/immer-middleware.ts | Immer 불변 업데이트 |
| 48 | 11-state-patterns/react-query/query-key-factory.ts | 쿼리 키 팩토리 패턴 |
| 49 | 11-state-patterns/react-query/optimistic-updates.ts | 낙관적 업데이트 + 롤백 |
| 50 | 11-state-patterns/react-query/infinite-query.ts | 무한 쿼리 + 페이지네이션 |
| 51 | 11-state-patterns/jotai/atom-patterns.ts | 기본/파생/비동기 atom 패턴 |
Phase 4: Next.js App Router 패턴 (신규 디렉토리 12-nextjs-patterns/)
| # | 파일 | 설명 |
|---|---|---|
| 52 | 12-nextjs-patterns/server-actions/form-action.ts | Server Action + Zod 검증 |
| 53 | 12-nextjs-patterns/server-actions/authenticated-action.ts | 인증 필수 Server Action |
| 54 | 12-nextjs-patterns/server-actions/optimistic-action.ts | 낙관적 UI 업데이트 |
| 55 | 12-nextjs-patterns/route-handlers/api-helpers.ts | 표준화된 API 응답 포맷 |
| 56 | 12-nextjs-patterns/streaming/suspense-pattern.tsx | Suspense + Error Boundary |
| 57 | 12-nextjs-patterns/rsc/server-client-composition.tsx | Server/Client 합성 패턴 |
| 58 | 12-nextjs-patterns/middleware/auth-middleware.ts | Next.js 미들웨어 인증 |
Phase 5: 테스팅 패턴 (신규 디렉토리 13-testing-patterns/)
| # | 파일 | 설명 |
|---|---|---|
| 59 | 13-testing-patterns/vitest/vitest.config.ts | Vitest 기본 설정 |
| 60 | 13-testing-patterns/testing-library/custom-render.tsx | Provider 래핑 커스텀 render |
| 61 | 13-testing-patterns/msw/handlers.ts | MSW 요청 핸들러 패턴 |
| 62 | 13-testing-patterns/msw/server-setup.ts | MSW 서버 설정 |
| 63 | 13-testing-patterns/playwright/base-page.ts | Page Object 베이스 클래스 |
| 64 | 13-testing-patterns/playwright/page-fixtures.ts | 커스텀 Fixture 패턴 |
Phase 7: Python 재사용 코드 (신규)
| # | 파일 | 설명 |
|---|---|---|
| 65 | http/httpx_client.py | AsyncClient + 재시도 + 동시성 제한 |
| 66 | models/pydantic_patterns.py | Pydantic v2 검증/설정/직렬화 |
| 67 | api/fastapi_dependencies.py | FastAPI DI (페이지네이션, 인증, 설정) |
| 68 | async/asyncio_patterns.py | TaskGroup, Semaphore, Queue, 주기적 태스크 |
| 69 | logging/structlog_setup.py | structlog 설정 + ContextVars + JSON |
| 70 | testing/pytest_patterns.py | fixture, conftest, parametrize, mock |
Phase 8: Error Boundary (신규 디렉토리 01-ui-components/error-boundary/)
| # | 파일 | 설명 |
|---|---|---|
| 71 | error-boundary/ErrorBoundary.tsx | 클래스 기반 Error Boundary |
| 72 | error-boundary/ErrorFallback.tsx | 재사용 가능 에러 폴백 UI |
| 73 | error-boundary/useErrorBoundary.ts | 명령형 Error Boundary 훅 |
Phase 9: 문서 업데이트
| # | 파일 | 변경 내용 |
|---|---|---|
| 74 | 02-reusable-code/README.md | 폴더 구조, 추출 이력, 카테고리별 테이블 |
| 75 | 02-reusable-code-python/README.md | 폴더 구조, 추출 이력 |
| 76 | CLAUDE.md | 폴더 구조, 추출 이력 1행 추가 |
상세 변경 사항
1. React 훅 28개 — 3단계 우선순위 분류
- Tier 1 (필수): 거의 모든 프로젝트에서 사용되는 핵심 훅 10개 (스토리지, DOM, 타이머, 상태)
- Tier 2 (매우 유용): 자주 사용되는 브라우저/센서 훅 10개 (윈도우, 스크롤, 마우스, 외부 스크립트)
- Tier 3 (데이터 구조): 자료구조 및 특수 용도 훅 8개 (Map, Set, Queue, Step, Cookie)
- 모든 훅에
'use client'지시문, JSDoc 헤더,@example사용 예제 포함
2. 유틸리티 함수 — 10개 카테고리
- 타입 가드, 딥 객체, Promise, 함수형, ID 생성, 수학/통계, 색상, 이벤트 이미터, Zod 검증
- 기존 array.ts/date.ts 확장 (총 15개 함수 추가)
- TypeScript 타입 유틸 3개 (브랜드 타입, 판별 유니온, 헬퍼)
3. 상태관리 패턴 — Zustand/React Query/Jotai
- Zustand: 슬라이스 패턴, persist 미들웨어 (만료 지원), immer 불변 업데이트
- React Query: 쿼리 키 팩토리, 낙관적 업데이트 + 롤백, 무한 스크롤
- Jotai: storage atom, toggle atom, resettable atom
4. Next.js App Router 패턴
- Server Actions: Zod 검증, 인증, 낙관적 UI
- Route Handlers: 표준화된 응답 + 에러 핸들링
- Streaming: Suspense + Error Boundary 조합
- RSC: Server/Client 합성, 직렬화 헬퍼
- Middleware: JWT/세션 기반 인증
5. Python 재사용 코드 확장
- httpx AsyncClient (재시도, 동시성 제한, JSON 헬퍼)
- Pydantic v2 패턴 (BaseSchema, Settings, 직렬화)
- FastAPI DI (페이지네이션, 정렬, 인증, 레이트 리밋)
- asyncio 패턴 (TaskGroup, Semaphore, Queue, 주기적 태스크)
- structlog 설정 (JSON 포매팅, ContextVars, 미들웨어)
- pytest 패턴 (fixture, parametrize, mock, 헬퍼)
검증 결과
- 모든 파일 JSDoc 헤더 (
@source GitHub-커뮤니티,@extracted 2026-02-16,@version 1.0.0) 포함 확인 - 코딩 컨벤션 (한국어 주석, 작은따옴표, 세미콜론, Named Export) 준수
- Python 컨벤션 (Google 독스트링, 큰따옴표, snake_case, 내장 타입) 준수
- TypeScript 컴파일 검증 (
tsc --noEmit) 미수행 — 다음 세션에서 권장
터치하지 않은 영역
- 기존 01-ui-components (shadcn 등) 미수정
- 기존 04-supabase-patterns ~ 10-stripe-patterns 미수정
- 기존 Python 파일 (utils/, api/, ai/) 미수정
알려진 이슈
- TypeScript 컴파일 검증 미수행 — 타입 에러 가능성
- Zod 의존성 (
validation-schemas.ts) — Zod 미설치 프로젝트에서 사용 불가 - 일부 훅의 SSR 호환성 검증 필요 (useLocalStorage, useSessionStorage 등은 SSR 안전 처리됨)
다음 작업 제안
tsc --noEmit으로 TypeScript 컴파일 전체 검증- 실 프로젝트에서 신규 훅/유틸 적용 테스트
- 시너지 개선 실전 검증 (kdyweb init → kdypick 연쇄)
- Hooks 템플릿 실 프로젝트 적용