Claude Code로 Astro 사이트 만들기: 폴더에서 게시까지

코드를 한 줄도 써 본 적 없는 사람도 Claude Code를 통해 Astro로 사이트를 만들 수 있습니다. 저는 오래전에 직접 코드를 쓰는 일을 그만뒀습니다. AI에게 말로 설명해 모든 일을 하고 있는데, Astro로 사이트를 만드는 방법도 똑같습니다. 필요한 것을 설명하면 Claude가 코드를 작성해 줍니다.

문제는 보통 사이트를 만드는 일 자체가 아니라, 과정이 여러 조각으로 나뉘어 있다는 점입니다. 어떤 글은 설치를 설명하고, 다른 글은 명령어를 다루고, 또 다른 글은 게시를 설명합니다. 그러다 보면 전체 과정이 머릿속에서 연결되지 않습니다. 이 글에서는 빈 폴더에서 인터넷 링크로 접속할 수 있는 사이트까지 안내합니다. 무엇을 설치해야 하는지, 프로젝트를 시작하려면 어떤 명령어를 사용해야 하는지, Claude Code로 페이지를 만드는 방법과 결과물을 무료로 게시하는 방법을 설명합니다. Astro 공식 문서를 참고합니다.

서비스 사용 방법은 Ailoot 문서에서 확인하세요.

시작하기 전에 무엇이 필요한가요?#

Astro는 미리 무엇인가를 다운로드하라고 요구하지 않습니다. 다음 단계의 명령어를 실행하면 필요한 것이 설치됩니다. 다만 이 모든 것이 실행될 환경은 있어야 합니다. Astro는 시작에 필요한 세 가지를 다음과 같이 설명합니다.

각 항목이 실제로 무엇을 뜻하는지 살펴보겠습니다.

1. Node.js — Astro뿐 아니라 대부분의 바이브 코딩 도구를 실행하는 데 필요한 프로그램입니다. nodejs.org에서 다운로드해 일반 앱처럼 설치하세요. 문서에 적힌 버전 번호는 시간이 지나면서 바뀌므로, 시작하기 전에 Astro 설치 페이지를 방문해 요구 사항을 확인하세요. 짝수 버전(22, 24)이 필요하며 홀수 버전(23, 25)은 피하는 편이 좋습니다.
2. VS Code — Microsoft의 무료 편집기입니다. 여기서 프로젝트 폴더를 열면 Claude Code도 사용할 수 있고, Claude Code가 코드를 작성합니다.
3. 터미널 — 명령어를 입력하는 창입니다. 따로 설치할 필요는 없습니다. VS Code 메뉴에서 열 수 있으며 아래의 모든 명령어를 여기에서 입력합니다.

Claude Code를 이미 설치해 무언가를 만들어 봤다면 필요한 항목이 모두 준비된 것이므로 이 단계를 건너뛰어도 됩니다. 그렇지 않다면 Claude Code 설치 방법을 별도로 안내하는 글을 참고하세요.

명령어 하나로 Astro 프로젝트를 만들려면 어떻게 하나요?#

이 단계에서 실제 프로젝트가 시작되며 명령어 하나면 충분합니다. 터미널을 열고 다음을 입력하세요.

npm create astro@latest

설치 마법사가 시작됩니다. 문서에서는 이에 대해 다음과 같이 설명합니다.

마법사가 단계를 안내하며 몇 가지 질문을 합니다. 프로젝트 폴더 이름, 시작할 템플릿, 종속성을 바로 설치할지 여부를 묻습니다. 모든 질문에 기본 옵션을 선택해도 됩니다. 첫 사이트라면 빈 템플릿이나 최소 템플릿이면 충분합니다. 종속성을 설치할지 묻는 질문에 “아니요”라고 답했다면 나중에 프로젝트 폴더 안에서 npm install 명령어를 실행해 직접 설치할 수 있습니다.

마법사가 완료되면 프로젝트가 생성되었다고 표시하고 다음 단계인 프로젝트 폴더로 이동하라고 안내합니다.

cd your-project-name

이것으로 프로젝트 생성이 끝납니다. 폴더 안에는 페이지를 만드는 데 사용하는 여러 파일과 폴더, 즉 작동 가능한 사이트 기본 구조가 이미 들어 있습니다. 직접 파일을 수정할 필요는 없지만 무엇이 어디에 있는지 알아두면 좋습니다. Astro에서 필수로 요구하는 폴더는 하나뿐입니다.

다시 말해 src/pages는 사이트의 페이지가 들어 있는 폴더입니다. 홈 페이지, “회사 소개”, 연락처 페이지 등이 여기에 들어갑니다. 보통 가까운 곳에 src/components(헤더나 버튼 같은 재사용 요소), src/layouts(페이지의 공통 틀), 이미지와 파일을 넣는 public 폴더가 있습니다. 구조를 외울 필요는 없습니다. 페이지는 src/pages에 있다는 점만 기억하고 Claude에게 “연락처 페이지를 추가해 줘”라고 요청할 때 이 위치를 참고하세요.

Claude Code로 사이트 자체를 만들려면 어떻게 하나요?#

기본 구조가 준비되었으니 이제 이를 바탕으로 사이트를 만들 차례입니다. Claude Code가 작업을 맡습니다. VS Code에서 프로젝트 폴더를 열고 Claude Code를 실행한 다음 필요한 것을 말로 설명하세요. Claude가 src/pages와 주변 폴더의 파일을 직접 수정하므로, 여러분은 작업을 지시하고 결과를 확인하기만 하면 됩니다.

제 경험상 작은 단계로 나누어 작업하는 것이 가장 좋습니다. “회사 웹사이트를 만들어 줘” 같은 거대한 요청 하나는 수정하기 힘든 뒤죽박죽인 결과를 낳습니다. 그러니 짧고 명확한 작업으로 나누어 하나씩 요청하세요.

1. “홈 페이지를 만들어 줘. 큰 제목과 내가 하는 일에 대한 짧은 문장 두 개, 연락처 페이지로 연결되는 버튼을 넣어 줘.”
2. “서비스 페이지를 추가하고 세 개의 섹션으로 된 목록을 넣어 줘.”
3. “전화번호와 Telegram 링크가 있는 연락처 페이지를 추가해 줘.”
4. “스타일을 바꿔 줘. 밝은 배경과 크고 읽기 쉬운 글꼴로 해 줘.”

다음 단계로 넘어가기 전에 각 결과를 확인하세요. 문제가 있을 때 더 쉽게 알아차리고 되돌릴 수 있습니다. 작은 작업이 더 안정적인 이유와 AI가 작업에 집중하도록 하는 방법은 컨텍스트 엔지니어링의 일부입니다. 작업과 프로젝트 구조가 명확할수록 결과를 예측하기 쉽습니다.

Astro는 이를 위해 AI가 사용하기 편리한 구조를 제공합니다. 페이지 콘텐츠와 스타일이 분리되어 있고 페이지는 공통 규칙에 따라 만들어집니다. 이 구조 덕분에 Claude가 혼란스러워하는 일이 줄고 한 곳을 수정하다 주변의 다른 부분을 망가뜨릴 가능성도 낮아집니다. Claude가 갑자기 파일을 인식하지 못하거나 엉뚱한 답을 한다면 Claude Code가 프로젝트 파일을 볼 수 없는 이유를 설명하는 가이드를 참고하세요.

게시하기 전에 사이트 미리 보기는 어떻게 하나요?#

사이트를 세상에 공개하기 전에 내 컴퓨터에서 먼저 확인합니다. Astro에는 사이트를 컴퓨터에서 실시간으로 보여 주는 개발 서버가 있습니다. 프로젝트 폴더 안에서 터미널을 열고 다음 명령어로 서버를 시작하세요.

npm run dev

Astro가 로컬 미리보기를 시작하고 터미널에 주소를 표시합니다. 기본 주소는 localhost:4321입니다. 주소를 복사해 브라우저에서 열면 사이트를 볼 수 있습니다. 지금은 여러분만 이 주소를 열 수 있고 외부에서는 접속할 수 없습니다. 이 단계의 사이트는 초안입니다.

미리보기가 실시간으로 업데이트되는 것이 편리합니다. Claude가 파일을 수정하면 브라우저의 페이지가 자동으로 바뀌므로 수동으로 새로고침할 필요가 없습니다. Claude에게 요청하고 브라우저에서 확인한 다음 수정 사항을 요청하고 다시 확인하면 됩니다. 이 단계에서 사이트를 다듬으세요. 결과가 마음에 들면 온라인에 게시하면 됩니다.

Astro 사이트를 온라인에 무료로 게시하려면 어떻게 하나요?#

완성된 사이트를 다른 사람들도 링크를 통해 열 수 있는 곳에 올려야 합니다. 가장 쉬운 무료 방법은 GitHub를 이용하는 것입니다. 먼저 프로젝트 코드를 저장소에 업로드한 다음 사이트를 빌드하고 게시하는 호스팅 서비스에 연결합니다. 진행 순서는 다음과 같습니다.

1. GitHub에 저장소를 만드세요. 저장소는 프로젝트 파일을 보관하는 온라인 공간입니다. Claude Code에 자연어로 요청해 도움을 받을 수 있습니다. “새 GitHub 저장소에 프로젝트를 업로드해 줘”라고 요청하면 Claude가 명령어를 제안합니다. GitHub를 처음 사용한다면 가입과 로그인 방법을 설명하는 안내를 가까이 두세요.
2. 호스팅 서비스를 연결하세요. 서비스(Netlify, Vercel) 중 하나에 접속해 GitHub 계정으로 로그인하고 저장소를 선택합니다. Astro 문서는 이 방법을 다음과 같이 설명합니다. 호스팅 서비스가 저장소를 확인하고 사이트를 빌드한 뒤 게시합니다.
3. 빌드 설정을 확인하세요. 호스팅 서비스는 보통 Astro를 인식해 필요한 항목을 자동으로 입력합니다. 수동 입력을 요청받는다면 문서에 안내된 빌드 명령어 astro build(또는 npm run build)를 사용하세요. 완성된 사이트는 dist 폴더에 저장됩니다.
4. “게시”를 클릭하세요. 서비스가 사이트를 빌드하고 site-name.netlify.app 같은 링크를 제공합니다. 누구나 그 주소에서 사이트를 열 수 있습니다.

저장소를 호스팅 서비스에 연결하는 방법에 관한 문서의 정확한 설명은 다음과 같습니다.

그다음부터는 게시가 자동으로 이루어집니다. 저장소에 새 변경 사항을 보내면 사이트가 자동으로 다시 빌드되고 업데이트되므로 따로 클릭할 필요가 없습니다.

두 번째 무료 옵션은 GitHub Pages입니다. GitHub 자체 도구를 사용해 저장소에서 사이트를 직접 게시합니다. Astro에는 이를 위한 공식 스타터가 있습니다.

이 방법을 사용하면 your-name.github.io/repository-name 같은 주소에서 사이트가 열립니다. 나중에 개인 도메인을 연결할 수도 있습니다. 여기서도 Claude Code에 말로 작업을 설명하면 필요한 파일을 준비해 줍니다.

Astro 사이트를 만드는 데 비용이 얼마나 드나요?#

이제 비용을 살펴보겠습니다. Astro는 무료 오픈 소스 도구이며 별도 요금이 없습니다. 기본 호스팅 서비스에도 무료 옵션이 있습니다. GitHub Pages와 Netlify, Vercel의 입문 요금제면 보통 가벼운 Astro 사이트에 충분합니다. (무료 요금제에는 트래픽 제한이 있지만, 가벼운 명함형 사이트나 랜딩 페이지에는 보통 충분합니다.)

실제로 비용이 발생할 수 있는 항목은 두 가지이며, 둘 다 항상 필요한 것은 아닙니다. 첫 번째는 사이트를 만드는 데 사용하는 AI 도구입니다. 두 번째는 name.netlify.app 같은 주소 대신 사용하는 개인 도메인입니다. 이는 선택 사항이며 연간 비용도 적습니다. Claude 비용만 내고 사이트를 만들어 온라인에 게시할 수도 있습니다.

Astro 사이트와 Claude Code에 관해 사람들이 또 무엇을 물어보나요?#

Ailoot을 알아보세요.