자동화 장애가 사라지면 문서도 사라진다

신규 사이트를 온보딩할 때마다 체크리스트를 따라 몇십 개 항목을 확인한다. API 키 설정부터 시작해 권한, 스키마, 모니터링까지. 그런데 문서에는 없는데 실제로는 매일 도는 작업이 하나 있었다. 바로 드리프트 감지 알림.

드리프트는 조용하지만 무서운 문제

데이터 시스템을 운영하다 보면 '기대했던 상태'와 '실제 상태' 사이의 간격이 생긴다. 예를 들어, 특정 필드가 항상 NOT NULL 이어야 하는데 몇 건의 레코드가 NULL로 들어온다거나, 이메일 형식이 정규식을 만족해야 하는데 이상한 값이 섞인다거나 하는 식이다. 또는 외부 API 응답이 예상하던 스키마를 어겨서 파싱이 실패하거나, 데이터 동기화 파이프라인이 중단되는 경우도 있다.

이런 상황들을 "드리프트"라고 부른다. 시스템이 정상 운영 중이지만 기대 상태에서 서서히 벗어나는 현상이다. 드리프트는 알람이 울지 않는다. 에러 로그도 없다. 그냥 데이터의 품질이 조용하게 떨어진다. 따라서 자동으로 감지하지 않으면 누구도 모르고 지나가기 쉽다.

드리프트 감지의 일반적 패턴은 이렇다:
- 매일 정해진 시간에 cron 잡이 실행
- 데이터 샘플을 걸러서 기대 조건(스키마, 범위, 비율) 검증
- 문제 발견 시 슬랙/이메일 알림
- 운영자가 확인하고 원인 조사

이 과정 자체는 단순하지만, 문제는 문서화가 흐지부지되기 쉽다는 것이다.

자동화가 잘 도니까 문서는 기억에만 머문다

처음 이 드리프트 감지 자동화를 만들 때는 다른 팀원들에게 슬랙으로 설명했다. "이제부터 매일 자정에 데이터 품질 리포트가 날아올 거야" — 이런 식으로. 몇 달 잘 돌아가니 다들 익숙해졌다. 매일 온다는 걸 알고, 대수롭지 않게 받아들인다.

그런데 신규 팀원이 들어왔다. 온보딩 체크리스트를 따라 환경 변수, 권한, 모니터링을 설명했다. 그런데 그 신규 팀원이 "어? 자정마다 이런 리포트가 왜 날아와?" 라고 묻는다. 아, 이걸 문서에 안 썼구나 싶었다.

그 이후로도 비슷한 상황이 몇 번 있었다. 자동화는 인프라라고 생각해서 문서화 대상으로 치지 않는 경향이 있다. 문서는 "설정 방법", "수동으로 할 때 참고하는 절차" 같은 것들이 주가 된다. 하지만 "매일 자동으로 도는 게 뭔지" 까지는 빠진다.

이런 구조적 맹점이 있다:
- 온보딩 담당자 → 자동화는 안내하지 않음 (자동으로 도니까 설명 안 해도 된다고 생각)
- 신규 팀원 → 갑자기 나타나는 알림에 당황 (또는 중요도를 몰라서 무시)
- 운영자 → 드리프트 감지 로직이 바뀌어야 할 때 누가 담당인지 불명확 (누가 처음 짰는지도 까먹음)

온보딩 문서에 "매일 도는 것들"도 명시했다

이번에는 다르게 접근했다. 온보딩 문서에 자동화된 일들을 별도 섹션으로 추가하기로 했다. 구체적으로:

## 매일 자동으로 실행되는 작업

### 드리프트 감지 알림 (매일 자정)
- 목적: 데이터 품질 이상 조기 감지
- 실행: cron job (UTC 자정)
- 담당: [팀]
- 알림 채널: Slack #data-quality
- 로그 위치: /var/log/drift-detection.log

작으면 작은 대로, 크면 큰 대로 이렇게 표로 정리했다:

이렇게 하니까:
- 신규 팀원이 문서를 읽으면 "자동으로 도는 게 다 뭔지" 한눈에 보임
- 나중에 기기가 지연되거나 잘못된 알림이 오면 "아, 이건 이 cron 때문이구나" 추적 가능
- 팀 리더 입장에서도 "이런 자동화들이 이만큼 있다"는 걸 정리할 수 있음

배운 점: 자동화는 문서의 대상이 아니라 문서의 일부다

이 작업을 통해 느낀 점이 몇 가지 있다.

첫째, 자동화가 안정적일수록 더 문서화해야 한다. 조용히 잘 돌아가니까 설명할 필요가 없다고 생각하기 쉽다. 하지만 그렇기 때문에 나중에 고장 났을 때 팀원들이 패닉한다. 또는 왜 이 알림이 오는지 모르는 상황이 반복된다. 구글의 SRE 문화에서 "작동하는 것만이 문서다"라고 하지만, 나는 그에 덧붙여 "작동하는 것은 더 자세히 문서화되어야 한다"고 본다.

둘째, 온보딩 문서는 "설정 방법" 만 아니라 "운영 환경의 지도"가 되어야 한다. 신규 팀원이 처음 들어왔을 때 "이 팀에서 뭐가 자동으로 돈다"를 빠르게 파악하는 게 정신 건강에 좋다. 리더 입장에서도 팀의 자동화 인프라를 한 번에 볼 수 있게.

셋째, 자동화 작업을 할 때 "누가, 왜, 언제, 어디로 문서화할 것인가"를 동시에 생각해야 한다. 기능 개발과 문서화를 분리하면 안 된다는 건데, 특히 운영(cron, 모니터링 등)은 더욱 그렇다. 여전히 많은 팀에서 "코드는 완성했으니 문서는 나중에" 하다가 영원히 안 한다. 하지만 운영 자동화는 처음부터 명시해야 나중에 엔지니어들이 혼란스러워하지 않는다.

지금은 모든 신규 사이트의 온보딩 리스트에 "자동 알림/자동화 작업" 섹션이 포함되어 있다. 작지만 분명한 변화다.

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

• 모니터 쿠팡에서 보기 →
• 노트북 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

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