그렇게 2년이 지나고 나서 회사의 인터랙티브 시스템이라는 프로그램에 문제가 생겼습니다. 인터랙티브 시스템은 웹사이트에서 강의 자료를 보고, 실시간 투표나 질문, 경품 추첨, 설문조사 등을 할 수 있는 시스템으로, 태블릿을 통해서 의사 선생님들 대상 심포지엄에서 사용하는 프로그램입니다.

그 프로그램 중 실시간 투표 시스템은 외부 프로그램이었는데요. 인터랙티브 시스템이 이 실시간 투표 시스템에 의존하고 있었습니다. 그런데 그 실시간 투표 프로그램의 정책이 바뀌면서 임베딩이 제한되어 버렸죠. 당장 일주일 안에 해결책을 내놓거나 새로 만들어야 하는 상황에 직면한 것입니다.

당연히 당황했죠. 영원히 변하지 않을 것 같았던 외부 프로그램이 업데이트를 거치면서 이런 일이 생길 거라고는 상상도 못 했습니다. 뭘 해야 할지 감이 안 잡혀서 사표를 던지고 싶은 기분이 들었습니다.

하지만 제가 뭔가 하지 않으면 심포지엄 행사가 망하게 되고, 행사가 망하면 회사의 거래가 끊길 수 있는 상황이었습니다. 저희가 기존에 계속 실시간 투표 시스템을 제공했기 때문에, 이를 제공하지 못한다면 최악의 경우 손해배상까지 청구될 수 있는 상황이었습니다.

해결 방법 고민: 새로 만드는 것이 답이다

여기서 엄청나게 고민했습니다. 당장 생각한 방법은 해당 외부 프로그램의 정책을 자세히 읽어보고, 인증을 받기 위해 문의 글을 남기고 며칠 기다리는 것이었습니다. 그런데 이 실시간 투표 시스템이 국내 프로그램도 아니었습니다. 해외 프로그램이라서 영어로 작성해야 했고, 피드백 시간도 오래 걸릴 것으로 예상되었습니다.

그래서 생각을 바꿨습니다. 차라리 아예 새로 만들어서 내가 컨트롤하는 게 가장 빠른 방법이 아닐까 싶었습니다.

저에게 주어진 시간은 단 일주일이었습니다. 다음 행사가 일주일 뒤에 열렸거든요. 매주 주말마다 심포지엄이 진행되기 때문에, 다음 주 주말 행사 전까지 해결해야 했습니다.

클로드 코드와 함께 시작한 개발

저는 아직 AI 친화적이지 않은 스파게티 같은 프로젝트에서 클로드 코드를 실행시켜 실시간 투표를 어떻게 만들어야 할지 물어보기 시작했습니다.

우선 가장 먼저 정한 것은 저희가 사용하고 있는 인프라를 그대로 사용하기로 한 것입니다. 사용자 세션 인증을 하고 있는 Redis, 데이터베이스는 MySQL, 그리고 최근에 SSE를 통해 개발했던 경험이 있어서 이를 활용하기로 결정했습니다.

이 세 가지 기술 스택을 정하고, 클로드와 함께 가이드 문서부터 작성하기로 했습니다.

사용자 시나리오 문서 작성

가장 먼저 클로드 코드와 함께 만든 문서는 사용자 시나리오 문서였습니다. 다음 주에 진행되는 행사는 제가 몇 번 가보고 계속 진행해 봤기 때문에, 행사장에서 원하는 요구사항은 손쉽게 파악할 수 있었습니다.

예를 들어 참여자가 태블릿을 통해서 해당 시간에 투표를 진행한다, 다음 투표가 넘어가면 화면이 바뀌어야 한다 등의 요구사항을 정리해서 사용자 시나리오를 만들었습니다.

그다음에는 관리자 시나리오를 작성했습니다. 관리자는 이벤트에 종속된 투표 이벤트를 생성할 수 있어야 하고, 투표를 여러 개 생성하고 수정할 수 있어야 합니다. 즉 CRUD를 할 수 있어야 하고, 투표에 관해서 다음 투표, 이전 투표로 왔다 갔다 할 수 있는 조작을 할 수 있어야 한다는 등의 시나리오를 작성했습니다.

CLAUDE.md 파일 생성

이렇게 기본 문서를 작성한 다음, 클로드가 프로젝트 전체 설정을 분석하게 해서 CLAUDE.md 파일을 만들었습니다. 이 파일에는 전체적인 구조, 기술 스택, 그리고 이 프로젝트가 어떤 목적을 가지고 있는지를 작성했습니다.

제가 직접 여러 번 검토했습니다. 이 코드는 제가 관리하고 유지보수하고 있었으니까, 직접 검수해서 맞는지 안 맞는지 판단했습니다. 목적에 부합하지 않는 것들을 수정하고, 이전에 작성했던 관리자 시나리오를 참고하게끔 추가했습니다.

핵심 문서들 작성

그다음부터 본격적으로 문서를 작성하기 시작했습니다. 가장 먼저는 데이터베이스를 가지고 어떤 데이터를 넣고 어떤 데이터를 참고할지 정하는 문서를 만들었습니다. 이 문서를 기반으로 프론트 서버, 프론트 동작 시나리오, 그다음에 API 계획서를 만들었습니다. 이 계획서를 앞으로 다른 코드를 짤 때 항상 필수적으로 참고할 수 있도록 핵심적인 문서로서 CLAUDE.md 파일에 추가로 기입해서 작성했습니다.

문서 관리의 어려움과 해결

그렇게 문서를 만들고 업데이트를 반복하다 보니 한 가지 문제가 발생했습니다. 관련 문서들을 확인하느라 토큰을 많이 사용하고, 사소한 시나리오 방향성을 수정할 때마다 문서 데이터가 점점 커지기 시작했습니다. 처음에는 500줄 이내로 시작했다면, 이제 2천 줄을 넘어가는 상황이 되었습니다. 기본적으로 클로드를 오래 실행할수록 문자열이 깨지는 버그가 있다 보니, 이 상태로는 정말 진행할 수가 없을 정도였습니다.

문서 압축 전략

다시 정신을 가다듬고 생각했습니다. 문서의 양이 많아서 수정할 때마다 확인해야 하는 시간이 길어진다면, 반대로 문서의 양을 줄이면 코드 작성하는 데 시간을 줄일 수 있지 않을까?

그래서 관련 문서를 읽는 시간을 먼저 줄이도록 개선하려고 노력했습니다. 제가 지금까지 작성했던 문서들을 자세히 보니, 대부분의 문서들이 사용자들이 쉽게 읽을 수 있도록 파악할 수 있도록 한글로 되어 있었습니다. 사용자가 이해하기 쉽도록 줄이 여러 개 쳐져 있고, 도표라든가 각종 이모티콘, 기호들로 줄 수나 데이터량이 많이 낭비되는 것들이 보였습니다.

그래서 클로드 코드에게 지금까지 작성한 문서를 압축하라고 요청했습니다. 그런데 한 가지 더 요청한 것은 이번에는 저 위주가 아닌, 클로드가 이해하기 쉬운 언어로 압축해 달라고 한 것입니다. "어차피 요구사항이 같은 것들은 제가 이미 다 알고 있으니까, 너만 이해하면 돼"라는 마인드로 "네가 이해할 수 있는 최고의 상태로 만들어"라는 프롬프트를 입력했습니다.

마지막 이미지를 보면, 2046줄(왼쪽)에서 359줄(오른쪽)로 많은 내용이 압축되었다는 것을 확인할 수 있습니다.

답변은 영어로 작성되었는데, 저는 영어를 잘 못해서 바로 한글로 문서 압축을 해달라고 했습니다. 그랬더니 이전에 말했던 이해하기 쉽게 줄쳐진 문장들, 쓸데없는 기호들, 줄 바꿈들이 대부분 삭제되어 최대 문서당 70% 이상은 압축할 수 있었습니다.

압축-검수-수정의 반복

압축을 한 후에는 그대로 사용하는 게 아니라 다시 한번 검수를 진행했습니다. 압축하면서 누락된 것들이 있지 않을까 생각했기 때문입니다. 압축하고 검수하고, 수정하고 업데이트하고, 다시 압축하고 검수하고 수정하고 업데이트하고... 이것을 계속 반복하면서 코드를 짜기 시작했습니다.

필요한 부분을 업데이트하면서 이전 대비 체감상 확실히 빨라졌습니다. 상황이 급박했던지라 정량화할 시간은 없었지만, 체감상으로도 확실히 문서를 읽고 코드를 작성하는 데 시간이 많이 빨라진 것을 느낄 수 있었습니다.

문서 분할 전략

그럼에도 불가피하게 문서가 많이 커지는 경우가 생겼습니다. 이런 경우에는 클로드 코드에 문서를 다시 분석하도록 요청했습니다. 이 문서의 역할이 무엇인가, 목적이 무엇인가, 세부 내용이 무엇인가를 기준으로 분석하게 했습니다.

예를 들어 관리자 시나리오에서 쓸데없는 API 항목이 들어갔다면 이런 문서를 걸러냈고, 관리자 시나리오인데 사용자에 대한 내용이 적혀있다면 걸러내면서 문서를 분할하기 시작했습니다.

이렇게 빠르게 문서와 코드를 작성하고 검토하고 압축할 수 있었던 이유는 요구사항을 제가 확실하게 알고 있었고, 무엇이 중요한지 확실하게 알고 있었기 때문입니다. 그래서 빠르게 확인해서 검수하고 분석하고, 코드를 작성하고 문서를 다시 업데이트하고 그렇게 진행할 수 있었던 것 같습니다.

최대한 한 문서당 천 줄 이상 넘어가지 않게 문서를 관리하려고 노력했고, 문서를 참고해서 코드를 작성할 때 문서를 읽는 속도가 압축하지 않았을 때보다 확실하게 빨라진 것을 정말 확실하게 체감할 수 있었습니다.

프론트엔드-백엔드 연결: 클로드가 클로드와 대화하다

이런 식으로 개발하다 보니 개발은 빠르게 할 수 있었습니다. 이제 남은 것은 실제로 연결해서 테스트해보는 것이었죠. 그런데 이 과정도 순탄하지는 않았습니다.

저희 repository가 모노레포였지만 프론트엔드와 백엔드가 분리되어 있었습니다. 그래서 바이브 코딩 시 클로드 세션에서 백엔드가 직접적으로 프론트엔드 코드를 참고하거나 프론트가 백엔드의 코드를 참조할 수가 없었습니다.

저는 프론트 작업을 할 때 API 호출 부분을 직접 코딩하다가 마음은 급한데 속도의 한계를 느껴서, 이걸 좀 편하고 빠르게 개선할 수 있지 않을까 생각했습니다.

리포트 방식의 의사소통

그러다 한 가지 생각이 났습니다. 어차피 프론트와 백엔드 repository가 분리되어 있고, 세션도 프론트와 백엔드가 분리되어 있었는데, 이 클로드 세션을 한 명의 인격으로 보고 각 파트에서 문제가 되는 부분을 정리해서 서로 읽게 한다면 제가 원하는 문제 해결이 좀 쉽게 되지 않을까 싶었습니다.

가장 먼저 프론트엔드 API를 계속 만들다가 뱅뱅 돌고 있는 클로드에게, 현재 발생하고 있는 오류가 무엇인지, 자기가 작업하고 있는 환경이 어떤지, 자기가 알고 있는 API endpoint가 무엇인지, 백엔드 API를 어디로 요청을 보냈는지, 백엔드 개발자에게 어떤 요청사항이 있고 확인이 필요한 사항이 있는지에 대해서 리포트를 작성하라고 했습니다.

그 리포트를 가지고 백엔드로 넘어갔습니다. 백엔드에서는 그 리포트를 읽게 하면서 답변을 보낼 때 자신이 가지고 있는 API endpoint가 무엇이고, 데이터를 보낼 때 어떤 형태, 어떤 형식으로 보내야 하고, 어떤 response가 오는지, 백엔드 아키텍처가 어떤 형식으로 되어 있는지를 문서로 만들었습니다. 이 문서를 프론트에 전달했습니다.

제가 의도한 대로 클로드 코드가 동작했습니다. 정말 기가 막힌 생각이었습니다.

클로드 코드가 서로 작업자로 인식하고, 문제가 생길 때마다 백엔드 작업자에게 리포트 형식으로 자기가 발생하고 있는 문제의 형식을 전달했습니다. 서로 대화가 아니라 리포트로 소통하는 상황이 발생했습니다.

이 방법은 정말 너무 간단했지만 효과적이었습니다. 그래서 빠르게 3일 만에 만들 수 있었습니다. 마지막으로 자기 전에 팀원들과 테스트를 했는데, 테스트도 정말 쉽게 진행되었습니다.

회고와 배운 점

지금 돌이켜 보면 다시 개선해야 하는 점도 많고, 초반에 시나리오에 집중하다 보니 UX를 좀 더 커버하려고 실제 필요한 기능보다 더 많이 만들려고 했습니다. 그런 것들이 없었다면 좀 더 빠르게 개발할 수 있지 않았을까 하는 생각이 듭니다.

지금까지 제가 클로드 코드를 활용해 문제를 해결하는 과정 전부를 말씀드렸습니다. 제가 현장 운영 매니저로서의 경험도 있기도 했고, 그때 당시에 정말 시간이 급박했던 것도 있었지만, 클로드 코드와 함께 이 방법을 통해서 3일 만에 기능을 완성했다는 사실이 아직도 뿌듯하기만 합니다.

비록 부족한 저의 경험과 발표였지만, 누군가에게 꼭 도움이 되셨으면 좋겠습니다. 감사합니다.