유피노트

백엔드/API설계

TypeScript Branded Types로 타입 안전성 높이기

모든 ID가 string 타입이라 인자 순서를 바꿔도 컴파일 에러가 안 났습니다. Branded Types 패턴으로 런타임 오버헤드 없이 타입 안전성을 확보한 방법을 공유합니다.

인프라/Docker

폐쇄망에서 pip install 사용하기: pypiserver + Docker로 PyPI 미러 서버 구축

외부 인터넷이 차단된 폐쇄망 환경에서도 `pip install`로 Python 패키지를 설치할 수 있습니다. pypiserver + Docker를 활용한 PyPI 미러 서버 구축 방법을 단계별로 설명합니다.

백엔드/API설계

Promise.all vs Promise.allSettled: 부분 실패를 허용하는 벌크 처리

100명에 대해 데이터를 생성하는데 1명이 실패하면 전체 99명도 실패로 처리되었습니다. Promise.allSettled로 부분 실패를 허용하는 벌크 처리를 구현한 방법을 공유합니다.

AI/Claude Code

Rust CLI 배포 자동화: Homebrew, Scoop, Shell Installer를 GitHub Actions로 한 번에 구축하기

Rust CLI 도구를 태그 하나로 6개 플랫폼에 자동 배포하는 방법. Homebrew tap, Scoop bucket, Shell installer를 GitHub Actions로 구축한 실전 경험을 공유합니다.

백엔드/API설계

API 에러 추적 개선하기: errorId 패턴으로 디버깅 시간 단축

"서버 오류가 발생했습니다" 메시지만으로는 어떤 에러인지 특정할 수 없었습니다. errorId 패턴으로 디버깅 시간을 90% 단축한 방법을 공유합니다.

백엔드/API설계

JavaScript 타임존 함정 피하기: UTC vs Local 날짜 처리

1월 31일을 선택했는데 1월 30일로 저장되는 버그를 발견했습니다. JavaScript Date 생성자의 타임존 해석 방식을 이해하고, 정오(12:00) 패턴으로 해결한 방법을 공유합니다.

백엔드/API설계

Next.js API에 Rate Limiting 구현하기 (메모리 기반)

API 보안을 위해 Rate Limiting이 필요했습니다. Redis 없이 메모리 기반으로 구현하고 HTTP 429 표준을 준수한 방법을 공유합니다.

도구/GitHub

GitHub Issues 완전 가이드: Epic, Sub-Issues, Labels로 프로젝트를 체계적으로 관리하는 법

GitHub Issues를 단순한 버그 트래커가 아닌, 프로젝트 전체 로드맵을 관리하는 도구로 활용하는 실전 가이드. 2025년 GA된 Sub-Issues를 포함해 Epic, Labels, Pin, Projects 통합까지 다룹니다.

백엔드/Prisma

Prisma 일괄 업데이트에서 동시성 이슈 해결하기 ($transaction 활용)

두 사용자가 동시에 일괄 상태 변경을 실행했을 때 데이터가 꼬이는 버그를 발견했습니다. Prisma $transaction으로 TOCTOU 취약점을 해결한 방법을 공유합니다.

백엔드/Prisma

Prisma Extension으로 민감 데이터 암호화 자동화하기

개인정보보호법 준수를 위해 DB 민감 데이터를 암호화해야 했습니다. Prisma Extension으로 투명한 암호화를 구현하고, Blind Index로 검색 문제까지 해결한 경험을 공유합니다.

프론트엔드/React

Vitest와 MSW로 React Hook 테스트하기 (실전 가이드)

Jest 테스트가 느려서 Vitest로 마이그레이션했습니다. MSW와 함께 Custom Hook을 테스트하는 실전 가이드를 공유합니다.

개발환경/Python

pyenv rehash 락 파일 에러 해결: "couldn't acquire lock" 60초 멈춤 문제

pyenv rehash가 "couldn't acquire lock" 에러와 함께 60초 동안 멈추는 문제의 원인은 스테일 락 파일입니다. 소스 코드의 noclobber 메커니즘을 분석하고, 해결 방법과 --no-rehash를 활용한 예방법을 정리했습니다.

프론트엔드/크롬확장

크롬 확장 공유 모듈 설계: 중복 코드 470줄 제거기

popup, options, manager, onboarding 4개 페이지에 복사된 동일한 코드를 발견했습니다. shared/ 폴더에 기능별 모듈로 추출하여 총 215줄을 줄이고, DOM 메서드로 XSS를 방지하는 아이콘 팩토리까지 구현한 과정을 공유합니다.

프론트엔드/크롬확장

크롬 확장 프로젝트 구조 정리하기: popup, options 폴더 분리

크롬 확장 루트 디렉토리에 뒤섞인 파일들을 기능별 폴더로 정리했습니다. manifest.json 경로 업데이트, git mv로 히스토리 보존, 트러블슈팅 팁까지 리팩토링 전 과정을 공유합니다.

AI/Claude Code

Astro Starlight + Vercel: 코드 없이 만드는 프로젝트 문서 사이트 실전 가이드

오픈소스 프로젝트 문서 사이트를 Astro Starlight로 구축하고 Vercel에 배포한 실전 가이드. 코드라고 할 만한 것이 거의 없이, 마크다운과 설정 파일 3개만으로 전문적인 다국어 문서 사이트를 완성한 경험을 공유합니다.

백엔드/Prisma

Prisma N+1 쿼리 성능 문제 해결하기 (50% 속도 개선)

API 응답이 느려서 쿼리 로그를 분석했더니 N+1 유사 패턴이 발견되었습니다. Prisma의 관계 중첩을 활용해 쿼리를 통합하고 50% 성능 개선을 달성한 방법을 소개합니다.

백엔드/Prisma

Prisma Decimal to Number 변환 시 silent failure 방지하기

API에서 계산 결과가 NaN으로 표시되는 버그를 발견했습니다. Prisma Decimal 타입을 Number()로 변환하면서 발생한 silent failure를 safeNumber 패턴으로 해결한 방법을 공유합니다.

백엔드/인증-보안

Express 프록시 레이어에서 파일 다운로드 자동 암호화 구현하기

http-proxy-middleware의 selfHandleResponse 옵션을 활용해 파일 다운로드 응답을 가로채고 AES-256-GCM으로 암호화하는 방법. 전략 패턴으로 사내 API 연동도 준비.

백엔드/인증-보안

민감 데이터 접근 추적: Audit Logging 구현하기

개인정보보호법과 GDPR 준수를 위해 민감 데이터 접근 이력을 추적해야 했습니다. Context 기반 감사 로깅과 Fire-and-forget 패턴으로 구현한 경험을 공유합니다.

인프라/네트워크

Tailscale로 Oracle Cloud 서버 SSH 포트 완전 차단하기: Bastion 대신 VPN을 선택한 이유

fail2ban으로 하루 250건의 SSH 공격을 막고 있었지만, Tailscale을 도입해 SSH 포트를 아예 닫아버렸습니다. Bastion Host 대신 Tailscale을 선택한 이유와, Oracle Cloud Security List, UFW, Termius 설정까지 완전한 가이드입니다.

Ghost/설치-운영

Ghost 셀프 호스팅 블로그 TTFB 3.7초 → 0.4초: Cloudflare Cache Rule로 87% 속도 개선

Ghost CMS는 기본적으로 HTML에 max-age=0을 설정해서 Cloudflare 캐시가 작동하지 않습니다. Cache Rule 하나로 TTFB를 3.7초에서 0.4초로 줄인 방법을 공유합니다.

AI/Claude Code

Obsidian CLI 없이 플러그인 E2E 테스트하기: Electron CDP 활용법

Obsidian CLI가 Early Access(v1.12+)라 사용할 수 없을 때, Electron의 Chrome DevTools Protocol을 활용해 플러그인 E2E 테스트를 구현한 경험을 공유합니다. 실제 버그 발견부터 11개 옵션 조합 테스트까지.

AI/Claude Code

claude-dashboard v1.10~v1.13: 테마, 성능 최적화, 그리고 셸 통합까지

claude-dashboard v1.10부터 v1.13까지 6번의 릴리스에 담긴 변경사항을 정리합니다. 테마 시스템, Effort Level 표시, 성능 최적화, 그리고 터미널에서 바로 쓰는 check-ai 커맨드까지.

Ghost/설치-운영

Ghost 셀프 호스팅에서 Google AdSense ads.txt 설정하기 (NPM + Docker)

Ghost는 정적 파일 서빙이 제한적이라 ads.txt를 직접 올릴 수 없습니다. NPM의 Advanced 설정에 location 블록을 추가해서 해결하는 방법을 정리했습니다.

프론트엔드/Next.js

Next.js "Event handlers cannot be passed to Client Component" 에러 해결

Next.js App Router에서 loading.tsx를 추가했더니 빌드 에러가 발생했습니다. 'use client' 컴포넌트의 prerendering 동작을 이해하고 Server/Client 분리 패턴으로 해결한 경험을 공유합니다.