AI로 첫 웹앱 만들 때 진짜 막히는 지점 5가지, 코드보다 먼저 무너진 건 ‘맥락’이었다

2026년 08월 22일

0 Views

AI로 첫 웹앱 만들 때 진짜 막히는 지점 5가지, 코드보다 먼저 무너진 건 ‘맥락’이었다

AI로 첫 웹앱 만들 때 진짜 막히는 지점 5가지 직접 겪은 것 기준으로 말하면, 문제는 “AI가 코드를 못 짜서”가 아니라 요구사항, 실행 환경, 인증, 배포, 수정 루프가 한 번에 엉키는 데서 터졌습니다. 저는 Claude Code와 Cursor로 작은 할 일 공유 웹앱을 만들며 이 다섯 군데에서 시간을 가장 많이 날렸고, 결국 해결책은 프롬프트를 길게 쓰는 게 아니라 작게 쪼갠 작업 단위와 검증 루프를 먼저 만드는 것이었습니다.

30분짜리 최소 웹앱 범위를 먼저 정하고, README와 .env.example부터 만들어보세요.

처음 만드는 분들은 “로그인 붙이고, DB 붙이고, 배포하면 끝 아닌가?”라고 생각하기 쉽습니다. 저도 그랬는데, 실제로는 첫 화면이 뜨기 전까지 AI에게 맡길 일과 사람이 직접 확인할 일을 나누는 게 더 중요했습니다.

처음 만드는 웹앱이라면 먼저 30분짜리 최소 기능부터 잡아보세요.

화면 1개, 데이터 1개, 배포 1번까지 끝내는 흐름을 만든 뒤 기능을 늘리는 쪽이 훨씬 덜 막힙니다.

제가 실제로 쓴 셋업: Next.js + Supabase + Vercel + Claude Code

이번 기준은 거창한 SaaS가 아니라 “로그인한 사용자가 할 일을 저장하고 공유 링크로 보여주는 웹앱”이었습니다. 로컬은 Node.js, 패키지는 pnpm, 프레임워크는 Next.js, DB와 인증은 Supabase, 배포는 Vercel을 썼습니다.

코드 생성은 주로 터미널에서 Claude Code로 진행했고, 파일 구조를 빠르게 훑거나 UI 수정이 필요할 때 Cursor를 같이 열었습니다. ChatGPT는 에러 메시지를 그대로 붙여 넣고 원인 후보를 좁히는 용도로만 썼습니다. 핵심은 도구를 많이 쓰는 게 아니라, 각 도구에 시킬 일을 분리하는 것이었습니다.

진짜 막혔던 5가지

1. “대충 이런 앱”이라고 말하면 대충 망가집니다

처음에는 “할 일 공유 웹앱 만들어줘”라고 시켰습니다. 결과는 그럴듯했지만 폴더 구조, 라우팅, 인증 흐름이 제각각이었습니다. 이후에는 README에 목표를 먼저 적었습니다. 예를 들면 이렇게요.

목표: 로그인한 사용자가 todo를 만들고, 공개 링크로 읽기 전용 목록을 공유한다.
범위: 모바일 우선, CRUD 중 update는 나중에, 첫 배포는 Vercel.
금지: 결제, 팀 기능, 이메일 초대는 이번 버전 제외.

이렇게 범위를 닫아두니 AI가 갑자기 관리자 페이지나 팀 권한 모델을 만들 가능성이 줄었습니다.

2. 인증과 DB 스키마를 동시에 맡기면 디버깅이 어려워집니다

Supabase Auth와 todos 테이블을 한 번에 붙였더니 RLS 정책에서 막혔습니다. 화면은 정상인데 저장이 안 되고, 콘솔에는 new row violates row-level security policy 비슷한 메시지가 떴습니다.

해결은 단순했습니다. 먼저 인증 없이 todos 테이블 CRUD를 확인하고, 그다음 사용자 ID를 붙였습니다. 마지막에 RLS를 켰습니다. AI에게도 “인증 붙여줘”가 아니라 “현재 insert가 되는 상태에서 user_id 컬럼 기준 RLS 정책만 추가해줘”라고 좁혀 요청했습니다.

3. 환경변수 이름 하나가 배포 시간을 잡아먹습니다

로컬에서는 되는데 Vercel 배포에서 죽는 경우가 있었습니다. 원인은 NEXT_PUBLIC_SUPABASE_URL을 로컬에는 넣고, Vercel 프로젝트 설정에는 빠뜨린 것이었습니다. AI가 코드를 잘 만들어도 운영 환경 변수는 사람이 확인해야 합니다.

이때부터 저는 .env.example을 먼저 만들고, Claude Code에게 “코드에서 참조하는 env 목록과 .env.example이 일치하는지 검사해줘”라고 시켰습니다. 작은 습관인데 배포 실패를 꽤 줄여줍니다.

4. UI 수정은 한 번에 많이 시키면 되돌리기 힘듭니다

“모바일 예쁘게 바꿔줘”라고 하면 컴포넌트 구조까지 크게 흔들리는 일이 있었습니다. 특히 Tailwind CSS 클래스가 길어지면 내가 의도한 디자인인지 확인하기 어렵습니다.

이후에는 버튼, 카드, 목록처럼 하나씩 고쳤습니다. Cursor에서 화면을 보며 “TodoItem 컴포넌트의 빈 상태만 수정”처럼 범위를 닫으니 결과가 훨씬 안정적이었습니다.

5. 에러를 붙여넣기 전에 재현 절차를 적어야 합니다

AI에게 에러 로그만 던지면 그럴듯한 추측이 여러 개 나옵니다. 제가 효과를 본 방식은 세 줄 포맷입니다.

재현: 로그인 후 /dashboard에서 새 todo 저장 클릭
기대: todos 테이블에 row 생성
실제: 401, 콘솔 메시지: Missing Supabase session

이렇게 주면 Claude Code가 수정할 파일을 좁히고, 세션 전달 문제인지 서버/클라이언트 경계 문제인지 더 빨리 잡았습니다.

첫 웹앱 도구 선택, 저는 이렇게 나눴습니다

도구	잘 맞는 순간	주의할 점
Claude Code	터미널에서 파일 여러 개를 읽고 수정하며 흐름을 잡을 때	작업 범위를 안 정하면 너무 많이 고칠 수 있음
Cursor	UI 컴포넌트 수정, 코드 위치 탐색, 작은 리팩터링	전체 설계를 맡기기보다 특정 파일 단위가 편함
ChatGPT	에러 메시지 해석, 대안 비교, 체크리스트 만들기	프로젝트 실제 파일을 모르면 답이 일반론으로 흐를 수 있음
Vercel	Next.js 첫 배포와 미리보기 URL 확인	환경변수와 빌드 로그 확인은 직접 해야 함

이런 분께는 이 방식이 잘 맞습니다

아직 추천하지 않는 경우

바로 결제, 개인정보 처리, 팀 권한, 관리자 대시보드까지 넣어야 한다면 첫 프로젝트로는 범위가 큽니다. 이런 기능은 나중에 붙이는 것이 아니라 설계 초반부터 보안과 데이터 모델을 잡아야 해서, 처음에는 읽기 전용 공유 페이지 정도로 줄이는 편이 안전합니다.

자주 막히는 질문

Q. 프론트엔드를 몰라도 AI로 웹앱을 만들 수 있나요?

가능은 합니다. 다만 HTML, 라우팅, API 호출, 환경변수 정도의 개념은 알아야 막혔을 때 AI 답을 검증할 수 있습니다. “모른 채로 맡기기”보다 “모르는 부분을 하나씩 확인하기”가 현실적입니다.

Q. 처음부터 Supabase나 Firebase를 붙여도 될까요?

붙여도 됩니다. 대신 인증, DB, 권한 정책을 한꺼번에 시키지 마세요. 먼저 로컬 상태 저장으로 화면을 만들고, 그다음 DB 저장, 마지막에 로그인과 권한을 붙이는 순서를 권합니다.

Q. AI가 만든 코드가 맞는지 어떻게 확인하나요?

최소한 pnpm lint, pnpm build, 실제 브라우저 클릭 테스트는 돌려야 합니다. 테스트 코드까지 어렵다면 “이 기능을 수동으로 확인하는 체크리스트를 만들어줘”라고 요청해도 꽤 도움이 됩니다.

지금 바로 할 일

만들 앱을 한 문장으로 적고, 이번 버전에서 뺄 기능 3개를 정합니다.
.env.example과 README를 먼저 만들고 AI에게 기준 문서로 읽힙니다.
인증 없이 화면과 DB 저장을 먼저 확인한 뒤 로그인 기능을 붙입니다.
배포 후에는 Vercel 빌드 로그와 환경변수 이름을 직접 대조합니다.

첫 웹앱은 완성도보다 “한 바퀴 돌아본 경험”이 더 큽니다. 작게 배포해보고, 에러를 기록하고, 다음 기능을 하나만 붙여보세요.

오늘도, 코딩할 용기.

AI로 첫 웹앱 만들 때 진짜 막히는 지점 5가지, 코드보다 먼저 무너진 건 ‘맥락’이었다

제가 실제로 쓴 셋업: Next.js + Supabase + Vercel + Claude Code