당신의 에이전트가 쇼핑몰의 방문 분석 도구를 다른 회사 것으로 바꾼다고 하자. 새 스크립트를 넣고, 옛 스크립트를 빼고, 화면을 열어 보니 잘 뜬다. 오류도 없다. 그런데 일주일 뒤 보니 새 도구에는 숫자가 하나도 없다. 아무것도 깨지지 않았는데 아무것도 일하지 않았다.
부품을 바꾸면 무엇이 남나
부품을 새것으로 갈아 끼워도, 옛 부품에 맞춰 둔 주변 설정은 그대로 남아 새 부품을 오류 없이 막거나 헛돌게 한다. 보안 허용 목록, 옛 부품 전용 도우미 함수, 외부 콘솔의 동의 항목, 옛 부품의 크기에 맞춘 숫자가 그런 주변이다. 이것들은 옛 부품과 짝을 이루던 것이라, 짝이 바뀌어도 스스로 고쳐지지 않는다.
교체 작업은 보통 "옛것을 빼고 새것을 넣는다"로 생각한다. 실제로는 세 가지가 바뀐다.
- 부품 자체
- 그 부품을 허락하던 것(허용 목록, 권한, 동의 항목)
- 그 부품에 맞춰 두었던 것(도우미 함수, 크기·속도 같은 숫자)
1만 바꾸고 2·3을 두면, 새 부품은 들어왔지만 막혀 있거나 엉뚱한 값으로 움직인다. 그리고 대개 오류를 내지 않는다.
왜 오류가 안 나나
주변 설정은 대부분 "조용히 실패하는" 자리에 있다.
- 보안 허용 목록: 웹 페이지의 콘텐츠 보안 정책(CSP)이 옛 공급자 주소만 허락하면, 새 스크립트는 브라우저 콘솔에 경고 한 줄을 남기고 안 실린다. 페이지는 멀쩡히 뜬다.
- 옛 부품 전용 도우미: 라이브러리의 "이벤트 보내기" 함수가 특정한 로딩 방식을 전제하면, 로딩 방식을 바꾼 뒤 그 함수는 아무것도 안 하고 돌아온다. 기본 페이지뷰는 다른 길로 가므로 숫자가 "조금은" 들어와 정상처럼 보인다.
- 외부 콘솔과 코드의 짝: 로그인 제공자 콘솔에서 동의 항목을 끄는 것과, 코드가 그 항목을 요청하는 것은 따로 논다. 한쪽만 바꾸면 그 사이 모든 로그인이 실패한다.
- 옛 부품의 크기에 맞춘 숫자: 3D 인물이나 이미지·폰트처럼 크기가 있는 부품을 바꾸면, 옛 크기로 잰 보폭·여백·간격이 그대로 남아 미세하게 어긋난다. 정지 화면에선 안 보이고 움직일 때만 보인다.
공통점은 하나다. 새 부품이 "일했다"는 신호가 끝단에서만 보인다. 화면이 떴다, 빌드가 됐다, 오류가 없다는 중간 신호로는 알 수 없다.
교체 전에 무엇을 적나
교체 작업을 시작하기 전에 에이전트에게 "옛 부품에 기대고 있던 것"의 목록부터 만들게 한다. 저장소 전체에서 옛 부품의 이름·주소·함수명을 검색하면 대부분 나온다.
부품을 교체하기 전에:
1. 옛 부품의 이름, 도메인, 패키지명, 전용 함수명을 저장소 전체에서 검색해 목록을 만든다.
(보안 정책 헤더, 환경 변수, 문서·약관 문구, 테스트, 외부 콘솔 설정 포함)
2. 각 항목을 "허락하던 것" / "맞춰 두었던 것" / "그냥 언급"으로 나눈다.
3. 외부 콘솔과 코드가 짝을 이루는 항목은 바꾸는 순서를 정한다:
코드에서 먼저 빼고 → 배포 → 운영에서 확인 → 그다음 콘솔에서 끈다.
4. 교체 뒤 확인은 중간 신호(빌드·화면·무오류)가 아니라 끝단으로 한다:
실제 네트워크 요청, 실제 저장된 값, 실제 움직임을 잰다.
순서는 왜 중요한가
짝을 이루는 두 설정이 서로 다른 곳(코드와 외부 콘솔)에 있으면, 바꾸는 사이에 둘이 어긋난 시간이 생긴다. 이 시간을 없앨 수는 없으니 어긋난 동안에도 동작하는 쪽을 먼저 바꾼다.
- 무엇을 빼는 교체라면: 요청하는 쪽(코드)을 먼저 빼고, 허락하는 쪽(콘솔)을 나중에 끈다. 반대로 하면 코드가 아직 요청하는 것을 콘솔이 거절한다.
- 무엇을 더하는 교체라면: 허락하는 쪽을 먼저 열고, 요청하는 쪽을 나중에 넣는다.
- 보안 허용 목록은 새 공급자 주소를 먼저 더하고, 새 스크립트가 운영에서 실리는 것을 본 뒤에 옛 주소를 뺀다.
끝단 확인은 어떻게 하나
중간 신호는 "부품이 들어왔다"까지만 말한다. "부품이 일한다"는 끝단에서만 보인다.
- 분석·광고 스크립트: 운영 빌드에서 브라우저 네트워크 탭을 열고 새 공급자로 가는 요청이 실제로 나가는지, 응답이 200인지 본다. 페이지뷰뿐 아니라 직접 보내는 맞춤 이벤트도 본다.
- 로그인: 운영에서 실제 계정으로 한 번 로그인한다.
- 크기가 있는 부품(3D 모델·폰트·이미지): 제자리 미리보기가 아니라 실제로 움직이는 상태에서 잰다. 미끄러짐·어긋남은 움직일 때만 보인다.
- 가능하면 이 확인을 시험으로 고정한다. 다음 교체 때 같은 자리를 또 잊는다.
우리가 겪은 사례
- 분석 도구 교체와 보안 정책: 한 사이트에서 방문 분석 도구를 바꾸자 보안 정책이 옛 공급자 주소만 허락하고 있어 새 태그가 경고만 남기고 안 실렸다. 운영에서 태그 요청을 직접 보고 알았다.
- 로딩 방식 변경과 이벤트 함수: 분석 스크립트를 페이지 로드 뒤로 미루자 라이브러리의 이벤트 보내기 함수가 오류 없이 아무 일도 안 했다. 페이지뷰는 살아 있어 다음 날 전수 점검에서 실제 전송 요청을 캡처하고서야 맞춤 이벤트가 0인 걸 알았다.
- 로그인 동의 항목: 프로필 사진 동의를 빼려고 콘솔부터 끄면 라이브러리 기본 요청 범위가 그 항목을 계속 요청해 배포 전까지 모든 로그인이 실패하는 구조였다. 코드 → 배포 → 확인 → 콘솔 순서로 바꿨다.
- 3D 인물 교체: 외부에서 받은 새 인물로 갈자 옛 인물에 맞춘 보폭이 그대로 남아 발이 땅을 미끄러졌고, 이름으로 찾는 뼈만 남기니 나머지 뼈에 실린 움직임(채널 85개 중 43개)이 같이 사라졌다. 제자리 미리보기에선 안 보여 실제 클립을 돌려 재는 시험을 만들었다.
- 곁 사례로, 3D 장면의 후처리 단계는 해상도 배율을 처음 만들 때 한 번만 읽어서, 나중에 렌더러 배율만 바꾸는 품질 조절 코드가 오류 없이 효과가 없었다. 부품 하나가 옛 값을 쥐고 있던 경우다.