시작하기 - 설치부터 첫 대화까지

이 장에서 배우는 것

Claude Code가 무엇인지
설치 및 API 설정
기본 명령어와 사용법
막혔을 때 스스로 해결하는 방법

Claude Code란?

터미널에서 동작하는 AI 코딩 어시스턴트입니다.

Anthropic이 공식 제공하는 CLI(Command Line Interface) 도구로, 단순한 챗봇이 아니라 실제 파일을 읽고 쓰고, 명령어를 실행할 수 있습니다.

일반 AI 챗봇과의 차이

일반 AI 챗봇	Claude Code
웹 브라우저에서 대화	터미널에서 직접 작업
파일을 업로드해서 분석	프로젝트 폴더 전체를 이해
결과물을 복사-붙여넣기	파일을 직접 생성/수정
매번 맥락을 설명	CLAUDE.md로 맥락 유지
일회성 대화	스킬로 반복 작업 자동화

비개발자도 쓸 수 있나요?

네. 이 과정은 개발자가 아닌 분들을 위해 설계되었습니다.

터미널 기초만 알면 됨 (cd, ls 정도)
코드를 직접 작성할 필요 없음
막히면 해결하는 방법도 함께 안내

설치하기

사전 준비: Node.js

Claude Code는 Node.js 환경에서 실행됩니다.

Mac (Homebrew)

brew install node

Windows

nodejs.org 접속
LTS 버전 다운로드 (v18 이상)
설치 파일 실행

설치 확인

node --version
# v18.x.x 이상이면 OK

npm --version
# 9.x.x 이상이면 OK

Claude Code 설치

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

설치 확인

claude --version

참고: 공식 레포지토리 anthropics/claude-code

API 키 설정

Claude Code는 Anthropic API를 사용합니다.

1단계: API 키 발급

console.anthropic.com 접속
계정 생성 또는 로그인
API Keys 메뉴로 이동
Create Key 클릭
키 이름 입력 (예: “claude-code”)
생성된 키 복사 (sk-ant-... 형식)

주의: 키는 한 번만 표시됩니다. 안전한 곳에 저장하세요.

2단계: 환경변수 설정

Mac/Linux (일회성)

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Mac/Linux (영구 설정)

# zsh 사용자 (Mac 기본)
echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.zshrc
source ~/.zshrc

# bash 사용자
echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell)

$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"

Windows (영구 설정)

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-your-key-here", "User")

3단계: 설정 확인

echo $ANTHROPIC_API_KEY
# sk-ant-... 형태로 출력되면 성공

GitHub 환경 구성 (권장)

Claude Code를 효과적으로 사용하려면 GitHub 환경을 설정하는 것이 좋습니다.

Git 설치 확인

git --version
# git version 2.x.x 이상이면 OK

Mac: Xcode Command Line Tools와 함께 설치됨 Windows: git-scm.com에서 다운로드

Git 기본 설정

# 사용자 정보 설정 (필수)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 기본 브랜치 이름 설정
git config --global init.defaultBranch main

GitHub CLI (gh) 설치

GitHub CLI를 설치하면 Claude Code가 PR 생성, 이슈 관리 등을 직접 수행할 수 있습니다.

Mac (Homebrew)

brew install gh

Windows (winget)

winget install --id GitHub.cli

설치 확인

gh --version

GitHub 인증

gh auth login

대화형 프롬프트를 따라가세요:

GitHub.com 선택
HTTPS 선택
Login with a web browser 선택
브라우저에서 인증 코드 입력

인증 확인

gh auth status

왜 GitHub 설정이 필요한가?

기능	Git 없이	Git + gh 있으면
파일 수정	✅ 가능	✅ 가능
버전 관리	❌ 불가	✅ 변경 추적, 롤백
PR 생성	❌ 불가	✅ `gh pr create`
이슈 관리	❌ 불가	✅ `gh issue create`
협업	❌ 어려움	✅ 브랜치, 리뷰

참고: GitHub CLI 공식 문서

첫 실행

Claude Code 시작

claude

> 프롬프트가 나타나면 성공입니다.

╭────────────────────────────────────────╮
│ Claude Code                             │
│ Type /help for available commands       │
╰────────────────────────────────────────╯

>

첫 대화

> 안녕, 넌 뭘 할 수 있어?

Claude가 자신의 기능을 설명해줍니다.

종료

> /exit

또는 Ctrl+D

기본 사용법

대화하기

일반 AI 챗봇처럼 자연어로 대화합니다.

> 마케팅 이메일 초안 작성해줘. 신제품 출시 알림이야.

파일 작업

파일 읽기

> 현재 폴더에 있는 파일 목록 보여줘
> README.md 파일 읽어줘

파일 생성

> report.md 파일 만들어서 오늘 할 일 정리해줘

파일 수정

> report.md에서 "회의" 부분을 "미팅"으로 바꿔줘

명령어 실행

> git status 실행해줘
> npm install 해줘

주의: Claude가 명령어를 실행하기 전에 확인을 요청합니다. 검토 후 승인하세요.

핵심 명령어

슬래시 명령어

명령어	설명
`/help`	도움말 보기
`/clear`	대화 내역 초기화
`/compact`	대화 요약 (토큰 절약)
`/cost`	현재 세션 비용 확인
`/model`	모델 변경
`/exit`	세션 종료

키보드 단축키

단축키	설명
`Tab`	자동완성
`Shift+Tab` (2회)	Plan 모드 토글
`Ctrl+C`	현재 작업 중단
`Ctrl+D`	세션 종료
`↑` / `↓`	이전 입력 탐색
`Esc`	입력 취소

Plan 모드 (중요!)

Shift+Tab을 두 번 누르면 Plan 모드로 전환됩니다.

Plan 모드란?

Claude가 실행하기 전에 계획을 먼저 보여줌
실수 방지에 매우 유용
비개발자에게 강력 추천

[Plan Mode ON]
> 마케팅 보고서 초안 작성해줘

Claude: 다음 단계로 진행하겠습니다:
1. 현재 폴더에서 관련 자료 확인
2. marketing-report.md 파일 생성
3. 보고서 구조 작성

진행할까요? (y/n)

막혔을 때 해결하는 방법

원칙 1: 에러 메시지를 Claude에게 보여주기

에러가 나면 당황하지 말고 그대로 복사해서 Claude에게 물어보세요.

> 이런 에러가 났어:
> [에러 메시지 전체 복사]
>
> 왜 그런지 설명하고 해결해줘.

원칙 2: 검색 활용하기

Claude Code로 해결이 안 되면:

에러 메시지 복사
Google 또는 Perplexity에 검색
해결책을 Claude에게 적용 요청

> 검색해서 찾은 해결책인데, 이거 적용해줘:
> [복사한 해결책]

원칙 3: 새 세션으로 시작

정말 막히면 새 터미널에서 다시 시작:

# 현재 세션 종료
exit

# 새 세션 시작
claude

원칙 4: 커뮤니티 활용

리소스	용도	링크
GitHub Issues	버그 리포트, 기능 요청	anthropics/claude-code/issues
Discord	실시간 질문	discord.gg/anthropic
Reddit	팁 공유	r/ClaudeAI

자주 발생하는 문제

”command not found: claude”

원인: Claude Code가 설치되지 않았거나 PATH에 없음

해결

# 재설치
npm install -g @anthropic-ai/claude-code

# PATH 확인
npm bin -g

”Error: Invalid API key”

원인: API 키가 없거나 잘못됨

해결

# 환경변수 확인
echo $ANTHROPIC_API_KEY

# 값이 없으면 다시 설정
export ANTHROPIC_API_KEY="sk-ant-..."

”Permission denied”

원인: 해당 폴더/파일에 권한 없음

해결

# 권한 확인
ls -la

# 본인 소유 폴더로 이동
cd ~/Documents

”Context length exceeded”

원인: 대화가 너무 길어짐

해결

> /compact

실습: 첫 번째 작업

과제: 자기소개 문서 만들기

Claude Code에게 요청해보세요:

> 나에 대한 자기소개 문서를 만들어줘.
>
> 이름: [당신의 이름]
> 직무: [당신의 직무]
> 회사: [당신의 회사]
>
> intro.md 파일로 저장해줘.

확인

> intro.md 파일 내용 보여줘

파일이 생성되고 내용이 보이면 성공입니다!

유용한 팁

1. 작업 폴더에서 시작

항상 작업할 폴더로 이동한 후 Claude를 시작하세요.

cd ~/Documents/my-project
claude

2. Plan 모드 습관화

처음에는 Plan 모드를 켜두고 사용하세요. 실수를 방지하고 Claude의 동작을 이해하는 데 도움됩니다.

3. `/compact` 자주 사용

긴 대화 후에는 /compact로 토큰을 절약하세요.

4. 구체적으로 요청

# 나쁜 예
> 보고서 만들어줘

# 좋은 예
> 주간 마케팅 보고서를 만들어줘.
> 포함할 내용: 이번 주 성과, 다음 주 계획, 이슈
> 형식: 마크다운
> 파일명: weekly-report.md

참고 자료

리소스	설명	링크
공식 레포지토리	Claude Code 소스 코드	github.com/anthropics/claude-code
공식 문서	상세 사용법	docs.anthropic.com/claude-code
API 콘솔	API 키 관리	console.anthropic.com

다음 단계

Claude Code 설치와 기본 사용법을 익혔다면, CLAUDE.md로 프로젝트 맥락을 설정하는 방법을 배워봅시다.

→ 2장. CLAUDE.md - 프로젝트 설정의 핵심

2장. CLAUDE.md - 프로젝트 설정의 핵심 →

시작하기 - 설치부터 첫 대화까지

Claude Code란?

일반 AI 챗봇과의 차이

비개발자도 쓸 수 있나요?

설치하기

사전 준비: Node.js

Claude Code 설치

API 키 설정

1단계: API 키 발급

2단계: 환경변수 설정

3단계: 설정 확인

GitHub 환경 구성 (권장)

Git 설치 확인

Git 기본 설정

GitHub CLI (gh) 설치

GitHub 인증

왜 GitHub 설정이 필요한가?

첫 실행

Claude Code 시작

첫 대화

종료

기본 사용법

대화하기

파일 작업

명령어 실행

핵심 명령어

슬래시 명령어

키보드 단축키

Plan 모드 (중요!)

막혔을 때 해결하는 방법

원칙 1: 에러 메시지를 Claude에게 보여주기

원칙 2: 검색 활용하기

원칙 3: 새 세션으로 시작

원칙 4: 커뮤니티 활용

자주 발생하는 문제

”command not found: claude”

”Error: Invalid API key”

”Permission denied”

”Context length exceeded”

실습: 첫 번째 작업

과제: 자기소개 문서 만들기

확인

유용한 팁

1. 작업 폴더에서 시작

2. Plan 모드 습관화

3. /compact 자주 사용

4. 구체적으로 요청

참고 자료

다음 단계

목차

3. `/compact` 자주 사용