AI 에이전트로 정적 홈페이지 완성하기 — 단계별 명령문 가이드

AI 에이전트로 정적 홈페이지 완성하기 — 단계별 명령문 가이드

  • 대상: Claude Code, Google Antigravity 등 “명령(프롬프트)만으로 일하는” AI 코딩 에이전트
  • 목표: 폴더 지정 → plan.md(Gemini Gems) → Hugo 사이트 제작 → GitHub 연동 → Cloudflare 빌드 → 도메인 연결까지, 명령문 순서대로 따라 하면 완성
  • 스택: Hugo(Extended) + GitHub + Cloudflare Pages

1. 큰 그림: 에이전트가 “할 수 있는 것”과 “못 하는 것”

명령만으로 자동화가 되는 부분과, 사람이 웹 화면에서 클릭해야 하는 부분을 먼저 구분하는 것이 핵심입니다. 여기서 헷갈리면 “왜 명령했는데 안 되지?”가 됩니다.

구간 에이전트가 터미널 명령으로 처리 사람이 직접 해야 함
폴더/파일 만들기 ✅ 전부 —
Hugo 사이트·테마·글·설정 ✅ 전부 —
Git 커밋·푸시 ✅ 명령 실행 GitHub 최초 로그인 인증(브라우저 1회)
GitHub 저장소 생성 ✅ gh CLI 있으면 가능 없으면 웹에서 저장소 생성
Cloudflare 빌드/배포 ⚠️ Wrangler CLI면 가능 대시보드 방식이면 웹에서 연결·설정
도메인 네임서버 변경 ❌ 도메인 등록업체(가비아 등)에서 직접

정리: 에이전트는 “내 컴퓨터 안의 코드 작업”은 100% 명령으로 처리합니다. 다만 **외부 서비스 계정 인증(GitHub 로그인, Cloudflare 연결, 도메인 네임서버)**은 보안상 사람이 한 번은 승인해야 합니다. 이 문서는 그 지점을 매 단계 표시해 둡니다.

2. 사전 준비 (한 번만)

에이전트에게 시키기 전에 갖춰야 할 것들. 에이전트에게 아래처럼 물어봐도 됩니다.

명령문

의미: 이후 모든 단계의 도구가 준비됐는지 점검합니다. hugo version 결과에 반드시 extended가 있어야 테마의 SCSS를 빌드할 수 있습니다. gh(GitHub CLI)와 node(Wrangler용)는 뒤 단계 자동화를 위해 미리 확인합니다.

단계별 명령 시퀀스

각 단계는 [명령문](에이전트에게 그대로 붙여넣는 문장)과 [의미](그 명령이 하는 일)로 구성됩니다.

1단계 — 작업 폴더 지정하고 그 안에서 시작하기

명령문

의미

  • 에이전트는 기본적으로 “현재 열린 폴더”에서 작업합니다. 이 폴더를 명시적으로 먼저 지정하지 않으면, 엉뚱한 위치에 파일이 흩어지거나 기존 파일과 섞입니다.
  • 경로에 한글·공백이 있으면 Hugo·Git 빌드에서 오류가 자주 납니다(예: C:\Users\지우\바탕 화면). 그래서 영문 전용 폴더를 따로 만드는 것입니다.
  • “지금 위치를 먼저 보여줘”는 에이전트가 잘못된 폴더에서 일하기 시작하는 사고를 막는 안전장치입니다.

💡 Antigravity·Claude Code 모두 “워크스페이스(작업 폴더)” 개념이 있습니다. 이 폴더를 워크스페이스로 열어두고 시작하면 이후 명령이 전부 이 폴더 기준으로 동작합니다.

2단계 — Gemini Gems 인터뷰로 plan.md 만들기

이 단계는 에이전트가 아니라 Gemini(Gems)에서 진행한 뒤, 결과물만 가져오는 하이브리드 단계입니다.

① Gemini Gems 쪽에서 (사람이 진행)
Gemini의 Gems에 아래 같은 “인터뷰어 Gem”을 만들어 두고 대화합니다.

인터뷰가 끝나면 Gemini가 출력한 마크다운 결과를 복사합니다.

② 에이전트 쪽에서 (복사한 내용을 붙여넣어 저장)

명령문

의미

  • 왜 Gems로 기획하나? 홈페이지 제작에서 가장 자주 실패하는 지점은 코드가 아니라 “무엇을 만들지 안 정해진 것”입니다. Gems 인터뷰는 질문을 통해 목적·메뉴·콘텐츠를 강제로 구체화시켜 줍니다.
  • 왜 plan.md로 저장하나? 이후 3~5단계에서 에이전트에게 “plan.md를 근거로 만들어줘”라고 지시하면, 에이전트가 이 파일을 설계도로 읽고 메뉴·페이지·톤을 일관되게 구성합니다. 기획서가 파일로 존재해야 매 명령마다 다시 설명할 필요가 없습니다.

💡 Gems 없이도 됩니다. 그냥 종이에 적은 기획을 붙여넣어도 되고, 에이전트에게 “나를 인터뷰해서 plan.md를 만들어줘”라고 해도 됩니다. 다만 Gemini Gems는 이 “인터뷰” 역할에 특화돼 있어 초안 품질이 좋습니다.

3단계 — plan.md 기반으로 Hugo 사이트 구성

명령문

의미

  • git submodule 방식을 지정하는 이유: Cloudflare가 빌드할 때 테마를 자동으로 함께 내려받아야 합니다. ZIP으로 넣으면 테마 안의 .git이 꼬여 배포에서 실패하기 쉽습니다.
  • plan.md를 근거로: 에이전트가 임의로 만드는 게 아니라 기획서의 메뉴·페이지를 그대로 반영하게 합니다.
  • ko-kr 언어 설정: 한국어 사이트의 날짜·정렬 처리가 자연스러워집니다.

⚠️ [테마 이름]은 원하는 테마로 바꾸세요. 초보자는 PaperMod(블로그형) 또는 Blowfish(개인 홈페이지형)를 추천합니다. 테마를 바꾸면 필요한 params도 달라지므로, 에이전트에게 “이 테마 Wiki의 예제 설정을 참고해서 hugo.toml을 채워줘”라고 덧붙이면 좋습니다.

4단계 — 제작 매뉴얼·문제보고서 문서화 + README 연결

명령문

의미

  • 제작 매뉴얼: 이 사이트를 어떻게 만들었는지, 글을 어떻게 추가하는지 기록 → 나중에 나(또는 다른 사람)가 이어서 운영할 때 설명서가 됩니다.
  • 문제보고서: 빌드 실패·오류와 해결법을 쌓아두는 로그 → 같은 문제를 반복해서 겪지 않게 합니다.
  • README 연결: GitHub 저장소 첫 화면(README)에서 두 문서로 바로 이동하게 해, 프로젝트의 “입구” 역할을 하게 합니다.

💡 “작업이 진행될 때마다 자동 업데이트”는 에이전트가 세션 내에서 기억하는 지시입니다. 확실히 하려면 매 작업 끝에 “방금 변경사항을 docs 매뉴얼/문제보고서에 반영해줘”라고 한 번씩 상기시켜 주세요.

5단계 — 로컬 서버로 미리보기

명령문

의미

  • hugo server -D를 실행해 http://localhost:1313에서 내 컴퓨터에서만 미리보기를 띄웁니다. 아직 인터넷 공개가 아닙니다.
  • 배포 전에 로컬에서 먼저 확인하는 습관이 중요합니다. 로컬에서 실패하면 Cloudflare에서도 반드시 실패합니다.
  • 메뉴, 홈 화면, 다크모드 등이 plan.md 기획대로 나왔는지 눈으로 확인하는 단계입니다.

6단계 — GitHub 저장소 준비 + 업로드 환경 구성

명령문 (gh CLI가 있을 때 — 가장 자동화)

명령문 (저장소를 웹에서 이미 만든 경우)

의미

  • .gitignore: 빌드 결과물(public/)과 캐시(resources/)를 GitHub에서 제외합니다. 이건 Cloudflare가 알아서 만들 것이므로 저장소에 올리면 안 됩니다.
  • origin 원격 연결: 내 컴퓨터의 코드를 GitHub의 어느 저장소로 보낼지 주소를 등록하는 것입니다.
  • gh CLI 활용: 있으면 저장소 생성까지 명령으로 끝납니다. 없으면 GitHub 웹에서 “빈 저장소”(README·라이선스 체크 안 함)를 먼저 만든 뒤 주소만 넘기면 됩니다.

7단계 — 첫 push

명령문

의미

  • git add . → commit → push 3단계를 실행해 소스를 GitHub(창고)에 올립니다.
  • 최초 push 시 GitHub 로그인 창(브라우저)이 한 번 뜹니다. 이건 에이전트가 대신 못 하는, 사람이 승인하는 인증입니다. 한 번 로그인하면 이후엔 자동입니다.
  • 이 시점부터 GitHub에 코드가 존재하므로, 다음 단계에서 Cloudflare가 이 저장소를 바라보게 만들 수 있습니다.

8단계 — Cloudflare로 빌드·배포

여기서부터 두 갈래입니다. 초보자는 방식 A(대시보드)를 권장하고, 완전 자동화를 원하면 방식 B(Wrangler CLI)를 씁니다.

방식 A — Cloudflare 대시보드 연동 (권장, 초보자용)

에이전트는 “준비와 안내”를 하고, 실제 연결 클릭은 사람이 웹에서 합니다.

명령문 (에이전트에게)

그다음 사람이 Cloudflare 대시보드에서 진행:

  1. dash.cloudflare.com → Workers & Pages → Create → Pages → Connect to Git
  2. GitHub 로그인·권한 승인 → jiwu-website 저장소 선택
  3. 빌드 설정 입력:
항목 값
Framework preset Hugo
Build command hugo
Build output directory public
환경변수 HUGO_VERSION 로컬 hugo 버전 (예: 0.148.0)
  1. Save and Deploy → 1~2분 후 jiwu-website.pages.dev 주소 발급

의미

  • HUGO_VERSION 환경변수가 핵심입니다. 이걸 안 넣으면 Cloudflare가 오래된 기본 Hugo로 빌드해서, “로컬은 되는데 배포만 실패”하는 가장 흔한 사고가 납니다.
  • 대시보드 연동은 한 번만 해두면, 이후 git push할 때마다 Cloudflare가 자동 감지 → 빌드 → 전 세계 배포합니다.
  • 왜 사람이 클릭하나? GitHub↔Cloudflare 계정 연결(OAuth 권한 승인)은 보안상 본인이 직접 승인해야 하는 부분이라 에이전트가 대신할 수 없습니다.

배포 후 마무리 명령문

의미: baseURL이 실제 주소와 다르면 배포된 사이트의 CSS·디자인이 깨집니다. 반드시 발급 주소로 맞춰 다시 push하면 자동 재배포됩니다.

방식 B — Wrangler CLI로 명령만으로 배포 (완전 자동화)

터미널에서 배포까지 끝내는 방식입니다. “명령만으로”에 가장 가깝지만, 최초 1회 인증 설정이 필요합니다.

명령문

에이전트가 구성해줄 핵심 명령의 형태:

의미

  • wrangler login: Cloudflare 계정에 이 컴퓨터를 인증합니다. 브라우저가 한 번 열리고, 이후엔 토큰으로 자동 처리됩니다(사람 승인 1회).
  • wrangler pages deploy public: 로컬에서 빌드한 public 폴더를 Cloudflare로 직접 업로드·배포합니다. GitHub를 거치지 않아도 됩니다.
  • 장점: 터미널에서 push 없이 즉시 배포. 단점: GitHub push마다 자동 배포되는 것은 아니어서, 배포 때마다 이 명령을 실행하거나 GitHub Actions로 자동화를 추가해야 합니다.
  • Cloudflare는 최근 신규 프로젝트에 Workers 사용을 권장하는 안내를 띄웁니다. Pages 방식도 계속 동작하지만, 화면 문구가 다를 수 있으니 에이전트에게 “지금 wrangler 버전에 맞는 최신 명령으로 알려줘”라고 덧붙이면 좋습니다.

어느 방식을 쓸까? 처음이라면 방식 A(대시보드). “글 쓰고 push만 하면 자동 배포”라는 가장 편한 운영 흐름이 만들어집니다. 방식 B는 GitHub 없이 빠르게 올리거나, CI 자동화에 익숙해진 뒤 추천합니다.

9단계 — 내 도메인(jiwumission.org) 연결

명령문 (에이전트에게 — 안내·검증용)

그다음 사람이 진행하는 실제 연결:

  1. Cloudflare 대시보드 → Add a domain → jiwumission.org 입력 → Free 플랜
  2. Cloudflare가 알려주는 네임서버 2개를 복사
  3. 도메인 구입처(가비아·후이즈 등) 관리페이지에서 네임서버를 Cloudflare 것으로 변경 (전파에 몇 분~최대 24시간)
  4. Workers & Pages → 프로젝트 → Custom domains → Set up a custom domain → jiwumission.org 추가 (www.jiwumission.org도 원하면 추가)
  5. 상태가 Active가 되면 HTTPS 인증서 자동 발급

마지막 baseURL 반영 명령문

의미

  • 네임서버 변경은 “이 도메인의 주소록을 누가 관리하는가”를 Cloudflare로 넘기는 것입니다. 이건 도메인 등록업체 사이트에서 본인이 직접 해야 하며, 에이전트가 대신할 수 없습니다.
  • 커스텀 도메인 추가: Cloudflare가 pages.dev 대신 내 도메인으로 사이트를 서비스하도록 CNAME을 자동 연결합니다.
  • HTTPS 자동: 별도 인증서 구매·설정 없이 Cloudflare가 무료로 발급·갱신합니다.
  • 연결 후 “너무 많은 리디렉션” 오류가 나면 SSL/TLS 설정을 Full 모드로 바꾸세요.

완성 후 — 운영 루틴 (외우면 끝)

이제부터 새 글이나 수정은 이 한 문장이면 됩니다.

명령문

의미: git push 순간 GitHub → Cloudflare가 자동 빌드·배포(방식 A 기준)하고, 문서까지 최신 상태로 유지됩니다. 서버비 0원, 트래픽 무제한.

부록 A — Claude Code vs Google Antigravity

두 에이전트 모두 이 시퀀스를 실행할 수 있습니다. 차이만 알아두면 됩니다.

항목 Claude Code Google Antigravity
형태 터미널 중심 CLI 에이전트 IDE + CLI + SDK 통합, 여러 에이전트 병렬 실행
강점 명령형 작업, 파일·git 자동화가 매끄러움 브라우저 하위 에이전트가 실제 Chrome를 띄워 사이트를 눌러보며 검증, 작업 결과물(스크린샷·계획)로 확인
폴더 지정 작업 디렉터리를 열고 시작 워크스페이스 단위로 폴더 배정
이 가이드 적용 명령문 그대로 사용 동일하게 사용, “브라우저로 localhost 열어 확인해줘” 같은 검증 명령을 추가로 활용 가능
모델 Claude Gemini 3 Pro 및 Claude·OpenAI 모델 선택

Antigravity는 **”만든 결과를 브라우저로 직접 확인”**하는 기능이 강하므로, 5단계(미리보기)나 배포 후 확인에서 “브라우저로 열어 화면을 캡처해서 보여줘”를 덧붙이면 유용합니다.

부록 B — 전체 명령문 치트시트

핵심 요약: 폴더를 먼저 못 박고 → Gemini Gems로 기획(plan.md)을 확정한 뒤 → 에이전트가 제작·문서화·GitHub까지 명령으로 처리하고 → Cloudflare 연결·도메인만 사람이 1회 승인하면, 그다음부터는 **”push 한 줄 = 전 세계 자동 배포”**가 완성됩니다.