인프라 설정 문서를 동료와 정합했다

개인 저장소에서 팀 저장소로 전환하면서 마주하는 문제 중 하나가 문서와 현실의 괴리다. 특히 여러 사이트가 각기 다른 설정을 갖고 있을 때, 누가 언제 어떤 설정을 적용했는지, 그 설정이 왜 필요한지가 명확하지 않으면 나중에 유지보수하는 사람은 그야말로 지뢰밭을 걷게 된다. 이번엔 한 사이트의 인프라 설정 정보를 동료와 맞추고, 그 과정을 사이트 상세 가이드 문서에 정리한 작업이다.

사이트마다 다른 설정, 어떻게 관리할 것인가

팀에 여러 개발자가 있고 여러 사이트를 운영하다 보면, 각 사이트마다 특수한 요구사항이 생긴다. 예를 들어 레거시 서비스에서 신규 인프라로 전환할 때, 완전히 갈아엎을 수도 있지만 대부분은 과도 기간을 거친다. 이 과도 기간에는 구버전 식별자(여기서는 PV)와 현재 운영 중인 설정이 모두 유효해야 한다.

문제는 이런 디테일이 팀원마다 다르게 이해되기 쉽다는 점이다. A가 "이건 레거시니까 결국 제거된다"고 생각했는데, B는 "아직 운영 중인 기능이다"라고 생각하면 상충이 생긴다. 커밋 로그나 구두 커뮤니케이션만으로는 부족하고, 정해진 가이드 문서가 단일 진실 공급원(single source of truth) 역할을 해야 한다는 걸 깨달았다.

작업 내용: PV 매핑과 nginx 정리

이번 작업의 구체적인 내용은 다음과 같다:

PV 매핑은 "옛날엔 이 ID로 불렀는데 지금은 이렇게 변했다"는 관계를 기록하는 것이다. 마이그레이션 과정에서 이 정보가 명시되지 않으면, 나중에 모니터링 대시보드가 깨지거나 로그를 추적할 때 혼란스러워진다. 동료가 모르는 사이에 ID가 바뀌었다고 착각하고 중복 작업을 할 수도 있다.

nginx stale 설정 제거는 한 번은 필요했던 구설정이 이제 불필요해졌다는 판단을 하고 정리한 것이다. 하지만 이건 신중해야 한다. "stale 응답을 허용하겠다"는 정책이 어떤 이유로 들어갔는지, 정말 제거해도 괜찮은지 확인해야 한다. 예를 들어 한때 연결이 불안정했던 레거시 환경에서는 stale을 허용하는 게 필수였지만, 신규 인프라는 충분히 안정적이므로 불필요한 경우가 많다. 그래도 남겨진 이유가 있을 수 있으니 동료에게 확인하는 게 맞다.

내부 슬러그 유지는 "팀 내부에서 이 사이트를 이 이름으로 부르자"는 일종의 계약이다. 코드나 문서에서 이 슬러그로 참조하는 곳이 많다면, 갑자기 바꾸면 PR이나 스크립트가 깨진다. 그래서 "이 부분은 변경하지 않되 명시적으로 정책을 쓴다"는 결정을 했다.

동료 정합 과정이 중요한 이유

혼자 판단해서 문서를 쓸 수도 있었겠지만, 그렇게 하면 안 되는 이유가 있다.

첫째, 내가 놓친 정보가 있을 수 있다. 동료가 "아, 그 stale 설정은 사실 지난달에 다른 팀에서 변경했어"라고 말해주면 나의 이해가 틀렸다는 걸 알 수 있다.

둘째, 팀원의 동의 없이 "이렇게 하자"고 문서화하면, 나중에 그 문서를 신뢰하지 않는다. "저 글도 한 사람의 추측이겠지"라는 태도가 생기고, 문서는 점점 낡아간다. 반면 여러 사람이 검증한 문서는 사실상의 규칙(de facto standard)이 된다.

셋째, 의사결정 과정을 기록하는 것 자체가 가치다. "왜 이렇게 했는가"를 모르는 사람이 나중에 "이거 필요 없는 거 아닌가?" 하고 또 건드리는 불필요한 반복을 줄인다.

배운 점과 앞으로

이번 작업으로 깨달은 건, 인프라 설정 같은 공유 자산은 문서화 속도보다 정확성과 일관성이 훨씬 중요하다는 것이다. 커밋을 100개 더 빠르게 하는 것보다, 한 번의 명확한 정합과 기록이 팀의 생산성을 훨씬 높인다.

특히 사이트마다 예외 사항(예: "이건 보안상 이유로 안 지운다", "이건 A팀과의 계약 때문에 유지한다")이 있을 때, 그걸 문서에 명시하는 게 얼마나 중요한지 실감했다. 코드만으로는 "왜 이렇게 했는가"를 표현하기 어렵거든.

다음엔 다른 사이트들도 이 방식으로 문서를 정리해야겠다. 그리고 문서 변경이 있을 때는 자동으로 해당 팀에 노티를 날릴 방법도 생각해봐야겠다.

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

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

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