Claude Code로 웹앱을 만드는 것까지는 생각보다 빨리 됩니다. 진짜 문제는 그다음입니다. 에디터 연결, spec 정리, 로컬 실행, Git, 배포 방식 판단, MCP 재배포까지 한 흐름으로 묶지 않으면 중간에서 자주 끊깁니다. 이 글은 그 순서를 한 번에 잡아 주는 글입니다.
먼저 답부터 말하면 순서는 이렇습니다. Claude Code 설치 -> 에디터 연결 -> spec 파일 작성 -> MVP만 생성 -> 로컬 실행 확인 -> Git 커밋 -> 첫 배포 -> MCP로 재배포 자동화.
이 순서를 지키면 "앱은 만들어졌는데 배포가 안 되는 상태"와 "수정하다가 더 망가졌는데 되돌릴 수 없는 상태"를 꽤 많이 피할 수 있습니다.
도구를 많이 아는 것보다, 덜 부서지는 조합을 고르는 게 먼저입니다
처음에는 Claude Code + Cursor(또는 VS Code 계열 에디터) + Next.js + Git + 배포 플랫폼 정도면 충분합니다. 이 조합이 좋은 이유는 단순합니다. 생성된 파일을 바로 확인할 수 있고, 첫 버전을 빨리 띄울 수 있고, 망가졌을 때 돌아갈 장치까지 붙이기 쉽기 때문입니다.
Claude Code 쪽은 제품 화면보다 "프로젝트 폴더 안에서 어떻게 시작하고 이어 가느냐"를 먼저 이해하는 편이 낫습니다. 공식 시작 가이드도 claude 명령으로 프로젝트 안에서 시작하는 흐름을 중심으로 설명합니다. 설치와 로그인 방식은 바뀔 수 있으니 시작 전에 Anthropic의 Claude Code 시작 가이드를 확인해 두면 덜 헷갈립니다.
에디터는 Cursor처럼 파일 트리를 보면서 작업할 수 있으면 충분합니다. 여기서 중요한 건 AI 편의 기능이 아니라 검증 가능성입니다. 어떤 파일이 생겼고, 어떤 설정이 바뀌었고, 빌드가 어디서 깨졌는지 눈으로 볼 수 있어야 뒤에서 덜 흔들립니다. Cursor가 아직 손에 안 익었다면 Cursor 완전 가이드 2025를 먼저 보고 오는 편이 훨씬 빠릅니다.
코드를 쓰기 전에 spec 파일부터 만드는 이유
Claude Code로 계속 꼬이는 경우를 보면, 대개 프롬프트가 짧아서가 아니라 기준 문서가 없습니다. 처음부터 코드 생성으로 들어가면 디자인, 기능, 데이터, 문구, 배포 방식이 한 요청 안에서 뒤엉키기 시작합니다.
그래서 시작 프롬프트는 이렇게 잡는 편이 낫습니다.
내가 만들고 싶은 사이트 아이디어를 말할 테니,
먼저 필요한 질문을 해줘.
답변이 모이면 사이트 요구사항을 spec.md로 정리해줘.
그 다음 그 파일 기준으로만 작업하자.
이 한 단계가 중요한 이유는 두 가지입니다.
- 지금 무엇을 만들기로 했는지 프로젝트 안에 남습니다.
- 다음 세션에서도 Claude Code가 같은 기준으로 이어서 작업할 수 있습니다.
랜딩 페이지나 포트폴리오처럼 단순해 보이는 작업일수록 이 과정이 더 중요합니다. 이런 작업은 기능보다 구조와 톤이 더 중요해서, 기준 없이 시작하면 수정이 끝없이 늘어납니다.
첫 구현은 크게 말고, 돌아가는 MVP 하나만 만드세요
AI 코딩에서 자주 실패하는 지점은 첫 요청이 너무 크다는 겁니다. 로그인, 관리자 페이지, 결제, 데이터 저장, 애니메이션까지 한 번에 넣으면 결과가 금방 흐려집니다.
이럴 때는 범위를 억지로 줄이는 문장이 필요합니다.
spec.md를 기준으로 MVP만 먼저 만들어줘.
너무 복잡하게 하지 말고,
로컬에서 실행해서 내가 바로 확인할 수 있게 해줘.
이 요청이 잘 먹히는 이유는 명확합니다. Claude Code는 큰 작업 한 번보다 작은 명확한 작업을 더 안정적으로 처리합니다. 처음 필요한 건 완성본이 아니라 브라우저에서 확인 가능한 첫 버전입니다. 그 상태를 본 뒤에 섹션을 늘리고 문구를 다듬고 기능을 추가하는 편이 결과가 훨씬 낫습니다.
이 단계에서 에디터 안에 Claude Code를 붙여 쓰는 이유도 분명합니다. 예쁜 UI 때문이 아니라, 생성된 컴포넌트와 설정 파일을 바로 볼 수 있기 때문입니다. 실제로 배포에서 막히면 package.json, next.config.*, 환경 변수, 빌드 산출물을 다시 보게 됩니다. 파일 구조가 안 보이면 그 순간부터 작업이 아니라 추측이 됩니다.
Next.js는 좋은 기본값이지만, 배포 방식은 따로 판단해야 합니다
단순한 웹사이트라면 Next.js는 여전히 무난한 기본값입니다. 문제는 여기서 멈추면 안 된다는 겁니다. 진짜 판단은 "Next.js를 쓸까?"가 아니라 "이 프로젝트가 정적 업로드로 끝나는가, 아니면 서버 런타임이 필요한가?"입니다.
이 구분을 놓치면 로컬에서는 잘 되는데 배포 후 깨지는 일이 바로 생깁니다. 공식 문서 기준으로 Next.js는 Node.js server, Docker container, static export, 플랫폼별 adapter 방식 등 여러 경로로 배포할 수 있습니다. 자세한 기준은 Next.js 공식 배포 문서에서 확인할 수 있습니다.
| 프로젝트 상태 | 먼저 볼 것 | 보통 맞는 방향 |
|---|---|---|
| 소개 페이지, 포트폴리오, 거의 정적인 랜딩 페이지 | 서버 코드가 정말 없는지 | Static export 우선 검토 |
| 인증, API route, 서버 액션, 동적 데이터가 있음 | 요청마다 서버 처리가 필요한지 | Node.js server 또는 container |
| 지금은 단순하지만 기능을 곧 붙일 예정 | 나중에 서버 기능이 늘어날 가능성 | 처음부터 Node 계열 배포 고려 |
판단 기준은 어렵지 않습니다. 빌드 결과물만 올리면 끝나는가, 아니면 배포 환경에서 서버가 계속 살아 있어야 하는가를 먼저 보면 됩니다. 영상처럼 압축 업로드 흐름만 따라가면 이 차이를 놓치기 쉽습니다.
압축 업로드 전에 이 질문 하나만 먼저 보세요. "이 사이트는 요청마다 서버에서 뭔가 처리해야 하나?" 이 답이 예라면 정적 업로드만으로 끝난다고 가정하면 안 됩니다.
Git은 나중에 배우는 게 아니라, 배포 전에 걸어 두는 안전장치입니다
Git을 길게 이해할 필요는 없습니다. 지금 필요한 건 checkpoint 개념 하나면 됩니다. 배포 전에 첫 커밋을 만들어 두면 이후 수정에서 망가져도 돌아갈 지점이 생깁니다.
이건 특히 AI 코딩에서 더 중요합니다. 사람이 수동으로 한두 줄 바꾸는 정도가 아니라, 도구가 여러 파일을 한 번에 건드리기 때문입니다. "방금 전 상태가 더 나았는데"가 나오는 순간 Git이 없으면 수정이 아니라 복구가 됩니다.
처음 프롬프트는 이 정도면 충분합니다.
지금 상태를 기준으로 Git 저장소를 초기화하고
첫 커밋까지 만들어줘.
앞으로 의미 있는 변경이 생길 때마다 커밋도 같이 해줘.
여기서 중요한 건 GitHub 공개 여부가 아닙니다. 로컬에서라도 되돌릴 수 있는 상태를 만드는 겁니다.
배포에서 많이 막히는 건 업로드보다 도구 연결입니다
실제로는 업로드 버튼보다 연결 방식에서 더 자주 막힙니다. 영상의 사례도 비슷합니다. 먼저 대시보드에서 한 번 배포를 성립시키고, 그다음 API 토큰과 connector를 붙여서 Claude Code 안에서 재배포 흐름을 만드는 식입니다.
이 접근은 꽤 현실적입니다. 첫 배포는 사람이 직접 확인하면서 연결을 만들고, 그 다음부터 자연어로 반복 작업을 줄이는 편이 안전하기 때문입니다.
여기서 흔한 마찰은 이런 식입니다.
- Cursor에서는 connector나 MCP가 보이는데 Claude Code 세션에서는 바로 안 잡힐 수 있습니다.
- 설정은 들어갔는데 현재 세션이 그 도구를 다시 인식하려면 재시작이나 별도 설정 추가가 필요할 수 있습니다.
이 개념이 아직 흐릿하다면 MCP 서버가 뭐길래?를 먼저 짧게 보고 오는 편이 좋습니다. 왜 배포 플랫폼이 Claude 안에서 "도구"처럼 보이는지 이해하면 설정 화면이 훨씬 덜 낯섭니다.
Hostinger처럼 MCP 연결을 제공하는 플랫폼은 공식 문서에서 필요한 토큰과 설정 예시를 안내합니다. 실제 연결 흐름은 Hostinger API MCP Server 문서로 확인할 수 있습니다.
중요한 건 특정 플랫폼 이름보다 순서입니다. 첫 배포 성공 -> 토큰 발급 -> MCP 연결 -> Claude Code 세션 재확인 -> 재배포 이 흐름으로 이해하면 덜 꼬입니다.
처음 설정은 공격적으로 만지지 않는 편이 낫습니다
처음부터 모델, effort, 모드, 확장 기능을 계속 갈아끼우면 오히려 기준이 사라집니다. 처음 하는 경우에는 예측 가능한 속도와 비용을 먼저 확보하는 편이 낫습니다.
정리하면 이 정도가 무난합니다.
- 처음엔 기본 모델과 중간 정도 effort로 시작합니다.
- 첫 구현은 크게 시키지 말고 기능 단위로 나눕니다.
- 명령 실행이 막히면 "무엇이 설치되지 않았는지"부터 묻습니다.
- 승인 창이 뜨면 무조건 누르지 말고 설치인지 파일 수정인지 정도는 구분합니다.
- 모드 차이가 헷갈리면 먼저 묻고 정리하는 흐름부터 익힙니다.
관련해서 모드 차이가 아직 헷갈리면 Claude Code Plan mode vs Ask mode vs Code mode 차이를 같이 보면 흐름이 더 빨리 잡힙니다.
마지막으로, 이 순서만 기억하면 됩니다
아래 체크리스트만 기억해도 처음부터 훨씬 덜 막힙니다.
- Claude Code를 프로젝트 폴더에서 시작합니다.
- 에디터에서 파일 구조를 같이 보며 작업합니다.
- 코드보다 먼저
spec.md를 만듭니다. - 첫 구현은 MVP만 만들고 로컬에서 확인합니다.
- 배포 전에 Git 첫 커밋을 만듭니다.
- 이 사이트가 정적 업로드인지 서버 런타임인지 먼저 구분합니다.
- 첫 배포를 확인한 뒤 MCP나 connector로 재배포를 붙입니다.
결국 중요한 건 AI가 대신 코드를 써 주느냐가 아닙니다. 사람이 어떤 순서로 질문하고, 어디에서 한 번 멈춰 확인하고, 언제 되돌릴 수 있게 만들지를 먼저 정하는가입니다. 이 감각만 잡히면 Claude Code로 만드는 웹앱은 훨씬 덜 불안해집니다.
FAQ
Claude Code는 꼭 터미널에서만 써야 하나요?
아닙니다. 에디터 통합으로 써도 됩니다. 다만 프로젝트 루트에서 시작하고 생성된 파일을 바로 확인할 수 있는 환경이 훨씬 유리합니다.
Next.js면 그냥 압축해서 올리면 끝 아닌가요?
정적인 사이트라면 그럴 수 있습니다. 하지만 서버 액션, 인증, API route, 동적 데이터가 붙으면 배포 조건이 달라질 수 있으니 먼저 런타임부터 구분해야 합니다.
'SW > 인공지능' 카테고리의 다른 글
| Pi vs Claude Code: 기능이 적은 하니스가 더 강하게 느껴지는 이유 (0) | 2026.06.12 |
|---|---|
| Claude Mythos 비용 폭탄 피하는 법: 강한 AI 모델을 정확히 쓰는 6가지 기준 (0) | 2026.06.11 |
| 2026년 AI 엔지니어링 강의 추천 5선: 초보자, 개발자, 데이터 사이언티스트별로 고르는 법 (0) | 2026.06.05 |
| AI가 코드를 쓰는 시대, 개발자는 지금 무엇을 준비해야 할까 (0) | 2026.06.04 |
| Claude Code로 이미지 생성 자동화하는 법: JSON 프롬프트, Gemini API, 참조 이미지 편집까지 (0) | 2026.06.03 |