Claude와 함께한 행사용 웹앱 개발기

1. 들어가며

팀 단위 오프라인 행사에서 진행되는 대항 활동을 디지털로 전환하기 위해, 참가팀이 가상의 재화로 자원을 구매하고 결과물을 만들며 실시간으로 변동하는 조건에 대응해 점수를 겨루는 웹 기반 애플리케이션을 1인 개발 체제로 기획·구현했습니다. 기존에는 종이 대장과 수기 계산으로 진행되던 활동이라 진행자의 실수가 점수에 그대로 반영되거나, 참가자 입장에서는 자신의 자원 현황을 실시간으로 확인할 수 없다는 한계가 뚜렷했습니다. 이런 비효율을 실제로 겪어본 입장에서, '이 정도 규모의 시스템이라면 혼자서도 제대로 만들어볼 수 있지 않을까'라는 생각이 프로젝트의 출발점이 되었습니다.

동시에 개인적으로는 AI를 단순 보조 도구가 아니라 설계·구현·디버깅 전 과정에 걸친 개발 파트너로 활용했을 때 실제로 어디까지 생산성을 끌어올릴 수 있는지 검증해보고 싶다는 목표도 있었습니다. 기획부터 배포까지 전 과정을 혼자 감당해야 하는 제약이 오히려, Claude와의 협업 방식을 여러 각도로 실험하고 그 효과를 가감 없이 확인할 수 있는 좋은 기회가 되었습니다. 관리자용 대시보드, 참가팀별 자산 관리, 실시간에 가까운 이벤트 처리, 다수 동시 접속 환경에서의 안정성까지 요구되는, 짧은 일정 안에서는 결코 가볍지 않은 과제였습니다.

이 글은 프로젝트의 기술적 세부 사항보다, 이 과정에서 Claude를 어떻게 개발 파트너로 활용했는지에 초점을 맞춰 정리한 것입니다. 혼자서 기획부터 설계, 구현, 디버깅, 배포까지 전 과정을 감당해야 하는 상황에서 AI와의 협업 방식이 실제 생산성에 어떤 영향을 미쳤는지를 실무 관점에서 공유하고자 합니다.

2. 프로젝트 개요

프론트엔드는 React와 TypeScript, 백엔드는 Next.js API Routes 기반 서버리스 함수, 데이터베이스는 서버리스 PostgreSQL을 사용했습니다. 배포 플랫폼의 서버리스 함수 개수 제한이라는 현실적 제약이 있어, 기능 단위가 아닌 도메인 단위로 API를 묶는 설계를 초기에 확정했습니다. 이 설계 논의 자체도 Claude와의 대화를 통해 여러 대안을 비교하며 결정한 것으로, 이후 프로젝트 전반의 구조를 좌우하는 중요한 시작점이 되었습니다.

3. Claude와의 협업 원칙

이번 프로젝트에서 Claude는 코드 자동완성 도구를 넘어, 설계 논의부터 디버깅, 리팩토링까지 함께하는 협업 파트너 역할을 했습니다. 여러 차례 시행착오를 거치며 정리한 협업 원칙은 다음과 같습니다.

“완벽한 답을 한 번에 받으려 하기보다, 질문의 정확도를 높이는 데 시간을 쓰는 것이 결과적으로 더 빨랐다.”

돌이켜보면 Claude를 효과적으로 활용하는 핵심은 결국 '얼마나 구체적인 맥락을 제공하는가'에 달려 있었습니다. 모호한 요청은 모호한 결과로 돌아왔고, 제약 조건과 기존 패턴을 명확히 제시할수록 실무에 바로 반영할 수 있는 결과물이 나왔습니다. 이는 단순한 팁이 아니라, AI를 개발 프로세스에 편입시킬 때 요구되는 커뮤니케이션 역량 자체가 새로운 생산성 요소라는 것을 의미했습니다.

4. 실제 협업 사례

4.1 설계 논의: 구조 변경의 범위를 함께 정리하기

초기 데이터 모델에서는 하나의 주체가 소속 정보와 자산을 동시에 가지고 있었는데, 실제 요구사항이 구체화되면서 '누가 활동에 참여하는가'와 '누가 자산을 소유하는가'를 분리해야 하는 상황이 발생했습니다. 이런 구조 변경은 관련된 모든 조회 로직과 권한 체계에 연쇄적으로 영향을 준다. 이때 Claude에게 곧바로 코드 수정을 요청하지 않고, 먼저 '이 변경이 영향을 주는 파일과 로직 목록을 함께 정리해달라'고 요청했습니다. 그렇게 나온 목록을 기준으로 하나씩 순서대로 반영하니, 누락이나 충돌 없이 마이그레이션을 마칠 수 있었습니다. 이 경험을 통해 AI에게 실행을 맡기기 전, 먼저 '지도'를 함께 그리는 단계가 얼마나 중요한지 체감했습니다.

4.2 최신 라이브러리 대응: 문서와 실제 동작의 간극 좁히기

이벤트 예약 처리를 위해 도입한 스케줄링 라이브러리가 마침 메이저 버전업을 거치면서, 기존에 알려진 사용법과 실제 동작이 어긋나는 지점들이 있었습니다. 이럴 때는 에러 메시지와 사용 중인 버전 정보를 Claude에게 함께 제공하고, 공식 문서상 API와 실제 동작의 차이를 하나씩 짚어가며 맞춰나갔습니다. 특히 트리거 설정 위치, 취소 조건 지정 방식, 시간대 변환처럼 미묘하지만 치명적인 부분에서 이 방식이 유효했습니다. 최신 기술을 다룰 때는 AI의 학습 시점과 실제 최신 버전 사이에 간극이 있을 수 있다는 점을 인지하고, 에러 로그와 버전 정보를 적극적으로 공유하는 것이 문제 해결 속도를 크게 좌우했습니다.

4.3 단계적 디버깅: 증상부터, 결론은 나중에

버그가 발생했을 때 곧바로 '고쳐 줘'라고 요청하기보다, 증상을 최대한 구체적으로 설명하고 원인 후보를 함께 좁혀나간 뒤 수정하는 순서를 지켰습니다. 특히 비동기 처리 타이밍이나 데이터베이스 제약 조건과 관련된 버그는 성급하게 해결책부터 적용하면 겉보기 증상만 사라지고 근본 원인이 남는 경우가 많았습니다. 원인을 먼저 설명하도록 요청하고, 그 설명이 실제 로그·데이터와 일치하는지 검증한 뒤에 수정을 진행하는 방식이 재발률을 크게 낮췄습니다.

4.4 리팩토링 시점 판단: 반복이 세 번째면 추출한다

기능이 늘어날수록 화면마다 비슷한 UI 패턴(필터, 로딩 처리, 확인창)이 반복해서 등장했습니다. 이때마다 Claude와 '이 패턴을 재사용 컴포넌트로 추출할 시점인지'를 함께 판단했는데, 정해둔 기준은 '동일 패턴이 세 번째 화면에 등장하는 순간'이었습니다. 이 기준을 명확히 대화에 포함시키자, Claude도 이후 유사한 요청이 올 때 먼저 재사용 가능성을 언급해주는 식으로 대응이 달라졌습니다. AI와의 협업이 반복될수록 대화 속에 쌓인 맥락 자체가 일종의 팀 컨벤션처럼 작동한다는 것을 확인할 수 있었습니다.

4.5 코드 리뷰 관점의 협업: 결과보다 근거를 묻기

Claude가 제시한 코드를 그대로 적용하기보다, 왜 그런 구조를 선택했는지를 되묻는 과정을 습관화했습니다. 예를 들어 특정 조회 로직에서 조인 방식을 제안받았을 때 '이 방식을 선택한 이유와 대안이 있다면 무엇인지'를 물었고, 그 답변 속에서 더 단순한 대안이 드러나는 경우가 종종 있었습니다. 이는 실제 사람 동료와의 코드 리뷰에서 하는 질문과 크게 다르지 않았습니다. AI가 제시한 결과물을 그대로 수용하지 않고 근거를 검증하는 절차를 거치는 것이, 결과적으로 코드 품질뿐 아니라 개발자 본인의 이해도를 유지하는 데에도 중요했습니다.

또한 하나의 큰 요청을 던지기보다, 검증 가능한 단위로 요청을 쪼개는 것도 효과적이었습니다. 예를 들어 '거래소 기능 전체를 만들어줘' 대신 '거래 등록 → 거래 목록 조회 → 거래 체결'처럼 단계를 나누어 요청하면, 각 단계마다 실제 동작을 확인하고 다음 단계로 넘어갈 수 있어 오류를 조기에 발견할 수 있었습니다. 결과물의 크기와 검증 주기를 맞추는 감각은 AI 협업에서도 사람과의 협업 못지않게 중요한 역량이라는 것을 체감했습니다.

5. 정량적으로 돌아본 프로젝트

완성된 시스템의 규모를 숫자로 정리하면 다음과 같습니다. 배포 플랫폼의 제약 안에서 백엔드 API는 11개 파일로 압축했고, 그 안에서 인증·조직·팀·구성원·자원·결과물·거래·조합·환율·이벤트 및 로그까지 총 11개 도메인을 처리합니다. 데이터베이스 테이블은 20개로 구성되어 있으며, 프론트엔드는 관리자용 화면 9종과 참가자용 화면 5종, 총 14개의 주요 화면으로 나뉩니다. 개발 기간 내내 데이터 모델을 두 차례 크게 재설계했음에도 일정을 지킬 수 있었던 것은, 변경 범위를 먼저 목록화하고 하나씩 순서대로 반영하는 협업 습관 덕분이었습니다.

• API 파일: 11개 (도메인 단위로 통합 설계)

• 주요 데이터 테이블: 약 20개

• 화면(View) 구성: 관리자 9종, 참가자 5종

• 데이터 모델 재설계: 2회 (① player-team-package 소유 구조 분리, ② 거래소 매입/매도 방식 → 단방향 판매 구조 전환)

6. 배운 점: AI 협업에서 얻은 실무 인사이트

• 맥락의 구체성이 결과물의 품질을 결정한다: 같은 질문이라도 제약 조건과 기존 코드 맥락을 함께 제공했을 때와 그렇지 않았을 때의 결과물 품질 차이가 컸습니다.

• 실행보다 '지도 그리기'가 먼저다: 구조 변경처럼 영향 범위가 넓은 작업은 곧바로 실행을 요청하기보다, 영향 범위를 함께 정리하는 단계를 거치는 것이 재작업을 줄였습니다.

• 대화는 누적된 자산이 된다: 설계 의도와 의사결정 근거를 대화 중에 명시적으로 정리해두면, 이후 관련 작업에서 반복 설명 없이 일관된 결과를 얻을 수 있었습니다.

• 최신 기술일수록 사람의 검증이 필요하다: 라이브러리 버전이 최신일수록 AI의 학습 시점과 괴리가 생길 수 있어, 에러 로그와 공식 문서를 함께 대조하는 습관이 중요했습니다.

• AI는 도구가 아니라 협업 상대에 가깝다: 코드를 대신 써주는 도구로 대하기보다, 의사결정 과정에 참여시키고 근거를 함께 쌓아가는 파트너로 대할 때 생산성 향상 폭이 훨씬 컸습니다.

7. 마치며

이번 프로젝트를 통해 얻은 가장 큰 배움은, 'AI에게 무엇을 맡길지'보다 'AI와 어떻게 대화할지'가 결과물의 품질과 개발 속도를 함께 좌우한다는 확신이었습니다. 구체적인 맥락 제공, 명확한 제약 조건 전달, 단계적인 검증이라는 세 가지 원칙을 지켰을 때 1인 개발 체제에서도 정해진 기간 안에 실제 서비스 수준의 결과물을 완성할 수 있었습니다.

이는 특정 프로젝트에 국한된 경험이 아니라, 앞으로의 업무 전반에 적용 가능한 협업 방법론이라고 생각합니다. AI를 실무 개발 파트너로 활용하는 역량은 결국 명확하게 사고하고 소통하는 역량과 직결되며, 이번 경험을 바탕으로 이 방식을 팀 업무 전반에도 점진적으로 적용해보고자 합니다.

PYS