AI에게 배포 트리거는 맡기되, 위험한 버튼은 손도 못 대게 했다

성격이 정반대인 두 서비스에 같은 원칙으로 Claude Code Skill을 들인 기록이다. 이 글(1편)은 배포 파이프라인을, 2편은 운영 응대 런북을 다룬다. 도메인은 다르지만 결론은 같았다. 핵심은 "얼마나 자동화하느냐"가 아니라 "절차를 가리지 않으면서 위험한 동작은 구조적으로 막느냐"였다.

2편은 아래 글을 참고하자.

고객 문의가 매번 똑같이 반복된다면, 그건 런북으로 만들 수 있다

정식 배포 담당이 따로 없는 납품형 IDP 프로젝트에서, 브랜치 통합·이미지 빌드 트리거·배포·API 검증 같은 반복 운영 업무를 Claude Code Skill로 직접 자동화했다. 핵심은 "얼마나 자동화하느냐"가 아니라 "자동화가 절차를 가리지 않으면서, 위험한 동작은 구조적으로 막느냐"였다.

Intro

• 반복 운영 업무(브랜치 통합 → 이미지 빌드 트리거 → 배포 → alpha API 검증)를 integration / deploy / qa-alpha 세 스킬로 묶어 자동화했다.
• 자동화 여부를 무작정 정하지 않았다. (a) 자동화 가능 영역인가 (b) 자동화 후에도 안정성이 검증되는가 (c) 팀 업무 패턴상 도입해도 무방한가 (d) 팀원이 절차의 흐름을 모르고 넘어가지 않는가, 네 가지를 함께 판단했다.
• 모든 스킬에 단계별 사용자 확인 게이트를 두고, 각 단계 결과를 출력해 절차를 가시화했다.
• QA 스킬은 POST/DELETE/비멱등 PUT 같은 destructive 호출을 자동 실행하지 않고 스키마 검증만 한다. 의도와 달리 200이 떨어지면 즉시 중단한다.
• JWT 만료가 임박(5분 이내)하면 미리 재입력을 요구하고, 토큰은 어떤 로그에도 남기지 않는다.
• 외부 연동(이슈 트래커 API)이 실패하면 REST fallback으로 떨어지고, 신규 생성 직후의 인덱싱 지연은 재시도로 흡수한다.

출발점: "이걸 매번 손으로 하고 있었다"

납품형 IDP는 고객 사업장 위에서 동작한다. 정식 배포 담당 포지션이 없는 구조라 통합/배포/QA를 사실상 내가 떠안고 있었고, 흐름은 늘 똑같았다.

1. develop을 main으로 통합하고, 커밋에서 이슈 번호를 추려 PR을 만든다.
2. BE 4개 모듈의 이미지 빌드 워크플로를 각각 트리거한다.
3. 빌드가 끝나면 이미지 태그를 로그에서 뽑아 차트 레포의 배포 워크플로에 넘긴다.
4. alpha 환경에 변경된 API를 일일이 호출해 회귀를 확인한다.
5. 그 결과를 이슈 트래커 태스크에 댓글로 남긴다.

문제는 이게 "기계적이지만 위험한" 일이라는 점이었다. 태그를 잘못 넘기면 엉뚱한 이미지가 배포되고, QA 한다고 검증용 호출을 잘못 날리면 실데이터를 건드린다. 그래서 "AI로 자동화한다"는 결정 자체를 신중하게 했다.

특히 QA 스킬(qa-alpha)을 만든 데에는 좀 더 현실적인 배경이 있었다. alpha는 내부 검증용 환경이라 부담 없이 배포하는 분위기였는데, 그러다 보니 배포 후 검증이 개인 재량에 맡겨져 있었다. 배포한 사람이 회귀 테스트나 본인이 추가한 신규 API를 따로 확인하지 않고 FE팀에 "올라갔어요"만 전달하면, 정작 문제는 그다음에 드러나는 일이 반복됐다. 사람을 탓할 일은 아니었다. 배포 후 검증이 "각자 알아서"의 영역으로 남아 있는 한, 일정에 쫓기면 누구든 건너뛰기 쉬운 구조였기 때문이다. 그래서 검증을 의지나 습관이 아니라 절차로 고정하고 싶었고, 그게 qa-alpha의 출발점이었다.

무작정 자동화하지 않는다는 판단 기준

반복 작업이라고 곧장 스킬로 만들지 않았다. 다음 네 가지를 통과할 때만 자동화 대상으로 봤다.

• 자동화 가능 영역인가: 입력과 출력이 결정적인가, 사람이 매번 다르게 판단해야 하는 영역은 아닌가.
• 자동화 후 안정성이 검증되는가: 자동화가 만든 결과를 사람이 곧바로 확인할 수 있는가.
• 팀 업무 패턴상 무방한가: 다른 팀원의 작업 흐름과 충돌하지 않는가.
• 절차를 가리지 않는가: 팀원이 "버튼만 누르면 되는 것"으로 받아들여 내부 절차를 모르고 넘어가게 되지는 않는가.

마지막 항목이 가장 중요했다. 자동화가 블랙박스가 되면, 장애가 났을 때 아무도 손을 못 댄다.

어디까지 자동화할지: 환경으로 경계를 그었다

이 자동화는 의도적으로 alpha 환경까지만 다룬다. Beta 이상은 자동화 대상에서 일부러 뺐는데, 이유는 두 가지다.

첫째, Beta는 우리 팀이 내/외부 공개용으로 취급하는 환경이다. FE팀, 납품 담당팀과 협의해 릴리즈 버전을 고정하고, 그 고정된 버전으로 Beta에 배포한 뒤 다음 사업장 납품 때 동일 버전을 기준으로 내보낸다. 즉 Beta 배포는 "버전을 합의하고 못 박는" 협의의 결과물이지, 코드가 머지됐다고 자동으로 흘러가도 되는 단계가 아니다. 여기에 트리거를 자동으로 걸면 협의 자체를 건너뛰게 된다.

둘째, Beta 이상의 배포는 각 리드와 팀 간 협의가 전제이고, 그 내용을 취합해 배포를 승인하는 책임은 리드인 나에게 있다. 이건 권한의 문제라기보다 "어디서 사람이 반드시 멈춰 판단해야 하는가"의 문제다. 그 판단 지점을 팀원에게 넘기거나 스킬에 맡기는 건 맞지 않다고 봤다. 그래서 alpha까지는 절차를 자동화해 누구나 같은 모양으로 돌릴 수 있게 하되, Beta 이상은 의도적으로 사람의 협의·승인 영역으로 남겨 뒀다.

설계 의도: 자동화 + 확인 게이트 + 절차 가시화

세 스킬은 한 줄로 이어진다.

• integration: 통합 PR 생성, 빌드 워크플로 트리거, 이슈 완료 처리, 배포 태스크 생성까지.
• deploy: 빌드 완료를 폴링으로 기다렸다가 이미지 태그를 추출하고, 차트 레포의 배포 워크플로를 트리거.
• qa-alpha: 통합 범위의 컨트롤러를 정적 분석해 변경된 API만 추려 alpha에서 호출하고, 결과를 이슈 트래커에 기록.

설계 원칙은 세 가지였다.

확인 게이트. 각 스킬은 "다음으로 넘어가기 전에" 사람에게 한 번 묻는다. integration은 통합할 커밋 목록을 보여주고 확인을 받는다. deploy는 추출한 이미지 태그로 정말 배포할지 확인한다. qa-alpha는 어떤 API를 자동 호출하고 어떤 API를 스키마 검증만 할지 분류표를 먼저 보여준다.

destructive 차단. QA에서 가장 신경 쓴 부분이다. 변경된 핸들러를 메서드별로 분류해 GET과 멱등 PUT(read-all, mark-all 같은)만 자동 호출한다. 나머지(POST/DELETE/비멱등 PUT)는 일부러 잘못된 path variable이나 빈 body로 호출해 라우팅과 4xx 응답만 확인한다. 만약 이 호출에 200이 떨어지면, 그건 "막아야 할 게 안 막혔다"는 신호라 즉시 중단하고 경보한다.

토큰 위생. QA는 Bearer 토큰을 입력받는데, 페이로드의 exp를 디코드해 남은 시간이 5분 이하이면 검증을 시작하지 않고 재입력부터 요구한다. QA 도중에 토큰이 만료돼 절반만 검증되는 상황을 막기 위해서다. 토큰 값 자체는 로그/출력 어디에도 남기지 않는다.

여기에 외부 연동 안정성을 더했다. 이슈 트래커는 MCP로 먼저 호출하되, 실패하면 환경변수의 API 토큰으로 REST를 직접 친다. 신규 태스크를 만든 직후엔 인덱싱 지연으로 조회가 잠깐 비는데, 짧게 대기 후 재시도로 흡수한다.

구조

전체 파이프라인 흐름이다.

destructive 호출을 거르는 분기는 이렇게 동작한다.

무엇이 남았나

이 스킬들이 준 가장 큰 효과는 "속도"가 아니었다. 통합부터 QA까지의 절차가 매번 같은 모양으로 남고, 각 단계가 화면에 출력되니 다른 팀원도 흐름을 따라 읽을 수 있게 된 점이었다. 자동화가 블랙박스가 아니라 "읽히는 절차"가 된 것이다.

다만 솔직히 말하면, 이 QA 스킬은 어디까지나 차선책이다. 원래는 BE 코드 레벨의 단위 테스트에만 머물지 말고, 테스트 코드를 기반으로 한 E2E 테스트 작성 규칙을 갖추는 게 맞다. 그래야 검증이 배포 시점의 외부 호출이 아니라 코드와 함께 굴러간다. 다만 업무 일정 우선순위와 리소스 한계로 거기까지는 손대지 못했고, 그 빈자리를 우선 메우는 현실적인 장치가 qa-alpha였다.

그래서 앞으로의 보강 방향은 세 가지로 본다.

• E2E 테스트 규칙 정립: QA 스킬이 외부에서 호출로 확인하는 것을, 테스트 코드 안으로 끌어들이는 게 다음 단계다. 검증을 배포 절차가 아니라 코드의 일부로 만드는 방향이다.
• 검증 커버리지 확대: 지금은 alpha 단일 환경 기준이라, 환경별 차이를 흡수하는 분류 규칙을 더 정교화할 수 있다.
• 회귀 신호의 구조화: QA 결과를 단순 PASS/FAIL이 아니라 "응답 envelope 규칙 위반" 같은 회귀 신호로 더 세분화하면, 배포 전에 잡히는 범위가 넓어진다.

자동화를 설계할 때 내가 계속 되물었던 질문은 하나였다. "이 자동화는 사람이 손댈 수 있는가, 아니면 손댈 수 없게 만드는가." 위험한 버튼일수록 AI에게 트리거는 맡기되 실행은 사람 확인 뒤로 미뤘고, 그게 이 스킬 세트의 일관된 기준이었다.