헤드리스 어드민: UI에서 AI로 환승한 어드민 이야기
세션 소개
배민 쿠폰 어드민은 2018년에 만든 레거시 「쿠폰 대장간」이 7년 넘게 그대로 남아 있었습니다. 조건이 촘촘히 얽힌 쿠폰 입력폼을 Schema Driven Architecture로 나눈 뒤, 웹 UI 자리에 AI를 넣어 대화로 쿠폰을 만드는 헤드리스 어드민 사례입니다.
핵심 내용
레거시 쿠폰 어드민이 바뀌지 않던 이유
입력값 하나만 잘못 들어가도 엉뚱한 고객 노출이나 정산 오류로 이어지는 폼인데, 개선 시도는 번번이 멈췄습니다.
| 이유 | 내용 |
|---|---|
| 우선순위 | 고객 대면 서비스와 비즈니스 로직 개선에 늘 밀림 |
| 거대한 입력폼 | 7년간 로직을 덧붙여 손대기 어려운 상태 |
| 개편 중 요구사항 | 기존·신규 어드민 양쪽에 같은 요구 반영. 개편이 길어질수록 부담이 커져 중단되기도 함 |
Schema Driven Architecture로 세 층 분리
화면과 규칙을 스키마로 서버에 두고 프런트엔드는 그 정의로 화면을 그립니다. 초기 설계 비용은 크지만 규칙이 바뀌어도 프런트엔드 코드를 고치지 않아도 되어, 규칙이 자주 바뀌는 쿠폰 어드민에 맞는 방식으로 골랐습니다.
| 층 | 내용 |
|---|---|
| 웹 UI | 화면 |
| 폼 Rule · Validation | 조건에 따라 필드를 숨기거나 잠그는 동적 동작, 입력값 검증 |
| API 스펙 | 서버 API |
- 결과: 첫 과제인 쿠폰 대장간은 일정에 맞춰 이전
그래도 웹 UI가 병목이 됨
커머스(장보기·쇼핑) 쿠폰 어드민도 같은 구조로 옮겨야 했는데, 새 쿠폰 형태 지원과 더 빠른 쿠폰 생성 요청이 한꺼번에 들어왔습니다. 구조를 나눠 두어도 복잡한 규칙을 웹 UI로 옮기는 작업이 사업 일정을 따라가지 못했습니다.
- 할인 유형을 정률→정액으로 바꾸면 할인율 칸이 할인 금액 칸으로 바뀌고 쿠폰 적용 범위의 배달팁이 잠기는 식의 연쇄 동작
- 「할인 유형이 정액」 룰 하나에 보이기·숨기기·초기화·선택지 잠금 동작 15개, 일부는 양방향
- 영향받는 필드: 분담 비율·금액, 할인 값, 중복·더하기 쿠폰, 사용 조건, 기간·수량, 정산 방식, 캠페인 등
- 필드 하나를 고칠 때마다 규칙 확인과 입력 상태·에러 표시·화면 전환 시 상태 관리까지 검토해야 해서, 이 검토가 기능 개발 시점을 늦춤
웹 UI만 AI로 바꾼 헤드리스 어드민
웹 UI를 고치는 대신 걷어 내고 AI 대화로 요청을 받는 구조로, 비즈니스 로직만 남은 어드민이라는 뜻에서 헤드리스 어드민이라고 불렀습니다. 에이전트에게는 폼과 버튼 대신 API나 CLI가 필요하다는 헤드리스 관련 글에서 아이디어를 얻었습니다.
| 층 | 헤드리스 어드민에서의 역할 |
|---|---|
| 웹 UI → AI | 대화로 요청 수집 |
| UI Schema | AI가 원래 화면 동작을 이해하는 데 사용 |
| 폼 Rule · Validation | 웹 어드민의 폼 Rule 178개, Validation 약 80개 그대로. 폼 엔진 코드도 함께 옮김 |
| API 스펙 | 웹 어드민의 서버 API 그대로 |
AI를 붙이는 위치는 두 가지를 비교해 정했습니다.
| 방식 | 구성 | 판단 |
|---|---|---|
| 어드민에 AI | 웹 어드민에 대화창 화면과 LLM 연동 인프라 신규 구축 | 대화창도 웹 UI라 상태·에러 처리 고민이 다시 생김 |
| AI에 어드민 | Claude Code 같은 사내 AI 도구에 헤드리스 어드민 스킬(지침서 · 스키마 · 폼 Rule · API 스펙)만 추가 | 채택. 웹 어드민을 건드리지 않아 언제든 되돌릴 수 있음 |
판정은 스크립트, 대화는 AI
AI는 확률적으로 동작해 언제 실수할지 예측하기 어렵습니다. 결과가 한 번이라도 달라지면 안 되는 판정과 데이터 처리는 모두 스크립트에 맡겼습니다.
| 담당 | 성격 | 하는 일 |
|---|---|---|
| 스크립트 | 결정론적 | 웹 어드민 규칙대로 검증, 통과한 값만 서버 전송, 생성 후 서버 저장본과 대조 |
| AI | 확률론적 | 자연어에서 스펙 추출, 빠진 필수 값 되묻기, 요약 확인, 결과 보고 |
- 수백 개 규칙을 프롬프트로만 검사하면 열 번 중 한 번쯤 잘못된 조건 통과 가능
- AI가 API 요청 데이터를 직접 조립하면 필드 누락·타입 변경 위험
- 명확한 규칙을 매번 AI가 추론하면 시간과 토큰 비용 낭비
- 예: "다음 주부터 일주일간 장바구니 10% 쿠폰"에서 기간·할인율을 뽑고, 검증기가 찾은 누락 값(스키마 필수인 최소 주문 금액, 폼 Rule이 이 조합에서 필수로 정한 캠페인)은 지난번 값을 먼저 제안하며 선택지로 되물음. 웹 UI의 필수 표시 역할을 대화가 대신함
내부 안전장치와 외부 안전장치
요청은 사용자 → AI → 게이트웨이 → 어드민 서버로 흐릅니다. 판정을 스크립트에 맡겨도 스크립트를 실행하는 쪽은 AI이므로, AI가 지침을 어겨도 잘못 동작할 수 없게 AI 전용 게이트웨이를 따로 두었습니다.
| 구분 | 항목 | 내용 |
|---|---|---|
| 내부(AI가 지키는 규칙) | 환경 확인 | 요청한 환경이 맞는지 먼저 확인 |
| 검증 | 분리해 둔 폼 Validation으로 입력값 검증 | |
| 생성 전 확인 | 요약을 보여 주고 사람이 최종 확인 | |
| 결과 대조 | 생성한 쿠폰그룹을 다시 조회해 요청 내용과 비교 | |
| 동작 제한 | 삭제·수정·승인·배포·발급은 직접 하지 않고 웹 어드민으로 안내 | |
| 외부(게이트웨이) | 사내 로그인 | 사람이 브라우저로 로그인, AI는 그 사람의 토큰으로 요청 |
| 어드민 권한 | 웹 어드민과 같은 권한 체계. 권한 신청·승인도 사람이 함 | |
| API 제한 | 정책에 등록된 API만 호출 | |
| 환경 분리 | 베타와 운영의 토큰·권한 분리 관리 |
두 사례로 확인한 범위는 다음과 같습니다.
- 규칙으로 막는 경우: 정액 2,000원 + 적용 범위 배달팁(
DELIVERY) 요청은discount-type-fixed(정액이면 장바구니만),discount-target-delivery(배달팁이면 정률만) 두 폼 Rule에 막혀 서버에 아무것도 보내지 않음. 웹 UI에서 막던 조합이 대화에서도 막히고, 이유를 더 자세히 설명함 - 규칙으로 못 막는 경우: 노출명 「15% 할인」에 정액 1,500원을 요청하자 AI가 이름과 실제 할인이 어긋난다고 짚고 정률 15% / 정액 1,500원·이름 변경 / 그대로 생성 중에서 고르게 함. 이름은 텍스트라 규칙 대상이 아니고 팀이 의도한 동작도 아니었음. AI가 모든 실수를 잡지는 못하지만 문맥까지 살핀다는 점을 확인한 사례
운영: 버전, 배포, 설정
헤드리스 어드민은 개인 자동화 스킬과 달리 실제 쿠폰 생성에 쓰이므로, 로그인·권한과 잘못된 요청 차단(앞 섹션) 외에 웹 어드민처럼 버전과 배포 체계도 갖췄습니다.
- 사내 스킬 허브(스킬의 버전·배포 범위 관리 도구)에 배포
- 실행할 때마다 새 버전을 확인해 자동 업데이트. 웹 어드민을 새로 배포하면 재접속 시 최신 버전을 쓰는 것과 같게 맞춤
- 맞춤 설정, 최근 선택, 생성 기록은 별도 사용자 폴더에 두어 업데이트 후에도 유지
| 설정 | 내용 |
|---|---|
| 프리셋 | 보고 길이, 질문 방식, 지난번 값 제안 여부 등 15개쯤 |
| 커스텀 | 프리셋에 없는 것은 자연어로 적으면 AI가 따름 |
| 변경 불가 | 안전 관련 설정. "검증 없이 보내라"라고 적어도 반영하지 않음 |
- 보고 형식 예: "앞으로 보고는 상세로"라고 하면 이후 보고가 간결(표와 결론)에서 상세(판단 근거 포함)로 바뀜. 간결 보고에서 "보낸 값 27개가 모두 같다"던 결과가 상세 보고에서는 "25개 일치, 빈 값 2개(
reissueAfterUse,settlementCalculateCriteria)는 서버가 저장 시 빼는 값"으로 정정됨
만드는 법과 쓰는 법의 변화
API를 인터페이스로 쓰면서 화면 고려 없이 해야 할 일과 하면 안 되는 일에만 집중하게 되었고, 새 기능을 웹 어드민보다 먼저 시도할 수 있게 되었습니다.
- 만드는 법: 구글 시트로 쿠폰을 여러 개 만드는 대량 생성 기능을 시트 읽기·쓰기 도구만 붙여 구현(웹 어드민에는 아직 없음). 웹 UI를 두고 다른 직군과 맞추는 리소스도 줄어듦
- 이어서 작업: 웹 어드민은 창을 오래 두면 세션이 풀리거나 상태가 꼬였지만, AI 도구는 세션 기록과 사용자 폴더 기록으로 다음 날에도 이어 가고 "지난번에 뭐 만들었지?"에 바로 답함
- 하나의 흐름: 생성부터 승인 요청(승인자 후보 제시), 목록 확인까지 대화 안에서 이어지고, 다음 단계 안내와 기능 문의도 AI에게 바로 함
웹 어드민이 남은 이유
웹 어드민은 그대로 두었고, 지금은 대화로 쿠폰을 만들고 웹 어드민에서 확인·승인하는 식으로 상황에 맞게 골라 씁니다.
| 이유 | 설명 |
|---|---|
| 간단한 작업은 AI가 더 느림 | 요청을 읽고 생각하는 기본 대기 시간이 늘 듦. 쿠폰 하나 만들기는 웹 UI가 빠름 |
| 여러 쿠폰 비교는 웹 UI가 나음 | CLI 표는 글자로 그린 표일 뿐이고, 웹 UI는 정돈된 화면에서 눌러 가며 확인 가능 |
| 실수하면 안 되는 동작 | 승인·배포·삭제는 오래 검증된 웹 UI로 함. 확률적인 AI에 맡기기엔 이르다고 판단(가장 큰 이유) |
앞으로
| 계획 | 내용 |
|---|---|
| 하나의 경험 | 웹 어드민과 헤드리스 어드민을 오갈 때 끊기는 작업 맥락 연결 |
| 화면 그리기 | 비교처럼 웹 UI가 나은 작업에서 AI가 화면을 그려 브라우저에 띄움 |
| 사용량 측정 | 대화 속 작업 요청을 로그로 남겨 실제 사용량 측정 |
| 위험한 작업 | 승인, 배포, 삭제처럼 지금은 웹 UI에서만 하는 작업을 어떤 안전장치를 갖추면 대화로 할 수 있을지 실험 |