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

성격이 정반대인 두 서비스에 같은 원칙으로 Claude Code Skill을 들인 기록이다. 1편은 배포 파이프라인을 다뤘고, 이 글(2편)은 운영 응대 런북을 다룬다. 도메인은 다르지만 결론은 같았다. 핵심은 "AI로 코드를 더 빨리 짠다"가 아니라 "반복 운영 업무를 절차로 고정하고, 외부로 나가는 답변엔 마스킹 관문을 둔다"였다.

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

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

폐쇄망 백업 서비스(Veritas NetBackup 기반 BaaS) 백엔드를 운영하면서, 반복되는 고객/운영팀/벤더 문의 대응과 코드 컨벤션 점검을 Claude Code Skill 세트로 표준화했다. "AI로 코드를 더 빨리 짠다"보다 "반복 운영 업무를 절차로 고정한다"가 이 작업의 진짜 목적이었다.
(사내 호스트/이슈 트래커 프로젝트명/리전 코드/고객사명/벤더 장비 호스트명은 모두 일반화했다. 자격증명류는 어떤 형태로도 적지 않는다. Veritas NetBackup은 벤더 제품명이라 그대로 둔다.)

Intro

• 백엔드 개발 사이클 전체를 13개 스킬로 덮었다. 코드 작성 규칙(8개) + 검증(convention-check) + 작업 기억(ai-memory-plan) + 운영 응대(runbook-customer-inquiry) + 커밋 컨벤션.
• 가장 효과가 컸던 건 코드 스킬이 아니라 고객 문의 대응 런북이었다. 반복되는 문의를 카테고리로 나누고, 5W1H 트리아지 → 조사 → 마스킹 → 종결 → 재발 방지까지 절차로 고정했다.
• 마스킹을 규칙으로 명문화했다. AppKey는 앞 4자리만, 자격증명(API Key/토큰/비밀번호)은 외부 응답에 절대 노출하지 않고, 고객사 명칭은 일반화한다.
• 컨벤션은 스킬 파일을 단일 진실 소스로 두고, convention-check가 그 파일을 직접 읽어 코드 위반을 CRITICAL/HIGH/MEDIUM으로 리포트한다. 규칙 사본을 여기저기 복사하지 않는다.
• 3단계 이상 복잡한 작업은 ai-memory-plan이 계획서·맥락노트·체크리스트 3종 문서를 만들어, 새 대화창에서도 맥락을 복구한다.

출발점: 같은 질문이 사람만 바꿔 다시 온다

폐쇄망 백업 서비스는 트래픽은 낮지만 책임도는 높다. 그리고 운영을 하다 보면 문의의 상당수가 "형태가 거의 같다"는 걸 알게 된다.

• 특정 리전에서 백업 결과가 콘솔에 안 보인다.
• 리포트 수집이 실패했다.
• 벤더 장비(Appliance) 쪽 API Key/ACL 문제로 Read Timeout이 난다.
• 특정 기관에서 사용 현황 데이터를 반출해 달라고 한다.

문제는 1차 대응의 품질이 사람마다, 그날 컨디션마다 들쭉날쭉했다는 점이다. 더 나빴던 건, 정보가 부족한 채로 곧장 DB를 뒤지기 시작하는 일이었다. 누가, 언제, 어느 리전에서, 어떤 AppKey로 겪었는지도 모르고 조사에 들어가면 시간만 태운다.

그래서 "이건 사람의 숙련도에 의존할 게 아니라 절차로 고정해야 한다"고 판단했다.

설계 의도: 반복 업무를 절차로, 절차를 스킬로

고객 문의 대응 런북

핵심 스킬은 runbook-customer-inquiry다. 이슈 트래커에 문의사항 태그가 달린 태스크가 들어오면 발동한다. 흐름은 이렇다.

1. 수집: 태스크 본문/메일에서 5W1H를 식별한다.
2. 분기: 발신 채널을 기준으로 카테고리를 정한다. 운영팀(리전 동작 이상) / 벤더 엔지니어팀(장비·ACL) / 특정 기관(데이터·기능 검증).
3. 트리아지: 5분 이내에 리전, AppKey, 발생 시각, 영향 범위 같은 최소 정보를 모은다. 이게 안 모이면 조사로 넘어가지 않는다.
4. 조사: 카테고리별 런북의 점검 단계를 따라간다(해당 도메인 테이블, 배치 로직, 메시지 토픽, 캐시, 장비 통신 등).
5. 대응 + 마스킹: 대응 표를 적용하고, 외부로 나가는 답변은 마스킹 가이드를 거친다.
6. 종결: 태스크를 완료하고, 재발 방지는 별도 작업으로 분리한다.

여기서 트리아지를 "관문"으로 둔 게 의도적이다. 정보가 부족하면 조사를 시작하지 못하게 막아, 헛조사를 줄였다.

마스킹을 규칙으로

폐쇄망/공공 도메인이라 외부로 나가는 답변의 위생이 특히 중요했다. 그래서 마스킹을 가이드로 명문화했다.

• AppKey: 앞 4자리 + ***.
• 자격증명(API Key/토큰/비밀번호/인증서): 외부 응답에 절대 포함하지 않는다.
• 고객사 명칭: 외부 답변에서는 "특정 공공기관"처럼 일반화한다.
• 서버 호스트명/IP: 마스킹한다.

컨벤션은 단일 진실 소스로

코드 규칙(스타일, 레이어링, JPA/QueryDSL, 프로필 분기, Kafka 요청-응답, 분산락, DB 쿼리 리뷰, 테스트)은 각각 스킬 파일로 두고, convention-check가 변경된 파일의 경로 패턴으로 적용할 규칙을 골라 그 스킬 파일을 직접 읽어 검증한다. 규칙을 어딘가에 복사해 두지 않으니, 규칙을 고치면 검증도 자동으로 따라온다. 위반은 CRITICAL(레이어/의존성/보안), HIGH(명시 컨벤션), MEDIUM(개선 권고)로 나눠 리포트한다.

작업 기억의 외부화

3단계 이상 복잡한 작업은 ai-memory-plan이 계획서(무엇을), 맥락노트(왜 그렇게 결정했는지), 체크리스트(어디까지 했는지) 3종 문서를 만든다. 대화가 끊겨도 이 세 파일만 읽으면 맥락이 복구된다. 이 레포에서는 plan 폴더를 로컬 메모리 모드로 운영한다.

구조

고객 문의가 들어왔을 때의 트리아지 분기다.

전체 스킬 세트의 책임 분리는 이렇게 본다.

무엇이 남았나

런북으로 얻은 건 단순히 "빨리 답한다"가 아니었다. 1차 대응의 모양이 사람과 무관하게 일정해졌고, 같은 유형의 문의가 세 번째 들어오면 "이건 런북 항목으로 승격"이라는 신호로 읽히게 됐다. 반복 업무가 자산으로 쌓이기 시작한 것이다.

재발 방지도 네 갈래로 표준화했다. 코드 레벨 방어 추가, 벤더 운영 가이드 갱신, 운영팀 알림 룰 추가, 런북 업데이트. 문의 한 건이 끝나면 이 중 어디에 흔적을 남길지 정하고 종결한다.

폐쇄망 환경에서 AI를 운영에 들이는 일은 "마스킹과 가드레일을 먼저 설계하느냐"로 성패가 갈린다고 본다. 절차를 고정하고, 외부로 나가는 모든 답변에 마스킹 관문을 두는 것. 그게 반복 업무 표준화의 핵심이었다.