'같은 것'을 정하는 건 받는 쪽이다 — 이름과 키는 받는 쪽의 동일성 규칙으로 짓고, 쓴 뒤에 실제로 바뀌었는지 센다

맥에서 한글 파일명을 정리하는 스크립트를 돌렸는데 rename 을 해도 이름이 하나도 안 바뀐다. GA4 유입 보고서에 tab 이나 (not set) 같은 이상한 출처가 섞여 있다. Vercel 프리뷰 배포를 다시 띄우려고 같은 커밋을 새 가지로 push 했는데 아무것도 안 생긴다. 공공 데이터를 매일 수집하는 표에 같은 거래가 두 줄씩 쌓인다. 넷 다 오류는 없다. 당신의 스크립트나 에이전트는 "성공"으로 끝났다.

왜 오류 없이 무시되거나 덮어써지나

쓰기를 받는 시스템은 저마다 '같은 것'을 가르는 규칙을 갖고 있고, 그 규칙이 당신의 생각과 어긋나면 쓰기는 오류 없이 무시되거나 남의 값을 덮어쓰거나 중복으로 쌓인다. 파일 시스템은 유니코드 정규화로, 분석 도구는 예약된 파라미터 이름으로, 배포 연동은 커밋 해시로, 데이터베이스는 당신이 정한 멱등키로 같은지를 판단한다. 받는 쪽이 보기에 "이미 있는 것"이면 할 일이 없고, "같은 이름"이면 덮어쓰고, "다른 것"이면 새로 넣는다. 셋 다 받는 쪽에서는 정상 동작이라 오류를 낼 이유가 없다.

어떤 규칙들이 '같다'를 정하나

흔히 부딪히는 규칙은 넷이다.

• 유니코드 정규화(파일 시스템). 한글 '가'는 완성형 한 글자(NFC)로도, 자모 두 개(NFD)로도 적을 수 있다. 맥의 파일 시스템은 둘을 같은 이름으로 본다. 그래서 NFD 로 저장된 파일을 NFC 이름으로 바꾸라고 하면 "이미 그 이름"이라 아무 일도 하지 않는다. 겉보기엔 같아도 바이트가 다른 이름이 그대로 남고, 그 이름에서 분류를 뽑는 다음 단계가 깨진다. 정규화 형식은 유니코드 표준 부록 15에 정의돼 있다.
• 예약된 이름(분석 도구). GA4 이벤트에 source 라는 파라미터를 붙이면 GA4 는 그것을 당신의 이벤트 속성이 아니라 유입 출처로 읽는다. "어느 탭에서 눌렀나"를 담으려던 값이 그 세션의 유입 출처를 덮어쓴다. medium, campaign 도 같다.
• 커밋 해시(배포 연동). Git 연동 배포는 이미 본 커밋 SHA 를 다시 받으면 새 배포를 만들지 않는다. 다른 가지로 push 해도, 강제 push 로 가지 끝을 옮겨도 같다. "건너뜀" 기록조차 없어서 연동이 죽은 것처럼 보인다.
• 멱등키(데이터베이스). 같은 레코드를 두 번 넣지 않으려고 만든 키에, 원천이 나중에 채우는 칸(등기 뒤에 붙는 번호 같은 것)이 들어 있으면, 그 칸이 채워지는 날 같은 레코드가 "다른 것"이 되어 새 줄로 들어간다.

앞의 셋은 받는 쪽이 당신보다 넓게 "같다"고 본 경우이고, 마지막은 당신이 만든 키가 너무 좁게 "같다"고 본 경우다. 방향은 반대지만 증상은 같다 — 오류 없이 결과가 틀린다.

쓰기 전에 무엇을 확인하나

새 시스템에 이름·키를 붙여 쓸 때 이 목록을 한 번 지난다.

1. 받는 쪽은 무엇으로 같은지를 가르나? 이름의 바이트인가, 정규화된 글자인가, 대소문자를 무시하나, 해시인가, 내가 정한 키인가.
2. 내 이름이 받는 쪽의 예약어와 겹치나? 분석 도구·메일 헤더·폼 필드·환경변수처럼 특별한 뜻을 가진 이름 목록이 있는 곳에서는 범용 단어(source, type, name, id)를 피하고 접두어를 붙인다(ui_source, click_origin).
3. 키에 나중에 바뀌는 칸이 들어 있나? 멱등키에는 처음부터 고정인 칸만 넣는다. 나중에 채워지는 칸이 꼭 필요하면, 채워진 줄이 들어올 때 빈 쪽 줄을 지우는 규칙을 같이 둔다.
4. "다시 하기"가 정말 새 일로 보이나? 같은 입력을 다시 보내 재실행을 기대하는 일(배포 재시도, 캐시 무효화)은 받는 쪽이 그것을 새 입력으로 보는지 먼저 본다. 아니면 입력을 바꾼다(빈 커밋 하나라도).

쓴 뒤에는 무엇을 세나

성공 응답은 "받았다"는 뜻이지 "바뀌었다"는 뜻이 아니다. 쓰기 뒤에 결과를 직접 센다.

• 이름을 바꿨으면 바꾼 뒤 목록을 다시 읽어 바이트 단위로 비교한다(정규화 전후 길이가 다르면 아직 NFD 다).
• 이벤트를 보냈으면 보고서에서 그 이벤트가 붙은 세션의 유입 출처가 바뀌지 않았는지 본다.
• 배포를 다시 띄웠으면 배포 목록에 새 항목이 생겼는지 본다.
• 수집을 돌렸으면 키에서 바뀌는 칸을 뺀 조합으로 중복을 센다.

에이전트에게 맡긴다면 지침에 이렇게 적어 둔다.

이름·키를 붙여 바깥 시스템에 쓸 때:
- 받는 쪽이 무엇으로 '같다'를 판단하는지(정규화·대소문자·예약어·해시·멱등키) 먼저 확인한다.
- 범용 단어(source, medium, campaign, type, name)를 파라미터 이름으로 쓰지 않는다. 접두어를 붙인다.
- 성공 응답을 결과로 보고하지 않는다. 쓰기 뒤에 다시 읽어 실제로 바뀌었는지 세고 그 수를 보고한다.
- 맥에서 파일 이름을 NFC 로 바꿀 때는 임시 이름을 거쳐 두 번 바꾼다.

우리가 겪은 일

• 파일명 정리(맥, APFS). NFD 로 저장된 한글 파일을 NFC 이름으로 rename 하니 아무 일도 안 일어났다. 임시 이름으로 한 번 바꾼 뒤 NFC 이름으로 바꾸자 정규화됐다. 파일명에서 분류를 뽑던 업로드가 그 전까지 깨져 있었다.
• GA4 유입 출처. 버튼 클릭 이벤트에 source 파라미터로 탭 이름을 실었더니, 버튼을 누른 세션의 유입 출처가 탭 이름으로 바뀌어 보고서에 tab 같은 출처가 섞였다. 파라미터 이름을 바꾸자 사라졌다.
• Git 연동 배포. 프리뷰를 다시 띄우려고 같은 커밋을 강제 push 하고 새 가지로도 push 했지만 배포가 생기지 않았고 건너뜀 기록도 없었다. 새 커밋을 얹자 구워졌다.
• 실거래 수집. 원천이 나중에 채우는 칸을 멱등키에 넣었더니 그 칸이 채워지는 순간 같은 거래가 새 줄로 들어와 중복이 조용히 쌓였다. 키에서 그 칸을 빼고, 채워진 줄이 오면 빈 쪽을 지우게 고쳤다(취소 기록처럼 상태가 다른 줄은 따로 남긴다).

네 곳 모두 응답은 성공이었다. 알아챈 것은 결과를 다시 셌을 때 — 이름 목록, 보고서의 출처 칸, 배포 목록, 중복 수 — 였다.