로스터 145명 규모 확대와 운영 정책 문서화

프로필 데이터 로스터에 신규 11명을 추가하면서 145명 규모까지 확대했다. 단순한 데이터 추가가 아니라, 이 규모에서 팀이 안정적으로 유지보수할 수 있도록 운영 기준과 쿼터 한도를 문서에 명시한 작업이다.

규모 성장에 따른 운영 난제

로스터가 100명을 넘으면서 몇 가지 문제가 생겼다. 신규 데이터를 추가하려는 사람들이 매번 같은 질문을 했다:

• 한 번의 커밋/PR에서 최대 몇 명까지 추가 가능한가?
• 각 항목의 필수 필드와 옵션 필드는 무엇인가?
• 데이터 형식이나 유효성 검사 기준은 어디에 정의되어 있는가?

이런 질문들에 답할 명확한 기준이 없었다면, 코드 리뷰 때마다 같은 내용을 반복 설명해야 했을 것이다. 팀이 커질수록 암묵적 합의만으로는 스케일이 맞지 않는다.

변경 작업: 데이터와 정책의 역할 분리

이번 작업의 핵심은 두 파일의 책임을 명확히 한 것이다.

데이터 파일에는 구체적인 항목들(이름, 채널, 가입 시점 등)을 넣고, 문서에는 "어떻게 이 파일을 확장하는가"에 대한 기준을 담았다. 문서에 담긴 내용은 대략 이런 식이다:

운영 정책 항목들:
- 로스터 추가 시 반드시 검증할 필드 목록
- 한 번의 변경에서 추가 가능한 최대 개수(쿼터)
- CI/자동화 테스트 체크리스트
- 신규 기여자를 위한 온보딩 절차

왜 이런 문서화가 필수인가

팀과 데이터가 함께 성장할 때, "코드 리뷰로 관례를 지킨다"는 전략에는 한계가 있다:

1. 온보딩 비용 - 신규 팀원이 들어올 때마다 구두로 설명해야 함
2. 일관성 부족 - 문서가 없으면 PR마다 기준이 달라질 수 있음
3. 자동화 불가능 - CI나 봇이 검증할 기준이 없으면 보조 도구를 쓸 수 없음
4. 역사 기록 - 나중에 "왜 이런 정책으로 했나" 물었을 때 답할 증거가 필요

단순한 데이터 추가라도, 이 규모쯤 되면 정책 문서화를 함께 진행하는 것이 향후 유지보수 비용을 크게 줄인다.

비슷한 도메인에서의 일반 패턴

이 "데이터 + 정책 분리" 방식은 모든 도메인에서 적용된다:

• 결제 시스템 - 지원하는 결제 수단(데이터) + 각각의 수수료/한도 정책(문서)
• 권한 관리 - 역할 목록(데이터) + 각 역할이 접근 가능한 자원 정의(정책)
• 콘텐츠 관리 - 항목 리스트(데이터) + 분류 기준/검증 규칙(정책)

패턴의 핵심은 데이터의 구조와 형식은 코드에서 관리하고, 데이터를 다루는 규칙과 제약은 문서에서 관리한다는 원칙이다.

다음부터의 교훈

100명 규모일 때는 "아, PR 리뷰로 케어하면 되겠네" 싶었는데, 145명이 되니 "이제는 정책 문서가 필수다" 싶었다. 팀이 작을 때는 구두와 코드 리뷰로 관례를 지키는 것도 가능하지만, 일정 규모를 넘어가면 반드시 문서화해야 한다. 다음부터는 비슷한 규모 작업을 할 때, 데이터 추가와 정책 문서화를 항상 함께 진행하기로 했다.

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

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

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