기술이 없던 곳에 기술 더하기: 사내 해커톤 플랫폼 만들기

그 어느 때보다 시스템이 필요해진 순간

우아한형제들에는 ‘우아톤’이라는 사내 해커톤이 있습니다. 구성원들이 무박 2일 동안 밤을 새워 가며 저마다 품어 온 아이디어를 마음껏 펼쳐 보는 무대입니다. 2019년 처음 열려 올해 7회를 맞았고, 어느새 사내 문화로 자리 잡았습니다.

올해는 회사 전체가 AI 활용을 넓혀 가자는 흐름에 맞춰 변화를 줬습니다. "AI와 함께 업무는 더 스마트하게, 서비스는 더 새롭게"라는 슬로건 아래 밤샘 대신 하루 만에 끝내는 원데이 챌린지로 형식을 바꿨고, 역대 가장 많은 36개 팀 153명이 참가했습니다. 전체 일정은 이렇게 짜였습니다.

저는 사내 기술 구성원의 배움과 성장을 돕는 Developer Relations(DR) 담당자입니다. 지난해 글로벌 해커톤에 이어, 올해는 우아톤을 기획하고 운영했습니다.

우아톤 운영 경험을 돌아보면, 결과물 제출이 마감되는 순간부터 늘 긴장의 연속이었습니다. 모든 팀이 제출했는지, 필수 제출 사항에 누락은 없는지 확인하고 심사를 거쳐 점수를 집계하기까지, 전체 과정이 제한된 시간 안에 실수 없이 진행되어야 했습니다. 올해는 참가팀이 크게 늘었는데 운영 인력은 부족했고, 행사가 하루로 압축되면서 각 단계에 쓸 수 있는 시간도 줄었습니다. 참가자의 작업 시간을 최대한 확보하고 나니 운영에 남는 시간은 예선 집계 15분, 결선 10분 안팎이었습니다.

특히 지난 글로벌 해커톤에서 급박하게 돌아가던 순간들이 떠오르면서 사람 손에만 맡기기엔 위험 부담이 크겠다 싶었습니다. 참가자는 결과물을 내기 편하고 운영자는 실수 없이 챙길 수 있는 시스템이 필요했습니다. 코드는 한 줄도 써 본 적 없었고 디자인도 Git도 GitLab도 처음이었지만, 마침 Claude가 전사 표준 AI 도구로 도입되며 사내 AI 교육 세션도 열려서 교육을 들으며 직접 만들어 보기로 했습니다.

시작은 작게, 파일과 드라이브 여기저기로 흩어지던 참가팀의 제출물을 한곳에서 취합하는 수고부터 없애 보자는 정도였습니다. 그런데 만들다 보니 운영을 어떻게 더 효율적으로 굴릴 수 있을까로 고민이 옮겨 갔고, 행사 전체를 한곳에서 관리하는 어드민까지 그려 보게 됐습니다. 그렇게 사내망 배포와 데이터베이스, AI 연동, 화면 디자인을 갖춘 운영 시스템이 됐습니다. 이 글에는 그 고군분투를 솔직하게 담았고, 특히 화면을 코드로 옮기는 과정은 저처럼 코드를 모르지만 AI로 무언가 만들어 보고 싶은 분들께 참고가 되길 바라며 조금 더 자세히 풀었습니다.

차례로 만난 네 개의 벽

첫 벽은 제출 페이지에서부터 시작됐습니다. 팀 이름과 파일을 받는 단순한 화면에 최소한의 디자인만 입혔는데, 이때만 해도 이 페이지는 제 컴퓨터에만 있는 HTML 파일이었습니다. 동료에게 보여 주려면 파일을 슬랙으로 보내야 했고, 받은 사람은 그 파일을 내려받아 브라우저로 열어야만 화면을 볼 수 있었습니다. ‘사이트처럼 바로 볼 수 있게 하려면 어떻게 하지?’ "그럼 배포해야 돼요." 얼핏 그런 답을 들었던 것 같습니다.

사실 그때는 배포를 하면 무슨 일이 일어나는지도 몰랐습니다. 단어는 여기저기서 들어 봤지만 직접 해 보는 건 처음이었습니다. 경험하고 보니 배포는 컴퓨터 안에만 있던 페이지를 서버에 올려서, 다른 사람들도 웹 브라우저에 주소를 입력하면 들어올 수 있게 만드는 일이었습니다. 이렇게 하나를 넘으면 다음 벽이 나타났습니다. 그렇게 이어진 여정이 이 글의 순서입니다.

① 사내 베타 배포: Failed to create deployment group

처음 Claude와 만든 코드는 Python이라는 언어로 짜여 있었습니다. 그런데 "Java나 Kotlin으로 포팅한 뒤 베타 배포하면 작업을 두 번 하지 않아도 된다"라는 조언을 받았습니다. 포팅이 뭔지 그때는 몰랐지만 코드를 다른 언어로 옮겨 다시 만드는 일이라고 합니다. 사내 표준이 Kotlin이니 어차피 옮길 거라면 지금 옮기라는 뜻이었습니다. 듣기엔 큰 작업 같은데 제가 한 일은 Claude에게 "FastAPI 대신 Kotlin과 Spring Boot로 바꿔 줘"라고 요청한 것뿐이었습니다. FastAPI는 Python으로, Spring Boot는 Kotlin으로 서버를 만들 때 쓰는 도구입니다. 이 문장 하나로 언어도 도구도 모두 바뀌었습니다.

다음은 배포 콘솔이었습니다. 배포에 필요한 설정을 입력하는 관리 화면인데, 이미 가이드 문서와 함께 어느 환경에 어떻게 올리면 되는지 방향을 안내받은 상황이었습니다. 나머지는 문서를 보며 낯선 항목을 하나씩 채워 나갔습니다. 테스트용 베타 환경에서 검증한 뒤 실제 운영 환경에 올린다는 건 알고 있었지만, 제가 만든 페이지도 그 절차를 밟게 될 거라고는 미처 생각하지 못했습니다.

문제는 제가 놓친 칸 하나, AWS Account였습니다. 베타 환경에 올리는 거니까 이름에 ‘beta’가 들어간 계정을 고르면 되겠지 싶어 그중 하나를 골랐는데, 엉뚱한 계정이었습니다. 화면에 빨간 글씨(Failed to create deployment group)가 떴습니다. 알고 보니 골라야 할 계정은 다른 이름으로 구분되어 있었습니다. 사실 이 계정은 앞서 보안팀에서도 안내받은 적이 있었는데, 그때는 어느 계정을 말하는지 감이 없어 지나쳤습니다. 실패하고서야 그 이름이 떠올랐고, 다시 보니 가이드 문서에도 적혀 있었습니다. 더 난감하게도 잘못 만든 건 지울 방법이 없어 배포 담당 팀에서 직접 정리해 주어야 했습니다. 결국 슬랙 채널에서 묻고 답하는 것만으로는 부족해 배포 담당자와 오프라인 미팅을 잡았고, 그 자리에서 남은 설정을 한 칸씩 함께 채웠습니다.

그렇게 남은 칸을 모두 채우고 드디어 배포 버튼을 눌렀습니다. 사내 배포 시스템에는 이 버튼을 누르면 자동으로 밟아가는 작업 순서표가 12단계로 정의되어 있었습니다. 어떤 기능이 활성화되느냐에 따라 실행되는 단계가 달라지는데, 제 경우엔 그중 5단계가 실행됐습니다. 진행률이 끝까지 차오르길 기대 반 걱정 반으로 지켜봤고, 3분 뒤 배포가 완료되며 제가 만든 페이지가 사내 주소로 열렸습니다. 와, 됐다! 최소 기능뿐인 화면이었지만 뿌듯했습니다. 기쁨도 잠시, 곧바로 다음 벽이 기다리고 있었습니다.

② 데이터베이스 구축: 로그도 없이 0.1초 만에 실패

화면은 떴는데 문득 이런 생각이 들었습니다. ‘그럼 팀들이 제출한 글과 데이터는 대체 어디에 저장되지?’ 만드는 동안엔 미처 생각하지 못했던 부분이었습니다.

처음엔 SQLite로 시작했습니다. 데이터베이스(DB)에도 여러 종류가 있는데 SQLite는 그중 가장 가벼운 방식입니다. 별도 서버 없이 데이터를 파일 하나에 저장하는 거라 혼자 만들어 보는 단계에선 이걸로 충분했습니다. 그런데 곧 문제가 생겼습니다. 사내 시스템은 안정성을 위해 같은 앱을 여러 대의 서버로 복제해 띄우는데 SQLite 파일은 서버마다 따로 있으니 데이터도 서버마다 따로 쌓였습니다. 어느 서버로 접속하느냐에 따라 로그인이 풀려 튕기기도 했고요. 모든 서버가 함께 바라보는 공유 DB가 필요했습니다. 후보는 사내에서 표준으로 쓰는 MySQL과 PostgreSQL이었습니다. 둘 다 별도의 DB 서버를 두고 여러 곳에서 동시에 접속해 쓰는 방식이라 이름만 다를 뿐 제 눈엔 차이를 알 수 없었습니다. 결국 문제가 생겨도 사내에서 빠르게 대처할 수 있고 행사 규모의 동시 제출에도 충분하다는 팀 내 개발자 의견에 따라 MySQL을 골랐습니다.

그런데 막상 앱을 띄우자 첫 명령이 0.1초도 안 돼 실패했습니다. 로그에는 원인조차 찍히지 않았습니다. 상세 기록(DEBUG 로깅)까지 켜 봤지만 소용없었고, 한참 엉뚱한 데서 헤매다 결국 DB 문의 채널에 물어보고서야 해결됐습니다. 제 계정에는 데이터를 조회하고 입력하는 기본 권한만 있고 테이블(데이터를 담는 표)을 새로 만드는 권한은 별도 신청으로 받아야 하는 게 사내 보안 정책이었던 겁니다. 권한이 없으니 요청은 시도조차 못 하고 곧바로 거부됐고 그래서 0.1초 만에 실패했던 것입니다. 저에겐 코드만이 아니라 권한과 정책도 벽이었습니다.

권한이 풀리고 앱이 떴지만 로그인은 여전히 서버마다 풀렸습니다. 로그인 상태(세션)를 각 서버가 따로 기억하는 게 아니라 공유 DB에 저장하도록 바꾸고서야 어느 서버로 접속해도 로그인이 유지됐습니다. 이제 데이터가 쌓일 곳이 생겼습니다. 다음은 눈에 보이는 부분, 화면이었습니다.

③ 디자인 구현: 아무리 맞춰도 미묘하게 어긋나는 화면

배포도 되고 데이터도 자리를 잡으니 이제 화면을 다듬을 차례였습니다. 특히 참가자 페이지에 신경을 썼습니다. 프로젝트 제출과 관련한 내용을 담은 화면이라 정보가 잘 전달되는지, 한눈에 읽히는지, 설명 없이도 직관적으로 쓸 수 있는지를 계속 들여다봤습니다. 화면 디자인은 직접 구상한 방향대로 Claude의 디자인 기능(Claude Design)으로 그려 냈습니다. 원하는 시안이 잘 안 나올 땐 같은 요청을 Figma Make에도 넣어 두 번째 시안을 받아 비교했고요.

정작 어려운 건 그다음이었습니다. 시안을 코드로 옮기면 분명 같은 화면인데 어딘가 달랐습니다. 처음엔 화면을 스크린샷으로 찍어 Claude에게 들이밀었습니다. ‘이거 다르잖아. 여기 다르잖아. 왜 그래?’ 그런데 그렇게 보여줘도 좀처럼 원하는 만큼 맞춰지지 않았습니다. 디자인 도구가 보여주는 화면과 코드가 만들어 내는 화면 사이엔 생각보다 차이가 있었습니다. ‘이 디자인을 어떻게 코드에 픽셀 단위로 정확히 옮기지?’ 이 이야기는 뒤에서 자세히 다루기로 하고 마지막 벽으로 먼저 넘어가겠습니다.

④ Bedrock 연동: 분명 맞는 키라고 하는데 인증이 안 된다

마지막은 AWS Bedrock으로 AI 모델을 붙이는 일이었습니다. Bedrock은 보안 이슈에 대비할 수 있고 여러 AI 모델을 한 창구에서 쓸 수 있는 사내 표준 도구입니다. 사내엔 Bedrock 접속 키를 빠르게 발급해 주는 전용 창구도 있었고요.

여기서 예상 못 한 벽을 만났습니다. 보통 AWS는 요청마다 비밀키로 ‘서명’을 만들어 인증합니다. 열쇠를 꽂아 돌려야 문이 열리는 방식입니다. 그런데 사내 창구에서 받은 건 비밀키가 아니라 ‘Bearer 토큰’이었습니다. 들고만 있으면 통과되는 출입증 같은 것이었습니다.

문제는 SDK라는 표준 도구가 기본적으로 서명할 비밀키부터 찾는다는 것이었습니다. 저에겐 비밀키 없이 토큰만 있으니 토큰을 어디에 넣어도 SDK는 계속 서명을 시도하다 실패했습니다. 같은 실패가 반복되자 뒤늦게 사내 Bedrock 연동 가이드를 찾아봤고 답이 있었습니다. 가이드대로 SDK가 서명하려는 동작을 꺼 두고 요청에 토큰 한 줄을 직접 끼워 넣자 그제야 통과됐습니다. Claude와 코드를 짜다 막힐 때마다 먼저 봐야 할 건 사내 가이드였습니다.

 
그렇게 하나씩, 네 번째 벽까지 넘었습니다. 그동안 만든 것을 한 장에 모아 보면 이런 구조입니다.

핵심은 수작업을 거치지 않고 데이터가 자동으로 흐르게 만든 것입니다. 팀이 제출한 자료는 동료평가가 시작되면 참가자에게 바로 보이고, 예선을 통과한 TOP10은 그대로 경영진의 최종 심사 화면에 오릅니다. 이 사이에 누군가 데이터를 모으고 옮기는 일은 없어졌습니다. 15분 안에 집계를 끝내야 했던 그 문제를 이렇게 풀었습니다. 각 단계를 열고 닫는 일은 어드민에 모아 두었고 해커톤이 끝난 뒤에는 제출된 프로젝트를 모아 온라인 전시 공간인 프로젝트 라운지도 만들었습니다.

이 구조가 만들어지는 동안 작업 환경도 함께 바뀌어 왔습니다. 처음엔 Claude 데스크톱 앱의 채팅 기능과 일반 터미널로 시작했습니다. 그다음엔 여러 파일을 한 번에 다루는 Claude Cowork로 옮겼는데 여기까지는 코드가 늘 때마다 스크린샷으로 화면을 주고받아야 해서 금세 화면이 캡처로 뒤덮이곤 했습니다. 그러다 개발자 동료의 추천으로 IntelliJ(코드 작성부터 실행, 오류 확인까지 한곳에서 하는 통합 개발 환경, IDE)를 설치했습니다. 처음엔 그 안에서도 Claude Cowork에 계속 물어보고 답으로 받은 코드를 복사해 붙여 넣어 커밋했는데 얼마 뒤부터는 IntelliJ 터미널에서 Claude Code를 직접 호출해 구현하고 커밋과 푸시까지 이어지는 흐름으로 정착했습니다. 코드가 전부 남으니 오류 추적도 한결 수월했고요.

이렇게 도구까지 갖춰졌지만 마지막까지 저를 붙든 벽이 하나 남아 있었습니다. 위쪽 그림 속 화면들을 시안 그대로 옮기는 일, 세 번째 벽입니다. 이제 그 이야기로 들어가, 제가 쓴 프롬프트까지 보겠습니다.

화면을 코드로 ‘정확히’ 구현하기

화면까지 그려 냈으니 절반은 끝났다고 생각했습니다. 착각이었습니다. 디자인을 코드에 반영하려고 "이 디자인을 구현하라"는 지시문을 코딩 AI용으로 자동 생성해 주는 handoff 기능을 적용했습니다. 그런데 막상 띄워 보니 화면이 달랐고 원본과 나란히 놓고 짚어 고쳐도 다른 데서 또 어긋났습니다. 왜 반복되는지 원인이 좀처럼 잡히지 않았습니다.

수십 번의 시도 끝에 원인이 잡혔습니다. 무엇을 넘기느냐에 따라 깨지는 쪽이 정반대였습니다. handoff 링크만 넘기면 화면의 뼈대와 이미지 같은 재료 중심이라 동작은 살아나도 색이나 간격이 조금씩 변형됐고, 반대로 디자인 화면(HTML)만 전달하면 겉모습은 똑같아도 버튼 동작(JavaScript, 서버 연결)이 빠졌습니다. AI는 "이 값 그대로"라는 지시가 없으면 근사치를 쓰고, 그게 쌓여 ‘미묘하게 다른’ 화면이 됐던 겁니다.

아래 그림은 이해를 돕기 위해 만든 예시입니다. 가운데가 기준 화면이고, 왼쪽은 handoff 링크만, 오른쪽은 HTML 파일만 넘겼을 때의 결과입니다. 왼쪽은 색과 간격이 어긋나고, 오른쪽은 동작이 빠진 게 보입니다.

이후로는 두 가지를 함께 넘겼습니다. 하나는 Claude Design의 handoff 링크(구조와 자산)였습니다. 다른 하나는 지침서였습니다. 처음엔 간결한 줄글 지시문으로 충분했지만, 사이트가 커질수록 그것만으로는 감당이 안 됐습니다. 그래서 Claude Design에게 "이 화면을 Claude Code로 한 치 오차 없이 옮기려면 어떻게 전달해야 해?"라고 물어 가며, 필요한 내용을 한 파일에 담은 HTML 지침서로 정리했습니다. 링크와 이 지침서를 같이 주자 디자인 값은 거의 그대로 유지되고 동작 누락도 눈에 띄게 줄었습니다.

여기에 또 하나 중요한 장치가 있었습니다. 지침서에 "비슷하게"를 금지한 것입니다. Claude에게 단순히 "이 디자인처럼"이 아니라, 정확한 색상 값(Hex 코드)과 치수(px)를 그대로 따르라고, 그리고 코드 스타일과 디자인 값이 충돌하면 디자인 값을 우선하라고 못을 박았습니다.

예를 들어 #2E7D6B는 색을 나타내는 코드로, # 뒤 여섯 자리가 특정한 초록색 하나를 정확히 가리킵니다. 앞서 말한 근사치가 바로 이런 자리에서 생깁니다. #2E7D6B를 #2E7C6A로 바꾸는 식입니다. 이 ‘그대로’는 색과 치수만이 아니라 텍스트에도 해당했습니다. Claude가 오탈자를 고친다며 문구를 슬쩍 다듬는 일이 있어 지시문에 "텍스트는 한 글자도 바꾸지 마라"를 덧붙였습니다.

이런 규칙을 담아 handoff 링크와 함께 넘긴 지침서의 주요 내용은 아래와 같습니다.

완성도를 결정하는 마지막 5%

값을 아무리 정확히 넘겨도 끝내 남는 부분이 있었습니다. 대표적인 게 화면 위에 생기는 원인 모를 흰 여백이었습니다. 화면 높이와 요소 배치를 정하는 값을 껐다 켰다 하며 원인을 좁혀 직접 잡았습니다. 이 흰 여백 하나를 잡는 데만 자잘한 수정이 14번이었습니다.

흰 여백 말고도 잔손질이 이어졌습니다. 한글 단어가 줄 끝에서 어색하게 잘리지 않게 하고, 화면 폭에 따라 카드가 데스크톱 4열에서 태블릿 2열, 모바일 1열로 접히게 했습니다. 긴 제목은 두 줄까지만 보이고 넘치면 말줄임표로 처리했습니다. 이런 건 화면을 직접 띄워 보고 폭을 줄여 보며 하나씩 확인해야 하는 부분이었습니다.

‘직접 확인’ 과정에서 어이없는 실수도 했습니다. 참가팀의 작품을 한데 모아 전시하는 ‘프로젝트 라운지’ 페이지의 크기와 폰트를 조정하던 어느 날, 화면이 유독 크게 보여 한동안 헤맸는데 알고 보니 제 브라우저가 그동안 80% 축소 상태였습니다. 그동안의 작업을 전부 그 줄어든 화면에 맞춰 온 탓에 되돌리자니 처음부터 다시 손봐야 했습니다. 결국 페이지 전체를 80%로 축소한 채 확정했습니다.

기능 확정하고 화면끼리 어울리게 구성하기

복잡한 페이지에서는 작업 순서가 중요했습니다. 기능이 여럿 얽힌 화면은 디자인부터 그리면 기능이 바뀔 때마다 화면을 다시 손봐야 해서 필요한 기능을 먼저 확정한 다음 디자인을 입혔습니다. 대표적인 게 행사를 관제탑처럼 한곳에서 관리하는 어드민 페이지였습니다.

화면 사이의 조화도 문제였습니다. 한 페이지 안에 탭이 여럿 있었는데 각 탭을 그때그때 따로 디자인하다 보니 톤이 들쑥날쑥했습니다. 탭 하나만 보면 괜찮은데 나란히 열면 서로 통일감이 없었습니다. 결국 옆 탭과 어울리게 다시 다듬는 데 한참이 걸렸습니다. 뒤늦게 디자인이 들어가는 화면이라면 기존 탭의 디자인 코드를 Claude Code에서 먼저 받아 뼈대로 깔아 두고 그 위에 새 작업을 얹는 게 나은 순서였습니다.

화면 구현 작업을 하면서 깨달은 건, 마지막은 사람이 확인해야 하고 그 확인의 기준부터 어긋나면 안 된다는 것입니다. 명확한 규칙과 제약을 전달해 AI가 체감상 95%를 완성해 줘도, 남은 5%, 그 마지막 한 끗을 채우는 일이 이 작업에서 가장 오래 걸렸습니다. 실제로 이 라운지 페이지 하나도, 위 지침서대로 AI로 구현한 뒤에도 색과 간격을 바로잡고 오타를 고쳐 다시 커밋한 것만 22번, 대개 한두 줄짜리 수정이었습니다.

마지막으로, 최근 Claude Code와 Claude Design을 양방향으로 잇는 /design-sync 기능이 나왔습니다. 아쉽게도 모든 작업을 끝낸 뒤라 이번엔 적용해 보지 못했지만 앞으로 화면을 구현할 때 이 기능을 써 보며 오차 범위를 좁혀 나가려 합니다.

요청하는 사람에서, 직접 만들어 가는 사람으로

그동안 저는 "이런 화면, 이렇게 만들어 주세요"라고 요청하는 사람이었습니다. 이번엔 그 화면을 직접 만들고 AI가 놓친 흰 여백 하나까지 추적하는 사람이 됐습니다.

일하는 방식도 조금 달라졌습니다. 예전엔 텍스트 위주로, 어떻게 하면 글이 잘 읽힐까를 오래 고민했고 시각 자료는 글을 보완하는 정도로만 곁들였습니다. 이제는 글로 잘 와닿지 않는 부분을 간단한 프로토타입으로 직접 만들어 보여 줄 수 있게 됐습니다.

코드를 한 줄도 못 쓰지만 AI로 제가 필요한 부분을 해결해 가며 여기까지 올 수 있었습니다. 그렇게 이 플랫폼에 남긴, 실제 배포까지 올라간 공식 커밋이 392개였습니다. 처음엔 커밋이 하루를 마칠 때 한 번 하는 일인 줄 알고 그렇게 올렸는데(그땐 작업량도 많지 않았고요), 나중엔 한두 줄만 고쳐도 그때그때 올리게 되면서 어느새 이만큼 쌓였습니다. 행사를 앞둔 6월 12일엔 안정적인 운영을 위해 팀 내 개발자에게 인수인계를 했고 행사가 끝난 뒤엔 프로젝트 라운지 작업으로 다시 커밋을 이어 갔습니다.

아래 그래프는 4월 28일부터 6월 22일까지 날짜별로 제가 남긴 커밋 수를 나타낸 것입니다. 막대가 오른쪽으로 갈수록 높아지다가, 6월 12일 인수인계를 기점으로 잠시 멈춥니다. 행사가 끝난 뒤 프로젝트 라운지를 만들면서 다시 이어졌습니다.

이번 경험으로 개발자와 디자이너가 이 일을 얼마나 정교하게 해내는지 직접 체감하게 됐습니다. 제가 해 본 건 그중 아주 일부였지만, 이 경험만으로도 이런 일을 매일 더 빠르고 완성도 높게 해내는 두 직군 담당자가 대단하게 느껴졌습니다. 마감의 과정은 고되었지만 저에겐 무엇보다 의미 있는 시간이었습니다. AI로 체감상 95%를 구현할 수 있더라도, 완성도를 결정하는 마지막 5%는 여전히 사람의 눈과 끈질김의 몫이라는 생각으로 이 글을 마무리합니다.