데이터 소유권 모델 정의로 팀 간 혼선 해결

동료 팀과 공유하는 데이터에 대해 명확한 소유 모델을 정의하고, 이를 문서에 기록했다. .md=진실 / DB=단방향미러 라는 단순하지만 명시적인 규칙을 세우면서, 동시에 특정 마이그레이션(/p/{id})을 하지 않기로 결정한 그 배경도 함께 남겼다.

왜 이런 문서가 필요했나

프로젝트가 커지다 보니 여러 팀이 같은 데이터를 다루게 됐는데, 각 팀이 그 데이터를 어느 정도로 신뢰하고 사용할지에 대해 명확한 합의가 없었다. 어떤 팀은 "DB에 있는 게 진실"이라고 생각했고, 또 다른 팀은 "마크다운 문서가 항상 최신"이라고 믿고 있었다. 결과적으로:

• 누가 이 데이터를 수정해도 괜찮은지 불명확함
• 데이터가 둘 다 존재할 때 어느 걸 믿을지 혼란스러움
• 버그 리포트나 설계 리뷰에서 "정확한 현황이 뭐냐"는 논의가 반복됨

이런 상황이 반복되면 결국 조직 전체의 결정 속도가 떨어진다.

명확히 정의한 모델

그래서 이번에 명시한 규칙은 이렇다:

마크다운을 "진실"로 삼은 이유는 버전 관리(Git), 코드 리뷰 프로세스, 감사 추적이 전부 마크다운에 남기 때문이다. DB는 성능이나 실시간 조회를 위해 필요하지만, 어디까지나 마크다운을 동기화한 사본일 뿐이다.

이렇게 정의하면:
- 정보 갱신은 항상 마크다운 우선 → 그다음 DB 싱크
- 데이터 불일치 발견 시 마크다운을 기준으로 수정
- 누구든 "뭐가 진짜냐?"고 물었을 때 답이 명확함

/p/{id} 미전환 결정을 기록한 이유

마찬가지로 마이그레이션 계획도 있었는데(특정 경로를 새로운 패턴으로 전환하는 작업), 이번에 "아직 전환하지 않기로 했다"는 결정을 명시적으로 문서에 남겼다. 이게 중요한 이유:

• 누군가는 "왜 아직도 저 옛날 패턴을 쓰나?" 라고 물을 수 있고
• 새로 합류한 팀원은 "이거 리팩토링해도 되나?" 하고 시간을 쓸 수 있고
• 6개월 뒤 본인도 "이거 미룬 이유가 뭐더라?" 하고 다시 생각할 수 있다

그런 낭비를 줄이려면 의사결정 자체와 그 배경(기술적 제약, 우선순위, 트레이드오프)을 기록하는 게 팀 투자 대비 가장 높은 ROI다.

작은 문서화가 큰 신뢰를 만든다

이번 작업은 코드 한 줄도 고치지 않았다. 단지 "이게 진실이고, 저건 미러고, 저 결정은 안 할 거고" 라는 걸 명확히 썼을 뿐이다. 하지만 이 몇 줄이:

• 동료 팀이 구현할 때 헷갈리지 않게 함
• 코드 리뷰에서 "진짜 이 접근이 맞나?" 는 논의를 줄임
• 6개월 뒤 나 자신도 그때의 맥락을 빠르게 복원할 수 있게 함

특히 아키텍처나 데이터 모델 같은 주제는 "왜?"를 놓치면 나중에 누군가는 틀린 방향으로 개선하려다가 낭비를 본다. 명확한 문서 한 장이 그런 엔트로피를 막는다.

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

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

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