프로젝트 전환 시 만나는 서버 함정 문서화

한 서비스에서 다른 서비스로 인수인계하거나 전환하는 과정은 생각보다 복잡하다. 겉으로는 "코드만 옮기고 배포하면 되지 않나" 싶지만, 실제로는 배포 환경, 네트워크 설정, 외부 연동 등 크고 작은 차이들이 도사리고 있다. psy에서 curiodot로 전환하면서 우리 팀이 마주한 서버 함정들—배포타겟, 포트, indexnow, 위젯 설정 관련 이슈들이—반복되지 않도록 이번엔 팀 공통 지침에 기록해 둔 것이다.

왜 문서화가 필요했는가

프로젝트 전환은 보통 한두 번 경험한다. 첫 번째엔 신기하고 배운다. 두 번째엔 "어? 지난번에도 이 문제 겪지 않았나?" 하면서 검색하느라 시간을 쓴다. 세 번째엔 팀 전체가 같은 함정에 빠진다. 이건 개인의 메모리 문제가 아니라 팀 차원의 학습 시스템이 없다는 뜻이다.

CLAUDE.md 같은 공통 지침 파일은 이런 상황에서 진가를 발휘한다. 새 팀원이 온보딩될 때, 새로운 프로젝트 전환이 생겼을 때, 누군가 같은 실수를 반복하려 할 때—"아, 이미 문서화되어 있네" 하고 즉시 답을 찾을 수 있다. 그것만으로 리뷰 시간, 디버깅 시간, 재작업 시간이 확 줄어든다.

함정의 구체적 항목들

이번에 기록한 함정들은 대략 이렇다:

각각은 작아 보이지만, 배포 직후 문제가 터진다. 배포타겟 설정이 잘못되면 의도와 다른 환경에 코드가 올라간다. 포트가 막혀 있으면 실제로 서비스에 접근할 수 없다. indexnow 설정 누락은 검색 시에만 눈에 띈다. 위젯 설정 오류는 고객 사이트에서 발견되기도 한다.

팀 리딩 차원의 선택

나는 이 문제들을 발견했을 때 여러 선택지가 있었다:

1. Slack에 공지 — 당장의 커뮤니케이션은 빠르지만, 한 달 뒤엔 사라진다.
2. 개별 코드리뷰 시 언급 — 대상자는 배우지만, 다른 팀원은 모른다.
3. 팀 공통 지침에 기록 — 느리게 보이지만, 구조화되고 지속된다.

당연히 3번을 택했다. CLAUDE.md는 모든 팀원이 프로젝트 셋업할 때 읽는 파일이고, 아키텍처 결정이나 주의사항을 담는 공식 채널이다. 여기에 "프로젝트 전환 시 이런 함정 있다" 라고 명시해 두면, 다음 번 유사 상황에서 온보딩하는 사람도, 기존 팀원도 즉각적으로 참고할 수 있다.

회고: 문서화의 효과

이런 "함정 지침"을 남기는 것의 가치는:

• 온보딩 시간 단축: 새 팀원이 프로젝트 역사를 배울 때, "이런 실수들이 있었다" 라는 사실을 미리 알고 들어간다.
• 반복 실수 방지: 배포/검색엔진/위젯 같은 설정은 계속 반복되는 작업이다. 한 번 기록해 두면 다음 담당자는 체크리스트처럼 쓸 수 있다.
• 심리적 안정감: 팀원들이 "우리가 이 문제를 이미 알고 있다"는 사실을 알면, 배포할 때나 새로운 환경을 셋업할 때 자신감이 생긴다.
• 코드리뷰 효율: 리뷰할 때 "이건 문서 참고해" 라고 한 줄로 끝낼 수 있다.

총괄 입장에서 보면, 팀이 배운 것들을 구조화하는 것이 결국 팀의 생산성과 심리 안정성을 높인다. 이번 커밋은 코드 한 줄 없이 문서 몇 줄만 추가한 작은 것이지만, 팀 차원의 학습 문화를 만드는 일이다.

🛒 이 글과 어울리는 추천 상품

• 사무의자 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.