서버 코드 자동 생성 툴: Sherpa는 왜 완전 자동화를 선택하지 않았을까

AI 챔피언 9번째 이야기 — T&A실 Experience팀 김관주님

마이리얼트립 T&A실의 제품을 책임지는 Experience팀 김관주님은 스스로를 “처음부터 개발자가 되겠다고 마음먹었던 사람은 아니다”라고 말합니다. 커리어는 우연처럼 시작됐고, 목표는 일을 하면서 생겼다고 하면서요.

대신 분명한 기준 하나는 있었습니다. 일을 잘 끝내고, 그 결과로 신뢰를 얻는 것. 관주님에게 개발은 그 과정이 가장 또렷하게 드러나는 일이었습니다.

그래서인지 관주님은 자동화에 유독 예민했습니다. AI가 코드를 잘 만들어주는 건 이미 당연한 시대였지만, “그 결과를 정말 믿어도 되는가”라는 질문에는 쉽게 넘어가지 않았습니다.

Sherpa 프로젝트를 바라보는 관점도 비슷했습니다. 코드는 자동으로 생성되고 있었지만, 사람은 여전히 결과를 다시 확인하고 있었습니다.

관주님은 이 상황이 마음에 걸렸다고 합니다. 자동화가 늘어날수록, 사람이 더 바빠지고 있다는 현실.

이 프로젝트는 그 불편함에서 시작됐습니다. 자동화는 분명히 되고 있는데, 왜 신뢰는 따라오지 않는지에 대한 질문이었습니다.

병목은 코드가 아닌 마크다운이었다

Sherpa는 연동사 API 문서를 기반으로 서버 코드를 자동 생성하는 도구입니다.

구조만 보면 단순합니다. 문서를 마크다운으로 정리하고, 그 마크다운을 기반으로 코드를 생성합니다.

문제는 이 중간 단계였습니다. 바로 마크다운이었습니다.

원본 문서 대비 필드가 누락되거나, 옵션 설명이 빠지는 일이 반복됐습니다. 이런 누락은 테스트로도 쉽게 잡히지 않았습니다.

결과적으로 만들어지는 것은 겉보기에는 정상처럼 보이지만, 운영에서는 위험한 코드였습니다.

관주님은 이 문제를 “AI가 아직 부족해서”라고 보지 않았습니다. 마크다운을 만드는 과정 자체가 검증되지 않은 채 자동화되고 있다는 점이 더 근본적인 문제라고 봤습니다.

수집 로직만 고쳐서 해결될 문제는 아니었다

초기에는 문서를 내부에서 검증 가능한 형태로 맞추기 위해, 여러 문서 유형을 동일한 구조로 재현하려는 시도가 있었습니다. 하지만 연동사가 늘어날수록 문서 구조와 표현 방식의 편차가 커졌고, 사소한 UI 변경만으로도 이 방식이 쉽게 깨진다는 한계가 드러났습니다.

이 시점에서 관주님은 문제를 이렇게 정리했습니다. 문제는 결과의 완성도가 아니라, 특정 표현 방식에 의존하고 있다는 점이었습니다.

PDF를 AI에게 맡기는 선택이 위험했던 이유

다음 시도는 더 과감했습니다. PDF 문서를 AI로 바로 마크다운으로 변환하는 방식이었습니다. 속도는 빨랐지만, 결과를 신뢰할 수는 없었습니다.

어디서 누락이 발생했는지 알 수 없었고, 표 구조가 왜 깨졌는지도 설명할 수 없었습니다. 무엇보다 문제였던 건 원본과 결과를 비교할 기준이 없다는 점이었습니다.

이 경험을 통해 한 가지 결론이 분명해졌습니다.

원본을 기준으로 검증할 수 없는 자동화는 운영에서 사용하기 어렵다는 판단이었습니다.

HTML을 기준 진리로 삼다

전환점은 “무엇을 기준으로 삼을 것인가”라는 질문에서 나왔습니다. AI Lab과의 협업 과정에서 나온 제안은 단순했습니다. 문서의 형태가 아니라, 모든 문서를 동일한 HTML 구조로 먼저 재현하자는 것이었습니다.

PDF든 SPA든, 어떤 형태의 문서든 완전한 HTML로만 확보할 수 있다면 그 HTML을 기준 진리(source of truth)로 삼을 수 있습니다.

이 선택의 핵심은 편의성이 아니었습니다. 검증이 가능해진다는 점이었습니다.

변환 파이프라인을 나눈 이유

HTML이 기준이 된 이후에도, 변환 방식은 신중하게 설계됐습니다. HTML을 한 번에 마크다운으로 변환하는 방식은 선택되지 않았습니다. 관주님이 중요하게 본 지점은 분명했습니다.

LLM 컨텍스트에는 한계가 있고, 문제가 발생했을 때 어디서 실패했는지 알 수 있어야 했습니다.

그래서 파이프라인은 의도적으로 나뉘었습니다. HTML을 분류하는 단계, API 단위로 마크다운을 생성하는 단계, 그리고 각 마크다운의 위치 정보를 기록하는 인덱스 생성 단계였습니다.

이 구조 덕분에 자동화는 처음으로 디버깅 가능하고 재실행 가능한 형태가 됐습니다.

이 구조가 만들어낸 가장 큰 변화는, 마크다운이 더 이상 문서의 끝이 아니라는 점이었습니다.

마크다운은 코드의 시작점이 된다

검증된 마크다운을 입력으로 삼아, Sherpa는 실제 연동에 사용되는 API Client 코드를 생성합니다.

연동을 진행했던 SwissActivities Leisure-Link API 문서를 기준으로 생성된 코드는 별도의 손작업 없이, 기존 프로젝트의 core / infra 레이어 구조 안으로 자연스럽게 들어갔습니다.

문서에 정의된 범위는 인터페이스와 DTO, WebClient 구현과 예외 처리, 설정 파일까지 하나의 코드 구조로 이어졌습니다.

중요한 건, 이 코드가 “생성됐다”는 사실이 아니라 기존 프로젝트에 그대로 써도 될 정도의 품질로 들어왔다는 점이었습니다.

검증 뷰어가 바꾼 사람의 역할

마지막으로 만들어진 것은 HTML과 마크다운을 동시에 보여주는 검증 뷰어였습니다. 같은 위치를 하이라이팅해 누락 여부를 빠르게 확인할 수 있도록 했습니다.

이제 사람은 문서를 처음부터 끝까지 읽지 않아도 됩니다.

사람의 역할은 바뀌었습니다. 모든 것을 직접 확인하는 검수자가 아니라, 자동화를 신뢰해도 되는지 판단하는 결정자가 됐습니다.

Sherpa - 도구를 넘어 인프라로

이 구조 이후 Sherpa의 성격은 분명히 달라졌습니다.

단순히 코드를 생성하는 도구가 아니라, 연동 자동화 전반의 정확성과 재사용성을 떠받치는 기준 구조가 됐습니다.

자동화를 더 밀어붙였기 때문이 아닙니다. 자동화를 믿을 수 있는 조건을 먼저 만들었기 때문입니다.

AI는 이미 코드를 잘 만들어냅니다. 하지만 그 결과를 어디까지 믿어도 되는지 결정하는 일은 여전히 구조를 이해하는 사람이 해야 합니다.

이 프로젝트는 AI를 더 쓰기 위한 시도가 아니었습니다. 관주님이 그 전에 AI를 활용 안 하던 개발자도 아니었습니다.

결국, AI를 쓰기 전에 무엇을 먼저 설계해야 하는지에 대한 고민이었습니다.