Claude Code 실전 가이드: 터미널에서 웹사이트 만들기

이 글은 devyul.studio 웹사이트를 실제로 Claude Code로 만든 경험을 바탕으로 작성했습니다. 설치부터 배포까지, 실전에서 바로 쓸 수 있는 팁을 공유합니다.

Claude Code란?

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 어시스턴트입니다. VS Code 같은 IDE가 아니라, 터미널에서 직접 대화하면서 코드를 작성합니다. 파일 읽기/쓰기, 명령어 실행, 검색까지 모두 가능합니다.

기존 AI 코딩 도구와의 가장 큰 차이점은 에이전트 방식이라는 것입니다. 단순히 코드를 제안하는 것이 아니라, 직접 파일을 만들고 수정하고 실행합니다.

설치와 시작

설치는 npm으로 간단합니다:

npm install -g @anthropic-ai/claude-code
claude

프로젝트 폴더에서 claude를 실행하면 대화가 시작됩니다. 이때 중요한 것이 CLAUDE.md 파일입니다.

CLAUDE.md: AI에게 프로젝트 알려주기

CLAUDE.md는 프로젝트 루트에 두는 설정 파일입니다. Claude Code가 대화를 시작할 때 자동으로 읽습니다. 여기에 프로젝트의 기술 스택, 구조, 빌드 명령어 등을 적어두면 AI가 프로젝트를 이해한 상태에서 작업을 시작합니다.

# CLAUDE.md

## Tech Stack
- Next.js 16, React 19, TypeScript
- Tailwind CSS v4
- Firebase (Firestore, Auth, Storage)

## Build Commands
npm run dev    # 개발 서버
npm run build  # 프로덕션 빌드

## Source Layout
- src/app/ — 페이지
- src/components/ — UI 컴포넌트
- src/services/ — Firebase CRUD

CLAUDE.md가 잘 작성되어 있으면 매번 프로젝트 구조를 설명할 필요가 없습니다.

실전 활용법

1. 컴포넌트 만들기

가장 기본적인 사용법입니다. 원하는 컴포넌트를 자연어로 설명하면 됩니다.

"히어로 섹션 컴포넌트 만들어줘. 배지, 제목, 부제목을 받고,
framer-motion으로 페이드인 애니메이션 넣어줘.
배경은 그래디언트로."

Claude Code가 파일을 생성하고, import 경로까지 자동으로 맞춰줍니다. 기존 프로젝트의 스타일 패턴을 CLAUDE.md에서 읽었기 때문입니다.

2. 버그 수정

에러 메시지를 그대로 붙여넣으면 됩니다:

"npm run build하면 이런 에러가 나와:
Type error: Cannot find module '../../../src/app/blog/detail/page.js'"

Claude Code가 관련 파일을 읽고, 원인을 분석하고, 수정까지 해줍니다. 빌드 캐시 문제인지, import 경로 문제인지 스스로 판단합니다.

3. 리팩토링

여러 파일에 걸친 리팩토링도 강력합니다:

"블로그 상세 페이지를 CSR에서 SSG로 전환해줘.
/blog/detail?slug=xxx → /blog/[slug] 형태로.
generateStaticParams와 generateMetadata 추가하고,
내부 링크도 다 바꿔줘."

이런 대규모 변경을 한 번의 대화로 처리할 수 있는 것이 Claude Code의 장점입니다.

4. 커스텀 명령어 만들기

.claude/commands/ 폴더에 마크다운 파일을 만들면 슬래시 명령어가 됩니다. 예를 들어 /write-blog라는 명령어를 만들면:

/write-blog Flutter 상태관리 비교

이렇게 입력하면 AI가 블로그 글을 작성하고, Firestore에 저장하고, 사이트를 재배포합니다. 반복 작업을 자동화하는 데 유용합니다.

효과적으로 쓰는 팁

구체적으로 지시하기

# 나쁜 예
"로그인 기능 만들어줘"

# 좋은 예
"Firebase Auth로 이메일/비밀번호 로그인 구현해줘.
useAuth 훅으로 감싸고, 로그인 실패 시 토스트 메시지 표시.
로그인 성공하면 /console로 리다이렉트."

구체적일수록 원하는 결과에 가까운 코드가 나옵니다.

단계별로 진행하기

한 번에 큰 기능을 요청하기보다, 단계별로 나눠서 진행하는 것이 좋습니다. 각 단계가 끝날 때마다 결과를 확인하고, 다음 단계로 넘어가세요.

빌드 확인 습관

코드를 생성한 후에는 반드시 빌드를 확인하세요. Claude Code에게 직접 요청하면 됩니다:

"npm run build 돌려서 에러 있는지 확인해줘"

devyul.studio를 만든 과정

이 사이트는 처음부터 끝까지 Claude Code로 만들었습니다. 주요 과정을 요약하면:

1. 프로젝트 초기 설정 — Next.js + Tailwind + Firebase 프로젝트 생성
2. 디자인 시스템 — 다크 테마, 공통 컴포넌트 (Button, Card, Badge 등)
3. 페이지 구현 — 홈, 소개, 서비스, 프로젝트, 블로그, 문의
4. 관리자 콘솔 — 프로젝트/블로그 CRUD, 이미지 업로드
5. SEO 최적화 — SSG 전환, 메타태그, 사이트맵
6. 자동 배포 — GitHub Actions + Firebase Hosting

전체 과정에서 직접 타이핑한 코드는 거의 없습니다. 의도를 전달하고, 결과를 검토하고, 방향을 수정하는 과정의 반복이었습니다.

마무리

Claude Code는 "코딩을 대신 해주는 도구"가 아니라, **"개발자의 생각을 빠르게 코드로 옮겨주는 파트너"**입니다. 프로젝트의 맥락을 이해하고, 일관된 스타일로 코드를 생성하며, 여러 파일에 걸친 변경도 한 번에 처리합니다.

한번 써보면 이전 방식으로 돌아가기 어려울 정도로 생산성이 달라집니다. AI와 함께하는 개발에 관심이 있다면, Claude Code로 시작해보세요.