어떤 프롬프트를 써야 할지, 만든 파일을 어떻게 열고 고쳐야 할지 막막하셨죠? 저도 코딩을 몰라서 똑같이 헤맸어요. Claude Code로 HTML 페이지를 처음부터 끝까지 만들고 수정하는 흐름을 직접 해본 그대로 정리했으니, 끝까지 따라오시면 작은 완성형 페이지 하나는 손에 남습니다.
Claude Code로 HTML 페이지 만들기 시작 전 준비 사항
Claude Code는 제가 글로 적은 요청을 읽고 실제 코드를 만들어주는 도구예요. 웹페이지 생성이 처음이라 무엇부터 손대야 할지 모를 때, 페이지 구조를 잡고 HTML 코드 작성까지 한 번에 도와줍니다. 저처럼 코딩을 모르는 사람도 “이런 페이지를 만들고 싶다”고 말하면 초안을 받아볼 수 있다는 게 가장 큰 장점이에요.
다만 도구만 있다고 끝이 아니에요. 코드를 받았을 때 어디에 저장하고 어떻게 열어볼지 그림이 안 잡히면 그대로 멈추게 됩니다. 그래서 실습 전에 개발 환경을 가볍게 정리해두는 게 좋아요. 작업할 프로젝트 폴더를 하나 만들고, 그 안에 파일 저장 위치를 정한 뒤, 만든 파일을 브라우저 미리보기로 바로 확인하는 흐름까지 한 줄로 연결해두면 훨씬 덜 헷갈립니다. 이 전체 그림이 잡혀 있으면 웹 개발 입문 단계의 막막함이 절반은 줄어듭니다.
- 바탕화면이나 문서 폴더 안에 작업용 프로젝트 폴더를 하나 만듭니다
- 첫 페이지 파일은 항상 index.html 이라는 파일명 규칙을 따릅니다
- 코드를 보고 고칠 수 있는 무료 에디터를 설치해 둡니다
- 결과를 확인할 기본 브라우저를 정해 둡니다
- 만든 파일을 더블클릭하거나 에디터에서 열어 결과 확인 방식을 익혀 둡니다
초보일수록 한 가지를 꼭 기억하시면 좋아요. Claude Code로 한 번에 완벽한 페이지를 뽑는다는 마음보다, 일단 초안을 받고 그걸 조금씩 수정한다는 흐름이 훨씬 현실적입니다. Claude 활용법의 핵심도 결국 “초안 생성 후 수정”이라는 반복에 있거든요. 첫 결과가 어설퍼도 당연한 거라 생각하면 마음이 편해집니다.
원하는 결과를 끌어내는 프롬프트 작성법
제가 직접 해보니 프롬프트 작성이 결과 품질의 절반 이상을 좌우했어요. 같은 도구라도 “페이지 만들어줘”라고만 하면 밋밋한 결과가 나오고, 페이지 목적과 대상, 구성, 스타일, 기술 요구사항을 구체적으로 적으면 바로 쓸 만한 초안이 나옵니다. 머릿속에 있는 그림을 최대한 글로 풀어 적는다고 생각하시면 됩니다.
그리고 한 번에 모든 걸 요구하지 않는 게 생산성 향상에 훨씬 유리했어요. 1차로 기본 구조 설계와 마크업 작성을 요청해 초안을 받고, 2차로 디자인을 보정하고, 3차로 기능을 추가하는 식으로 단계별 제작을 하면 수정도 쉽고 오류도 줄어듭니다. 반복 작업을 잘게 쪼개는 게 코드 작성과 웹페이지 생성 모두에서 안정적이더라고요.
- 페이지 유형: 간단한 랜딩페이지, 소개 페이지, 포트폴리오 페이지 중 무엇인지
- 필요한 섹션: 헤더, 히어로, 기능 소개, 문의 등 들어갈 블록
- 원하는 톤과 색상: 깔끔한, 차분한, 밝은 같은 분위기와 색 계열
- 반응형 여부: 모바일에서도 깨지지 않게 만들지
- CSS/JS 분리 여부: 한 파일에 넣을지, 외부 파일로 나눌지
- 수정 가능한 코드 형식 요청: 주석을 넣고 읽기 쉬운 구조로
| 요청 요소 | 프롬프트에 넣을 표현 예시 | 기대 결과 |
|---|---|---|
| 페이지 목적 | 1인 디자이너 소개용 간단한 랜딩페이지를 만들어줘 | 목적에 맞는 섹션 구성 |
| 섹션 구성 | 헤더, 히어로, 서비스 소개, 문의 섹션을 넣어줘 | 요청한 블록이 순서대로 배치 |
| 디자인 톤 | 흰 배경에 파란 포인트 색으로 깔끔하게 | 일관된 색상과 분위기 적용 |
| 반응형 | 모바일에서도 레이아웃이 깨지지 않게 해줘 | 화면 크기에 맞춘 반응형 코드 |
| 코드 형식 | HTML과 CSS를 파일로 분리하고 주석을 넣어줘 | 검토하기 쉬운 분리된 코드 |
여기에 “코드만 출력”, “파일 분리”, “주석 포함”, “접근성 고려” 같은 요청 문구를 덧붙이면 생성 결과를 검토하기가 훨씬 수월해져요. 이런 표현 하나가 나중에 수정 시간을 크게 줄여주니, 실습 가이드처럼 미리 메모해 두는 걸 추천합니다.
HTML 기본 구조와 시맨틱 마크업 설계
HTML 페이지의 뼈대를 이해하면 Claude Code가 만든 코드도 무섭지 않아요. 모든 문서는 크게 head 태그와 body 태그로 나뉩니다. head 태그에는 화면에 직접 보이지 않지만 페이지 정보를 담는 메타 태그, 제목, 링크 태그가 들어가고, body 태그에는 실제 화면에 보이는 콘텐츠가 들어갑니다. 이 둘의 역할만 구분해도 코드를 읽는 눈이 확 트입니다.
여기에 시맨틱 HTML을 쓰면 유지보수와 접근성, SEO 최적화에 모두 도움이 돼요. 시맨틱 HTML이란 그냥 의미 없는 칸으로 나누는 대신, 헤더는 헤더답게 본문은 본문답게 의미를 가진 태그로 구조 설계를 하는 방식입니다. 사람도 검색 엔진도 페이지 구조를 더 잘 이해하게 되죠.
- html: 문서 전체를 감싸는 가장 바깥 태그, 한 문서에 하나만 있으면 됩니다
- head: 메타 정보를 담는 영역, Claude Code에 "head에 기본 메타를 넣어줘"라고 명시하면 좋아요
- meta: 문자 인코딩과 모바일 화면 설정 등을 담당, 반응형이면 꼭 포함하도록 요청합니다
- title 또는 제목 태그: 브라우저 탭과 화면 제목, 페이지 주제를 명확히 적어달라고 합니다
- header: 로고나 내비게이션이 들어가는 상단 영역, 메뉴 구성을 함께 요청하면 편합니다
- main 또는 section: 핵심 콘텐츠를 섹션 구분해 담는 영역, 섹션 추가를 부탁할 때 기준이 됩니다
- footer: 저작권이나 연락처가 들어가는 하단 영역, 푸터 구성도 함께 요청하면 깔끔합니다
기본 템플릿을 요청할 때 “시맨틱 구조로 작성해줘”라는 한마디를 넣어보세요. 이렇게 받아두면 이후에 섹션을 추가하거나 템플릿 수정을 할 때 어느 부분을 고쳐야 하는지 바로 보입니다. HTML 학습을 따로 안 했어도, HTML 예제를 받아 구조를 눈에 익히는 것만으로 충분히 출발할 수 있어요.
랜딩페이지와 소개 페이지용 초안 생성 예시
처음부터 기능이 많은 사이트를 노리면 오류가 쏟아져서 금방 지칩니다. 저는 간단한 랜딩페이지, 소개 페이지, 개인 웹사이트처럼 작은 완성형 결과물부터 시작하길 권해요. 페이지 하나를 끝까지 완성해보면 웹페이지 생성과 코드 작성 흐름이 손에 잡히고, 그 경험이 다음 페이지를 만들 때 그대로 쓰입니다.
- 간단한 랜딩페이지: 제품이나 서비스 하나를 알리는 목적, 히어로와 핵심 장점, 문의 CTA 섹션, 한 화면에서 흐름이 끊기지 않는 깔끔한 디자인
- 소개 페이지: 개인이나 가게를 소개하는 목적, 인사말과 활동 소개, 연락 정보 섹션, 신뢰감을 주는 차분한 색감
- 포트폴리오 페이지: 작업물을 보여주는 목적, 자기소개와 작업 갤러리, 연락 섹션, 카드 형태로 정렬되는 레이아웃
- 제품 소개 페이지: 제품 특징을 설명하는 목적, 제품 이미지와 기능 설명, 가격이나 구매 안내 섹션, 시선이 자연스럽게 아래로 흐르는 구성
재밌는 건 같은 프롬프트라도 콘텐츠 배치, 제목 태그 구성, CTA 버튼 위치만 바꿔도 전혀 다른 웹 페이지 초안이 나온다는 점이에요. 그래서 Claude Code가 만든 HTML 예제를 그대로 두지 말고, 직접 눈으로 보면서 “이 버튼은 위로 올려줘”, “이 섹션을 앞으로 빼줘” 식으로 다듬어야 진짜 내 페이지가 됩니다. 단계별 제작의 묘미가 여기에 있어요.
CSS 연동으로 레이아웃과 스타일 다듬기
초안이 밋밋하다면 CSS 연동으로 스타일 적용을 해주면 됩니다. CSS를 넣는 방법은 여러 가지지만, 초보자에게는 외부 스타일시트를 따로 파일로 만들어 HTML에 연결하는 방식을 추천해요. 인라인 스타일은 태그마다 직접 스타일을 박아 넣어서 당장은 빨라 보여도, 수정과 재사용이 어렵고 코드가 금방 지저분해지거든요. 외부 스타일시트는 한 곳만 고치면 전체에 반영돼서 레이아웃 개선이 훨씬 편합니다.
- 색상 팔레트: "메인 색은 파랑, 보조 색은 회색으로 통일해줘"처럼 색 계열을 지정합니다
- 폰트 설정: "본문은 읽기 편한 산세리프 폰트로"라고 가독성 기준을 적습니다
- 버튼 스타일: "버튼은 둥근 모서리에 마우스 올리면 색이 바뀌게" 식으로 상태까지 요청합니다
- 여백 조정: "섹션 사이 위아래 여백을 넉넉히" 라고 답답하지 않게 부탁합니다
- 정렬 방식: "제목과 내용을 가운데 정렬"처럼 기준을 명확히 합니다
- 컨테이너 클래스: "콘텐츠 폭을 일정하게 잡는 컨테이너 클래스를 넣어줘"라고 요청합니다
- 카드 컴포넌트: "항목들을 카드 형태로 나란히 배치"라고 반복 요소를 정리합니다
- 히어로 섹션: "첫 화면에 큰 제목과 버튼이 있는 히어로 섹션을" 라고 강조 영역을 지정합니다
| 디자인 요소 | 권장 CSS 방식 | 초보자가 자주 겪는 문제 |
|---|---|---|
| 전체 레이아웃 | 플렉스박스나 그리드 시스템 활용 | 요소가 한 줄로 안 모이고 흩어짐 |
| 가로 정렬 | 플렉스박스로 정렬 방식 지정 | 가운데 정렬이 안 먹음 |
| 여백 조정 | 여백 단위를 일관되게 사용 | 섹션마다 간격이 들쭉날쭉 |
| 카드 컴포넌트 | 공통 클래스로 카드 스타일 재사용 | 카드마다 크기가 다르게 나옴 |
| 반응형 디자인 | 화면 폭별 분기로 모바일 대응 | 모바일에서 레이아웃이 깨짐 |
| 버튼 스타일 | 외부 스타일시트에 버튼 클래스 정의 | 버튼마다 모양이 제각각 |
레이아웃 구성이 막막하면 플렉스박스와 간단한 그리드 시스템을 활용해달라고 요청하세요. 요소를 가로세로로 정렬하고 화면 크기에 맞춰 배치하는 데 가장 쉬운 방법이라, 반응형 디자인도 한결 수월해집니다. 이때 “모바일에서는 한 줄로, 데스크톱 레이아웃에서는 세 칸으로”처럼 모바일 대응과 데스크톱 차이를 프롬프트에 명시해두면 두 화면 모두 깔끔하게 나옵니다.
자바스크립트 삽입과 기본 상호작용 추가
화면이 움직이거나 반응해야 할 때는 자바스크립트 삽입이 필요해요. 대표적으로 버튼을 클릭하면 메시지가 뜨는 반응, FAQ 섹션을 눌러 열고 닫는 동작, 회원가입 폼이나 연락처 페이지에서 입력값을 검사하는 폼 유효성 검사 같은 기능이 여기에 해당합니다. 처음부터 복잡한 기능을 욕심내기보다 이런 작은 상호작용부터 붙여보는 걸 권해요.
자바스크립트는 보통 스크립트 태그를 body 하단에 두는 게 기본 관례입니다. 화면 요소가 먼저 다 그려진 뒤에 스크립트가 실행돼야 “없는 버튼 요소를 찾다가 나는 오류”가 줄어들거든요. 그래서 HTML 구조가 먼저 안정된 다음 기능을 얹는 순서가 안전합니다.
- 기능 지정: "FAQ 항목을 클릭하면 답이 펼쳐지게 해줘"라고 무엇을 할지 명확히 적습니다
- 대상 요소 이름 지정: 어떤 버튼 요소나 폼 요소에 동작을 붙일지 클래스나 아이디를 알려줍니다
- 동작 설명: 클릭하면 무엇이 열리고 닫히는지 흐름을 구체적으로 풀어 적습니다
- 에러 처리 요청: 입력 필드가 비었을 때 안내가 뜨도록 예외 상황 처리를 부탁합니다
- 주석 포함 요청: 각 코드가 무슨 일을 하는지 주석으로 설명해달라고 합니다
특히 로그인 화면, 회원가입 폼, 연락처 페이지처럼 입력 필드와 폼 요소가 들어가는 페이지는 동작 테스트가 정말 중요해요. 빈칸으로 제출해보고, 잘못된 값을 넣어보면서 의도대로 반응하는지 꼭 확인하세요. 기능을 재사용 코드나 컴포넌트 분리 형태로 만들어달라고 하면 나중에 다른 페이지에도 옮겨 쓰기 편합니다.
생성된 결과 검토와 오류 수정 체크포인트
결과물이 예쁘지 않거나 오류가 나도 원인을 못 찾아 답답할 때가 많죠. 저는 생성 결과 검토를 “구조 오류, 스타일 오류, 기능 오류” 세 범주로 나눠서 봐요. 화면 배치가 이상하면 구조, 색이나 정렬이 어긋나면 스타일, 버튼이 안 움직이면 기능 쪽을 의심하는 식이에요. 이렇게 나눠두면 막연하게 헤매지 않고 디버깅 방향을 잡을 수 있습니다.
- 닫히지 않은 태그: 여는 태그만 있고 닫는 태그가 빠지면 화면이 무너집니다
- 잘못된 파일 경로: CSS나 이미지 파일 경로가 어긋나면 연결이 안 됩니다
- CSS 연결 누락: 외부 스타일시트 링크가 빠지면 스타일이 하나도 안 먹습니다
- 이미지 표시 실패: 파일명이나 위치가 안 맞으면 이미지가 깨져 보입니다
- 버튼 동작 없음: 스크립트 연결이나 요소 이름이 어긋난 경우가 많습니다
- 모바일 화면 깨짐: 반응형 설정이 빠졌거나 폭 지정이 잘못된 경우입니다
- 텍스트 위계 불명확: 제목 태그 순서가 뒤섞이면 읽는 흐름이 흐트러집니다
- 불필요하게 긴 코드: 중복된 코드가 많으면 코드 품질이 떨어지고 수정이 어려워집니다
문제를 찾을 때는 브라우저 미리보기와 로컬 실행을 계속 반복하면서 템플릿 수정을 진행하세요. 한 번 고치고 바로 새로고침해 확인하는 습관이 디버깅 시간을 크게 줄여줍니다. 그래도 원인을 모르겠으면 Claude Code에 “지금 이 부분이 이렇게 안 되는데, 현재 오류 원인을 설명하고 수정된 코드만 다시 작성해 달라”고 요청해보세요. 어디가 잘못됐는지 짚어주면서 문법 검사까지 거친 코드를 받을 수 있어 훨씬 수월합니다.
접근성·SEO·페이지 속도까지 함께 챙기는 방법
보기 좋은 페이지를 만들었다면 한 단계 더 나아가 사용성도 챙겨보세요. 접근성이란 누구나 페이지를 이용할 수 있게 만드는 배려예요. 이미지를 넣을 때 대체 텍스트를 함께 적으면 이미지가 안 보이는 상황에서도 내용이 전달되고, 제목 태그 위계를 지키면 화면을 소리로 듣는 사용자도 흐름을 따라갈 수 있습니다. 키보드만으로도 메뉴와 버튼을 누를 수 있는 키보드 탐색까지 고려하면 더 좋고요.
SEO 최적화도 처음부터 챙겨두면 나중이 편합니다. 메타 태그로 페이지 설명을 넣고, 시맨틱 HTML로 영역을 구분하고, 명확한 섹션 구분을 해두면 검색 엔진이 페이지 내용을 더 정확히 이해해 검색 엔진 색인에 도움이 됩니다. 이런 구조는 결국 사람이 읽기에도 좋은 페이지라는 뜻이기도 해요.
| 점검 항목 | 적용 방법 | 기대 효과 |
|---|---|---|
| 대체 텍스트 | 이미지마다 내용을 설명하는 텍스트 추가 | 접근성과 색인 품질 향상 |
| 제목 위계 | 큰 제목부터 작은 제목까지 순서대로 사용 | 구조 이해와 가독성 개선 |
| 메타 태그 | 페이지 설명과 모바일 화면 설정 추가 | 검색 노출과 반응형 대응 |
| 이미지 최적화 | 적절한 크기와 가벼운 형식으로 변환 | 페이지 속도 개선 |
| 코드 정리 | 불필요한 코드와 중복 제거 | 코드 품질과 로딩 속도 향상 |
페이지 속도를 높이고 싶다면 이미지 최적화, 불필요한 코드 제거, 외부 리소스 최소화를 Claude Code 프롬프트에 직접 넣어 요청할 수 있어요. 검색 엔진 색인과 모바일 환경까지 함께 고려한 구조여야 결과물을 진짜 사이트처럼 활용할 수 있습니다. 디자인만 멋진 페이지보다, 찾기 쉽고 쓰기 편한 페이지가 오래 살아남아요.
파일 실행, 수정 반복, 배포 전 최종 점검
HTML 페이지를 만들었다고 바로 끝내면 아쉬운 부분을 놓치기 쉬워요. 저는 파일 저장, 로컬 실행, 브라우저 미리보기, 수정 반복의 순서로 꼭 한 바퀴 돌립니다. 만든 파일을 브라우저로 직접 열어 눈으로 확인하고, 어색한 부분을 메모해 다시 고치는 거죠. 이 과정을 몇 번 거치면 처음 초안과는 비교가 안 되게 완성도가 올라갑니다.
- index.html 열기: 파일명 규칙대로 저장했는지 확인하고 브라우저로 엽니다
- CSS/JS 연결 확인: 스타일과 기능이 제대로 불러와지는지 봅니다
- 모바일 화면 확인: 화면 폭을 줄여보며 레이아웃이 깨지지 않는지 점검합니다
- 링크와 버튼 테스트: 모든 링크와 버튼이 의도대로 동작하는지 눌러봅니다
- 이미지와 텍스트 검수: 이미지가 다 보이고 오타나 빈 영역이 없는지 살핍니다
- 최종 코드 백업: 완성된 코드를 프로젝트 폴더에 안전하게 따로 저장해 둡니다
Claude Code는 반복 작업과 자동화 작업을 덜어주는 든든한 보조 도구지만, 최종 검수는 결국 제가 직접 해야 한다는 걸 매번 느껴요. 도구가 짜준 코드도 사람의 눈으로 한 번 더 확인해야 안심하고 쓸 수 있거든요. 초보일수록 “생성 → 미리보기 → 수정 요청 → 재확인”이라는 루프를 몸에 익히는 게 가장 중요합니다. 이 흐름만 손에 잡히면 다음 페이지부터는 훨씬 빠르고 자신 있게 만들 수 있어요.
Claude Code로 HTML 페이지 만들기, 결국 반복이 답이었어요
처음엔 어떤 프롬프트를 써야 할지, 만든 파일을 어떻게 열고 고칠지조차 막막했죠. 그런데 준비물 정리, 구체적인 프롬프트, 기본 구조 이해, CSS와 자바스크립트 다듬기, 오류 점검, 접근성과 SEO, 마지막 검수까지 차근차근 밟아보면 코딩을 몰라도 작은 페이지 하나는 충분히 완성할 수 있어요. 핵심은 한 번에 완벽하게가 아니라, 초안을 받고 미리보기로 확인하며 조금씩 고쳐가는 반복이라는 점입니다. 저도 그렇게 헤매면서 배웠으니, 여기까지 읽어주신 분도 분명 해낼 수 있어요. 끝까지 함께해 주셔서 고맙습니다.
