터미널에서 자연어로 코드를 작성하고, 파일을 편집하고, 테스트를 실행하고, git 커밋까지 자동으로 처리해주는 AI 도구가 있다면 믿으시겠습니까? Claude Code 사용법을 알면 이 모든 것이 가능합니다. Anthropic이 만든 이 터미널 기반 AI 코딩 에이전트는 2026년 현재 SWE-bench Verified 80.9%라는 압도적인 벤치마크 점수를 기록하며, 코드 품질 면에서 최고 자리를 차지하고 있습니다.
저는 약 60개월 전부터 Claude Code를 실무에 사용하고 있습니다. 처음에는 “터미널에서 코딩한다고? 불편하지 않을까?”라는 의구심이 있었는데, 지금은 복잡한 리팩토링이나 버그 수정 작업에서 빼놓을 수 없는 도구가 되었습니다. 이 글에서는 제가 직접 사용하면서 느낀 점들을 바탕으로 Claude Code 사용법을 처음부터 끝까지 정리합니다.
Claude Code란? – 터미널에서 작동하는 AI 코딩 에이전트
Claude Code는 Anthropic이 만든 터미널 네이티브 AI 코딩 에이전트입니다. Cursor나 GitHub Copilot 같은 도구가 IDE 안에서 동작하는 것과 달리, Claude Code는 터미널(명령줄)에서 실행됩니다. 특정 IDE에 종속되지 않기 때문에 VS Code, JetBrains, Neovim, Vim 등 어떤 편집기를 쓰든 상관없이 사용할 수 있습니다.
기본적인 동작 방식은 이렇습니다. 터미널에서 claude를 입력하면 대화형 세션이 시작됩니다. 여기에 자연어로 작업을 설명하면, Claude Code가 알아서 프로젝트 구조를 파악하고, 관련 파일을 읽고, 코드를 작성하거나 수정하고, 필요하면 명령어까지 실행합니다. 단순한 코드 자동완성이 아니라 자율적으로 작업을 수행하는 에이전트라는 점이 핵심입니다.
가장 인상적인 특징은 1M(100만) 토큰 컨텍스트 윈도우입니다. 이 덕분에 대규모 프로젝트의 전체 코드베이스를 한 번에 이해할 수 있고, 파일 간의 의존성이나 아키텍처 패턴을 파악한 상태에서 코드를 생성합니다. 실제로 사용해보면 “이 정도로 프로젝트를 잘 이해하고 있었나?”라고 놀라는 순간이 자주 있습니다.
Claude Code 설치 방법
사전 요구사항
Claude Code를 설치하기 전에 다음이 필요합니다.
- Node.js 18 이상: Claude Code는 npm 패키지로 배포됩니다.
- Anthropic 계정: claude.ai에서 가입할 수 있습니다.
- Claude Pro 이상 구독 또는 API 키: 무료 계정으로도 제한적 사용이 가능하지만, 제대로 활용하려면 유료 구독을 권장합니다.
npm으로 설치하기
설치는 한 줄이면 됩니다.
npm install -g @anthropic-ai/claude-code글로벌로 설치하면 어디서든 claude 명령어를 사용할 수 있습니다. 설치가 완료되면 처음 실행 시 인증 과정을 거칩니다.
claude
처음 실행하면 브라우저가 열리면서 Anthropic 계정으로 로그인하라는 안내가 나옵니다. 로그인하면 토큰이 자동으로 설정되고, 이후부터는 바로 사용할 수 있습니다.
API 키로 사용하기
조직에서 API를 직접 사용하고 싶다면 환경변수를 설정합니다.
export ANTHROPIC_API_KEY="sk-ant-..."이 방법은 토큰 단위로 비용이 발생하므로 사용량을 관리할 때 유리합니다.
Claude Code 사용법 – 기본 명령어와 워크플로우
대화형 모드
가장 기본적인 사용법은 프로젝트 디렉토리에서 claude를 실행하는 것입니다.
cd my-project
claude이렇게 하면 대화형 REPL(Read-Eval-Print Loop)이 시작됩니다. 여기서 자연어로 무엇이든 요청할 수 있습니다.
> 이 프로젝트의 구조를 분석해줘
> src/api/auth.ts에 있는 로그인 로직에 버그가 있는 것 같아. 확인해줘
> 사용자 프로필 편집 API를 만들어줘
> 테스트 코드를 작성하고 실행해줘
원샷 모드
간단한 작업은 명령줄에서 바로 처리할 수 있습니다.
claude -p "package.json의 의존성 목록을 분석하고 업데이트가 필요한 패키지를 알려줘"-p 플래그를 사용하면 대화형 세션 없이 한 번에 결과를 받을 수 있습니다. CI/CD 파이프라인이나 스크립트에서 활용할 때 유용합니다.
파이프 입력
다른 명령어의 출력을 Claude Code에 전달할 수도 있습니다.
git diff | claude -p "이 변경사항을 리뷰해줘"
cat error.log | claude -p "이 에러 로그를 분석하고 해결 방법을 제안해줘"이런 방식이 가능하다는 것 자체가 터미널 네이티브 도구의 강점입니다. Unix 철학에 맞게 다른 도구들과 자연스럽게 조합할 수 있습니다.
주요 기능 상세 – 파일 편집, 검색, 테스트, Git 연동
1. 파일 읽기와 편집
Claude Code는 프로젝트 내의 파일을 직접 읽고 편집할 수 있습니다. 중요한 것은 수정 전에 반드시 확인을 요청한다는 점입니다.
> src/components/Header.tsx에서 네비게이션 메뉴에 "블로그" 링크를 추가해줘이렇게 요청하면 Claude Code가 해당 파일을 읽고, 수정 내용을 보여준 다음, 적용할지 묻습니다. 무턱대고 파일을 바꾸지 않으므로 안심하고 쓸 수 있습니다.
멀티파일 편집도 자연스럽게 처리합니다. “사용자 프로필 기능을 추가해줘”라고 요청하면, 라우터 설정, 컴포넌트 생성, API 엔드포인트, 타입 정의 등 여러 파일을 동시에 수정합니다.
2. 코드베이스 검색
내장된 검색 기능으로 프로젝트를 빠르게 탐색합니다.
> "handleSubmit" 함수가 어디서 정의되고 어디서 사용되는지 찾아줘
> 이 프로젝트에서 deprecated된 API를 사용하는 곳을 모두 찾아줘단순 텍스트 검색이 아니라 코드의 맥락을 이해하고 관련 파일을 찾아주기 때문에, IDE의 “Find References”보다 더 포괄적인 결과를 얻을 수 있습니다.
3. 테스트 실행과 디버깅
테스트 실행도 Claude Code의 강점입니다.
> 이 프로젝트의 테스트를 실행해줘
> 실패한 테스트를 분석하고 수정해줘
> auth 모듈에 대한 단위 테스트를 작성해줘특히 “테스트가 실패했는데 원인을 모르겠다”는 상황에서 진가를 발휘합니다. 에러 메시지를 분석하고, 관련 코드를 확인하고, 수정안을 제시하고, 수정 후 다시 테스트를 돌려서 통과하는지까지 확인합니다. 이 과정이 자율적으로 이루어진다는 점이 단순 코드 제안 도구와의 결정적 차이입니다.
4. Git 연동
Claude Code의 Git 연동 기능은 제가 가장 자주 쓰는 기능 중 하나입니다.
> 현재 변경사항을 확인하고 적절한 커밋 메시지로 커밋해줘
> 최근 5개 커밋의 변경사항을 요약해줘
> 이 PR을 리뷰해줘커밋 메시지를 자동으로 작성할 때, 단순히 “파일 수정”이 아니라 변경의 목적과 맥락을 반영한 의미 있는 메시지를 만들어줍니다. PR 리뷰에서도 코드 품질, 잠재적 버그, 성능 이슈 등을 꼼꼼히 짚어줍니다.
5. CLAUDE.md – 프로젝트별 맞춤 설정
프로젝트 루트에 CLAUDE.md 파일을 만들면 Claude Code에게 프로젝트별 지침을 줄 수 있습니다. 빌드 방법, 코딩 컨벤션, 아키텍처 정보 등을 적어두면 Claude Code가 이를 참고하여 프로젝트에 맞는 코드를 생성합니다.
# 프로젝트 설명
React + TypeScript 기반 웹 앱
## 빌드 방법
npm run build
## 코딩 컨벤션
- 함수형 컴포넌트만 사용
- styled-components 대신 Tailwind CSS 사용
- 변수명은 camelCase이 기능은 팀 프로젝트에서 특히 유용합니다. 새로운 팀원이 합류했을 때 CLAUDE.md만 잘 작성해두면, Claude Code가 팀의 컨벤션에 맞게 코드를 생성합니다.
실전 활용 예시 – 실제로 이렇게 씁니다
예시 1: 레거시 코드 리팩토링
가장 만족스러웠던 경험은 오래된 JavaScript 프로젝트를 TypeScript로 전환할 때였습니다.
> 이 프로젝트를 분석하고 TypeScript로 마이그레이션 계획을 세워줘Claude Code가 파일별 의존성 그래프를 분석하고, 마이그레이션 순서를 제안하고, 하나씩 변환해나갔습니다. 타입 추론이 놀라울 정도로 정확했고, 함수 시그니처에서 누락된 타입도 컨텍스트를 보고 적절하게 추가해주었습니다.
예시 2: 버그 수정
프로덕션에서 간헐적으로 발생하는 버그를 찾을 때도 효과적입니다.
> 이 에러 로그를 봐줘. "TypeError: Cannot read property 'id' of undefined"가
> src/services/userService.ts:47에서 발생해. 원인을 찾고 수정해줘.에러가 발생하는 코드뿐만 아니라, 해당 함수를 호출하는 모든 경로를 추적해서 어떤 조건에서 undefined가 전달되는지 찾아냅니다. 단순 null 체크가 아니라 근본적인 원인을 해결하는 수정안을 제시하는 경우가 많습니다.
예시 3: 새 기능 구현
> 사용자가 프로필 이미지를 업로드할 수 있는 기능을 추가해줘.
> S3에 저장하고, 이미지 리사이징은 sharp 라이브러리를 사용해.
이런 요청을 하면 필요한 패키지 설치, API 엔드포인트 생성, 프론트엔드 컴포넌트 작성, 에러 처리까지 한 번에 처리합니다. 물론 각 단계마다 확인을 받으므로 원치 않는 변경이 적용되지는 않습니다.
Cursor와의 차이점 요약
같은 AI 코딩 도구라도 Cursor와 Claude Code는 근본적인 접근 방식이 다릅니다. 어떤 도구가 더 낫다기보다는, 작업 방식과 상황에 따라 적합한 도구가 다릅니다.
| 비교 항목 | Claude Code | Cursor |
|---|---|---|
| 동작 환경 | 터미널 (CLI) | 독립형 AI IDE (VS Code 포크) |
| 자동완성 | 미지원 (에이전트 방식) | Supermaven (100ms 미만 지연) |
| 작업 방식 | 자율적 에이전트 실행 | 인터랙티브 코딩 |
| 컨텍스트 윈도우 | 1M 토큰 | 모델별 상이 |
| 모델 | Claude 전용 | GPT-5.4, Claude, Gemini 등 다중 |
| SWE-bench 점수 | 80.9% (최고) | 51.7% |
| 토큰 효율성 | 기준 | Claude Code 대비 5.5배 소모 |
| 학습 곡선 | 터미널 익숙해야 함 | IDE 경험 있으면 쉬움 |
한 줄 요약: 빠른 인터랙티브 코딩과 자동완성이 중요하면 Cursor, 복잡한 작업의 자율 실행과 코드 품질이 중요하면 Claude Code가 적합합니다.
두 도구를 함께 쓰는 것도 좋은 전략입니다. 평소에는 Cursor로 빠르게 코딩하고, 대규모 리팩토링이나 복잡한 버그 수정이 필요할 때 Claude Code를 꺼내 쓰는 개발자가 제 주변에도 많습니다.
더 자세한 비교가 궁금하다면 Cursor vs Claude Code 비교 글을 참고하세요.
요금제 – 무료 vs Pro vs Max
2026년 3월 기준 Claude Code의 요금 체계입니다.
무료 사용
Claude 무료 계정으로도 Claude Code를 사용할 수 있지만, 사용량이 매우 제한적입니다. 간단한 테스트 용도로만 적합합니다.
Claude Pro ($20/월)
가장 기본적인 유료 플랜입니다. Claude Code를 포함한 Claude의 모든 기능에 접근할 수 있으며, 일반적인 개인 개발 용도로 충분한 사용량을 제공합니다. 다만 Claude Code를 집중적으로 사용하면 하루 사용량 제한에 걸릴 수 있습니다.
Claude Max 5x ($100/월)
Pro 대비 5배 사용량을 제공합니다. Claude Code를 주력 도구로 사용하는 개발자에게 적합합니다. 대부분의 개인 개발자는 이 플랜이면 부족함 없이 사용할 수 있습니다.
Claude Max 20x ($200/월)
Pro 대비 20배 사용량입니다. Claude Code를 하루 종일 사용하거나, 대규모 프로젝트에서 집중적으로 활용하는 팀에 적합합니다.
API 사용 (종량제)
Anthropic API 키를 직접 사용하는 방식입니다. 토큰당 비용이 발생하며, 사용한 만큼만 지불합니다. 비용을 세밀하게 관리하고 싶거나, CI/CD 파이프라인에서 자동화할 때 유용합니다.
개인적인 추천: 처음에는 Pro($20/월)로 시작하고, 사용량이 부족하다고 느끼면 Max 5x로 올리는 것을 권장합니다. 저는 Max 5x를 사용 중인데, 하루 3~4시간 정도 Claude Code를 쓰는 기준으로 월말까지 넉넉합니다.
Claude Code 사용법 정리 – 장단점
장점
- 최고 수준의 코드 품질: SWE-bench 80.9%는 단순 숫자가 아닙니다. 실제로 사용해보면 생성되는 코드의 품질이 체감될 정도로 높습니다.
- 뛰어난 프로젝트 이해력: 1M 토큰 컨텍스트 덕분에 대규모 코드베이스에서도 정확한 수정이 가능합니다.
- IDE 독립적: VS Code든 Vim이든 어떤 편집기와도 함께 쓸 수 있습니다.
- 토큰 효율성: 같은 작업을 더 적은 비용으로 처리합니다.
- 자율 실행: 복잡한 작업도 자연어 한 줄로 맡길 수 있습니다.
- Unix 철학: 파이프, 스크립트 등 기존 터미널 도구와 자연스럽게 조합됩니다.
단점
- 터미널 기반 진입장벽: GUI에 익숙한 개발자에게는 처음에 불편할 수 있습니다.
- 자동완성 미지원: Cursor처럼 실시간 코드 제안 기능이 없습니다. 코딩 흐름 속에서 즉각적인 도움이 필요한 상황에서는 아쉽습니다.
- 비용: 제대로 활용하려면 최소 Pro($20/월) 이상이 필요하고, 집중 사용 시 Max 5x($100/월)가 필요할 수 있습니다.
- Claude 모델 전용: 다른 AI 모델(GPT, Gemini 등)은 선택할 수 없습니다.
- 오프라인 사용 불가: 인터넷 연결이 필수입니다.
자주 묻는 질문 (FAQ)
Q. Claude Code는 게임 해킹 같은 불법 도구인가요?
A. 전혀 아닙니다. Claude Code는 Anthropic이 공식 개발한 AI 코딩 도구이며, 일반적인 소프트웨어 개발에 사용됩니다.
Q. 터미널을 잘 몰라도 쓸 수 있나요?
A. 기본적인 터미널 명령어(cd, ls 등)만 알면 사용할 수 있습니다. 나머지는 자연어로 요청하면 Claude Code가 처리합니다.
Q. 내 코드가 Anthropic 서버에 저장되나요?
A. Claude Code는 작업에 필요한 만큼 코드를 API로 전송하지만, Anthropic은 API 데이터를 모델 학습에 사용하지 않는다고 명시하고 있습니다.
Q. Cursor와 동시에 쓸 수 있나요?
A. 네, 완전히 독립적인 도구이므로 같은 프로젝트에서 병행 사용이 가능합니다.
마무리 – 누가 쓰면 좋을까?
Claude Code는 모든 개발자에게 맞는 도구는 아닙니다. 하지만 다음과 같은 상황이라면 강력하게 추천합니다.
- 터미널 환경에 익숙한 개발자: CLI를 즐겨 쓴다면 Claude Code의 진가를 바로 느낄 수 있습니다.
- 복잡한 코드베이스를 다루는 개발자: 파일 수백 개짜리 프로젝트에서 리팩토링이나 기능 추가를 할 때 특히 유용합니다.
- 코드 품질을 중시하는 개발자: 생성되는 코드의 수준이 다른 도구 대비 확실히 높습니다.
- 특정 IDE에 묶이기 싫은 개발자: Vim, Emacs, VS Code 등 어떤 환경에서든 쓸 수 있습니다.
반대로 실시간 자동완성이 중요하거나, GUI 기반 작업을 선호하거나, 다양한 AI 모델을 번갈아 쓰고 싶다면 AI 코딩 도구 추천 글에서 다른 선택지도 확인해보세요.
AI 코딩 도구 시장은 매달 새로운 기능이 추가될 정도로 빠르게 변하고 있습니다. 코딩 없이 앱을 만드는 바이브 코딩이라는 새로운 트렌드도 주목할 만합니다. 중요한 것은 어떤 도구가 “최고”인지 따지는 것보다, 자신의 작업 스타일에 맞는 도구를 찾아서 생산성을 끌어올리는 것입니다.
Claude Code 공식 문서는 Anthropic 공식 사이트에서 확인할 수 있습니다.
AI Desk | AI 도구와 IT 소프트웨어를 직접 써보고 솔직하게 리뷰합니다
