AI 배포 매니저 세팅기

안녕하세요. 제로백데브 임재균입니다.
오늘은 배포 매니저에 관해 이야기 해보려고 합니다.

앱 배포는 코드를 짜는 일보다 절차를 기억하는 일에 가깝습니다.
앱을 배포하려면 매번 같은 질문을 스스로에게 던져야 했습니다.
이번 변경은 JS만 수정한 거라 OTA 업데이트로 되는지, 아니면 네이티브 전체 빌드를 새로 해야 하는지. 버전은 올려야 하는지, 올리면 기존 설치 앱에 어떤 영향이 있는지. 빌드가 끝나면 TestFlight와 Play 내부 테스트에 제출해야 하는데, 여기서도 함정이 있습니다.

실제로 겪은 일입니다. 앱 아이콘 이미지에 알파 채널(투명도 정보)이 남아 있다는 이유로, 빌드와 업로드까지 전부 성공해놓고 TestFlight에는 앱이 뜨지 않고 거부 메일만 받은 적이 있습니다. 에러도 아니고 실패도 아닌데 결과물만 없는 상황이라 원인을 찾는 데 한참이 걸렸습니다. 버전 정책도 함정이었습니다. 저희 프로젝트는 앱 버전을 기준으로 업데이트 호환성을 판단하는 정책을 쓰는데, 이걸 모르고 버전을 올리면 기존 설치자들이 OTA 업데이트를 받지 못하는 상태가 됩니다. 절차가 많고, 문서화는 애매하게 되어 있고, 하나만 틀려도 비용이 큰 전형적인 업무입니다. 그래서 이 업무를 통째로 AI에게 맡겨보기로 했습니다.

마크다운 두 개로 끝난 세팅

세팅 방법은 생각보다 단순했습니다. 코드를 짠 게 아니라 마크다운 문서를 썼습니다.

첫 번째는 배포 전문 에이전트 정의 문서입니다.

Claude Code에는 특정 업무를 전담하는 에이전트를 마크다운 파일 하나로 정의하는 기능이 있는데, 여기에 저희 프로젝트의 배포 지식을 전부 적었습니다. 개발·스테이지·운영 환경별 설정값과 API 주소, 빌드·스토어 제출·OTA 업데이트에 쓰는 명령어, 버전을 올릴 때와 유지할 때의 판단 기준. 그리고 가장 공을 들인 부분은 과거에 실제로 겪은 실패 사례와 해결법을 표로 정리한 것입니다. "이 에러 메시지가 나오면 인증서 만료이니 이렇게 갱신한다", "제출 전에 아이콘 알파 채널을 이 명령어로 검사한다", "버전을 올리면 기존 앱이 업데이트를 못 받으니 반드시 전체 빌드를 함께 한다" 같은 내용들입니다. 사람이 보면 배포 매뉴얼이고, AI가 보면 업무 지침서입니다. 흥미로운 건 이 문서를 쓰는 과정 자체가 저희 배포 프로세스를 처음으로 제대로 문서화하는 일이 됐다는 점입니다. AI에게 일을 가르치려다 보니 그동안 머릿속에만 있던 암묵지가 글로 내려왔습니다.

과거의 실패가 표로 정리된 에이전트 정의 문서. 사람에겐 매뉴얼, AI에겐 업무 지침서입니다.

두 번째는 진입점이 되는 /build 명령입니다.

터미널에서 /build를 입력하면 AI가 곧바로 빌드부터 돌리는 게 아니라, 먼저 현재 코드의 변경 사항을 스스로 확인합니다. 네이티브 모듈이 추가됐는지, 설정 파일이 바뀌었는지를 보고 "이번 변경은 JS만 수정됐으니 OTA 배포가 가능합니다" 같은 판단을 내린 뒤, 그 판단을 근거와 함께 선택지로 제시합니다. 저는 OTA로 갈지 전체 빌드로 갈지, 어느 환경에 배포할지, 버전을 올릴지만 고르면 됩니다. 각 선택지에는 "버전을 올리면 전체 빌드가 필수" 같은 주의사항이 함께 표시되니, 판단에 필요한 맥락을 매번 기억해낼 필요가 없습니다. 결정은 사람이 하고, 절차는 AI가 수행하는 구조입니다.

변경 사항을 먼저 읽고, 판단 근거와 함께 선택지를 내밉니다. 사람은 고르기만 하면 됩니다.

못 믿는 부분은 규칙으로 막았습니다

물론 그냥 맡기지는 않았습니다. 배포는 잘못되면 사용자에게 직접 영향이 가는 일이라, 문서에 안전장치를 명시하는 데 세팅 시간의 절반을 썼습니다.

첫째, 운영 배포는 사람의 확인 문구 없이는 절대 진행되지 않습니다. 운영 환경 대상 명령을 실행하기 전에 AI가 체크리스트(버전 업데이트 여부, 배포 브랜치 여부, 스테이지 검증 여부)를 제시하고, 제가 "production 빌드 확인"이라는 문구를 직접 입력해야만 다음으로 넘어갑니다. 엔터 한 번의 실수로 운영 배포가 나가는 일을 원천 차단한 것입니다.

엔터 한 번으로는 운영 배포가 나갈 수 없습니다.

둘째, 인증서와 스토어 서비스 계정 파일은 AI가 절대 읽지 못하게 금지했습니다. 배포에는 서명 키 같은 민감한 파일이 필요한데, AI는 파일이 존재하는지만 확인할 수 있고 내용은 열람 자체가 불가능하도록 규칙을 박아뒀습니다.

셋째, 실패는 축적되게 했습니다. 에이전트에게 전용 메모리 공간을 주고, 새로 겪은 빌드 실패의 원인과 해결법을 기록하게 했습니다. 같은 실수를 두 번 반복하지 않는 건 사람에게도 어려운 일인데, 이건 문서에 한 줄 쌓이는 것으로 해결됩니다.

정리하면 이렇습니다. AI를 전적으로 믿어서 맡긴 게 아니라, 못 믿는 부분을 규칙으로 막아뒀기 때문에 맡길 수 있었습니다.

배포가 대화 한 번이 됐습니다

지금은 배포가 /build 한 줄로 시작됩니다. 예전에는 배포할 때마다 지난 배포 기록과 명령어를 뒤지며 순서를 복하는 선택지에 서너 번 답하는 것으로 끝납니다. 절차와 과거의 실수는 AI가 외우고 있고, 저는 판단만 합니다.배포에 걸리는 시간보다 배포를 앞둔 긴장감이 줄어든 게 더 큰 변화입니다.

배포의 끝은 결과 요약 보고. 뒤지던 기록은 이제 AI가 들고 옵니다.

반복적이고, 절차가 많고, 실수 비용이 큰 업무. 그동안은 그래서 사람이 꼭 붙어 있어야 한다고 생각했던 일입니 업무일수록 오히려 AI에게 맡기기 좋은 후보였습니다. 절차는 문서로 옮길 수 있고, 실수는 체크리스트로 만들 수 있기 때문입니다. 단, 순서가 있습니다. 맡기는 게 먼저가 아니라, 안전장치를 설계하는 게 먼저입니다.

이상입니다. 또 다른 이야기로 찾아오겠습니다.
감사합니다.