봇 자동화 공통 헬퍼와 저장소 구조를 처음부터 제대로 잡은 이유

봇 자동화 시스템의 기반을 다지는 첫 commit이었다. 사내 여러 팀에서 필요로 하는 공통 헬퍼와 운영 스크립트들을 정리하고 저장소 구조를 확립하는 작업이었다.

왜 이런 구조가 필요했나

초반엔 각 팀이 필요한 자동화 스크립트들을 따로따로 만들고 관리하곤 했다. 클라우드 API 호출, 인증 처리, 간단한 데이터 변환 같은 작업들이 중복되면서 유지보수 비용이 점점 늘어났다. 특히 인증 토큰 갱신이나 API 레이트 제한 처리 같은 부분에서 팀마다 다른 방식으로 처리하다 보니 버그 패턴도 반복됐다. 이걸 보면서 "공통 모듈화가 꼭 필요하겠다"고 판단했다.

파이썬과 Node.js 동시 지원

흥미로운 부분은 claude_cli.mjs(JavaScript)와 claude_cli.py(Python), 그리고 interlink.py를 함께 놓은 것인데, 이건 우리 팀의 다양한 런타임 환경을 반영한 선택이었다.

이렇게 분리하면서 "각 팀이 자기 환경에 맞춰 쓸 수 있으면서도 핵심 로직은 한 곳에서 관리"하는 구조를 만들 수 있었다. 물론 이건 나중에 프로토콜 통일이나 API 게이트웨이로 진화할 여지도 남겨뒀다.

운영 스크립트의 중요성

scripts/claude-auth-check.sh 같은 운영 스크립트는 처음엔 "자잘한 것" 취급받을 수 있지만, 실제로 프로덕션에서는 굉장히 자주 돌려진다. 인증 문제로 밤 11시에 화이팅 호출이 들어올 때, 이런 진단 스크립트 한두 개가 있으면 평상시 수작업 확인에 15분 걸리던 걸 2분에 끝낼 수 있다. 그래서 초기부터 "ops" 영역을 제대로 구성하는 것이 중요했다.

README나 .gitignore 같은 메타 파일들도 마찬가지로, 나중에 새로운 팀 멤버가 왔을 때 "뭘 어디다 놓지?"라는 혼란을 줄이는 데 핵심이다.

초기 구조 설계의 함정

이렇게 "초기 제대로" 하는 게 맞긴 한데, 실무에선 함정이 있다. 너무 완벽하게 설계하려다가 실제 요구사항이 나올 때까지 구조를 미리 정하면, 3-4개월 뒤에 "아 우리는 저렇게 안 했는데?"라고 뜯어고치기 일쑤다. 그래서 이번 commit은 의도적으로 "최소한의 진입점"만 만들었다. 공통 헬퍼는 있지만 너무 과도한 추상화는 지양했고, 스크립트도 운영에서 자주 사는 것 위주로 먼저 들어갔다.

시간이 지나면서 실제 사용 패턴이 보이면 그때 refactoring 하는 게 훨씬 현실적이었다. 팀의 입장에서도 "쓰다 보니 이렇게 나아야 할 것 같은데"라는 피드백이 나올 때가 가장 구조 개선이 효과적이다.

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

• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

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