Claude Code에서 랜딩 페이지 구축하기
Claude Code로 마케팅 페이지를 구축, 출시 및 개선하기 위한 실용적인 설정입니다. 다섯 가지가 대부분의 작업을 수행합니다: 저장소, 호스트, 브랜드 키트, 성능 및 퍼널 데이터. 이것들을 올바르게 설정하면 나머지는 반복 작업일 뿐입니다.
출시 전 페이지를 확인하는 두 가지 방법(섹션 4): 당신과 Claude를 위한 로컬 개발 서버와 비개발자를 위한 Claude Design이 있습니다. Design을 사용하는 경우, 먼저 섹션 4의 엄격한 규칙을 읽으십시오. 거기에는 실행 취소가 없습니다.
핵심 원칙: 작업은 배포에서 끝나지 않습니다. 추적되지 않는 라이브 페이지는 개선할 수 없는 페이지입니다.
작업 순서
다음 순서대로 진행하십시오. 각 단계는 다음 단계를 더 쉽게 만듭니다.
- 저장소 우선 — 코드보다 먼저. 버전 관리는 다른 모든 것을 위한 실행 취소 버튼입니다.
- 호스트 + 배포 파이프라인 두 번째 — 사이트가 간단하고 잘못된 배포가 문제되지 않을 때.
- 브랜드 키트 세 번째 — 카피를 한 줄도 작성하기 전에, 첫 번째 초안이 이미 브랜드에 부합하도록 합니다.
- 페이지 구축 — 시각적/정적 요소를 먼저, 인터랙티브는 다음, 추적은 마지막에.
- 최소한의 추적과 함께 당일 출시 — 그런 다음 실제 데이터를 기반으로 속도와 카피를 최적화합니다.
1. 저장소 사용 (GitHub 또는 동등한 서비스)
이미 Claude Code를 사용하고 있다면 당연한 것입니다. 처음 사용해보는 경우라면 이것은 준비 운동입니다: 저장소는 버전 제어, 클라우드 백업, 그리고 가장 중요한 배포 전략을 제공합니다.
main은 프로덕션 브랜치이며, 직접 병합하는 풀 리퀘스트를 통해서만 코드가 여기에 도달할 수 있습니다.
이 규칙을 CLAUDE.md에 명시적으로 작성하십시오 — starters/CLAUDE.md를 참조하십시오.
작업 루프
이것이 전체 사이클입니다. 모든 작업에 대해 실행하십시오.
- 버전 번호에 동의합니다. Claude가 하나를 제안하면 동의하거나 원하는 버전을 말하면 됩니다. 어느 쪽이든 작업이 시작되기 전에 번호가 결정되며, 결정은 당신의 몫입니다.
- Claude가 브랜치를 생성합니다 —
git checkout -b v1.03. - 브랜치에서 작업을 수행합니다. 커밋은 여기에만 기록됩니다.
- Claude가 브랜치를 GitHub에 푸시합니다.
- Claude가 풀 리퀘스트를 엽니다.
- GitHub에서 검토하고 승인한 후 병합합니다. 이것이 배포입니다. 프로덕션이 변경되는 유일한 순간이며 항상 인간의 결정을 따릅니다.
git checkout main후git pull. 절대 건너뛰지 마십시오. 로컬main이 정확히 하나의 병합만큼 뒤처지며, 오래된main에서 다음 브랜치를 시작하면 분기, 유령 충돌 및 빨리 감기를 거부하는git pull이 발생할 수 있습니다.- 반복 다음 버전 번호로 1단계부터 다시 시작합니다.
Claude가 제안하고, 당신이 결정하며, Claude가 실행합니다. 버전 번호, 병합 및 배포는 당신의 몫입니다. 브랜칭, 푸시 및 PR 생성은 Claude의 몫입니다. 모호한 호출이 있으면 Claude가 질문합니다.
작동하는 버전 명명: v1.0x는 패치(카피, 설정, 작은 수정), v1.x는 마이너 작업(새 페이지, 새 기능),
v2.x는 리디자인에 사용합니다.
유지할 가치가 있는 두 가지 검토 게이트:
- 각 커밋뿐만 아니라 전체 브랜치 차이를 병합하기 전에 검토하십시오. 개별적으로는 괜찮은 커밋이 결합되어 실제 버그가 될 수 있습니다. 브랜치 포인트 이후의 모든 것을 읽는 전체 검토는 작업별 검토가 구조적으로 놓칠 수 있는 것을 잡아냅니다.
- 사용자 데이터를 수집하는 모든 배포 전에 보안 검토를 실행하십시오. 양식 처리 브랜치에서 한 번의 검토로 원시 객체 스프레드가 방문자로 하여금 서버 관리 필드에 값을 제출하도록 허용하는 실제 취약점을 발견했습니다. 이를 게이트로 취급하십시오.
2. 실제 배포 파이프라인이 있는 호스트 사용
AWS Amplify가 잘 작동합니다: 무료 티어는 트래픽이 적은 랜딩 페이지를 커버하고, 그 이상은 소액 청구됩니다. 현재 약관을 확인하십시오 — AWS는 2025년에 무료 티어를 재구성했습니다. Netlify, Vercel 및 Cloudflare Pages도 동일한 형태를 제공합니다.
진정한 장점은 배포 경로입니다: PR을 병합하면 사이트가 재구축되고 라이브가 됩니다.
저장소를 호스트에 연결하는 것은 사람들이 종종 막히는 단계이며, 설정 파일이 아닌
클릭 경로입니다: 호스트 콘솔에서 새 웹 앱을 만들고 → GitHub 계정에 대해 승인하고 →
저장소와 main 브랜치를 선택하면 → 빌드 사양을 감지하고 → 첫 번째 배포가 실행됩니다.
그 후로는 해당 브랜치에 푸시할 때마다 재구축됩니다. 사이트가 단일 "hello" 페이지일 때 이 작업을 수행하여
파이프라인이 깨져도 디버깅 비용이 들지 않도록 하십시오.
첫날에 설정하고, 비용이 저렴할 때 수행하십시오:
main에서 자동 배포.- HTTPS가 포함된 사용자 정의 도메인.
- 청구 알람. 방금 클라우드 계정에 카드를 등록했습니다. 예상치 못한 금액에 대한 예산 알림을 설정하십시오. 2분이면 되며, 낮은 확률의 불쾌한 놀라움을 이메일 하나로 전환합니다.
- 보안 헤더 — 정적 호스트는 기본적으로 없음을 제공합니다.
- 콘텐츠 해시된 빌드 자산에 대한 장기 캐시
Cache-Control. 쉽고 영구적이며, 그렇지 않으면 아무 것도 차단하지 않기 때문에 영원히 연기됩니다.
도메인 및 DNS에서 예측 가능한 함정이 있습니다:
- 베어 도메인은 CNAME을 사용할 수 없습니다 —
www.example.com은 사용할 수 있지만example.com은 불가능합니다. DNS 제공업체의 ALIAS/ANAME 레코드 또는 호스트 자체의 apex 옵션이 필요합니다. 정식 URL에www가 포함될지 조기에 결정하고, 다른 쪽으로 리디렉션하십시오. - HTTPS 인증서는 유효성을 검사하기 위해 DNS 레코드가 필요하며, 해당 레코드가 확인될 때까지 발급되지 않습니다. DNS 변경이 잘못되었다고 판단하기 전에 몇 시간을 기다리십시오 — 전파 지연은 실패와 똑같이 보입니다.
실제 시간을 소모하는 배포 함정:
- 어떤 부분이 자동 배포되고 어떤 부분이 그렇지 않은지 정확히 파악하십시오. 스택의 일부
(서버리스 함수, 백엔드, 워커)가 별도의 수동 명령으로 배포된다면,
CLAUDE.md에 대문자로 작성하십시오. 고전적인 무음 실패는 표시되는 사이트는 업데이트되지만 백엔드는 업데이트되지 않는 브랜치를 병합하는 것입니다. - 자동 배포는 마지막 체크포인트를 제거합니다. 병합-투-배포를 사용하면 PR 검토가 게이트 역할을 합니다. 검증은 병합 전에 이루어져야 하며, 후가 아닙니다.
- 빌드 호스트의
npm ci는 로컬의npm install보다 더 엄격합니다. 잠금 파일이package.json과 미묘하게 동기화되지 않으면 로컬의 최신 npm에서는 잘 설치되지만 호스트의 이전 npm에서는 빌드가 실패합니다. 호스트에서는 빌드가 실패하지만 로컬에서는 성공합니까? 먼저 잠금 파일을 의심하십시오. - 런타임을 버전 파일뿐만 아니라 빌드 사양에 고정하십시오.
.nvmrc만으로는 안정적으로 적용되지 않습니다 — 빌드 명령에서도 버전 관리자를 호출하십시오. - 모든 새 환경 변수는 코드에서 읽는 것과 별도로 호스트 콘솔에 추가해야 합니다. 놀랍게도 자주 발생하는 "왜 고장났는지"에 대한 답변입니다.
- Content-Security-Policy는 당신을 괴롭힐 헤더입니다. 페이지가 실제로 통신하는 모든 타사 출처 (분석, 태그 관리자, 픽셀, 폰트, 양식 엔드포인트)는 올바른 지시문에 허용 목록에 추가되어야 하며, 그렇지 않으면 로컬 개발에서 완벽하게 작동하는 동안 프로덕션에서 자동으로 차단됩니다. 증상: "로컬에서는 추적이 작동하지만, 라이브에서는 아무 것도 전송되지 않습니다." 다른 것을 디버깅하기 전에 브라우저 콘솔에서 CSP 위반을 확인하십시오.
- 소스 파일이 아닌 배포된 아티팩트에 대해 확인하십시오. 실제 프로덕션 응답(
curl -I, 브라우저 개발자 도구)을 검사하여 수정 사항을 확인하고, 이를 생성해야 하는 구성을 읽지 마십시오. "내 변경 사항이 실제로 배포되었는지" 확인하는 경우에도 병합이 발생했는지 여부만 확인하지 말고 빌드 ID/타임스탬프를 확인하십시오.
양식이 실제로 제출되는 방식
정적 호스팅에는 백엔드가 없습니다. 정적 페이지의 일반 <form>은 유용한 작업을 수행하지 않습니다.
이것은 첫날 사람들을 놀라게 하며, 이것이 페이지의 핵심입니다. 세 가지 현실적인 옵션이 있습니다:
| 옵션 | 적합한 경우 | 주의할 점 |
|---|---|---|
| 호스팅된 양식 서비스 | 오늘 오후에 작동시키고 싶을 때 | 볼륨별 월 비용; 제공업체 브랜딩; 데이터가 그들과 함께 있음 |
| 서버리스 함수 (Lambda, Netlify/Cloudflare Functions) | 제어권과 거의 제로 비용을 원할 때 | 이제 유효성 검사, 스팸 및 CORS를 직접 처리해야 함 |
| CRM의 임베디드 양식 또는 웹훅 | 리드가 어쨌든 CRM에 들어가야 할 때 | 임베드 무게 및 스타일 제한; 종종 로딩이 느림 |
어떤 것을 선택하든:
- CORS가 첫 번째 오류가 될 것입니다. 페이지와 다른 출처에 있는 서버리스 엔드포인트는 해당 출처를 명시적으로 허용 목록에 추가해야 합니다. 그렇지 않으면 브라우저가 요청을 보내기 전에 차단합니다. 로컬호스트도 허용 목록에 추가하십시오. 그렇지 않으면 로컬에서 테스트할 수 없습니다.
- 허니팟 필드를 추가하십시오 (인간은 작성하지 않고 봇만 작성하는 숨겨진 입력) 그리고 그것을 채우는 모든 것을 거부하십시오. 가장 저렴한 스팸 필터입니다.
- 원시 요청 본문을 데이터베이스 쓰기에 직접 스프레드하지 마십시오. 이것이 방문자가 서버 측에서 제어하려는 필드를 설정하게 만드는 방법입니다. 원하는 필드를 명시적으로 선택하십시오.
- 가능하면 엔드포인트를 웜 상태로 유지하십시오. 콜드 스타트하는 서버리스 함수는 페이지에서 가장 중요한 순간인 제출 버튼 클릭을 고장난 것처럼 느끼게 만듭니다.
3. 브랜드 키트를 Claude에 제공하고 강제로 로드하십시오
이것은 목록에서 가장 레버리지가 높은 항목입니다. 최소한 키트는 다음을 포함합니다:
제안 · 대상 시장 / 고객 프로필 · 메시징 전략 · 색상 · 글꼴 · 로고
폴더(brand/)에 넣으십시오. 템플릿: starters/brand-kit/brand.md.
그런 다음 자동으로 로드되도록 설정하십시오. CLAUDE.md에 "브랜드 키트를 읽으십시오"라는 지침은
권고 사항이며 일관되게 따르지 않습니다. 파일을 컨텍스트로 cat하는 SessionStart 훅은
선택 사항이 아니며 건너뛰지 않습니다. 이 한 가지 변경 사항이 "가끔 브랜드에 부합함"과 "기본적으로 브랜드에 부합함"의 차이입니다.
starters/settings.json을 참조하십시오.
세션 시작 시 로드: 브랜드 키트, 짧은 아키텍처 문서 (사이트 구축, 호스팅, 배포 방식), 및 가장 최근 세션 로그.
잘 구성하는 방법:
- "브랜드의 모양"과 "브랜드가 말하는 방식"을 분리하십시오. 항상 켜져 있는 파일은 간결하게 유지하십시오 — 팔레트, 글꼴, 로고, 제안, 대상 독자. 더 깊은 음성/메시징 자료는 "카피 작업 시 읽으십시오"로 연결하십시오. 자동 로드되는 모든 것은 영원히 모든 세션에서 컨텍스트를 소모합니다.
- 색상에 역할을 부여하십시오. 단순한 16진수 코드가 아닌 ("기본 강조 — 주요 CTA에 사용"). 역할은 Claude가 색상이 필요할 때 색상을 임의로 만드는 것을 막습니다. 규칙을 명확히 명시하십시오: 키트 외부의 색상은 어디에도 나타나지 않습니다. 그렇지 않으면 템플릿 및 생성기의 비브랜드 기본값이 조용히 스며듭니다.
- 두세 가지 전/후 음성 예제는 형용사 목록보다 훨씬 빠르게 음성을 가르칩니다.
- 메시징이 상업적으로 민감한 경우 gitignore하십시오 하지만 여전히
CLAUDE.md에서 참조하십시오 — 전략이나 가격을 저장소에 게시하지 않고 일관된 로딩을 얻을 수 있습니다. - 외부 동기화된 브랜드 문서는 오래됩니다. 공유 드라이브에서 음성 또는 대상 독자 문서를 복사한 경우, 복사 작업 전에 소스와 다시 확인하십시오 — 마케팅 결정은 문서에 다시 반영되지 않는 대화에서 이루어집니다.
브랜드 키트가 적용해야 하는 카피 규율:
- 이메일을 캡처하는 것이 작업인 페이지에서 "가입 불필요 / 이메일 필요 없음"을 절대 약속하지 마십시오. 양식이 나타날 때까지는 마찰 감소로 읽히지만, 신뢰가 필요한 바로 그 순간에 모순이 됩니다. 대신 시간, 비용 및 결과에 대해 안심시키십시오 — "2분 · 무료 · 결과를 즉시 이메일로 보내드립니다."
- 제안이 변경될 때마다 안심 마이크로카피를 재감사하십시오. 페이지 변형 간에 복사되어 그것이 작성된 제안보다 오래 지속됩니다. 정확히 도움이 되는 것처럼 들리기 때문입니다.
- 광고의 약속, 페이지의 약속 및 양식의 실제 요청은 모두 일치해야 합니다. 불일치는 진실이 도착하는 단계에서 이탈로 나타나며, 불일치가 도입된 단계가 아닙니다. 단계에서 누수가 발생하면 그 이전 단계를 의심하십시오.
4. 출시 전에 확인하십시오
배포하지 않고 페이지를 보는 두 가지 방법입니다. 서로 다른 사람들을 위한 것이므로 둘 다 사용하십시오.
로컬 개발 서버
당신과 Claude를 위해, 빌드 중에 사용합니다. Claude는 개발 서버를 시작하고, 실제 브라우저를 구동하고, 결과를 스크린샷하고, 콘솔 및 네트워크 로그를 읽을 수 있습니다. 따라서 "이것이 올바르게 렌더링됩니까?"라는 질문은 코드를 검사하는 것이 아니라 실제로 확인함으로써 답을 얻을 수 있습니다.
- 동일한 프로젝트에 대해 두 개의 개발 서버를 동시에 실행하지 마십시오. 기존 프로세스가 있는지 먼저 확인하고 다른 것을 시작하기 전에 종료하십시오. 특히 병렬 에이전트가 각각 하나씩 실행할 수 있는 경우 더욱 그렇습니다.
- 자동 재시도 루프를 약 3회 시도로 제한하십시오. 개발 서버와 브라우저 자동화를 감싼 "작동할 때까지 계속 다시 로드하고 다른 타이밍을 시도"하는 개방형 루프는 단순한 성가심이 아니라 실제 리소스 고갈 위험입니다 — 실제로 기계를 다운시킨 사례가 있습니다.
- 정리를 신뢰하지 말고 확인하십시오. "서버를 중지하고 탭을 닫았습니다"는 다른 것과 마찬가지로 확인되지 않은 주장입니다 — 프로세스 목록을 확인하십시오.
- 로컬이 프로덕션과 의도적으로 다를 것으로 예상하십시오. 실제 분석 ID 또는 라이브 API 엔드포인트 뒤에 있는 모든 것은 일반적으로 로컬에서 작동하지 않습니다. 이는 예상된 동작이며 버그가 아닙니다. 문서화하여 몇 주마다 재진단되지 않도록 하십시오.
- 기본적으로 엔드 투 엔드 테스트가 로컬호스트를 가리키도록 유지하고, 실제 배포된 URL을 가리키는 것은 의도적인 별도의 행동으로 만드십시오. 그렇지 않으면 일상적인 테스트 실행이 프로덕션에 대해 실제 제출을 수행합니다.
Claude Design (claude.ai/design)
다른 모든 사람을 위한 것입니다. Claude는 페이지를 Claude Design 프로젝트에 푸시할 수 있으며, 클라이언트, 디자이너 또는 비기술적 파트너가 로컬 설정 없이 브라우저에서 시각적으로 카피와 레이아웃을 편집할 수 있는 공유 가능한 URL을 제공합니다. 페이지가 실제 사이트에 연결되기 전에 승인을 받는 데 탁월합니다.
하나의 엄격한 규칙: Design에 절대 맹목적으로 쓰지 마십시오.
Claude Design 프로젝트에 어떤 것을 쓰기 전에, Claude는 현재 원격 버전을 가져오고, 차이점을 비교하고, 덮어쓰기 전에 당신에게 확인해야 합니다. 매번.
Design 쪽에는 버전 기록, 실행 취소 및 휴지통이 없습니다. 캔버스 파일은 추적되지 않는 로컬 파일보다 더 취약합니다. 협력자의 편집 내용을 맹목적으로 덮어쓰는 것은 영구적으로 복구할 수 없으며, 이미 손으로 쓴 카피의 전체 저녁을 날린 사례가 있습니다.
- 페이지를 독립형 정적 HTML/CSS/JS로 작성하십시오. Design은 전체 정적 자산을 지원하므로 최종 페이지를 정확히 보여줄 수 있습니다.
- 로컬 개발 서버와 Design 간에 일관성을 유지하십시오. Design에서 수정한 내용은 로컬 소스 파일로 다시 가져와야 합니다. Design을 최종 편집 지점으로 취급하지 마십시오.
- Design을 협업 및 승인 도구로 사용하고, 개발 도구로 사용하지 마십시오. 실제 구현은 여전히 코드 저장소에 있으며, Design은 시각적 피드백 루프를 가속화하는 방법일 뿐입니다.
5. 첫날부터 추적 기능 추가
라이브 페이지는 추적 없이는 최적화할 수 없습니다. 방문자가 어디에서 드롭오프하는지 모르면 어디를 개선해야 할지 알 수 없습니다. 이것이 "출시"가 끝이 아니라 시작인 이유입니다.
설정해야 할 항목
| 도구 | 목적 | 빠른 설정 참고 |
|---|---|---|
| Google Analytics 4 (GA4) | 트래픽 소스, 사용자 행동 | GTM을 통해 Google 광고 ID를 GA4로 직접 보내기 위해 GA4 구성 태그에서 overwrite 모드를 사용; 기본값은 동의하지 않음 |
| Google Tag Manager (GTM) | 태그 관리 | 페이지 헤드에 <script> 2개; 기본 작동을 위해 dataLayer 선언이 GTM 스니펫 앞에 와야 함 |
| Facebook Pixel | 광고 전환 | GTM 사용자 정의 HTML 태그로; 오프라인 이벤트가 관련이 있다면 CAPI도 고려하십시오 |
| Microsoft Clarity | 행동 분석, 히트맵 | 무료이며 세션 기록 포함; GTM 템플릿을 사용할 수 있음 |
| Google Search Console | SEO 성능 | 별도 설정 필요; 소유권은 TXT 레코드 또는 HTML 파일로 확인 |
Google Tag Manager 설정 참고 사항:
- GTM 스니펫보다 먼저
dataLayer를 전역 변수로 선언하십시오. 그렇지 않으면 초기 이벤트가 실행되기 전에 사라집니다. 이는 자주 발생하는 "이벤트가 GTM에 표시되지 않음" 원인 중 하나입니다. - GTM UA(범용 분석) 태그를 GA4로 마이그레이션하지 마십시오. GTM 컨테이너에서 처음부터 GA4 구성 및 이벤트 태그를 새로 만드십시오. 변환에는 문제가 있습니다.
- GA4 구성 태그에서
overwrite모드를 사용하십시오. GA4는 기본적으로 Google 광고 ID를 덮어쓰지 않으며, 이는 트래픽 소스 보고를 분석 수준에서 중단시킵니다. GTM 태그에서 명시적으로 활성화해야 합니다.
확인해야 할 추적별 확인 사항
- 로컬에서 완벽하게 실행되는 추적을 프로덕션에서 배포하자마자 확인하십시오. 페이지의 소스 태깅만 변경하고 브라우저에서 직접 GA4 보고서를 확인하십시오.
- 모든 픽셀/태그가 의도된 이벤트와 함께 실제로 실행되는지 확인하십시오. GTM 미리보기 모드, 브라우저 개발자 도구 네트워크 탭 및 태그 어시스턴트를 모두 사용하십시오.
- 폼 제출 시 의도된 전환 이벤트를 실행하는지 확인하십시오. 후속 페이지 또는 AJAX 응답에 의존하지 마십시오.
- Google Ads 전환 추적을 설정하는 경우, 브라우저에서 GTM 미리보기를 통해 전환 링커 태그가 올바르게 실행되고 있는지 확인하십시오.
- 트래픽 소스 보고서가 작동 중인지 확인하십시오. GA4 보고서에서 직접 트래픽 소스 데이터를 확인하여 캠페인 추적이 올바르게 수집되는지 확인하십시오.
문제 해결 가이드 (일반적인 함정)
| 문제 | 가능한 원인 | 해결 방법 |
|---|---|---|
| 사이트가 로컬에서는 작동하지만 배포 후에는 작동하지 않음 | 빌드 캐시/종속성 문제 | npm ci (또는 동등)를 사용하여 깨끗한 빌드 실행; 배포된 아티팩트와 소스 파일 비교 |
| 양식 제출에 405 오류가 표시됨 | 정적 호스트가 POST를 수락하지 않음 | 양식 엔드포인트를 서버리스 함수 또는 타사 양식 서비스로 이동 |
| 추적이 로컬에서 실행되지만 라이브에서는 실행되지 않음 | 콘텐츠 보안 정책 차단 | 브라우저 콘솔에서 CSP 위반 확인; 필요한 출처 허용 |
| 이미지/스타일시트가 404 오류를 반환함 | 상대 경로 문제 (특히 SPA) | 절대 경로 또는 올바른 기본 URL 사용 확인 |
| 병합 후 사이트가 업데이트되지 않음 | 자동 배포가 올바르게 설정되지 않음 | 자동 배포가 main으로 설정되어 있는지 확인; 호스트의 빌드 기록 확인 |
| Google Tag Manager가 GA4에 데이터를 보내지 않음 | GA4 구성 태그에서 잘못된 overwrite 설정 | overwrite 모드를 true로 설정하여 Google Ads ID가 GA4로 전달되도록 함 |
한 줄 요약: 가장 중요한 것
Claude에 브랜드 키트를 제공하고, GitHub에 저장소를 설정하고, 자동 배포를 구성하고, 첫날부터 기본 추적을 설정하고, 배포 후 데이터를 기반으로 반복하십시오.
모든 것은 추적으로 귀결됩니다. 그것 없이는 실험하고 개선할 데이터가 없습니다. 데이터가 없으면 추측만 할 수 있습니다.