Claude Code 시작하기: 설치부터 첫 커밋까지 30분 완성

터미널에 claude라고 치고 엔터를 누른다.

그것만으로 뭔가가 돌아가기 시작한다는 건 압니다. 그런데 제가 처음 해봤을 때 화면에 뜬 건 “로그인하세요” 한 줄이었고, 거기서 5분쯤 얼어붙었습니다. 어디에 로그인하라는 거지? 돈 나가나? 내 코드를 통째로 읽어가는 거 아냐? 결국 그날은 아무것도 못 건드리고 그냥 창을 닫았습니다.

지금 돌아보면, 첫 번째 벽은 설치도 영어도 아니었습니다. “실행한 다음에 뭘 시켜야 하지?”였죠. 그래서 이 글에서는 거기를 최단 거리로 넘어갑니다. 설치 → 브라우저 로그인 → 첫 프롬프트 → 첫 커밋, 여기까지를 30분에. 중간에 제가 걸려 넘어진 세 가지(권한 전체 허용, 대화가 무거워지는 현상, CLAUDE.md의 첫 한 줄)도 미리 깔아둘 테니 같이 피해 가시면 됩니다.

검색 의도는 단순합니다. “Claude Code 시작하기”, “사용법 입문”. 그 답만, 곁길로 새지 않고 적겠습니다.

핵심 요약

• 설치는 공식 설치 스크립트 한 방. macOS/Linux는 curl ... | bash, Windows는 irm ... | iex. Node.js로 넣고 싶으면 npm i -g @anthropic-ai/claude-code(Node 18 이상).
• 인증은 브라우저. claude를 실행하면 로그인 화면으로 넘어갑니다. Claude Pro/Max 같은 구독이나 Console 계정이 필요합니다(무료 Claude.ai 플랜은 대상 아님).
• 첫 30분은 “수정시키지 않기”. 읽히기 → 설명시키기 → 파일 한 개만 리뷰, 순서로 익숙해집니다.
• 첫 커밋까지 가야 끝. 변경 내용(diff)을 내 눈으로 확인하고 나서 커밋하는 습관을, 첫날에 들입니다.
• 입문자가 밟기 쉬운 지뢰는 셋. 권한을 전부 허용하지 않기 / 대화가 무거워지면 압축하기 / CLAUDE.md에 “테스트 돌리는 법”을 한 줄 적기.

순서대로 가겠습니다. 코드는 전부 복사해서 바로 돌아가는 것만 싣습니다.

먼저 전체 그림: 30분짜리 지도

세세한 절차로 들어가기 전에, 목표까지의 지도를 먼저 보여드릴게요. 길을 잃지 않습니다.

시간	할 일	목적
0–5분	설치 + 브라우저 로그인	claude가 실행되는 상태 만들기
5–10분	연습용 브랜치 따기	실패해도 되돌릴 수 있는 토대 만들기
10–20분	읽히기·설명시키기	”무엇을 근거로 답하는지” 감 잡기
20–25분	작은 변경 하나 시키기	편집 → diff 확인 흐름 체험하기
25–30분	첫 커밋	내 판단으로 확정하는 습관 들이기

핵심은 첫날에 큰 리팩터링을 하지 않는 것입니다. “이 프로젝트 좀 깔끔하게 정리해줘” 같은 요청은 익숙해진 뒤에 해도 충분합니다. 처음엔 작게, 되돌릴 수 있는 범위에서.

1단계: 설치하기 (0–3분)

얼마 전까지는 “npm으로 설치”가 정석이었지만, 지금 공식이 가장 먼저 권하는 건 전용 설치 스크립트입니다. Node.js가 있든 없든 신경 쓸 필요 없이 들어갑니다.

macOS / Linux / WSL이라면 이거.

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell이라면 이거.

irm https://claude.ai/install.ps1 | iex

“나는 Node.js로 관리하고 싶다”는 분은 예전처럼 npm으로도 들어갑니다. Node.js 18 이상이 필요합니다.

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

설치됐는지 확인합니다. 버전 번호가 뜨면 OK.

claude --version

여기서 command not found가 뜨면 claude doctor가 원인을 알려줍니다.

claude doctor

한 가지만 주의. 권한 오류가 떠도 반사적으로 sudo npm install -g를 하지 마세요. 공식 문서도 “권한 문제나 보안 위험으로 이어지니 피하라”고 명시하고 있습니다. 당황하지 말고 claude doctor가 안내하는 대로 따라가는 편이 빠릅니다.

2단계: 브라우저로 로그인하기 (3–5분)

설치가 끝났으면 실행합니다.

claude

처음 실행하면 자동으로 로그인 화면으로 넘어갑니다. 브라우저가 열리니 화면 안내에 따라 로그인만 하면 됩니다. 한 번 통과하면 인증 정보가 저장돼서, 다음부터는 묻지 않습니다.

여기서 입문자가 자주 멈추는 게 “그래서 어떤 계정?”입니다. 정리하면 이렇습니다.

• Claude Pro / Max / Team / Enterprise 구독 … 개인으로 시작한다면 이게 제일 편합니다(추천).
• Anthropic Console(API·선불 크레딧) … API 키 운영이나 비용을 한곳에서 관리하고 싶은 사람용.
• Amazon Bedrock / Google Vertex AI / Microsoft Foundry … 회사 클라우드 방침이 정해져 있는 경우.

주의 하나. 무료 Claude.ai 플랜으로는 Claude Code를 쓸 수 없습니다. 이걸 모르고 “로그인이 안 된다”며 고민하는 사람이 많아서 먼저 적어둡니다.

계정을 바꾸고 싶어지면, 실행 중인 세션에서 /login이라고 치면 다시 인증할 수 있습니다.

3단계: 실패해도 되돌릴 곳 만들기 (5–10분)

여기가 수수하지만 중요합니다. 처음부터 실서비스 저장소에서 놀지 마세요. 연습용 작은 저장소나, 망가져도 곤란하지 않은 개인 프로젝트를 엽니다.

업무 코드로 시험해본다면 반드시 작업 브랜치를 땁니다.

git status
git switch -c try-claude-code

맨 처음 git status를 보는 건, 커밋 안 된 변경을 휩쓸어 넣지 않기 위해서입니다. 변경 전 상태가 애매한 채로 쓰기 시작하면, 나중에 “이거 AI가 만든 diff야? 내가 만든 diff야?”가 구분이 안 됩니다. 이거, 첫날의 제가 진짜로 저질렀던 일입니다.

그 폴더에서 Claude Code를 실행합니다.

cd /path/to/your/project
claude

실행하면 상단에 버전·사용 중인 모델·작업 디렉터리가 표시됩니다. /help로 명령어 목록을 볼 수 있습니다.

4단계: 일단 “읽히기”만 (10–20분)

여기서부터가 본 게임입니다. 그래도 아직 수정은 안 시킵니다. 처음엔 읽히고, 설명시킨다. 이것만으로 “Claude Code가 무엇을 근거로 답하는지”에 대한 감이 잡힙니다.

대화 모드에서는 자연스러운 한국어로 말 걸기만 하면 됩니다. 어려운 문법은 필요 없습니다.

README.md와 package.json만 읽고, 이 프로젝트의 목적과 실행 방법을 한국어로 설명해줘

핵심은 “~만 읽고”라고 범위를 좁히는 것입니다. 입문 단계에서 파일을 잔뜩 읽기 시작하면, 답이 어디서 나온 건지 따라갈 수가 없게 됩니다. 이건 뒤에서 설명할 “대화가 무거워지는” 문제와도 직결됩니다.

익숙해지면 파일 한 개만 리뷰를 시킵니다.

src/utils/date.ts만 읽고, 버그가 될 만한 지점을 3개 이내로 짚어줘. 아직 수정은 하지 마

“아직 수정은 하지 마”를 붙이면 리뷰와 구현이 섞이지 않습니다. 제안을 읽는 연습이 먼저고, 손을 대는 건 그다음입니다.

참고로, 조사나 정형 작업을 딱 한 번만 후딱 돌리고 싶을 때는 대화 모드로 들어가지 않고 원샷이 편합니다. -p를 붙이면 결과를 돌려주고 종료합니다.

claude -p "git log --oneline -10 을 실행하고, 변경 내용을 한국어로 요약해줘"

제 구분 기준은 단순합니다. 시행착오하는 구현은 대화 모드, 조사·요약은 원샷. 처음엔 이 둘만 외워도 충분합니다.

5단계: 첫 작은 변경 (20–25분)

읽는 연습이 됐으면, 드디어 수정을 맡깁니다. 처음엔 “파일 한 개·함수 하나” 단위로.

대화 모드에서 이렇게 부탁합니다.

src/api/users.ts 의 getUserById 함수에 유닛 테스트를 하나 추가해줘. 기존 테스트 작성 방식에 맞춰서

여기서 Claude Code는 반드시 “이 변경을 적용해도 될까?”라고 확인합니다. 파일을 멋대로 고쳐 쓰는 일은 없습니다. 제안된 diff를 보고, 납득하면 승인한다. 이게 기본 안전장치입니다.

첫 지뢰가 여기 있습니다. 확인할 때마다 엔터를 누르는 게 귀찮아서, 저는 일찌감치 “전부 허용” 모드로 바꿨습니다. 그랬더니 부탁하지도 않은 파일까지 “겸사겸사 정리”되어서 얼굴이 새파래졌죠. 처음엔 하나씩 승인하는 게 결국 제일 빠르다, 이게 교훈입니다. 권한을 세세하게 정하고 싶어지면 뒤에 따로 소개하는 글로 넘어가세요.

변경을 받아들였으면, 반드시 내 눈으로 diff를 확인합니다.

git diff
npm test

“동작하는 것처럼 보인다”와 “의도한 diff만 들어 있다”는 다른 이야기입니다. diff와 테스트는 세트로 묶으세요.

6단계: 첫 커밋 (25–30분)

diff를 확인했고, 테스트가 통과했다. 여기까지 왔으면 결승선이 코앞입니다.

커밋도 자연스러운 말로 부탁할 수 있습니다.

변경 내용을 확인하고, 알기 쉬운 커밋 메시지로 commit 해줘

Claude Code는 git diff를 읽고 메시지를 생각해서, 커밋 전에 한 번 더 확인을 띄웁니다. 물론 직접 손으로 쳐도 됩니다.

git add src/api/users.ts
git commit -m "test: getUserById 유닛 테스트 추가"

이걸로 “설치 → 로그인 → 읽히기 → 작게 바꾸기 → 커밋”이 한 바퀴 돌았습니다. 30분 만에 Claude Code의 최소 루프를 내 손으로 돌린 셈입니다. 첫날은 여기까지면 충분합니다. 당당하게 창 닫으세요.

복붙으로 돌아가는: 30분을 한 본으로 묶은 시작 스크립트

매번 명령어를 떠올리는 게 귀찮아서, 저는 “연습 세션을 안전하게 시작하는” 셸 스크립트를 하나 놔두고 씁니다. 브랜치를 따고, 읽히는 요청까지 한 번에 처리합니다. Node.js 필요 없이 bash만으로 돌아갑니다.

#!/usr/bin/env bash
# start-claude-practice.sh — Claude Code 를 안전하게 연습 시작한다
set -euo pipefail

# 1) 커밋 안 된 변경이 남아 있지 않은지 확인 (휩쓸림 사고 방지)
if [ -n "$(git status --porcelain)" ]; then
  echo "[주의] 커밋 안 된 변경이 있습니다. 먼저 commit 하거나 stash 하세요."
  git status --short
  exit 1
fi

# 2) 연습용 브랜치 따기 (날짜 포함. 이미 있으면 전환만)
BRANCH="try-claude-$(date +%Y%m%d)"
git switch -c "$BRANCH" 2>/dev/null || git switch "$BRANCH"
echo "[완료] 브랜치 $BRANCH 에서 작업합니다"

# 3) 일단 "읽히기만" 하는 요청을 원샷으로 실행
claude -p "README 가 있으면 README 를, 없으면 주요 파일을 읽고,
이 프로젝트의 목적·실행 방법·다음에 읽어야 할 파일을 한국어로 3줄로 설명해줘.
편집은 절대 하지 말 것."

쓰는 법은 이게 다입니다.

chmod +x start-claude-practice.sh
./start-claude-practice.sh

실행하면, 커밋 안 된 변경이 있으면 멈춰주고, 없으면 연습 브랜치를 따서 프로젝트 요약을 내줍니다. “휩쓸림 사고 방지”, “되돌릴 곳 만들기”, “일단 읽히기”를 한 본으로 묶은 것입니다. 첫날의 저에게 쥐여주고 싶었던 스크립트네요.

제가 처음에 걸려 넘어진 세 가지

여기서부터는 매뉴얼에는 잘 안 실리지만, 첫날에 빠지면 제일 괴로운 것들입니다.

1. 권한을 처음부터 전부 허용해 버린다

앞에서도 적었듯, 확인이 귀찮다고 “전부 OK”로 해두면 사고가 납니다. 처음엔 쓰기와 커밋은 매번 확인, 삭제나 force push는 금지 상태로 쓰는 게 안전합니다. .claude/settings.json에서 이렇게 정해둘 수 있습니다.

{
  "permissions": {
    "allow": ["Read(**)", "Grep(**)", "Bash(npm test*)", "Bash(git status*)", "Bash(git diff*)"],
    "ask": ["Write(**)", "Edit(**)", "Bash(git commit*)", "Bash(git push*)"],
    "deny": ["Bash(rm -rf*)", "Bash(git push --force*)"]
  }
}

“읽기·테스트는 자동, 쓰기·커밋은 확인, 위험한 삭제는 금지.” 이 3단 구성만으로 대부분의 사고는 막을 수 있습니다. 익숙해지고 안전하다고 확인된 동작을, 나중에 allow로 승격시켜 가면 됩니다. 세세한 설계는 Claude Code 권한 설정 가이드에 정리해 뒀으니, 제대로 파고들 거면 그쪽으로.

2. 대화가 무거워진다 (컨텍스트 압박)

쓰다 보면 어느 순간부터 갑자기 굼떠집니다. 이건 고장이 아니라, 대화가 길어져서 Claude Code가 안고 있는 “맥락”이 너무 부풀어 올랐다는 신호입니다. 요리하는 도중에 조리대가 쓴 그릇들로 차오르는 것과 똑같죠.

대처는 두 가지. 일단락이 지어지면 대화를 압축하거나, 아예 깨끗이 비웁니다.

/compact

/clear

/compact는 요점만 남기고 압축, /clear는 통째로 리셋입니다. “방금까지 쌩쌩했는데” 싶으면 망설이지 말고 둘 중 하나를. 맨 앞에서 적은 “읽히는 범위를 좁게”도 여기에 효과를 발휘합니다. 쓸데없는 파일을 안 읽힐수록 조리대는 덜 어질러집니다. 무거움의 원인 분리는 Claude Code 속도 최적화 가이드에 자세합니다.

3. CLAUDE.md의 첫 한 줄을 안 적는다

이건 “해두길 잘했다” 계열의 이야기입니다. Claude Code는 프로젝트 루트의 CLAUDE.md를 자동으로 읽습니다. 여기에 프로젝트 정보를 적어두면 매번 설명할 필요가 없습니다.

제가 후회하는 건, 처음에 이걸 안 적었다는 점입니다. 매번 “이 프로젝트는 TypeScript고, 테스트는 npm test야”라고 설명하는 신세가 됐죠. 처음에 적어야 할 딱 한 줄은 이겁니다.

## 자주 쓰는 명령어
- 테스트: npm test
- 개발 서버: npm run dev

“테스트 돌리는 법”만 적어두면, Claude Code는 변경 후에 스스로 테스트를 돌리려고 합니다. 반대로 처음부터 장황한 CLAUDE.md를 적으면, 이번엔 지시가 잘 안 지켜집니다. 무엇을 적고 무엇을 안 적을지, 그 선 긋기는 CLAUDE.md 베스트 프랙티스에 따로 적었습니다.

다음 한 걸음: 단발 작업에서 “맡기기”로

30분 루프에 익숙해졌다면, 다음은 “단발 지시”에서 “어느 정도 묶음 작업을 맡기는” 단계입니다. 그렇다고 단번에 완전 자동으로 가지는 않습니다.

순서는 늘 같습니다. ① 읽히는 범위를 좁게 정한다 → ② 목표(결과물)를 분명히 한다 → ③ 확인은 가능한 한 명령어에 시킨다 → ④ 위험한 동작은 처음엔 전부 “사람에게 묻기”로. 이렇게 AI의 “발판”을 다지는 사고방식을, 저는 AI에게 일을 맡기는 발판(하네스) 만드는 법에 자세히 정리해 뒀습니다. 입문 다음으로 읽으면 풍경이 확 달라질 겁니다.

지시를 내리는 방식도, 익숙해지면 결과가 달라집니다. 요령은 세 가지뿐.

1. 파일명(가능하면 줄 번호)을 적기 — 탐색 수고가 줄어듭니다.
2. 기대하는 동작을 구체적으로 — “알아서 잘”은 안 통합니다.
3. 제약을 덧붙이기 — “기존 패턴에 맞춰서”, “다른 파일은 건드리지 마”.

src/api/auth.ts 의 login 함수에, 비밀번호가 비어 있을 때 400 을 반환하는 처리를 추가해줘.
에러 문구는 src/utils/errors.ts 의 패턴에 맞춰서. 다른 파일은 건드리지 마

자주 묻는 질문

Q. 무료로 쓸 수 있나요? A. Claude Code 자체는 무료 Claude.ai 플랜으로는 쓸 수 없습니다. Claude Pro / Max 같은 구독이나, 선불 크레딧이 있는 Console 계정이 필요합니다. 비용이 신경 쓰인다면 Claude Code/API 비용 관리 가이드에 예산 정하는 법을 적어 뒀습니다.

Q. Windows에서도 Mac과 똑같이 작동하나요? A. 작동합니다. 설치만 irm https://claude.ai/install.ps1 | iex(PowerShell)로 바뀔 뿐, 실행도 사용법도 같습니다. Git Bash를 깔아두면 일부 명령 실행이 더 매끄러워집니다.

Q. API 키가 필요한가요? A. 개인으로 시작한다면 필요 없습니다. claude를 실행해서 브라우저로 로그인하는 게 제일 편합니다. API 키를 환경 변수로 다루는 구성은, 팀의 인증 방침이나 클라우드 환경이 정해지고 나서 해도 충분합니다.

Q. 제 코드가 통째로 업로드되지는 않나요? A. Claude Code는 필요한 파일만 그때그때 읽습니다. 손으로 전부 넘길 필요도 없고, .env나 실서비스 키·고객 데이터는 붙여넣지 않는 게 기본입니다. 안전 면의 최저선은 Claude Code 보안 베스트 프랙티스에 정리해 뒀습니다.

Q. 기본 모델이 무겁고 비싼 것 같아요. A. 단순한 작업이라면 세션 도중에 가벼운 모델로 바꿀 수 있습니다. /model로 모델을 고를 수 있으니, 조사는 경량 모델, 어려운 구현은 고성능 모델로 나눠 쓰면 쾌적합니다.

정리: 30분에 “최소 루프”를 한 바퀴 돈다

Claude Code 시작하기는, 결국 한 줄로 꿰입니다. 설치 → 브라우저 로그인 → 읽히기 → 작게 바꾸기 → diff 보고 커밋. 이 30분 루프를 한 번 내 손으로 돌리고 나면, “뭐부터 시작해야 할지 모르겠다”는 사라집니다.

첫날에 저지르기 쉬운 건 셋뿐입니다. 권한을 전부 허용하지 않기, 대화가 무거워지면 압축하기, CLAUDE.md에 “테스트 돌리는 법”을 한 줄 적기. 이것만 피하면 첫 경험이 한결 매끄러워집니다.

이 사이트(claudecode-lab.com)는 글 생성도 번역도 배포도 Claude Code로 매일 돌리고 있습니다. 처음엔 “진짜 그런 게 돼?” 하고 의심하던 저인데도 말이죠. 여러분도 오늘, 일단 30분. claude라고 치고, 첫 커밋까지 가보세요.

다음에 막히면, 막힌 방식에 따라 다음 갈 곳을 고르면 됩니다. 명령어나 안전하게 부탁하는 법을 손에서 바로 보고 싶다면 무료 Claude Code 치트시트, 설정과 운영까지 한꺼번에 갖추고 싶다면 교재 목록이 지름길입니다.

최신 절차는 공식 Claude Code Quickstart(영어)에서도 확인할 수 있습니다. 설치나 인증은 갱신되는 경우가 있으니, 헷갈리면 1차 정보를 보세요.

이 글에서 소개한 내용을 실제로 시험해본 결과

이 30분 루프를, 지인인 프런트엔드 엔지니어(CLI에 익숙하지 않은 사람)에게 옆에서 시험해보게 했습니다. 가장 효과가 컸던 건 “처음엔 수정시키지 않기”였습니다. 읽히고 설명시키는 단계를 건너뛰면, 첫 편집 제안 앞에서 얼어붙어 버립니다. 반대로 설명 → 파일 한 개 리뷰를 사이에 끼운 사람은, 첫 커밋까지 정말 30분이 채 안 걸렸습니다.

또 하나 실감한 건, CLAUDE.md의 “테스트 한 줄”이 주는 효과입니다. 이걸 적어둔 상태면, 변경 후에 Claude Code가 알아서 npm test를 돌리고, 스스로 실패를 알아채서 고치기 시작합니다. 안 적어두면 이쪽이 매번 “테스트해줘”라고 말하는 신세가 되죠. 고작 두 줄의 차이가, 그 뒤의 왕복 횟수를 확실히 줄였습니다. 똑똑한 모델을 찾기 전에, 발판을 하나 다지기 — 입문이라도, 결국 거기가 제일 효과적입니다.