얼마 전 자동화 시스템의 제목 동기화 버그를 잡고 기분 좋게 퇴근했다. 오랫동안 나를 괴롭히던 동기화 문제를 말끔히 해결하고 밀린 데이터를 맞추기 위해 수동 복구 스크립트까지 깔끔하게 돌린 직후였다. 하지만 다음 날 아침, 모닝커피를 마시며 링크드인 피드를 확인한 나는 경악을 금치 못했다. 분명히 논리적인 순서대로 차근차근 업로드되어야 할 시리즈 게시글이 가장 최근에 작성된 글부터 거꾸로 나가고 있었기 때문이다.
내가 운영하는 개발 블로그는 단순한 잡담 공간이 아니라 작업 기록을 시리즈 순번대로 차곡차곡 쌓는 공간이다. 콘텐츠의 전후 맥락이 무엇보다 중요하기 때문에 순서가 뒤죽박죽 엉키는 것은 블로그 정체성에 매우 치명적이었다. 어쩌다가 잘 돌아가던 자동화 발행 시스템에서 순서가 뒤집히는 참사가 발생했는지 원인을 파악하기 위해 곧바로 로그를 분석하기 시작했다.
정렬 조건 누락이 불러온 대참사
원인은 생각보다 너무 허무하면서도 뼈아픈 곳에 있었다. 최근에 추가한 재활용 발행 기능을 담당하는 노션 API 조회 쿼리에 정렬 조건을 아예 지정하지 않았던 것이다. 큐 빌더가 조회 시점에 아무런 정렬 규칙을 전달하지 않자, 노션 데이터베이스는 자체적인 임의 순서대로 데이터를 반환해 버렸다.
불행히도 노션이 판단한 임의 순서의 최상단에는 방금 내가 복구 스크립트로 신나게 수정한 글들이 배치되어 있었다. 결과적으로 자동화 발행 큐 정렬 메커니즘이 완전히 붕괴한 상태에서 최근 수정본이 가장 먼저 발행 프로세스에 투입되는 결과를 낳았다. 소스 시스템의 임의 반환 조건에만 전적으로 의존하는 구조가 얼마나 허술한지 뼈저리게 느끼는 순간이었다.
이 문제를 완전히 해결하려면 큐에 콘텐츠를 채워 넣을 때마다 사전에 정의된 명확한 기준에 따라 재정렬하는 로직을 새로 보강해야만 했다. 외부 API의 정렬 동작에 의존하는 대신, 내부 코드에서 최종 순서를 완벽하게 통제할 수 있도록 기존에 세워둔 프로젝트 표준 설계를 다시 들여다보았다.
CLAUDE.md 우선순위 규칙에서 답을 찾다
다행히도 프로젝트의 빌드와 개발 가이드라인을 정의해 둔 CLAUDE.md 파일에는 콘텐츠 발행 우선순위가 명확하게 기재되어 있었다. 정의된 우선순위는 긴급도가 가장 높은 글부터 시작하여 높음 단계, 시리즈 순번순, 보통 단계, 마지막으로 낮음 단계 순서로 배정되는 구조였다. 이 우선순위 정의 규칙을 큐 빌더에 그대로 녹여내면 문제를 완벽히 해결할 수 있었다.
심지어 같은 구글 앱스 스크립트(GAS) 프로젝트 안에는 이미 개별 아이템의 우선순위 가중치를 계산해 주는 기존 함수가 존재하고 있었다. 바로 getItemSortRank라는 이름의 헬퍼 함수였는데, 이 녀석은 콘텐츠의 긴급도 태그와 시리즈 순번 값을 조합하여 정렬용 가중치를 숫자로 변환해 주는 아주 유용한 도구였다.
새로운 복잡한 정렬 코드를 처음부터 다시 작성할 필요 없이, 기존 프로젝트 안에 만들어 두었던 getItemSortRank 함수를 그대로 재사용하기로 결정했다. GAS 큐 빌더가 노션에서 API 데이터를 받아오는 직후에 이 가중치를 기준으로 수집된 데이터 배열을 다시 오름차순으로 완벽히 정렬하도록 코드를 전면 수정했다.
명시적인 자동화 발행 큐 정렬의 중요성
코드를 수정하고 다시 복구 스크립트를 시뮬레이션해 보니, 이제야 내가 의도했던 대로 큐가 차곡차곡 쌓이기 시작했다. 우선순위가 높은 글과 시리즈 순번이 앞서는 글들이 정확한 순서대로 배열에 배치되었고, 이 순서 그대로 안전하게 발행 대기 상태로 넘어갔다. 이번 삽질을 통해 시스템 간 연동에서 명시적인 정렬 규칙이 왜 핵심 요소인지를 다시금 똑똑히 깨닫게 되었다.
세상의 모든 콘텐츠가 최신순으로 발행되어야 하는 것은 아니다. 독립적인 주제의 글이라면 무작위로 올라가도 지장이 없겠지만, 흐름이 이어지는 시리즈형 콘텐츠의 경우 발행 순서가 독자의 이해도를 완벽히 좌우한다. 앞으로는 그 어떤 외부 API를 연동하더라도 데이터의 순서를 소스 시스템에 내맡기지 않고, 자체적인 정렬 로직을 명시적으로 선언하여 주도권을 쥐고 설계할 것이다.