왜 만들었나AI 코딩 에이전트한테 TDD로 구현해달라고 하면 대개 "테스트부터 작성하겠습니다"라고 답한다. 그런데 막상 작업을 들여다보면 테스트랑 구현이 한 번에 나오거나, 테스트를 한 번도 실패시켜보지 않은 채 초록 바만 보여주는 경우가 많았다. 프롬프트에 규칙을 적어두는 것만으로는 사이클이 지켜지지 않았다.그래서 규칙을 프롬프트가 아니라 훅에 넣었다. 이 하네스는 Java/Kotlin 백엔드 프로젝트에 설치하는 .claude/ 템플릿이고, RED -> GREEN -> REFACTOR 순서를 어기는 편집을 Claude Code의 PreToolUse 훅이 실제로 막는다. 핵심 원칙은 한 줄이다.상태는 에이전트의 말이 아니라 Gradle이 쓴 파일로만 바뀐다. 에이전트가 "RED 확인했습니다"라고 해도 소..
이전 글에서는 지도 홈 API(GET /map/me)를 그리드 셀 캐시, 픽셀 병합, 방향 기반 prefetch로 빠르게 만든 과정을 다뤘다. 그런데 캐시를 붙이면 반드시 따라오는 질문이 있다. 사진이 바뀌었을 때 뭘 얼마나 버려야 할까?너무 많이 버리면 캐시를 붙인 의미가 없고, 너무 적게 버리면 방금 올린 사진이 지도에 안 보인다. 이 글에서는 Lokit이 이 문제를 네 가지 장치로 나눠 푼 과정을 정리해보려 한다.커플 단위 변경 시퀀스 (MapMutationTracker)클라이언트와 주고받는 dataVersion / lastDataVersion포인트 기반 무효화와 커플 단위 무효화의 조합기본 앨범 정규화 요구사항사진을 올리거나, 위치를 고치거나, 앨범을 옮기거나, 지우면 다음 /map/me 응답에 ..
Lokit은 커플이 함께 찍은 사진을 지도 위에 기록하는 아카이빙 서비스다. 앱을 열면 제일 먼저 지도가 보이고, 사용자는 이 지도를 계속 끌고(pan) 확대/축소(zoom)한다. 그때마다 zoom 레벨에 따라 사진(POI)들이 클러스터로 묶였다가 다시 갈라진다. 이 글에서는 지도 홈 API(GET /map/me)가 지도를 움직일 때마다 DB를 처음부터 다시 훑지 않도록 만든 과정을 정리해보려 한다. 그리드 셀 단위 캐시, 픽셀 거리 기반 클러스터 병합, 이동 방향과 속도를 보고 미리 채우는 prefetch, 그리고 연속 zoom을 0.5 단위로 끊은 이유를 다룬다. 캐시 무효화와 dataVersion 이야기는 분량이 많아서 다음 글로 나눴다. 이 글은 "읽기 경로를 어떻게 빠르게 만들었나"에만 집중한다..
Lokit은 커플이 함께 찍은 사진을 촬영 위치 기준으로 지도에 쌓아두는 서비스다. 사용자가 앱에서 제일 많이 하는 건 지도를 움직이는 거고, 그다음이 알림함과 앨범 목록 보기다.이 흐름을 DB 쿼리로 옮겨보니 성격이 꽤 다른 쿼리들이 나왔다. 이 글에서는 쿼리 모양별로 인덱스를 어떻게 골랐는지, 그리고 그걸 서비스 중에 어떻게 반영했는지 정리해보려 한다. 요구사항기능쿼리 형태호출 빈도지도 이동화면 영역(bbox) 안의 사진 조회, 촬영 시각 최신순지도를 움직일 때마다알림함수신자별 최신순 정렬 + 오프셋 페이지네이션알림함 들어갈 때홈 배지안 읽은 알림이 하나라도 있는지 (EXISTS)홈 들어갈 때마다커플 조회user_id로 소속 커플 찾기 (EXISTS 서브쿼리)거의 모든 인가 경로고아 파일 정리 배치최..
Lokit 서버는 커플, 앨범, 사진, 지도, 알림, 사용자 여섯 개 도메인을 하나의 Spring Boot 애플리케이션 안에서 다룬다. 이 글에서는 이 도메인들을 DDD의 바운디드 컨텍스트처럼 나누고 각각을 헥사고날 계층으로 쌓은 구조, 그리고 그 규칙을 사람의 기억이 아니라 ArchUnit 테스트로 지키게 만든 방법을 정리해보려 한다. 요구사항도메인 규칙은 프레임워크 없이 테스트할 수 있어야 한다."커플은 최대 2명", "연결을 끊고 31일이 지나면 재연결 불가" 같은 규칙이 서비스의 핵심이다.JPA나 Spring 컨텍스트 없이 순수 단위 테스트로 검증할 수 있어야 한다.외부 시스템이 바뀌어도 도메인까지 번지면 안 된다.실제로 인프라는 AWS에서 GCP로 옮겨갔고, 지도 쿼리는 JPA가 아니라 Expo..
Lokit은 커플이 함께 찍은 사진을 지도 위에 아카이빙하는 서비스다.서버는 Spring Boot 4.0 + Kotlin + Java 24 위에서 돌고, 요청 처리 전체를 Virtual Thread(이하 VT)에 올려뒀다.이 글에서는 VT 위에서 StructuredTaskScope로 요청 하나 안의 독립 I/O를 병렬화한 과정과, 병렬화 때문에 새로 생긴 문제인 "DB 커넥션 수요 폭증"을 세마포어로 막으려다 결국 어떻게 정리했는지를 다뤄보려 한다.요구사항병렬화 대상이 된 흐름은 크게 세 가지다.흐름요청 하나 안의 독립 작업성격지도 홈 (GET /map/me)커플 앨범 목록 조회, 뷰포트 안 사진 클러스터 조회DB 2건사진 업로드S3 객체 존재 확인, 좌표 역지오코딩, 앨범 검증외부 HTTP 2건 + D..
Lokit은 커플이 함께 찍은 사진을 지도 위에 아카이빙하는 서비스다. 사진 한 장은 두 군데에 나뉘어 저장된다. 이미지 바이너리는 S3에, 위치나 앨범, 설명 같은 메타데이터는 PostgreSQL에 들어간다. 문제는 이 둘을 하나의 트랜잭션으로 묶을 수 없다는 점이었다. 이 글에서는 "어차피 둘 중 하나는 실패할 수 있다"는 걸 받아들이고, 실패하더라도 사용자 눈에는 안 보이는 쪽으로만 실패하도록 설계한 과정을 정리해보려 한다. 요구사항업로드 트래픽은 서버를 거치지 않는다.클라이언트가 Presigned URL로 S3에 직접 PUT하고, 서버에는 객체 URL과 메타데이터만 등록한다.사진 삭제 API의 성공 여부는 S3 상태와 상관없어야 한다.S3가 느리거나 잠깐 실패한다고 사용자의 "사진 삭제"가 실패하..
커플 서비스의 데이터에는 끝이 있다. 커플은 헤어지고, 사용자는 탈퇴하고, 알림은 금방 쓸모가 없어진다.그런데 "이제 지워야 할 때"가 왔다고 해서 요청이 들어오진 않는다.연결을 끊은 지 31일이 지났다고 누가 API를 호출해주는 게 아니다. 이 글에서는 Lokit에서 시간이 흘러야 상태가 바뀌는 데이터를 스케줄러로 어떻게 처리했는지 정리하고, 코드를 다시 보면서 발견한 구멍까지 같이 기록해보려 한다. 요구사항커플 연결을 끊고 31일 동안은 재연결할 수 있어야 한다.실수나 다툼으로 끊었다가 다시 돌아오는 경우를 위한 유예기간이다.유예기간이 지나면 커플의 사진, 앨범, 댓글, 이모티콘과 S3 원본을 파기한다.개인정보 보호법은 보유기간이 지나면 개인정보를 지체 없이 파기하도록 정하고 있다.특히 위치가 담긴 ..