스케줄 범위 확대할 땐 '정상적인 이상'도 문서화하라
목차
크론 작업 범위를 25개에서 35개로 확대하고, 그 과정에서 도메인 특성을 CLAUDE.md에 명시했다. 간단해 보이지만 이 작은 문서화 항목이 팀의 많은 오해와 불필요한 버그 조사를 막을 수 있다.
범위 확대의 배경
VTuber 프로필 데이터를 매일 갱신하는 크론 작업인데, 초기엔 상위 25개 프로필만 대상이었다. 근데 추적해야 할 대상이 늘면서 35개까지 확대하게 됐다. 단순한 숫자 변경처럼 보이지만, 처리량 제약이 있었다. 일일 처리 용량이 약 8.5k 정도이고, 시스템 한도는 10k였다. 즉 여유가 겨우 1.5k밖에 없었다. 25개를 35개로 늘리면서도 안정적으로 한도 내에 머물러야 했던 거다.
도메인 특성을 왜 문서화했나
사실 숫자 변경만으로는 부족했다. VTuber의 활동 패턴이 일반적인 데이터와 다르기 때문이다. 주년 행사(Anniversary, 아니면 채널 개설 기념일)가 있을 때는 집중적으로 스트림하지만, 평소에는 상대적으로 적을 수 있다. 이를 모르는 팀원이나 모니터링 시스템이 보면 "어? 이 프로필 데이터가 요즘 적네. 버그인가?"라고 착각하기 쉽다.
그래서 CLAUDE.md에 명시했다: "주년이 본체이고, 스트림이 적은 게 정상". 한 줄이지만 이 한 줄로 다음을 방지할 수 있다.
- 온콜 엔지니어가 불필요한 알림에 대응하는 시간
- "버그가 아닌데 버그인 줄 알고" 시작된 조사
- 새로 온 팀원의 혼란
처리량 최적화 결정
범위를 단순히 35개로 확대하는 것만으로는 부족했다. 10k 한도를 고려하면서 8.5k 수준에서 안정적으로 운영할 방법을 찾아야 했다. 일부 프로필의 갱신 주기를 조정하거나, 처리 로직을 더 효율화하는 방식도 고려했지만, 결국 "현재 시스템 한도 내에서 35개가 최대"라는 결론에 도달했다. 이를 명시하는 것도 향후 누군가 "그럼 50개로 늘릴 수 있지 않을까?"라는 질문에 답할 수 있게 해준다.
작은 문서화의 힘
이 커밋을 보면 코드 변경은 없다. CLAUDE.md에 주석만 추가했을 뿐이다. 그런데 이게 중요하다. 자동화 시스템이 늘어날수록, 정상 동작의 정의가 애매해진다. 프로필이 이틀을 더 갱신 안 됐다고 해서 항상 문제는 아니다. 그 프로필이 최근 활동이 적으면 정상이다. 이런 도메인 지식은 코드에 남기기 어렵다. 쿼리 주석이나 경고 로그로 처리하기도 어렵다. 그래서 운영 문서, 특히 온보딩 문서(CLAUDE.md)에 남기는 게 가장 효과적이다.
앞으로의 교훈
크론 작업이나 자동화 시스템을 확대할 때 놓치기 쉬운 부분:
- 숫자만 바꾸지 말 것: "25→35로 확대" 이상의 의도를 남겨야 한다
- 시스템 한도를 명시할 것: 왜 35인지, 50은 안 되는지를 나중 담당자가 이해하게
- 도메인의 '정상적 이상'을 문서화할 것: 데이터가 없어 보이면, 버그가 아닐 수도 있다
- 모니터링 규칙도 함께 검토할 것: 35개 대상 시 알림 임계값이 바뀌어야 할 수도 있다
이번 작업 자체는 작지만, 이런 습관이 팀 규모가 커질수록 더 중요해진다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.