자동화 봇 운영 기반 정식 문서화

인프라 자동화 시스템들이 프로덕션에서 실제로 동작하기 시작했고, 그에 따른 운영 체계를 CLAUDE.md에 정리했다. 개별 변경들은 작아 보이지만 누적되면 팀 전체의 신뢰성을 좌우하는 결정들이다.

자동화, 문서 없이는 반쪽짜리

요즘 인프라 자동화는 "코드가 돌아간다"는 것만으로 끝나지 않는다. 그 자동화가 어디서 어떻게 실행되는지, 언제 실패했을 때 누가 어떻게 대응하는지를 팀이 알아야 한다. 내가 이번에 한 일은 바로 그 "알아야 할 것들"을 한 곳에 모으는 작업이었다.

autobot 이 cron live로 전환된다는 건, 더는 개발자 손으로 수동 트리거 하지 않고 정해진 스케줄에 자동 실행된다는 뜻이다. 그럼 다음 질문들이 생긴다:

• 이 자동화가 실제로 돌고 있나?
• 실패했으면 누가 알고 누가 고칠 건가?
• 이 자동화가 어느 버전/릴리스 부터 적용되는 건가?
• 접근 권한은 누가 갖나?

이런 것들을 문서로 못 박지 않으면, 6개월 뒤 다른 팀원이 같은 자동화를 다시 만들거나, 장애 원인을 찾으려다 결국 초기 설계자만 아는 상태가 된다.

운영 체계의 네 가지 축

자동화, 이제 진짜 운영한다

autobot의 cron이 live라는 건, 내가 수동으로 트리거할 때와는 완전히 다른 책임이다. 정기적으로 "반드시" 실행되어야 하고, 실패하면 알려줘야 하고, 결과를 추적해야 한다. 이렇게 되면:

• 주기성 — 매주 월요일 아침 자동 실행처럼, 정확한 일정이 필요
• 실패 감지 — cron이 뻗으면 누구도 모를 수 있으니, 헬스체크 연동
• 버전 호환 — 이 cron이 어느 버전부터 실행되는지 명확히 해야 롤백·버그 추적이 가능

내 경험으로는, 이걸 문서화하지 않으면 약 3개월 뒤 "어? 이 시스템이 왜 지금 작동하는데 작동하지 말아야 하는 거 아닌가?" 하는 혼란이 생긴다. 특히 여러 팀이 관여하면 더 그렇다.

57+ series: 버전, 드디어 기록하다

자동화 시스템은 자주 업그레이드된다. 주기적으로 큰 변경이 들어가고, 때론 이전 버전과 호환되지 않는다. 그런데 이걸 명시하지 않으면:

• 누군가 구 버전으로 롤백할 땐 언제쯤 안 되는지 모른다
• 버그 리포트가 들어왔을 때 "어느 버전에서부터인가" 추적이 어렵다
• 신입이 온보딩될 때 "지금 뭐가 표준 버전이야?"라고 물었을 때 답할 수 없다

57+ series를 공식화한다는 건, 이 버전부터는 이 규칙을 따른다, 이 버전엔 이 기능이 없다, 이런 식으로 약속하는 것이다. 즉, "지금 우리가 뭘 쓰고 있는가"를 팀이 공식적으로 인정하는 첫 단계다.

uptime registered: 모니터링으로 운영한다

autobot이 프로덕션 cron으로 돌아갈 땐, 단순히 "돌고 있다"는 확인만으로는 부족하다. 마지막 성공은 언제였는지, 지난 한 달 가용률은 몇 %인지, 최근 에러는 뭔지 같은 정량적 지표가 필요하다.

uptime을 registered한다는 건:
- 이 자동화의 실행 기록을 중앙 모니터링 시스템에 등록한다
- 실패 임계값을 정하고, 넘으면 알람이 울린다
- 대시보드에서 한눈에 상태를 본다

이렇게 되면 팀리드로서 "우리 자동화가 잘 돌고 있는가"를 직관적으로 판단할 수 있다. 로그를 뒤적거릴 필요가 없다.

slecs ssh note: 보안도 문서다

접근 권한은 "그냥 주면" 된다고 생각하기 쉽지만, 운영하면서는 "누가 뭘 했는가"를 나중에 추적해야 한다. 감시 정책이 생기고, 감사(audit)가 필요해지면, "이 계정은 왜 저 서버에 접근했나"라고 물어볼 때 답해야 한다.

slecs ssh note를 문서화하는 건:
- 이 자동화가 어느 호스트에 접근하는가
- 어느 사용자 계정 권한으로 실행되는가
- 보안 규칙(예: IP 제약, 포트 제한) 무엇인가

이걸 기록으로 남기면, 나중에 보안 팀이나 감사자가 "맞나요?"라고 물었을 때 즉시 답할 수 있다.

회고: 작은 커밋의 누적이 시스템을 만든다

이 커밋은 코드를 고쳤다기보다 "상태를 기록했다"는 의미다. autobot이 처음 개발될 땐 누군가 "수동으로 한 번 돌려볼까"로 시작했을 거다. 그다음 "좀 더 자주 필요하니까 스케줄로 해볼까"라고 생각했을 것. 그 후 "이제 충분히 안정적이니까 프로덕션에 올려야지"로 진화했다.

하지만 그 모든 단계를 팀이 함께 알고 있지 않으면, 결국 "이 자동화는 누가 소유하나?", "이게 왜 갑자기 깨졌나?", "다음 버전은 뭐야?" 같은 질문에 답할 수 없다.

내가 이 문서를 업데이트한 이유는 단순하다. 팀 전체가 같은 버전의 진실을 공유하기 위해서다. 그게 CLAUDE.md의 존재 이유고, 그게 없으면 자동화는 한 개인의 영역에 머문다.

이런 일반론적 관점에서 보면, 자동화 시스템을 온전히 운영하려면:
- 언제 어디서 실행되는가 (스케줄, 호스트)
- 어떤 버전인가 (series, 호환성)
- 얼마나 잘 작동하는가 (uptime, SLA)
- 누가 접근할 수 있는가 (권한, 감시)

이 네 가지를 문서로 고정해야 한다. 이번 커밋은 정확히 그걸 한 것이다.

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

• 모니터 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

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