글 저장소 이중 기록 방식 기록 완성
목차
동료가 작성한 데이터 레이어 설명 문서를 검토하다가 놓친 부분을 발견했다. 글이 단순히 하나의 데이터 저장소에만 쌓이는 줄 알았던 기록이 있었는데, 실제로는 두 곳에 중복으로 기록되는 하이브리드 방식이었다. cms_post DB에 별도로 id를 부여하고 적재되는 구조였는데, 그 부분의 설명이 누락되어 있었다. 91건 규모의 데이터가 이 방식으로 처리되고 있었으니, 문서상으로는 상당한 오류였다.
왜 이런 일이 발생하나
데이터 저장 구조가 시간에 따라 진화하다 보면, 문서가 이를 따라가지 못하는 경우가 종종 있다. 특히 하이브리드 구조는 복잡도가 높아서 더 그렇다. 처음엔 단순한 구조로 출발했을 수 있고, 나중에 성능이나 조회 패턴 때문에 이중 저장이 필요해진 뒤, 기존 문서를 대대적으로 갱신하지 않고 코드에만 반영되는 경우가 많다. 동료도 코드를 따라 설명했을 테지만, 최신 아키텍처 전체를 한눈에 파악하기는 어렵다는 뜻이다.
하이브리드 데이터 구조는 조회 효율(빠른 검색)과 정규화(중복 제거) 사이의 트레이드오프인 경우가 많다. cms_post DB에 따로 id를 달아 적재한다는 것은, 글을 여러 각도에서 빠르게 조회해야 하는 요구가 있었다는 의미다. 그런데 문서에 그 의도가 명시되지 않으면, 나중에 유지보수하거나 기능을 확장할 때 혼란을 준다. "왜 두 군데 저장되나?" "이 데이터는 어디가 진실인가?" 같은 질문이 반복된다.
동료 검토가 가져온 이점
이번 일은 사실 좋은 신호다. 동료가 문서를 작성하고, 내가 그것을 읽으며 오류를 찾은 것. 이게 정상적인 팀 문화다. 혼자서 코드와 문서를 동시에 관리하면 오류가 눈에 띄지 않는다. 하지만 누군가 다른 관점에서 "이게 맞나?" 하고 물어보면, 빠진 부분이 드러난다.
팀 리딩 관점에서 보면, 이런 리뷰 사이클을 장려하는 것이 중요하다. "문서 리뷰는 코드 리뷰와 같은 수준으로 중요하다"는 메시지를 팀에 계속 전달해야 한다. 특히 아키텍처나 데이터 구조 같은 핵심 문서는, 초안 단계부터 여러 사람의 눈을 거쳐야 한다. 한 명이 작성하고, 한 명이 리뷰하고, 그 과정에서 질문이 생기는 것이 정상이다.
문서와 현실의 괴리 줄이기
이번 정정으로 배운 점은, 데이터 구조가 바뀐 뒤 문서 갱신은 자동이 아니라 의도적인 작업이라는 것이다. 코드 변경이 일어나면, 그 변경이 아키텍처 문서에도 반영되어야 한다. 여러 팀이 이 글 데이터를 활용한다면, cms_post DB에 별도로 저장되는 방식이 성능에 영향을 미칠 수 있다. 캐시 전략, 동기화 주기, 데이터 일관성 보장 방식 등이 모두 이 구조에 얽혀 있기 때문이다.
실무에서는 이런 하이브리드 구조가 흔하다. 마이크로서비스 환경에서 각 서비스가 필요한 데이터를 로컬에 갖고 있기도 하고, 검색 성능을 위해 별도의 인덱싱 DB를 운영하기도 한다. 그때마다 "어디가 진실인가", "어느 저장소를 먼저 갱신하나", "동기화 실패 시 어떻게 하나" 같은 질문이 뒤따른다. 그 모든 고민이 문서에 녹아있어야 다음 사람이 이해하고, 운영할 수 있다.
마무리
이번 작업은 작은 문서 정정이었지만, 팀 문화와 아키텍처 문서의 중요성을 다시 상기시켜 줬다. 동료가 작성한 것을 검토할 기회를 갖고, 그 과정에서 놓친 부분을 함께 보완하는 것. 이게 우리 팀이 성장하는 방식이다. 앞으로도 데이터 구조가 변할 때마다, 문서 갱신을 함께 체크하는 습관을 유지해야겠다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.