Claude Code 사용법 — 터미널 AI 코딩 에이전트 완전 가이드

코딩하다가 "이거 누가 대신 좀 해줬으면" 싶을 때가 있다. 단순 반복 작업, 귀찮은 리팩토링, 테스트 코드 작성 같은 거. Claude Code를 쓰기 시작하고 나서 이런 작업들이 확 줄었다. 자동완성 수준이 아니라, 프로젝트 전체를 이해하고 여러 파일을 동시에 고쳐주는 진짜 "에이전트"다.

처음엔 "터미널에서 AI를 쓴다고?" 싶었는데, 한번 써보면 안 돌아간다. 오늘은 Claude Code가 뭔지, 어떻게 설치하고 쓰는지 처음부터 정리해본다.

---

Claude Code가 뭔데

Anthropic이 만든 터미널 기반 AI 코딩 에이전트다. Copilot 같은 에디터 자동완성 도구와는 성격이 다르다.

• Copilot/Cursor: 커서 위치의 코드를 자동완성. 한 파일 내에서 동작.
• Claude Code: 프로젝트 전체를 읽고, 여러 파일을 동시에 수정하고, 쉘 명령어를 실행하고, Git 커밋까지 한다.

코드베이스를 이해하고, 파일을 수정하고, 명령을 실행한다는 점에서 "에이전트"라는 표현이 맞다.

---

준비물

1. Node.js (v18 이상)

Claude Code는 npm으로 설치하니까 Node.js가 필요하다. v22 LTS를 권장한다.

node -v   # v18 이상이면 OK
npm -v

2. Anthropic 유료 계정

무료 플랜에서는 못 쓴다. 최소 Pro 구독($20/월) 이상이 필요하다.

Pro ($20/월)    — 일반적인 코딩 세션은 충분
Max ($100/월)   — 전문 개발자 일일 작업량 커버
Max ($200/월)   — 대규모 자율 작업
Team / Enterprise — 팀/기업용

3. 운영체제

• macOS 13.0 이상
• Ubuntu 20.04+ / Debian 10+
• Windows는 WSL 환경에서

---

설치

CLI 설치

# Native 설치 (권장)
curl -fsSL https://cli.claude.ai/install.sh | sh

# 또는 npm
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

npm 설치 시 권한 에러가 나면 sudo 쓰지 말고 npm 경로를 사용자 디렉토리로 바꾸자.

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

첫 로그인

cd ~/my-project
claude

# 브라우저가 열리면서 Anthropic 로그인 → 인증 완료

---

기본 사용법

실행하면 채팅 입력창이 뜬다. 자연어로 요청하면 된다.

"이 프로젝트에 로그인 API를 추가해줘. JWT 인증 방식으로."

"src/utils/helpers.ts의 날짜 포맷 함수를 리팩토링해줘."

"현재 프로젝트 구조를 분석하고 개선점을 알려줘."

Claude가 변경사항을 diff로 보여주고, 수락하면 코드가 적용된다.

@-멘션으로 파일 지정

특정 파일을 직접 가리킬 수 있다. 이게 정확도를 크게 올려준다.

@src/controllers/auth.ts 이 파일의 에러 핸들링을 개선해줘

@src/models/ 이 폴더의 모든 모델에 타입을 추가해줘

---

핵심 기능들

CLAUDE.md — 프로젝트 규칙 설정

프로젝트 루트에 CLAUDE.md 파일을 두면 Claude가 세션마다 자동으로 읽는다. 프로젝트 설명서 역할이다.

# CLAUDE.md

## 프로젝트
Next.js 14 + TypeScript + Prisma 기반 서비스

## 명령어
- 개발: pnpm dev
- 테스트: pnpm test
- 빌드: pnpm build

## 코딩 규칙
- 함수형 컴포넌트만 사용
- Tailwind CSS만 사용
- 작업 완료 전 pnpm test 통과 확인

이렇게 해두면 매번 "pnpm 써", "Tailwind로 해줘"를 반복하지 않아도 된다.

Plan Mode — 실행 전 계획 확인

큰 작업은 Plan Mode로 계획을 먼저 받자. 바로 코드를 고치는 게 아니라 "이렇게 할 거다"를 보여준다.

"이 프로젝트를 Express에서 Fastify로 마이그레이션해줘" (Plan Mode)

→ Claude가 단계별 계획 제시
→ 계획 검토/수정
→ 승인하면 실행

방향이 틀어지기 전에 잡을 수 있어서, 큰 변경에는 거의 필수다.

Checkpoints — 되감기

Claude가 여러 파일을 수정했는데 결과가 마음에 안 들면, 체크포인트로 특정 시점으로 되돌릴 수 있다. Git stash보다 편하다.

슬래시 명령어

/init      — 프로젝트 분석해서 CLAUDE.md 초안 생성
/clear     — 대화 초기화
/config    — 설정 변경

# 키를 누르고 지시사항을 입력하면 자동으로 CLAUDE.md에 저장된다. 작업 중에 흐름 안 끊고 규칙을 추가할 수 있다.

---

실전 워크플로우

코드 리뷰 + 리팩토링

1. 파일을 연다
2. "@src/services/payment.ts 리뷰해줘. 보안/성능/스타일 문제 찾아줘"
3. 분석 결과 확인
4. "3번 이슈를 수정해줘"
5. diff 확인 후 수락

테스트 코드 생성

"@src/utils/calculator.ts에 대한 단위 테스트를 Jest로 작성해줘. 엣지 케이스도 포함해서."

버그 디버깅

"앱 실행하면 'Cannot read property map of undefined' 에러가 나.
@src/components/UserList.tsx 여기인 것 같은데 원인이랑 수정 방법 알려줘."

Git 작업

"지금까지 변경한 내용으로 커밋해줘. conventional commit 형식으로."

---

IDE에서도 쓸 수 있다

터미널뿐 아니라 VSCode, JetBrains(IntelliJ 등) 확장으로도 쓸 수 있다. IDE에서 쓰면 diff를 IDE 뷰어로 보고, 선택한 코드를 자동 공유하고, 에러까지 실시간으로 넘겨준다. 같은 CLI를 쓰니까 코드 품질은 동일하다.

---

자주 겪는 문제

"claude: command not found"

which claude  # 안 나오면 PATH 문제
npm config get prefix  # 이 경로/bin이 PATH에 있어야 함

인증 문제

claude auth status  # 인증 상태 확인
claude auth login   # 재인증

Windows에서 안 됨

Claude Code는 Windows 네이티브를 지원하지 않는다. WSL에서 써야 한다.

wsl --install  # PowerShell 관리자 모드
# WSL 안에서 Node.js + Claude Code 설치

---

비용

Claude Code 자체는 무료고, 비용은 Anthropic 구독료에 포함된다. Pro($20/월)로 시작해서 사용량 한도에 자주 걸리면 Max로 올리는 게 합리적이다. API 크레딧 종량제도 가능한데, 코딩 에이전트는 컨텍스트를 많이 쓰기 때문에 월정액이 마음 편하다.

---

마무리

Claude Code 시작하는 과정을 정리하면:

1. Node.js 설치 (v18 이상)
2. CLI 설치 (curl 또는 npm)
3. 프로젝트 폴더에서 claude 실행 → 로그인
4. 자연어로 작업 요청

핵심 팁:

• @-멘션으로 파일을 지정하면 정확도가 올라간다
• 큰 작업은 Plan Mode로 계획 먼저 확인하자
• CLAUDE.md에 프로젝트 규칙을 써두면 반복 설명이 필요 없다
• diff는 항상 확인하자. 무조건 수락은 금물
• Pro로 시작해서 한도에 자주 걸리면 Max로