총 102편
교육과정 도메인 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 가드로 재발을 막은 트러블슈팅을 정리한다.
PM·BE·FE·QA·외부 단말 5개 역할을 한 사람이 워크트리 4개로 돌리는 동안 통신 손실을 막은 단일 파일 운영기. 500줄 임계치를 넘어 1,974줄까지 누적된 하루치 통신을 풀 아카이브로 떨어뜨린 시점의 회고와, 같은 파일 위에서 변경 명세서·LESSONS 갱신·다음 작업 지시가 어떻게 직렬화됐는지 정리한다.
Unity 안에 카메라 입력 흐름을 끌어들이는 대신, QR 코드 한 장으로 모바일 외부 웹앱을 띄우는 결정. 인증 없는 Public Submit API, PROCESSING_SPEED 서버 자동 계산, sessionId 폴링 흐름, 그리고 같은 결정 트리의 연장선에서 Level-Test SPA 와 3개 운영 포털을 Firebase Hosting 멀티사이트로 분리 배포한 구현기.
외부 뷰어 리포트 4탭 N+1 을 잡아 2.3 초까지 줄였는데 목표 500ms 와의 마지막 1.8 초가 코드 어디에서도 나오지 않았다. Cloud SQL Query Insights 가 쿼리 자체는 0.1~1ms 라고 답했다. 진짜 범인은 한국 ↔ us-central1 왕복 100~200ms × 응답당 6~8 쿼리 누적이었다. 레플리카 프로모션으로 asia-east1 (대만) 으로 옮기고 .env 두 줄을 갈아끼우자 `/content-candidates` 가 2,340ms → 682ms (71% ↓), `/student/home` 이 2,000ms+ → 400~600ms 로 떨어졌다. 인덱스·N+1 이 아니라 리전·RTT 가 본진이었던 인프라 사고를 정리한다.
외부 뷰어 리포트 토큰 한 줄로 들어가는 공개 페이지의 4탭 단일 응답이 최대 14.4초까지 늘어났다. Prisma `include` 만 의심하다 진짜 범인을 놓쳤다. 두 층의 N+1 — 4탭 빌더 6 건의 순차 await + 일별·주별 for 루프 안 `findMany` 반복 — 을 Promise.all 병렬화 + 단일 findMany + 메모리 그룹핑으로 풀어 55 개 쿼리를 10 개로, p95 응답을 ~2.3 초로 끌어내린 트러블슈팅을 정리한다.
외부 뷰어 리포트의 4탭에 인사이트 카드와 빈 데이터 폴백을 같이 깔고 나니 일부 motion.section의 whileInView 애니메이션이 트리거되지 않았다. 같은 컴포넌트가 같은 코드로 어떤 탭에서는 정상이고 어떤 탭에서는 opacity 0으로 그대로 멈췄다. 원인은 조건부 마운트 시점에 IntersectionObserver의 첫 콜백이 framer-motion 이펙트 부착 전에 끝나 버린 레이스 + viewport.once 기본값 false의 합이었다. once:true 표준화 + sentinel ref + ESLint 가드를 같이 깐 트러블슈팅을 정리한다.
외부 뷰어가 보는 4탭 리포트에 차트 옆으로 한 줄 자연어 메시지를 붙이는 인사이트 시스템 도입 머지를 정리한다. AI 호출 없이 결정성을 보장하는 룰 기반 메시지 생성기, 5 + 4 + 5 = 14종 긍정 규칙, 빈 데이터 폴백 카피 4종, 4탭별 메시지 슬롯 배치 — 같은 dev 머지 사이클 안에서 응답 표준 + 룰 + 폴백을 동시에 굳힌 설계 흐름과 트레이드오프를 기록한다.
도입 단계 머지가 같은 날 밤 사용자 검토 1회로 폐기된 사고. Parent / ParentStudent / ParentInvitation 3 모델 + 회원가입 단일 트랜잭션 + 별도 JWT 시크릿 흐름 전부 삭제, StudentReport 1 모델 + nanoid 21자 공개 토큰 + 7일 만료 정책으로 같은 dev 머지 사이클 안에 갈아엎은 BE -2,099 / +563 + FE -1,475 / +968 의 갈아엎기 비용과 결정 사유, 사후 평가를 정리한다.
회원 레포트와 같은 데이터를 보호자(외부 뷰어) 그릇으로 옮기는 별도 앱 도입 머지. 모바일 우선 컨테이너(max-w-[430px]), Parent/ParentStudent/ParentInvitation 3 신규 모델, 초대 토큰 + 회원가입 단일 트랜잭션(4 write), 별도 JWT 시크릿(1h access / 30d refresh), 전화번호 = 로그인 ID 결정을 같은 dev 머지 사이클 4시간 안에 BE + FE Mock + FE 인증 연동까지 묶은 도입 단계 마일스톤이다.
관리자 페이지 회원 레포트 페이지를 5탭(개요·학습 분석·지표 분석·레벨 이력·상세 기록)으로 설계한 머지. 신규 4 API + 기존 1 API 재사용, 공통 기간 필터, 인사이트 3파트(긍정/격려/개선) 구조, 학습 진도 집계 단위를 묶음에서 콘텐츠로 바꾼 결정, 상세 기록의 드릴다운 3계층(과제→묶음→콘텐츠) 응답 표준을 정리한다. NestJS + Prisma 환경에서 명세 우선·FE Mock 선행 워크플로우로 BE 구현 전 사용자 검토를 확보한 도입 단계 마일스톤이다.
회원 활동 동기 부여용 코인 지갑을 도입한 첫 머지. Prisma 단일 트랜잭션 안에서 잔액 변경과 거래 원장을 함께 기록하고, balanceAfter는 감사용으로 불변 처리한다. 도입 단계(스키마 + Domain Service + Debug API 4개 + 단위 테스트 18개)와 같은 dev 머지 사이클에 함께 들어간 노출 단계 Wallet API 3개(잔액 조회/입금/출금)의 결정·코드·트레이드오프를 정리한다. NestJS + Prisma 환경에서 통화 시스템을 첫 머지로 옮길 때의 스키마 분리, 응답 표준화, 옵셔널 멱등성, 클라이언트 신뢰 모델을 다룬다.
회원이 번들에서 콘텐츠 1건을 고를 때마다 호출되는 후보 추천 API는 4단계 폴백(level+metric → 유사 지표 → level only → 전체)이 각각 별도 쿼리를 내던 구조였다. 본 글은 페널티 기반 순위 조정으로 제외 로직을 비우고(v2.1.5), 레벨 콘텐츠를 한 번만 조회해 메모리 풀로 옮긴 뒤, FB0~FB2 폴백을 모두 인메모리 필터로 처리해 4,670ms를 2,340ms로 떨어뜨린 3차 최적화 마일스톤을 정리한다. NestJS + Prisma 환경에서 다단계 폴백 쿼리를 단일 쿼리 + 메모리 필터링 패턴으로 옮길 때의 결정·코드·트레이드오프를 다룬다.
운영자가 본인 담당 클래스 1개만 떠야 하는데 모든 클래스가 떴다. 목록 API에 operatorId 필터를 깔고 끝낸 줄 알았는데, 직접 URL로 미담당 클래스 ID를 두드리니 상세·수정·승인 5개 엔드포인트가 그대로 200을 돌려줬다. 원인은 JWT payload.sub(User ID)와 Operator 테이블 id(Operator ID)의 분리 + validateClassAccess 헬퍼 부재 둘이었다. 라운드 한 번에 BE → QA → 추가 BE → QA 재검증으로 닫은 NestJS ForbiddenException + Prisma classOperator.findFirst 패턴을 정리한다.
이전 편의 배치고사 MVP 머지가 가능했던 것은 같은 날 오후에 Problem 모델의 콘텐츠 종속을 먼저 끊었기 때문이다. 본 작업은 Problem 테이블이 ContentItem에 종속돼 재사용 불가하던 구조를 끊고, 1,891개 문제를 신 스키마로 옮기고, Admin/Student 8 엔드포인트와 단위 테스트 38건을 한 머지에 묶은 마일스톤이다. 스키마·마이그레이션·API·테스트가 한 dev 머지 사이클에 들어간 BE 작업 기록을 정리한다.
이전 편에서 배치고사 명세를 자동 레벨 배치 폐기로 정리했다. 같은 날 저녁 그 명세를 실제 코드·테스트·시드 데이터로 한 번에 옮긴 마일스톤이다. 도메인·응용 갱신, Legacy 컨트롤러 3개 + 도메인 서비스 3개 + DTO 9건 571줄 삭제, 단위 테스트 22개, 회원 시드 보강, QA E2E 5 시나리오까지 5개 커밋이 한 머지 사이클에 들어간 운영 기록을 정리한다.
Unity 네이티브 클라이언트의 Lobby 씬과 배치고사 씬을 같은 빌드 안에 묶었다. NestJS 응답 모델과 Unity C# 모델의 필드명 불일치, NetworkManager 단일 진입점 래퍼, AuthGuard 패턴, 배치고사 완료 시 첫 숙제 자동 발행 체인, contentUrl 전체 경로 정책까지 6가지 설계 결정과 트레이드오프를 정리한다.
혼자서 BE·FE·QA·PM 네 역할을 갈아끼우며 학습 클라이언트 웹 프로토타입의 QA 라운드 3~7을 연속으로 돌렸다. 라운드 3의 타이머 NaN·시드 부족부터 라운드 7의 BundleContent nullable·다음 번들 자동 생성까지, 5라운드 동안 버그가 BE·시드·스키마를 차례로 옮긴 흐름과 혼자서 여러 역할을 맡는 QA의 회고.
QA Round 2에서 EC-3 엣지 케이스가 잡은 타이머 NaN:NaN 버그. 같은 컴포넌트가 같은 코드로 한 화면에서 정상, 다른 화면에서 NaN:NaN으로 뜨던 패턴이다. 원인은 BE 응답 DTO에서 한 필드 누락 + FE 무방어 + seed 데이터 부족 세 가지의 합이었다. 응답 스키마 검증과 콘텐츠 후보 0건 방어를 같이 깐 라운드 회고.
혼자서 BE·FE·QA·PM을 동시에 맡는 환경에서 학습 클라이언트 웹 프로토타입 첫 QA 라운드를 돌렸다. 브랜치 미동기화로 인한 미구현 오보, 만료 토큰 잔존으로 인한 401, UI 스모크 수준의 검증 충실도 부족까지 세 함정을 한 라운드에 만났고, 다음 라운드부터의 운영 체크리스트로 정리했다.
첫 배치 작업으로 짠 NestJS 킥오프 배치(@nestjs/schedule)가 @Cron('EVERY_HOUR') + findExpiredAssignments() 시간 체크 누락 두 함정에 걸려 모든 ACTIVE 숙제를 매시간 EXPIRED로 굳혀 버린 사고를 복기한다. fix는 두 줄(시간 비교 + cron 표현식)이었지만, 사고가 일어났는데도 콘솔이 흘러가 흔적이 없었던 점이 더 컸다. 콘솔 일변도에서 Winston 파일 로깅(daily-rotate, app/error 분리, GCP severity) 으로 갈아탄 결정과 설정 전문을 정리한다.
다섯 개 지표의 점수를 가중평균으로 0~100 범위에 수렴시키던 설계를 폐기하고, 누계 점수를 매 묶음 완료마다 INSERT 전용으로 쌓아 distinct로 최신 1행씩 읽어 TOP1~5 순위를 굳히는 스냅샷 시스템을 짠다. 결정 5건, 트레이드오프, 두 진입점(배치고사 완료·묶음 완료)에서의 호출 패턴, 회복성 try-catch까지 코드 인용으로 정리한다.
Unity WebView 안에서 동작하는 웹 콘텐츠 10종을 같은 PostMessage 브릿지 규격으로 묶는 마일스톤 작업을 정리한다. bridge/ 폴더 하드카피와 useProblemResults 훅으로 콘텐츠별 차이를 흡수하고, 통계 필드 8개·2개·contentType·problems 배열을 네 차례에 걸쳐 점진적으로 확장하면서 마주친 400 Bad Request·accuracyPct 재정의·시간 정확도 변환 로직 회수의 결정 사유와 트레이드오프를 기록한다.
Unity WebView 호스트가 보낸 첫 contentInit 메시지를 웹 콘텐츠가 0개로 인식하는데 에러는 없다. window.vuplex가 비동기로 주입되는 탓에 detectMode()가 'standalone'을 오판하고, isStandalone() 가드가 메시지 핸들러 등록을 막은 침묵 실패를 추적해 해결한 기록.
Unity 네이티브 앱이 WebView로 웹 콘텐츠를 임베드할 때, 호스트와 콘텐츠는 PostMessage로만 대화한다. Vuplex·iframe·Standalone 세 환경을 런타임에 자동 감지하는 ContentBridge 모듈을 설계하고, contentInit·contentReady·contentResult·contentExit 메시지 규격을 한곳에 고정한 과정을 정리한다. 핵심 제약은 Standalone 모드에서 기존 콘텐츠 코드가 100% 그대로 동작해야 한다는 것이었다.
Swagger UI는 멀쩡한데 모듈마다 빠진 데코레이터·interface DTO 때문에 API 문서가 실제 동작과 어긋났다. 35개 컨트롤러에 @ApiTags·@ApiBearerAuth를 일괄 적용하고, 한 모듈의 9개 메서드·22개 DTO를 interface에서 class로 한 번에 정리했다. 모듈별 점진 적용을 거절하고 일괄 적용을 택한 트레이드오프와 적용 패턴을 정리한다.
Unity 클라이언트 QA에서 할당 만료를 보려고 30분을 기다리거나 DB를 직접 건드리던 흐름을 운영용 디버그 API 7개로 흡수했다. PLATFORM_ADMIN 단독 권한·환경 토글·멱등 reset 같은 설계 결정과 후속 개선(loginId 쿼리, createNewAssignment 옵션)까지의 트레이드오프를 정리한다.
활동 로그 인터셉터에서 request.user가 undefined로 잡혔다. 원인을 파고드니 JwtAuthGuard 구현 누락, Auth Service와 Guard 간 JWT_SECRET 불일치, FE의 base64(JSON) Mock 토큰까지 3중 함정이 차례로 드러났다. 새벽 3시 임시 우회부터 다음 날 17시 정상화까지의 디버깅 흐름과 NestJS 글로벌 Guard·명시적 secret 검증·실제 BE API 시드 패턴을 정리한다.
초기 배치고사는 정확도로 회원 레벨을 자동 배치하려 했지만, 출제 문제 셋이 바뀌면 레벨이 출렁였다. 측정과 결정을 분리해 레벨 배치 로직을 걷어내고 5지표 정확도 측정만 남긴 명세 갱신과 트레이드오프 4건을 정리한다.
교육과정 목표를 Member 한 곳에만 두면 운영 비용이 폭증한다. Prisma 두 컬럼 추가 + 도메인 서비스 한 메서드로 Member → Class → 분기 기본값 3계층 폴백을 한 곳에 모은 리팩토링. 응답에 출처(curriculumSource)를 함께 실어 운영자 UI도 한 화면에 결론을 보여준다.
PATCH body에 끼워 넣은 다른 tenantId가 통과해 옆 고객사 회원이 옮겨 쓰였다. NestJS Guard + DTO에서 tenantId 제거 + whitelist:true 3중 차단으로 쓰기 가드를 만들고, count/sum/groupBy는 where 변수 추출 + $transaction으로 묶었다. 시간 슬라이스는 KST 자정 고정, 멱등성은 Redis EX 60 + 충돌 검사 + audit, 정책 위반은 bypassPolicy + reason + audit. ts-morph 정적 스캔까지 1일 트러블슈팅.
NestJS 멀티테넌트 도입 다음 날 아침, 다른 고객사 토큰으로 회원 상세를 열었더니 200 OK가 떨어졌다. JWT payload·@CurrentUser·Repository 시그니처 3계층에 tenantId를 강제하고, ts-morph 정적 스캔과 cross-tenant e2e로 회귀까지 차단한 6시간 트러블슈팅.
단일 정수 sortOrder로 줄세운 선형 레벨을 노드/엣지 분리 DAG로 옮겼다. 셀프 참조 1:N vs 별도 엣지 테이블, PostgreSQL recursive CTE로 진행도 계산, 엣지 INSERT 시점 사이클 검출, 선형 i→i+1 자동 마이그레이션 4가지 결정과 zod invariants e2e로 회귀를 차단한 트러블슈팅.
SystemPolicy 8필드를 id @default(1) 싱글톤으로 묶고, 상호 의존 임계값은 zod superRefine으로 BE/FE 두 곳에서 검증했다. 동사 액션은 별도 라우트로 분리하고, 정책 변경은 방향성만 검증하는 e2e로 회귀를 차단한 1.5일 트러블슈팅.
1차 점검(SC-A01~A17)이 *FE 단독·BE 단독*의 단위 검수였다면, 2차 점검은 *FE-BE를 처음 같이 돌려 보는 자리*였어요. 그날 자정부터 새벽까지 한 사이클에 11건이 터졌습니다. CORS PATCH·DTO interface→class·운영자 상태 변경 400·콘텐츠 FK 제약·dbVersion 동적 조회 다섯 자리(BE)에 모니터링 useCustom·진단평가 문제 추가 버튼 결정·이메일 인라인 에러·SUPER_ADMIN 활성화 가드·배치고사 상태 엔드포인트 분리·콘텐츠 목록 null 크래시 여섯 자리(FE)까지. 코드 변경은 한 줄짜리 자리가 많았는데, *어떤 자리가 깨질 수 있는지*를 미리 보지 못한 게 11건이 한꺼번에 몰린 이유였어요. 합류 지점이라는 디버깅 환경의 본질을 11개의 자리로 짚은 글입니다.
DTO를 class로 바꾼 다음 날 새벽, 같은 PATCH 흐름에서 이번엔 CORS가 빨갛게 물들었어요. 'Method patch is not allowed'. 메서드 이름이 소문자였습니다. 한쪽은 NestJS의 `allowedHeaders` 한 줄이 비어 있어서, 다른 한쪽은 React Admin의 dataProvider가 `method`를 소문자로 그대로 넘기고 있어서 — 그리고 그걸 Vite 6 프록시가 정규화 없이 그대로 흘려보내서. 두 자리를 동시에 잡고, `.env.local`을 절대 URL에서 `/api` 프록시 경유로 바꾸고, OPTIONS 응답 헤더를 검수 체크리스트로 박은 자정 디버깅 6시간을 다시 짚었습니다.
VITE_USE_MOCK_API=false로 토글한 순간 useTable이 멈췄다. BE는 TransformInterceptor로 모든 응답을 `{ success, data, meta }`로 표준화했고, Refine은 `{ data, total }`을 기대했다. dataProvider 어댑터 한 줄로 메우면 끝나는 줄 알았는데 — 경로가 `/api/v1/api/v1/...`로 중복되고, FE가 `order`로 보낸 정렬 키를 BE는 `sortOrder`로 받았으며, 중첩 리소스 `/contents/:id/problems`는 dataProvider 기본 구현이 못 그렸다. 결국 어댑터 한 줄이 아니라 경로 정규화·필드 매핑·중첩 리소스 라우터·401 인터셉터까지 네 자리를 박아야 토글이 진짜 한 줄이 됐다.
SC-A01부터 SC-A20까지 20개 시나리오를 5일 만에 75%에서 90%까지 끌어올린 Admin Portal MVP 사이클. 혼자 PM·BE·FE 세 역할을 돌리면서 만든 병렬화의 환상은 사실 코드 한 줄 — `VITE_USE_MOCK_API=true` 환경변수 토글과 그 뒤에 붙은 Mock/REST DataProvider 두 구현체에서 시작됐다. Refine + Vite 위에서 14개 page 모듈을 어떤 순서로 박았는지, [FE → PM] 태그로 셀프 보고하던 협업 프로토콜이 왜 효과가 있었는지, Mock에서 REST로 갈아끼울 때 실제로 바뀐 건 한 줄이었는지 — 다섯 H2로 정리한다.
devlog-13부터 devlog-20까지, v2.0 갈아엎기 5편과 v2.1로 끌어올리기 2편, v3.0 한 단계 더 1편을 한 발 떨어져서 다시 읽는다. Block에서 Bundle로의 전환, 5-Phase로 쪼갠 마이그레이션, 같은 날 v2.1로 SSoT를 끌어올린 결정, 1,682줄을 한 커밋에 박은 도메인 레이어, 그리고 그 위에 얇은 막을 입힌 Application Service까지. Before/After가 정말로 달라진 다섯 축(코드 책임, 문서 트랙, 멘탈, 도메인 명확성, 테스트 가능성)과 80일이 지나도 안 달라진 한 축(혼자 결정하고 혼자 박는 운영 모드)을 코드 위에서 정리한다.
도메인 서비스를 박은 다음 그 위에 Application Service 4종 + Controller 4종 + DTO 4종을 한 번에 박은 결정 이야기. trackState, secondLevel, track1/2Completed, curriculumProgress 같은 v3.0 필드가 Application 경계에서 어떻게 흡수되는지, 그리고 그 결과로 터진 빌드 에러 51개를 다섯 카테고리로 잡아간 새벽의 디버깅 흐름까지. 도메인이 비즈니스 규칙을 가지고, Application은 그것을 호출하는 얇은 오케스트레이션 막이 된다는 결합 규약을 코드 위에서 다시 한 번 확인한 한 Phase의 기록.
전날 4,658줄짜리 DDD 문서를 박은 다음 날 저녁, 그 문서를 입력으로 받아 도메인 레이어 코드를 다시 박았다. 한 커밋에 1,682줄 추가. MetricRank TOP1~5와 V21_THRESHOLDS를 도메인 타입으로 박은 결정, ContentCandidateService의 후보 폴백 설계, 90% 이상도 복습 필수로 바꾼 ReviewModuleService 리팩토링, BundleCompleted 이벤트로 Aggregate 간 결합을 끊은 결정 — 다섯 개의 도메인 서비스가 같은 커밋에 들어간 이유와 각각의 설계 철학.
v2.0 코드 마이그레이션이 끝난 직후, 같은 날 밤 24분 사이에 두 개의 docs 커밋이 들어갔다. v2.0 DDD 문서들은 _archived/v2.0/으로 묻혔고, 마스터 문서가 v2.1로 진화하면서 1,354줄이 갈아 끼워졌고, 그 위에 새 DDD 문서 4,658줄이 새로 적혔다. 코드와 문서를 다른 트랙으로 두지 않기 위해 무엇을 묶었고 무엇을 일부러 묻었는지의 기록.
Phase 3-1·3-2가 만든 Repository와 Domain Service 위에 Application(953줄), Controller+DTO(763줄), Module(39줄)을 차례로 얹어 v2.0 번들 기반 학습 시스템을 닫는 단계. UC-06~10과 UC-14~17을 어떻게 코드로 옮겼는지, 인메모리 챌린지 스토어를 왜 일부러 남겼는지, 39줄짜리 모듈 한 장이 왜 끝의 끝인지를 기록한다.
Phase 2가 남긴 36개 빌드 에러를 봉합하는 단계. BundleRepository 인터페이스 204줄과 Prisma 구현체 294줄, BundleGenerationService 417줄을 어떻게 분리해 작성했는지, 5콘텐츠 고정 구조와 4단계 폴백 전략을 코드로 어떻게 옮겼는지의 기록. 인터페이스 분리가 멘탈에 어떤 보호막을 쳐줬는지 포함.
v2.0 Phase 2는 self-reference를 배열로 바꾸고, enum 두 개를 추가하고, NOT NULL을 nullable로 푸는 스키마 대수술이었다. Prisma migrate가 자동 생성한 SQL의 'data will be lost' 경고 4개를 어떻게 무력화했는지, 그리고 마이그레이션 직후 36개 빌드 에러가 났는데도 왜 멘탈이 멀쩡했는지의 기록.
v1.1의 UC-06/07/08/09를 Bundle 기반으로 다시 쓰면서 알고리즘 자체를 새로 썼다. 재작성 도중 리마인드 레벨 역설, 가중치 NaN, POOR 정책 중복이라는 v1.1의 숨은 공백 3개를 발견한 이야기.
기획자의 43줄짜리 검토 내용이 마스터 문서 1,013줄, 마이그레이션 로드맵 441줄, CLAUDE.md 307줄로 풀어졌다. Block에서 Bundle로, 레벨링 모듈 설계, 그리고 AI 지식 전승 문서를 처음 만든 이야기.
358개 테스트, 30개 테이블, 6개 Controller까지 완성한 v1.0. 기획 검토 한 번에 핵심 구조가 통째로 바뀌었다. Block에서 Bundle로, 갈아엎기로 결심하기까지의 기록.
DDD 3계층 위에 REST API Controllers를 올리는 과정. Use Case 단위로 6개 컨트롤러를 분리하고, ApplicationModule로 조립하고, 27개 단위 테스트로 검증한 실전기록.
로컬 PostgreSQL에서 잘 되던 E2E 테스트가 Cloud SQL에서 전멸한 이야기. session_replication_role 미지원, 테이블 이름 케이스 불일치, 스키마 필드 누락까지 — 4/8에서 8/8 passing으로 가는 과정을 기록한다.
NestJS + Prisma 프로젝트에서 Jest 테스트 인프라를 처음부터 세팅한 기록. 단위/통합 설정 분리, Test Data Factory 패턴, PrismaService Mock 전략, 그리고 mockResolvedValue 타입 오류까지.
NestJS에서 TypeScript interface를 DI 토큰으로 쓸 수 없는 이유와, 인터페이스 의존을 구현체 의존으로 전환한 커밋 하나의 기록. 이론적 DDD와 프레임워크 현실 사이의 실용적 타협.
교육용 SaaS 백엔드에 DDD 3계층 구조를 도입한 과정. PrismaService 직접 호출에서 Repository 패턴, Domain Service, Application Service로 분리하기까지 4개 커밋에 걸친 아키텍처 전환 실전기.
Prisma seed 스크립트에서 deleteMany 순서를 잘못 잡으면 FK 제약 조건 위반으로 터진다. 30개 테이블의 의존 그래프를 분석하고 자식→부모 역순 삭제 패턴을 정립한 실전 삽질기.
B2B SaaS 플랫폼의 RBAC 인가 체계를 설계한 과정. 4역할 계층 구조, 리소스별 권한 매트릭스, Multi-tenancy 격리 전략, NestJS Guard/Decorator 구현까지 — 권한 설계 문서 1,292줄이 코드가 되기까지의 기록.
전체 테이블 CUID String PK에서 Mixed ID Strategy(User=CUID, Master=Int, Transaction=BigInt)로 전환한 과정. BigInt JSON 직렬화 버그를 만나고, Junction Table을 다시 Int로 다운그레이드한 첫 번째 스키마 리팩토링 기록.
Claude Code Agent Teams의 아키텍처를 이해하고, team-setup 스킬로 tmux 멀티 에이전트 환경을 자동 구성하는 방법. 실제 캡처와 함께 단계별로 안내합니다.
B2B SaaS 백엔드의 Prisma 스키마를 설계한 과정. 인증 → 조직 → 러닝 코어 → 트래킹 순서로 27개 테이블과 15개 enum을 만들면서 겪은 설계 결정과 실수들을 기록합니다.
수동 오케스트레이션에서 Claude Agent Teams로 전환한 첫 실전. 듀얼 레포 ERP 시스템의 권한 체계를 프론트/백엔드 팀메이트와 병렬로 리팩토링한 8시간의 기록.
B2B SaaS 백엔드를 만들면서 도메인 모델링을 시작한 이야기. 마스터 문서 2,486줄을 쓰고, 유즈케이스를 정의하고, 핵심 엔티티 관계를 잡아가는 과정을 기록합니다.
Claude Code 세션 4개를 PM/BE/FE/QA로 나눠 3개월간 운영한 경험. session-sync.md로 에이전트 간 통신을 구현했지만, 사람이 중계하는 구조의 한계를 깨달은 이야기.
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에서 놓치지 않는 예방 전략을 실전 코드와 함께 정리한다.
Refine의 useCustom hook에서 config.query 객체에 number 타입 값을 전달해도, URL 쿼리 파라미터로 직렬화되면서 문자열이 된다. NestJS @Type(() => Number) 검증과 조합하면 targetClassId must be an integer number 400 에러가 터진다. URL 직접 삽입 패턴으로 해결한 실전 사례를 정리한다.
NestJS + Prisma 프로젝트에서 Soft Delete 필터를 Application Service에만 적용하고 Domain Repository를 누락하면, 삭제된 데이터가 배치 프로세스와 조회 API에서 좀비처럼 되살아난다. PM 코드 리뷰에서 11곳 추가 발견된 실전 사례를 통해, 레이어별 필터 점검 체크리스트와 grep 기반 검증법을 정리한다.
react-hook-form과 Zod를 연동할 때 자주 발생하는 6가지 트러블슈팅 사례를 정리합니다. zodResolver 미연결, defaultValues 타입 불일치, mode 설정 누락 등 실전에서 놓치기 쉬운 함정과 해결법을 코드와 함께 설명합니다.
NestJS 서비스에서 메서드 간 재귀 호출이 발생하면 스택 오버플로우와 504 Gateway Timeout이 터진다. 통계 API에서 추세 계산이 무한루프에 빠진 실전 사례를 통해, 재귀 호출 탐지법과 skipFlag 패턴으로 방어하는 방법을 정리한다.
Framer Motion whileInView로 만든 스크롤 애니메이션이 Chrome DevTools MCP 스크린샷이나 OG 이미지 생성에서 보이지 않는 원인은 IntersectionObserver의 뷰포트 의존성이다. initial hidden 상태가 캡처되는 근본 원인과 3가지 해결 전략을 실전 코드로 정리한다.
Docker에서 pnpm 모노레포 NestJS 프로젝트를 빌드하면 TypeScript 데코레이터 에러가 3132개 터진다. TypeScript 버전 충돌부터 tsconfig 누락, pnpm deploy --legacy, Prisma Client 수동 복사까지 — 4가지 함정과 해결법을 실전 코드로 정리한다.
1인 개발 모노레포에서 CI/CD 파이프라인을 구축하며 겪은 실전 트러블슈팅. Docker 빌드 경로 오류, 배포 자동화 실패, Cloud Scheduler 설정 함정까지 — 수동 배포의 고통에서 벗어나는 과정을 정리했다.
NestJS에서 Nest can't resolve dependencies 에러를 만나면 당황스럽습니다. 모듈 imports 누락, @Injectable() 빠짐, 순환 참조까지 — DI 에러의 3대 원인을 실전 코드로 분석하고, 서버 기동 테스트로 사전에 잡는 방법을 정리합니다.
shadcn init 실행 후 커스텀 CSS 변수가 기본값으로 덮어씌워지는 문제의 원인과 해결법을 정리합니다. 디자인 토큰이 초기화되는 근본 원인을 분석하고, git diff 기반 복구 및 예방 패턴을 코드와 함께 설명합니다.
Prisma seed 스크립트에서 deleteMany 순서를 잘못 잡으면 FK 제약 조건 위반 에러가 발생합니다. 테이블 의존 관계를 분석하고 자식→부모 순으로 삭제하는 실전 패턴을 정리합니다. 바로 적용할 수 있는 방법을 알려드릴게요.
스펙이 바뀔 때마다 API를 뒤엎지 않으려면? NestJS + Prisma 모노레포에서 겪은 5가지 스펙 변경 사고와 그로부터 얻은 API 설계 원칙을 정리했다.
Prisma가 생성한 enum과 도메인 타입이 TypeScript에서 호환되지 않아 빌드 에러가 발생합니다. 명시적 캐스팅 패턴과 아키텍처별 예방 전략을 정리합니다.
WordPress에서 Astro 5로 블로그를 마이그레이션하면서 겪은 콘텐츠 변환, SEO 보존, 빌드 에러, 댓글 시스템 전환까지. Cloudflare Pages 배포와 MDX 컴포넌트 설계 과정을 기록한다.
API가 200 OK를 반환하는데 프론트엔드에서 에러 페이지가 뜬다면, BE 응답 래퍼 구조를 의심하세요. useCustom + ApiWrapper 패턴으로 2중 언래핑하는 실전 해결법을 정리합니다.
Astro 블로그를 GitHub Actions와 Cloudflare Pages로 자동 배포하면서 만난 삽질들. Wrangler v3 설정부터 pnpm 캐시, Secrets 관리, 배포 실패 디버깅까지 실전 트러블슈팅.
React useEffect의 비동기 cleanup이 Pixi.js RenderTexture를 파괴하는 레이스 컨디션 버그를 추적합니다. 웹 브라우저에서는 정상인데 Vuplex WebView + 고사양 GPU에서만 재현되는 3중 함정의 원인과 해결법을 정리합니다.
NestJS + Prisma에서 콘텐츠 등록 시 Foreign key constraint violated 500 에러가 터졌습니다. 존재하지 않는 Level ID가 원인이었고, 저장 전 검증 패턴으로 해결한 과정을 정리합니다.
pnpm workspace + Turborepo 모노레포에서 의존성 관리 중 겪은 실전 트러블슈팅. TypeScript 버전 충돌, Docker 빌드 실패, Prisma Client 미생성, DI 에러까지 — 증상별 원인과 해결법을 정리했다.
NestJS에서 DTO를 interface로 만들면 400 에러와 Swagger 스키마 누락이 동시에 발생합니다. class-validator와 @ApiProperty가 작동하는 원리부터 해결까지 정리했습니다.
Oracle ARM 서버에 Umami를 Docker로 올리고, 4개 블로그에 트래커를 심으면서 만난 삽질들. TRACKER_SCRIPT_NAME이 안 먹는 문제부터 AdBlock 우회, WP mu-plugin 자동 매핑까지 실전 트러블슈팅.
Refine 기반 React 어드민에서 DataProvider 커스터마이징 시 흔히 겪는 두 가지 함정을 정리합니다. BE가 객체를 반환하는데 useList를 쓴 경우, 그리고 total 파싱 경로가 어긋난 경우의 증상·원인·해결법입니다.
Oracle ARM 서버에 CouchDB를 Docker로 올리고, Obsidian Self-hosted LiveSync 플러그인으로 실시간 메모 동기화를 구축하면서 만난 삽질들. CORS, max_document_size, 시스템 DB 누락까지 실전 트러블슈팅.
Express vs NestJS, TypeORM vs Prisma. B2B SaaS 백엔드를 만들면서 기술 스택을 고르기까지의 과정과 첫 커밋 이야기.
NestJS + Prisma 마이그레이션에서 테이블 하나를 빠뜨려 운영 DB에 컬럼 없음 에러가 터졌습니다. schema.prisma 변경 시 모든 모델을 확인하는 체크리스트와 migrate diff 예방법을 정리했어요.
1인 개발로 NestJS 백엔드 + React 프론트엔드를 모노레포로 구성한 이유와 pnpm workspace + Turborepo 세팅 과정을 정리했다. 삽질 포인트와 구조 결정 기록. 초보자도 따라할 수 있게 정리했어요.
Cloudflare Origin Certificate 발급부터 Nginx SSL 종단, PHP-FPM HTTPS 인식 문제까지. 멀티사이트 SSL 구성에서 만난 실전 트러블슈팅 기록. 실전 경험을 바탕으로 정리했어요.
Vite 6.x 개발 서버 프록시 환경에서 PATCH 요청만 CORS 에러가 발생하는 원인은 HTTP 메서드 대소문자입니다. toUpperCase() 한 줄로 해결하는 방법과 프록시 디버깅 체크리스트를 정리합니다.
PATCH 요청만 CORS에 막힌다면 allowedHeaders와 Vite 프록시를 의심하세요. 프리플라이트부터 해결까지 실전 트러블슈팅 기록. 지금 바로 확인해 보세요.
NestJS + Prisma에서 API가 갑자기 느려졌다면 N+1 쿼리를 의심하세요. 650개 쿼리를 2개로 줄인 실전 해결기와 예방법을 정리했어요.
Oracle Cloud Free Tier ARM 인스턴스에 Docker로 WordPress 멀티사이트를 올리면서 만난 문제들과 해결 과정. 무료 서버로 블로그 4개 운영하는 실전 인프라 구축기.
홈브루 명령어 한 줄로 맥북을 꾸미는 드레스업 패키지 총정리. 메뉴 바 정리, 폰트 설치, UI 유틸리티, 배터리 모니터링까지 다뤄요.
터미널 명령어 한 줄로 맥북 앱 설치를 자동화하는 홈브루(Homebrew) 설치법과 기본 사용법