Claude Code 설치부터 첫 코딩까지: 비전공자를 위한 완벽 가이드 (2026)
Claude Code를 처음 사용하는 비전공자를 위한 설치 가이드입니다. Node.js 설치, API 키 발급, 첫 프로젝트 생성까지 단계별로 안내합니다.
🤖 Claude Code란 무엇이고, 다른 도구와 어떻게 다른가
Claude Code는 터미널에서 실행하는 AI 코딩 도구입니다. Cursor처럼 별도 에디터를 설치하는 것이 아니라, 터미널 창에서 AI와 대화하면서 코딩하는 방식입니다. 파일 생성, 코드 작성, 프로젝트 구조 설계, 에러 수정까지 모두 대화로 요청할 수 있습니다.
Cursor나 VS Code + Copilot 같은 도구는 에디터 안에서 AI를 보조적으로 사용하지만, Claude Code는 AI가 주도적으로 프로젝트 전체를 관리합니다. 파일을 직접 만들고, 수정하고, 터미널 명령어까지 실행합니다. 비전공자 입장에서는 "내가 원하는 것을 말하면 AI가 알아서 구현해주는" 느낌에 더 가깝습니다.
이 글은 Claude Code를 처음 설치하고, AI에게 웹사이트 만들기를 요청하는 과정까지 안내합니다.
📋 설치 전 준비 사항
Claude Code를 사용하려면 세 가지가 필요합니다.
💻 시스템 요구 사항
| 항목 | 요구 사항 |
|---|---|
| OS | Windows 10 이상, macOS 12 이상, Linux |
| Node.js | 18 버전 이상 |
| RAM | 4GB 이상 |
| 인터넷 | AI 요청 시 항상 필요 |
📌 Node.js 설치 확인
Claude Code는 Node.js 기반으로 동작합니다. 터미널을 열고 아래 명령어를 입력하세요.
node --version
v18.0.0 이상의 버전 번호가 출력되면 됩니다. 숫자가 안 나오거나 18 미만이면 Node.js 설치 가이드를 참고해서 설치하세요.
🔑 Anthropic API 키 또는 Claude 구독
Claude Code를 사용하는 방법은 두 가지입니다.
| 방법 | 비용 | 특징 |
|---|---|---|
| Claude Max 구독 | 월 $100~$200 | 구독 로그인으로 바로 사용, 사용량 한도 있음 |
| Anthropic API 키 | 사용한 만큼 과금 | API 콘솔에서 키 발급, 세밀한 비용 관리 가능 |
입문자에게는 API 키 방식을 추천합니다. 적게 사용하면 비용이 거의 발생하지 않고, 사용량을 직접 확인할 수 있기 때문입니다.
🔑 Anthropic API 키 발급받기
📌 계정 생성
- 브라우저에서 console.anthropic.com에 접속합니다.
- "Sign Up"을 클릭하고 이메일 또는 Google 계정으로 가입합니다.
- 이메일 인증을 완료합니다.
📌 API 키 생성
- 로그인 후 좌측 메뉴에서 "API Keys"를 클릭합니다.
- "Create Key" 버튼을 클릭합니다.
- 키 이름을 입력합니다 (예: "claude-code-local").
- 생성된 키를 복사합니다. 이 키는 한 번만 표시되므로 안전한 곳에 저장하세요.
API 키는 sk-ant-로 시작하는 긴 문자열입니다. 이 키를 다른 사람과 공유하거나 코드에 직접 넣으면 안 됩니다. 키가 유출되면 다른 사람이 내 비용으로 API를 사용할 수 있기 때문입니다.
📌 결제 수단 등록
API를 사용하려면 결제 수단을 등록해야 합니다. 좌측 메뉴의 "Billing"에서 신용카드를 등록하세요. 사용량 한도(Spending Limit)를 설정할 수 있으므로 예상치 못한 과금을 방지할 수 있습니다. 처음에는 $5~$10 정도로 설정해두면 안심입니다.
📥 Claude Code 설치
터미널을 열고 아래 명령어를 입력합니다.
npm install -g @anthropic-ai/claude-code
-g 옵션은 시스템 전체에서 사용할 수 있도록 전역으로 설치한다는 뜻입니다. 설치가 끝나면 아래 명령어로 확인합니다.
claude --version
버전 번호가 출력되면 설치 성공입니다. 숫자가 안 나오고 "command not found" 에러가 나타나면 터미널을 닫았다가 다시 열어보세요. 그래도 안 되면 Node.js의 전역 패키지 경로가 PATH에 포함돼 있는지 확인해야 합니다.
🍎 macOS에서 권한 에러가 발생할 때
macOS에서 npm install -g를 실행할 때 EACCES 에러가 발생할 수 있습니다. 이 경우 앞에 sudo를 붙여서 실행합니다.
sudo npm install -g @anthropic-ai/claude-code
비밀번호를 입력하라는 메시지가 나오면 Mac 로그인 비밀번호를 입력하세요. 입력 중 화면에 아무것도 표시되지 않는 것이 정상입니다.
🔧 API 키 설정
설치 후 Claude Code에 API 키를 연결합니다.
📌 환경 변수로 설정하기
터미널에서 아래 명령어를 입력합니다.
Windows (PowerShell):
$env:ANTHROPIC_API_KEY = "sk-ant-여기에-키를-붙여넣으세요"
macOS / Linux:
export ANTHROPIC_API_KEY="sk-ant-여기에-키를-붙여넣으세요"
이 방법은 터미널 창을 닫으면 설정이 사라집니다. 매번 입력하기 번거로우니 영구 설정을 권장합니다.
📌 영구 설정하기
macOS / Linux:
셸 설정 파일에 추가합니다.
echo 'export ANTHROPIC_API_KEY="sk-ant-여기에-키를-붙여넣으세요"' >> ~/.zshrc
source ~/.zshrc
bash를 사용한다면 ~/.zshrc 대신 ~/.bashrc를 사용하세요.
Windows (PowerShell):
시스템 환경변수에 등록합니다.
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-여기에-키를-붙여넣으세요", "User")
설정 후 터미널을 닫았다가 다시 열면 적용됩니다.
📌 Claude 구독으로 사용하기
Claude Max 구독자라면 API 키 없이도 사용할 수 있습니다. 터미널에서 claude를 입력하면 로그인 화면이 나타납니다. 브라우저가 열리면 Claude 계정으로 로그인하세요.
🚀 Claude Code 첫 실행
📌 시작하기
프로젝트를 만들 폴더로 이동한 뒤 claude를 입력합니다.
# Windows
cd C:\Users\사용자이름\Documents
mkdir my-claude-project
cd my-claude-project
# macOS
cd ~/Documents
mkdir my-claude-project
cd my-claude-project
claude
Claude Code가 시작되면 > 프롬프트가 나타납니다. 여기에 한국어 또는 영어로 원하는 것을 입력하면 됩니다.
📌 인터페이스 이해하기
Claude Code의 인터페이스는 단순합니다.
| 요소 | 설명 |
|---|---|
> 프롬프트 | 사용자가 명령을 입력하는 곳 |
| Claude 응답 | AI의 답변과 실행 계획 |
| 도구 사용 알림 | Claude가 파일을 읽거나 수정할 때 표시 |
| 권한 요청 | 파일 수정이나 명령 실행 전 사용자 확인 |
Claude가 파일을 수정하거나 터미널 명령어를 실행하기 전에 항상 사용자에게 확인을 요청합니다. "y"를 입력하면 허용, "n"을 입력하면 거부합니다. 처음에는 하나씩 확인하면서 진행하세요.
📁 첫 프로젝트 만들기
📌 Next.js 프로젝트 생성 요청
Claude Code 프롬프트에 아래처럼 입력합니다.
이 폴더에 Next.js 프로젝트를 만들어줘. TypeScript를 사용하고,
App Router로 만들어줘. 간단한 자기소개 페이지도 함께 만들어줘.
이름은 "홍길동", 한 줄 소개는 "바이브코딩을 시작한 비전공자",
좋아하는 것은 "커피, 고양이, 여행"으로 해줘.
Claude가 실행 계획을 보여주고, 승인하면 다음 작업을 자동으로 진행합니다.
npx create-next-app명령어 실행- 프로젝트 파일 구조 생성
app/page.tsx파일을 자기소개 페이지로 수정- 스타일 파일 수정
각 단계마다 Claude가 무엇을 하려는지 설명하고 권한을 요청합니다. 내용을 읽고 "y"를 눌러 승인하세요.
📌 개발 서버 실행
프로젝트 생성이 완료되면 Claude에게 요청합니다.
개발 서버를 실행해줘
또는 직접 터미널에서 실행합니다.
npm run dev
브라우저에서 http://localhost:3000을 열면 AI가 만든 자기소개 페이지가 보입니다.
📌 추가 수정 요청
페이지를 더 꾸미고 싶다면 계속 대화하면 됩니다.
배경색을 연한 파란색으로 바꾸고, 프로필 사진 자리를 동그란
플레이스홀더로 추가해줘. 반응형으로 만들어서 모바일에서도
보기 좋게 해줘.
Claude가 해당 파일을 수정하고, 브라우저를 새로고침하면 변경 사항을 확인할 수 있습니다.
✅ 설치 확인 점검 목록
| 항목 | 확인 방법 | 정상 신호 |
|---|---|---|
| Node.js | node --version | v18 이상 출력 |
| Claude Code 설치 | claude --version | 버전 번호 출력 |
| API 키 설정 | claude 실행 | 에러 없이 프롬프트 표시 |
| 프로젝트 생성 | Claude에게 프로젝트 생성 요청 | 파일이 생성됨 |
| 개발 서버 | npm run dev | localhost:3000 접속 가능 |
⚠️ 자주 발생하는 문제와 해결
🚫 "command not found: claude" 에러
Node.js의 전역 패키지 경로가 PATH에 없는 경우입니다. 아래 명령어로 전역 패키지 경로를 확인하세요.
npm config get prefix
출력된 경로의 bin 폴더(Windows는 루트 폴더)가 시스템 PATH에 포함돼 있는지 확인합니다. PATH 설정이 어렵다면 npx로 실행하는 방법도 있습니다.
npx @anthropic-ai/claude-code
🚫 "Invalid API key" 에러
API 키가 잘못 입력됐거나 환경 변수가 설정되지 않은 경우입니다. 아래 명령어로 환경 변수가 설정돼 있는지 확인하세요.
macOS / Linux:
echo $ANTHROPIC_API_KEY
Windows (PowerShell):
echo $env:ANTHROPIC_API_KEY
아무것도 출력되지 않으면 환경 변수가 설정되지 않은 것입니다. 위의 "API 키 설정" 섹션을 다시 따라하세요. 키를 복사할 때 앞뒤 공백이 포함되지 않았는지도 확인하세요.
🚫 "EACCES permission denied" 에러 (macOS)
전역 설치 시 권한 문제입니다. sudo를 앞에 붙여서 실행하세요.
sudo npm install -g @anthropic-ai/claude-code
🚫 Claude가 파일을 수정하지 않음
Claude Code는 보안을 위해 파일 수정 전에 반드시 사용자 확인을 요청합니다. 권한 요청이 나타나면 "y"를 입력해야 합니다. 권한 요청 없이 아무 일도 일어나지 않는다면 프롬프트를 더 구체적으로 작성해보세요.
🚫 API 비용이 걱정됨
Anthropic 콘솔의 "Billing" 페이지에서 사용량 한도를 설정하세요. 한도에 도달하면 API가 자동으로 중단되므로 예상치 못한 과금이 발생하지 않습니다. 일반적인 바이브코딩 입문 단계에서는 월 $5 이내로 사용하는 경우가 많습니다.
💡 Claude Code를 더 잘 쓰는 팁
📌 한 번에 하나씩 요청하기
"웹사이트 전체를 만들어줘"보다 "먼저 메인 페이지 레이아웃을 만들어줘"처럼 단계별로 요청하면 결과가 더 정확합니다. 한 단계가 끝나면 결과를 확인하고 다음 단계를 요청하세요.
📌 에러 메시지를 그대로 전달하기
개발 중 에러가 발생하면 에러 메시지를 그대로 Claude에게 붙여넣으세요. "에러가 났어"보다 에러 메시지 전체를 보여주는 것이 훨씬 정확한 해결 방법을 얻을 수 있습니다.
📌 /help 명령어 활용하기
Claude Code에서 /help를 입력하면 사용 가능한 명령어 목록을 볼 수 있습니다. /clear로 대화 초기화, /cost로 현재 세션의 API 비용 확인 등 유용한 명령어가 있습니다.
📌 CLAUDE.md 파일 활용하기
프로젝트 루트에 CLAUDE.md 파일을 만들고, 프로젝트 규칙이나 선호하는 코딩 스타일을 적어두면 Claude가 이를 참고해서 코드를 생성합니다. 예를 들어 "한국어 주석 사용", "함수형 컴포넌트만 사용" 같은 규칙을 적어두면 일관된 코드를 얻을 수 있습니다.
🔄 Cursor와 Claude Code 함께 사용하기
Cursor와 Claude Code는 경쟁 도구가 아니라 함께 사용할 수 있습니다. Claude Code로 프로젝트 구조를 만들고 큰 기능을 구현한 뒤, Cursor에서 세부 코드를 수정하는 방식이 효율적입니다.
| 작업 | 추천 도구 |
|---|---|
| 프로젝트 생성 및 구조 설계 | Claude Code |
| 대규모 기능 구현 | Claude Code |
| 특정 파일 세부 수정 | Cursor |
| 코드 리뷰 및 설명 | 둘 다 가능 |
| 에러 디버깅 | 둘 다 가능 |
두 도구의 자세한 비교는 다음 글에서 다룰 예정입니다.
⚡ 한 번에 끝내기: VibeStart 활용
Node.js와 Git 설치가 아직 안 됐다면 VibeStart를 이용해보세요. 운영체제에 맞는 설치 명령어를 단계별로 안내합니다. 개발 환경이 준비된 뒤에 Claude Code를 설치하면 바로 바이브코딩을 시작할 수 있습니다.
🔗 관련 글
- 바이브코딩 시작 전 개발환경 세팅 완벽 가이드
- Cursor 설치 방법과 첫 프로젝트 만들기
- Node.js 설치부터 바이브코딩 시작까지 3단계
- 터미널 처음 사용하는 비전공자를 위한 가이드
- 바이브코딩에 Git이 필요한 이유 + 5분 설치 가이드