단일 소스로 정보 산재 해결하기

sites.json을 단일 진실(single source of truth)로 정하고, 여기서 메인 페이지·깃헙 공개 정보를 자동으로 생성하는 자동화를 구축했다. 여러 곳에 흩어진 사이트 메타데이터를 한곳에서 관리하면서 반복 작업을 제거하고 팀의 온보딩 프로세스를 단순화한 경험을 나눈다.

산재된 정보가 만드는 비용

팀이 운영하는 사이트들이 몇십 개 수준으로 늘어나자, 각 사이트의 이름·설명·URL·담당자·상태 같은 메타데이터가 여러 곳에 흩어지기 시작했다. README 에도 있고, 대시보드 설정에도, 내부 협업 문서에도 따로따로 존재했다. 신규 사이트를 추가할 때마다 "어디어디에 또 이름을 넣어야 했더라?"는 질문이 반복됐다. 최악의 경우 한 곳만 업데이트하고 다른 곳을 빠뜨려서 팀 내 정보가 불일치하는 상황도 발생했다.

이건 단순한 "업데이트 누락" 문제가 아니다.

• 온보딩 마찰: 새 팀원이 사이트 목록을 파악하려면 문서들을 여러 군데서 찾아봐야 한다
• 변경의 비용: 한 사이트의 상태를 업데이트하려면 여러 파일을 동시에 수정해야 한다
• 자동화 불가: 이 정보들을 메인 페이지나 깃헙 프로필에 자동 반영할 수 없다
• 리뷰 복잡도: PR에서 "이 정보 빠진 곳이 또 있나?" 체크해야 한다

이런 상황은 대부분 조직이 성장하면서 자연스럽게 마주친다. 처음에는 문서 하나, 설정 하나로 충분했지만, 관리 대상이 늘어나면서 일관성 유지 비용이 지수적으로 커지는 현상이다.

구조 재설계: 단일 소스 + 생성기

해결책은 명확했다. data/sites.json을 "유일한 정보원(golden source)"으로 정하고, 이를 기반으로 필요한 곳에 자동으로 파일을 생성하는 파이프라인을 만드는 것이다.

변경된 파일들의 역할은 다음과 같다:

구조적으로는 전형적인 "싱글 소스 + 코드 생성" 패턴이다. 예를 들어 대부분의 모던 프로젝트가:

# 생성기 로직 예시 (실제 구현은 더 복잡할 것)
def generate_public_surfaces():
    sites = load_json('data/sites.json')

    # 메인 페이지용 마크다운 생성
    main_readme = render_main_section(sites)

    # 깃헙 조직 정보 생성
    github_metadata = render_github_profile(sites)

    # 결과 저장
    write('README.md', main_readme)
    write('.github/profile/README.md', github_metadata)

이런 식으로, 단 하나의 소스에서 여러 출력물을 만들어낸다. 프로그래밍에서 DRY(Don't Repeat Yourself) 원칙을 데이터 관리에 적용한 것이다.

팀에 미친 변화

이 작업을 통해 몇 가지 구체적인 개선이 생겼다:

온보딩 프로세스 명확화
- 새 팀원: "사이트 추가하려면?" → 답: "sites.json 수정하고 스크립트 실행"
- 단일하고 반복 가능한 절차로 통일됨

신규 기능 추가의 용이성
- 메인 페이지에서 새 칼럼(예: 담당팀, 우선순위)을 보여주고 싶어? → sites.json 스키마 확장 + 생성기만 수정
- 여러 파일을 찾아다니며 수정할 필요 없음

코드 리뷰의 간단화
- "사이트 정보 변경 PR"은 더이상 "README도 수정했나?", "문서도 수정했나?" 체크가 필요 없음
- sites.json 한 파일만 보면 됨

자동화의 연쇄
- 이제 새 사이트가 추가되면 메인·깃헙에서 자동으로 반영된다
- 배포 파이프라인에 이 생성기를 넣으면 "사이트 추가 후 깃헙 반영까지" 전자동

일반화: 비슷한 상황에서

회고해보면, 이 패턴은 꽤 널리 적용된다:

• 마이크로서비스 환경: 서비스 메타데이터(포트, 헬스체크 URL, 의존성)를 중앙화하고 배포 설정·모니터링 규칙 자동 생성
• 설정 관리: 각 환경(dev/staging/prod)의 변수들을 YAML·JSON 한곳에 두고 배포 환경별 설정 파일 자동 생성
• 문서 자동화: API 스펙 한 곳에서 읽어서 마크다운·OpenAPI·타입스크립트 타입 동시 생성
• 멀티테넌시 플랫폼: 고객 목록을 중앙화했다가 청구서·대시보드·이메일 템플릿 자동 반영

핵심은 "누군가는 손으로 유지해야 하는 정보"와 "그 정보에서 파생되는 콘텐츠"를 분리하는 것이다. 파생 콘텐츠는 절대 수동으로 건드리면 안 되고, 항상 생성기를 통해서만 만들어진다는 원칙을 지키면 비용과 오류를 크게 줄일 수 있다.

다음은 이 생성기가 CI/CD 파이프라인에 자동으로 탑재되면, 혹시 누가 손으로 메인·깃헙을 수정하려는 순간을 원본 부터 차단할 수 있는 단계다.

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

• 사무의자 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

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