Claude Code 완전 입문: 비전공자를 위한 첫 프로젝트 실습 가이드

Claude Code가 뭔가요?

Claude Code는 Anthropic이 만든 AI 코딩 어시스턴트입니다. 터미널(명령 프롬프트)에서 자연어로 대화하듯 지시를 내리면, AI가 코드를 직접 작성하고 수정하고 실행까지 해줍니다. 기존 코파일럿이나 ChatGPT와 다른 점은 파일 시스템에 직접 접근한다는 겁니다. “이 폴더에 있는 파일들을 정리해줘”라고 하면 실제로 그렇게 합니다.

바이브 코딩(Vibe Coding)이란 개념 자체가 이런 AI 도구를 활용해서 코딩의 느낌과 흐름을 타며 개발하는 방식입니다. 완벽하게 문법을 외우지 않아도, 내가 원하는 것을 말로 설명하면 AI가 구체화해줍니다. 비전공자에게 특히 강력한 이유가 바로 이것입니다.

설치 방법 — Node.js부터 Claude Code까지

1. Node.js 설치

Claude Code는 Node.js 환경에서 실행됩니다. 먼저 Node.js 공식 사이트(nodejs.org)에서 LTS 버전을 내려받아 설치하세요. 설치 후 터미널에서 버전을 확인합니다.

node --version
# v20.x.x 이상이면 정상

2. Claude Code 설치

Node.js 설치가 완료되면 npm을 통해 Claude Code를 전역 설치합니다.

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

설치 후 버전 확인:

claude --version

3. API 키 설정

Anthropic Console(console.anthropic.com)에서 API 키를 발급받아야 합니다. 가입 후 API Keys 메뉴에서 새 키를 생성합니다. 생성된 키는 한 번만 표시되니 반드시 복사해두세요.

환경 변수로 등록하는 방법(Mac/Linux):

export ANTHROPIC_API_KEY="sk-ant-여기에본인키입력"

매번 설정하기 번거롭다면 홈 디렉터리의 셸 설정 파일에 추가합니다.

# Mac의 경우 ~/.zshrc 파일 끝에 추가
echo 'export ANTHROPIC_API_KEY="sk-ant-여기에본인키입력"' >> ~/.zshrc
source ~/.zshrc

Windows 사용자는 시스템 환경 변수 편집에서 ANTHROPIC_API_KEY를 추가하면 됩니다.

처음 실행 — 프로젝트 폴더 만들기

설치가 끝났으면 실제로 프로젝트를 시작해봅시다. 터미널을 열고 원하는 위치에 폴더를 만들고 이동합니다.

mkdir my-first-project
cd my-first-project

이제 Claude Code를 실행합니다.

claude

처음 실행 시 약관 동의와 간단한 초기 설정 화면이 나옵니다. 안내에 따라 진행하면 됩니다. 설정이 끝나면 프롬프트가 뜨고, 여기서부터 AI와 대화를 시작합니다.

기본 명령어 파악

Claude Code 안에서 자주 쓰는 명령어입니다.

/help         # 사용 가능한 명령어 목록
/status       # 현재 세션 상태 확인
/clear        # 대화 기록 초기화
/exit         # 종료 (또는 Ctrl+C)

실전 실습 — 간단한 웹페이지 만들기

이제 실제로 뭔가를 만들어봅시다. Claude Code 프롬프트에서 다음과 같이 입력합니다.

안녕하세요, 라는 텍스트가 가운데 표시되고 배경이 하늘색인 HTML 페이지를 index.html로 만들어줘

Claude Code가 즉시 index.html 파일을 현재 폴더에 생성합니다. 파일을 열어보면 실제로 동작하는 HTML이 들어 있습니다. 생성된 파일을 브라우저에서 확인하고 싶다면 파일 탐색기에서 더블클릭하거나, 터미널에서 다음 명령어를 씁니다.

# Mac
open index.html

# Windows
start index.html

파일 수정 요청

이번에는 만들어진 파일을 수정해달라고 해봅니다.

index.html에 버튼을 추가하고, 버튼을 클릭하면 "반갑습니다!"라는 알림창이 뜨게 해줘

Claude Code가 기존 파일을 읽고 수정합니다. 변경 내용도 요약해서 보여줍니다. 브라우저를 새로고침하면 버튼이 추가된 것을 확인할 수 있습니다.

여러 파일 다루기

프로젝트가 커지면 여러 파일을 동시에 다뤄야 합니다. Claude Code는 폴더 구조 전체를 컨텍스트로 이해합니다.

이 프로젝트에 CSS를 분리해서 style.css 파일로 만들고, index.html이 그걸 참조하도록 해줘

결과적으로 style.css가 생성되고 index.html은 이 파일을 링크하도록 자동 수정됩니다.

오류 수정 요청

코드가 예상대로 동작하지 않을 때는 오류 메시지를 그대로 붙여넣으면 됩니다.

콘솔에 이런 오류가 나와: "Uncaught ReferenceError: handleClick is not defined"
어디가 문제야?

Claude Code가 관련 파일을 스캔하고 원인을 찾아 수정안을 제시합니다.

비전공자가 자주 막히는 포인트 & 해결법

포인트 1: “permission denied” 오류

npm install 시 권한 오류가 발생하면 Mac/Linux에서는 앞에 sudo를 붙입니다.

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

관리자 비밀번호를 묻는데, 입력 시 화면에 아무것도 표시되지 않는 게 정상입니다. 그냥 입력하고 엔터를 누르면 됩니다.

포인트 2: API 키 오류 (Invalid API Key)

환경 변수가 제대로 설정됐는지 확인합니다.

echo $ANTHROPIC_API_KEY

아무것도 출력되지 않으면 설정이 안 된 것입니다. 터미널을 껐다 켜거나 source ~/.zshrc를 다시 실행해보세요.

포인트 3: Claude Code가 잘못된 파일을 수정함

Claude Code는 현재 폴더 기준으로 작동합니다. pwd 명령어로 현재 위치를 확인하고, 올바른 프로젝트 폴더 안에 있는지 체크하세요.

pwd
# /Users/yourname/my-first-project 처럼 표시되어야 함

포인트 4: 한국어로 요청해도 되나요?

네, 됩니다. Claude Code는 한국어 명령을 잘 이해합니다. 영어로 할 필요 없습니다. 다만 코드 주석이나 변수명은 영어를 권장합니다. 나중에 다른 도구와 호환성 문제가 생길 수 있기 때문입니다.

포인트 5: 생성된 코드를 이해 못해도 되나요?

바이브 코딩의 핵심 질문입니다. 처음에는 이해 없이 써도 됩니다. 단, 점점 흐름을 파악하려고 노력하세요. Claude Code에게 “이 코드가 왜 이렇게 작동하는 거야?”라고 물으면 설명해줍니다. 바이브 코딩은 게으른 방법이 아니라 학습 속도를 높이는 방법입니다.

Q&A

Q. Claude Code는 유료인가요?

Claude Code 자체는 무료로 설치할 수 있습니다. 다만 실행할 때 Anthropic API를 사용하므로 사용량에 따라 요금이 발생합니다. 처음 가입하면 무료 크레딧이 제공됩니다. 가벼운 실습 수준이라면 초기 크레딧으로 충분히 연습할 수 있습니다.

Q. Windows에서도 잘 작동하나요?

네, 작동합니다. 단 Windows 사용자는 PowerShell이나 WSL(Windows Subsystem for Linux)을 사용하는 것을 권장합니다. 일반 명령 프롬프트(cmd)에서는 일부 명령어가 다르게 동작할 수 있습니다. WSL2 설치 후 Ubuntu를 사용하면 Mac/Linux와 거의 동일한 환경을 쓸 수 있습니다.

Q. 프로그래밍을 전혀 모르는데 바로 쓸 수 있나요?

기본 개념(파일, 폴더, 터미널이 뭔지)만 알면 시작할 수 있습니다. 코딩 문법은 몰라도 됩니다. 중요한 건 내가 만들고 싶은 것을 구체적으로 설명하는 능력입니다. “예쁜 사이트”보다 “흰 배경에 검은 텍스트, 상단에 네비게이션 메뉴가 있고 메뉴 항목은 홈, 소개, 연락처인 사이트”처럼 구체적으로 말할수록 좋은 결과가 나옵니다.

Q. 생성된 코드에서 보안 문제가 생길 수 있나요?

AI가 생성한 코드도 보안 취약점을 가질 수 있습니다. 특히 사용자 입력을 받는 기능(로그인, 폼 등)이 포함된 경우 반드시 보안 전문가의 검토가 필요합니다. 단순한 정적 페이지나 내부용 도구라면 크게 걱정하지 않아도 됩니다.

Q. AntiGravity와 Claude Code의 차이는 뭔가요?

Claude Code는 터미널 기반 AI 코딩 어시스턴트이고, AntiGravity는 노코드/로우코드 방식으로 앱을 만드는 플랫폼입니다. Claude Code는 자유도가 높고 복잡한 프로젝트에 적합하며, AntiGravity는 빠른 프로토타입이나 드래그앤드롭 방식의 구현에 강점이 있습니다. 둘을 함께 쓰면 시너지가 납니다.

오늘 5분 실습

오늘 배운 내용을 바로 적용해봅시다. 딱 5분만 투자하면 됩니다.

터미널을 열고 mkdir vibe-test && cd vibe-test 입력
claude 실행
다음 문장 입력: “내 이름과 좋아하는 음식을 보여주는 HTML 페이지를 만들어줘. 배경은 연한 노란색으로”
생성된 index.html을 브라우저에서 열어 확인
이번엔 “버튼을 하나 추가하고 클릭하면 좋아하는 음식이 바뀌도록 해줘”라고 수정 요청

5분이면 충분합니다. 직접 해봐야 손에 익습니다.

미래이음연구소 바이브 코딩 교육

이신우 소장이 이끄는 미래이음연구소에서 Claude Code, AntiGravity 등 최신 바이브 코딩 도구 실전 강의를 진행합니다.
강의 문의: 010-3343-4000 | lab.duonedu.net

마무리

Claude Code는 비전공자에게 코딩의 문턱을 낮춰주는 강력한 도구입니다. 오늘 다룬 내용을 정리하면, 설치는 Node.js와 npm 두 단계면 끝이고, 실행은 프로젝트 폴더 안에서 claude 명령 하나입니다. 이후로는 자연어로 원하는 것을 요청하면 됩니다.

바이브 코딩은 완성된 결과물을 AI가 대신 만들어주는 게 아닙니다. 인간의 아이디어와 방향성을 AI가 빠르게 구현해주는 협업입니다. 아이디어를 구체화하고, 설명하고, 결과를 검토하는 능력이 앞으로 가장 중요한 기술이 됩니다.

더 깊은 실습과 체계적인 교육은 미래이음연구소(lab.duonedu.net)에서, 교육 관련 출판 콘텐츠는 두온교육(main.duonedu.net)에서 확인하세요.