팀 블로그 도메인 통합, 문서와 배포 스크립트까지 정정하기
목차
동료 블로그가 새로운 도메인으로 이전되면서 우리 팀 문서 전체에 산재된 참조들을 정리하는 작업을 했다. 단순히 링크 몇 개를 바꾸는 수준이 아니라, 중앙 문서(CLAUDE.md)부터 자동화 스크립트까지 전반적으로 정정해야 했던 경험이다.
도메인 이전이 미치는 범위가 생각보다 넓다
처음 작업 지시를 받았을 때는 "werebridge.com에서 mingsblog.hedvion.com으로 링크 몇 개 바꾸면 되겠지" 정도로 생각했다. 하지만 막상 팀 문서들을 뒤져보니 참조가 한두 곳이 아니었다. 특히 CLAUDE.md처럼 여러 팀원이 참고하는 중앙 문서에는 행15, 행16 같은 여러 곳에 걸쳐 옛 도메인 참조가 있었고, 심지어 배포나 동기화(rsync) 로직을 담당하는 스크립트까지 영향을 받고 있었다.
이런 상황은 흔히 간과하기 쉽다. 도메인 이전 담당자가 "사용자 페이지는 리다이렉트 처리했으니 괜찮겠지" 생각할 수 있지만, 자동화 스크립트나 배포 프로세스에 하드코딩된 URL은 리다이렉트로 해결 안 된다. 예컨대 rsync로 데이터를 동기화할 때 소유권(owner) 확인이나 원본 경로 검증 같은 부분에서 옛 도메인이 임베딩되어 있으면, 스크립트가 오동작할 여지가 생긴다.
섹션 정리와 오기 정정의 중요성
이번 작업에서 주목할 점은 단순한 텍스트 치환(find & replace)이 아니었다는 것. 행15, 행16을 정정한 것 외에도 "섹션" 부분을 정리했다고 기록되어 있는데, 이는 문서의 논리적 구조까지 검토했다는 뜻이다. 도메인이 변경되면 자연스럽게 그 링크가 가리키는 컨텍스트도 달라질 수 있으니, 문서 섹션 내 설명이나 맥락도 함께 다듬어야 한다.
특히 "rsync 주체 오기"를 정정했다는 부분이 흥미롭다. 이것은 단순한 철자 오류가 아니라, 시스템의 권한 흐름이나 프로세스 소유권 명시와 관련된 것 같다. 팀 문서에 자동화 스크립트의 실행 주체(owner)나 권한 설정이 제대로 반영되지 않으면, 새로 온 팀원이나 온콜 담당자가 장애 대응할 때 혼란스러울 수 있다.
중앙 문서의 정확성이 팀 전체 신뢰를 결정한다
CLAUDE.md 같은 중앙 문서는 팀의 "소스 오브 트루스(source of truth)"다. 누군가 "우리 팀의 배포 프로세스가 뭐라고?" 물었을 때, 그사람이 참고하는 첫 번째 자료다. 만약 그 문서에 옛 도메인이나 잘못된 owner 정보가 남아 있다면, 누군가는 그것을 따라 실수를 반복할 것이다.
이번처럼 도메인 이전이나 조직 변화가 생기면, 단순히 "영향받는 시스템 관리자에게만 공지"하는 수준이 아니라, 팀이 공유하는 문서 전체를 감시(audit)하는 습관이 중요하다. 특히 자동화나 배포와 관련된 부분은 문서가 정확하지 않으면 직접적인 운영 장애로 이어진다.
비슷한 리소스 이전할 때 체크리스트
팀 내에서 도메인, API 엔드포인트, 계정명 같은 변경이 생기면, 다음 정도는 검토해 볼 가치가 있다:
- 중앙 문서(README, CLAUDE.md, 온보딩 가이드) — 여기가 가장 중요
- 배포/자동화 스크립트 — 하드코딩된 URL이나 owner 필드
- 팀 위키나 노션 같은 협업 문서 — 의외로 오래된 참조가 많음
- CI/CD 파이프라인 설정 — secret, endpoint, webhook URL
- 모니터링·로깅 설정 — 쿼리나 필터에 임베딩된 이름/경로
이번 작업은 작아 보였지만, 팀 리소스를 통합하거나 이전할 때 "얼마나 꼼꼼하게 전체 시스템을 점검하는가"가 나중의 버그나 운영 비용을 얼마나 줄이는지 보여준다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.