📚 Series
🏷️ Tags
교육과정 도메인 BE 완성 머지 직후 7 시간 안에 7 건 핫픽스가 묶여 배포된 하루를 정리한다. Class API 폴백 사슬·level displayName 11 곳·login response teacherId 까지는 기능 보완이었지만, 06:00 킥오프 배치가 2 중 실행되며 회원당 과제 2 개가 생성된 사고는 NestJS ScheduleModule.forRoot() 중복 등록의 고전 함정이었다. forRoot 단일화·배치 1.5 단계 만료 로직·Student Home 조회 가드 세 방어 층을 같은 머지에 묶어 1,502 줄 세션 로그가 끝났다.
그룹 교육과정에 *레벨 25* 를 지정해 둔 회원이 *배치고사 건너뛰기* 직후 *레벨 15* 로 배정된 사고. 표면 증상은 하나였지만 진짜 원인은 *Class 동기화 누락 / getEffectiveCurriculum 폴백 누락 / 배치고사 건너뛰기의 currentLevelId 폴백* 세 도메인 버그가 한 사슬을 이루고 있던 점이었다. 폴백 4 단으로 재정렬하고 자동 승급 메서드 두 개를 들여 *EXCELLENT 3 일 + Top 도달* 조건을 한 흐름에 묶은 A 톤 트러블슈팅을 정리한다.
NestJS + Prisma 프로젝트에서 Member·Class·Operator 세 도메인 모델에 deletedAt 한 컬럼을 도입하며 마주친 27곳의 쿼리 필터, 트랜잭션 dependent 정리, 로그인 차단, FE 다이얼로그 흐름까지 도메인 모델 표준의 구현기를 정리한다. delete-check + DELETE 두 단계 API와 Application Service 16곳 + Domain Repository 11곳의 필터 분포까지 한 흐름으로 묶었다.
여러 운영 페이지와 외부 SPA 에 흩어진 폼 12 개가 각자 다른 검증·정규화·에러 표시 흐름을 갖고 있었다. zod 공용 스키마를 `lib/validations/` 에 모으고, react-hook-form + zodResolver + shadcn/ui Form 한 흐름으로 묶으면서 입력 정규화·필드 에러·BE 에러 매핑까지 한 줄의 표준으로 정착시킨 구현기.
한 고객사에서 연락처 010-1234-5678 을 입력하면 BE 400, 01012345678 을 입력하면 통과되는 비대칭이 보고됐다. DB 를 열어 보니 같은 컬럼에 *하이픈 포함* 과 *숫자만* 이 섞여 누적돼 있었다. 진짜 범인은 *저장 포맷·입력 포맷·표시 포맷 세 축의 표준이 어디에도 없었던 점* 이었다. BE `phone.util.ts` + DTO `@Transform/@Matches` + FE zod `transform/refine` + 마이그레이션 SQL 을 *한 머지에 묶어* BE·FE·DB 세 곳을 동시에 정규화한 트러블슈팅을 정리한다.
Unity 주간 출석 API 가 운영 한 달 후 월요일 칸만 무작위로 비었다. DB 에는 COMPLETED 과제가 분명히 있는데 화면은 null 이었다. 진짜 범인은 `new Date('2026-03-09')` 가 ISO 8601 로 파싱되어 UTC 자정 (= KST 09:00 월) 으로 잡힌 점이었고, batch 가 KST 00:00 으로 고정한 scheduledAt 이 쿼리 범위 *직전 9 시간* 에 들어가 통째로 누락되고 있었다. KST 자정 명시 생성자로 두 줄을 갈아끼우고, ESLint 룰과 jest mocking 가드로 재발을 막은 트러블슈팅을 정리한다.
Claude Code Agent Teams의 아키텍처를 이해하고, team-setup 스킬로 tmux 멀티 에이전트 환경을 자동 구성하는 방법. 실제 캡처와 함께 단계별로 안내합니다.
Google E-E-A-T(경험, 전문성, 권위, 신뢰)를 개인 기술 블로그에 실제로 적용한 과정을 정리합니다. 품질 평가 가이드라인을 읽고, 환경 명시 박스·레퍼런스 박스·구조화 데이터·시리즈 구조를 도입하기까지 — 공식 문서에서 근거를 찾고 하나씩 적용한 기록입니다.
Anthropic이 서드파티 하네스를 구독에서 분리했다. 에러 원인, $200 크레딧 수령, CLI 브릿지 대응까지 정리.
Claude Max 플랜의 OAuth 토큰(sk-ant-oat)으로 Messages API를 직접 호출하면 429 Rate Limit이 뜹니다. Claude Code의 인증 우선순위 5단계, sk-ant-oat vs sk-ant-api 차이, 그리고 스크립트에서 Max 플랜을 활용하는 우회법을 실제 트러블슈팅 사례와 함께 정리합니다.
Vite 프로젝트에서 새 패키지를 설치한 뒤 Invalid hook call 에러가 발생하는 원인은 의존성 사전 번들링 캐시(.vite/deps)다. React 중복 인스턴스 문제의 근본 원인부터 node_modules/.vite 삭제, vite --force, optimizeDeps 설정까지 실전 해결법과 예방 전략을 정리한다.
NestJS + Prisma 프로젝트에서 schema.prisma에 새 필드를 추가한 뒤 prisma generate를 빠뜨리면, TypeScript 빌드는 as any 캐스팅 덕에 통과하지만 런타임에서 Prisma Client가 새 필드를 모른다. pnpm build와 prisma generate가 별개 명령인 구조적 함정, prebuild 훅으로 자동화하는 해결법, Docker와 CI에서 놓치지 않는 예방 전략을 실전 코드와 함께 정리한다.
1인 개발 모노레포에서 CI/CD 파이프라인을 구축하며 겪은 실전 트러블슈팅. Docker 빌드 경로 오류, 배포 자동화 실패, Cloud Scheduler 설정 함정까지 — 수동 배포의 고통에서 벗어나는 과정을 정리했다.
홈브루 명령어 한 줄로 맥북을 꾸미는 드레스업 패키지 총정리. 메뉴 바 정리, 폰트 설치, UI 유틸리티, 배터리 모니터링까지 다뤄요.
