신규 사이트 온보딩 복잡도를 문서로 풀다

신규 사이트 온보딩 문서를 보강했다. 포크 구조의 다국어 라우팅 설정([lang] 라우트)과 external apex CMS 수동등록 절차를 명시적으로 기록했다. 작은 변경이지만 팀 규모가 커질수록 이런 "프로세스 문서화"의 중요도는 급격히 올라간다.

왜 문서를 다시 손봐야 했나

사내 내부 정책 다국어 서비스를 포크해서 새로운 사이트를 추가하는 일이 점점 빈번해졌다. 초기엔 경험 많은 개발자 1-2명이 직접 셋업했지만, 팀이 성장하면서 신입이나 다른 팀원들도 이 작업을 맡게 됐다. 그 순간부터 문제가 터지기 시작했다.

포크 사이트 온보딩은 단순해 보이지만 실제론 꽤 복잡하다:

• 다국어 라우팅 설정 — [lang] 라우트를 어떻게 등록하고, 폴백은 어떻게 되는지, 각 지역별 설정의 차이는?
• CMS 연동 — 기존 cms_site를 단순히 복사하는 게 아니라, external apex에 수동으로 등록해야 한다는 점
• 검증 단계 — 설정을 다 했다고 해서 끝이 아님. 각 언어/지역에서 제대로 라우팅되고 CMS가 정상 동작하는지 확인 필요

문서화 없이 진행하면 이런 일들이 반복된다:
- 신입이 기존 사이트 코드를 따라 가다가 "어? 왜 이건 이렇게 되어 있지?" 에서 멈춤
- "다국어 라우트를 등록했는데 왜 302 리다이렉트가 안 되는 거지?" 라는 질문
- CMS 설정을 빠뜨렸는데 배포 후에 라이브에서 발견 → 긴급 대응
- "마지막에 뭘 확인해야 하는 거죠?" 같은 질문

팀원들이 비슷한 지점에서 막히거나 실수하는 패턴을 보면서, "구두 설명" 만으로는 한계가 있다는 걸 깨달았다.

NEW-SITE-ONBOARDING.md에 추가한 것들

온보딩 문서에 다음 두 가지를 명시적으로 기록했다:

1) [lang] 라우트 정책 및 설정 방식

포크 사이트에서 다국어를 지원할 때 라우팅이 실제로 어떻게 동작하는지를 풀어 썼다. 기본 설정(기본 언어 설정, 폴백 로직), 주의점, 흔한 실수까지 담았다:
- 라우트 등록 누락했을 때의 증상
- 미들웨어 순서가 잘못됐을 때 어떤 버그가 생기는지
- CMS와 코드의 언어 설정이 불일치했을 때 어떻게 보이는지

체크리스트 형태로도 정리해서, 신입이 따라갈 수 있도록 했다.

2) External apex CMS 수동등록 절차

왜 수동 등록을 해야 하는지부터 시작해서:
- 어떤 필드가 필수고 어떤 필드가 선택사항인지
- 등록 후 어떻게 검증할 것인지 (admin 콘솔 확인, 라이브 환경 테스트)
- 흔한 오류 시나리오와 대응 방법

팀 규모와 문서화 ROI

초보자 입장에서 "비동기적으로 배울 수 있다" 는 게 얼마나 중요한지를 이번에 다시 느꼈다. 누군가의 시간을 빌려 설명을 듣는 것보다, 자신의 페이스로 문서를 읽고 진행할 수 있다면:
- 선배 개발자에게 물어볼 시간 절감
- 야근 없이도 온보딩 완료 가능
- "왜?"를 문서에서 찾을 수 있으니, 단순 복사가 아니라 깊이 있는 이해

팀 규모 관점에서 이런 "저수준의 프로세스 문서화"는 언제쯤 투자 가치가 가장 높을까? 내 경험상:

우리 팀도 지금 그 분기점을 지나가는 중인 것 같다.

마무리

이번 작업은 단순한 "코드 변경" 이 아니었다. 기술 부채를 갚는 것, 성능을 개선하는 것도 중요하지만, 팀이 효율적으로 성장할 수 있도록 프로세스를 명시화하는 것도 똑같이 중요하다. 오히려 팀 규모가 커질수록, 이런 일이 코드 최적화나 기능 개발보다 더 큰 임팩트를 준다는 걸 계속 확인하게 된다.

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

• 사무의자 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

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