Claude Code 사용법 입문｜설치부터 코드 분석·수정·테스트까지

Claude Code 사용법 입문｜설치부터 코드 분석·수정·테스트까지

 

Claude Code는 코드 질문에 답하는 채팅창을 넘어, 실제 프로젝트 폴더를 읽고 파일을 수정하며 명령어와 테스트를 실행하는 에이전트형 코딩 도구입니다.

터미널에서 사용할 수 있고 VS Code와 JetBrains 계열 IDE, 데스크톱 앱과 웹에서도 이용할 수 있습니다. 초보자는 기능을 많이 아는 것보다 코드를 바로 고치게 하기 전에 구조를 이해시키고, 계획을 검토한 뒤 작은 단위로 수정하게 하는 흐름을 익히는 것이 중요합니다.

이 글에서는 Windows와 macOS·Linux 설치, 로그인, 첫 프로젝트 분석, 파일 수정과 테스트, CLAUDE.md 설정, 비용과 보안 주의사항까지 순서대로 설명합니다.

핵심 요약

• Claude Code는 코드베이스를 읽고 여러 파일을 수정하며 명령과 테스트를 실행할 수 있습니다.
• Windows PowerShell, macOS·Linux·WSL에서 공식 설치 명령을 사용할 수 있습니다.
• 처음에는 “분석만 하고 수정하지 마”라고 요청해 프로젝트 구조부터 확인합니다.
• 변경 전 계획을 검토하고, 수정 후에는 테스트와 diff를 반드시 확인합니다.
• CLAUDE.md에 빌드 명령, 코딩 규칙과 프로젝트 관례를 기록하면 반복 설명을 줄일 수 있습니다.
• Claude 구독 사용량과 Claude Code 사용량은 같은 한도를 공유할 수 있으며 API 키 사용 시 별도 비용이 발생할 수 있습니다.

---

Claude Code란 무엇인가요?

Anthropic 공식 문서는 Claude Code를 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하며 개발 도구와 통합되는 에이전트형 코딩 도구로 설명합니다.

일반 Claude 채팅과의 차이는 다음과 같습니다.

구분	일반 Claude 채팅	Claude Code
주 사용 목적	설명, 글쓰기, 분석, 코드 질문	실제 저장소 분석·수정·테스트
파일 접근	사용자가 첨부한 파일 중심	허용한 프로젝트 폴더를 직접 탐색
코드 변경	코드 블록으로 제안	실제 파일을 수정할 수 있음
명령 실행	제한적 도구 환경	터미널 명령과 테스트 실행
작업 범위	대화 단위	여러 파일과 개발 도구 연결
적합한 사용자	코드 설명이 필요한 사람	실제 프로젝트를 고치고 검증할 사람

Claude Code는 다음 업무에 특히 유용합니다.

• 처음 보는 저장소 구조 파악
• 오류 원인과 관련 파일 찾기
• 작은 기능 추가
• 반복되는 리팩터링
• 테스트 코드 작성과 실행
• 린트 오류와 타입 오류 수정
• 문서와 릴리스 노트 작성
• Git 변경 내용 요약과 Pull Request 준비

코딩 경험이 많지 않더라도 사용할 수 있지만, 실행되는 명령과 변경 파일을 검토할 기본 습관은 필요합니다.

---

Claude Code를 사용할 수 있는 환경

2026년 7월 기준 Claude Code는 다음 환경을 지원합니다.

• 터미널 CLI
• VS Code와 VS Code 기반 IDE
• JetBrains IDE
• Claude 데스크톱 앱
• Claude 웹
• Slack
• GitHub Actions와 GitLab CI/CD

처음 배우는 사용자는 다음 중 하나를 선택하면 됩니다.

터미널 CLI가 좋은 경우

• 프로젝트 폴더와 명령어를 직접 다루고 싶다.
• Git과 테스트 명령을 자주 사용한다.
• Claude Code의 전체 기능을 익히고 싶다.

VS Code 확장이 좋은 경우

• 터미널이 낯설다.
• 코드와 변경 diff를 화면에서 함께 보고 싶다.
• 특정 파일과 선택 영역을 빠르게 참조하고 싶다.

데스크톱 앱이 좋은 경우

• 명령어 설치보다 그래픽 화면을 선호한다.
• 로컬 프로젝트를 Claude 인터페이스에서 다루고 싶다.
• 코딩 입문 단계라 터미널 사용을 최소화하고 싶다.

이 글에서는 가장 기본이 되는 터미널 CLI를 기준으로 설명합니다.

---

Claude Code 설치 전 준비 사항

공식 문서의 기본 요구 사항은 다음과 같습니다.

• Claude Pro, Max, Team, Enterprise 구독 또는 Claude Console 계정
• 인터넷 연결
• 작업할 코드 프로젝트
• 지원되는 운영체제와 터미널
• 최소 4GB RAM

지원 환경에는 macOS 13 이상, Windows 10 1809 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상이 포함됩니다. Windows에서는 Git for Windows를 설치하면 Bash 기반 도구를 활용하기 편합니다.

중요한 회사 저장소라면 설치 전에 회사의 AI 도구 사용 정책, 외부 전송 금지 자료와 허용된 인증 방식을 확인합니다.

---

Claude Code 설치 방법

 

Windows PowerShell

PowerShell을 열고 다음 명령을 실행합니다.

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

또는 WinGet을 사용할 수 있습니다.

winget install Anthropic.ClaudeCode

macOS, Linux, WSL

터미널에서 다음 명령을 실행합니다.

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

macOS에서 Homebrew를 사용한다면 다음 방법도 있습니다.

brew install --cask claude-code

공식 문서는 네이티브 설치를 권장합니다. 네이티브 설치는 백그라운드 자동 업데이트를 지원하며, Homebrew와 WinGet 설치는 사용자가 직접 업그레이드해야 할 수 있습니다.

설치 확인

설치 후 기존 터미널을 닫고 새로 엽니다. 다음 명령을 실행합니다.

claude --version

claude: command not found가 나오면 새 터미널을 열거나 셸 설정을 다시 불러옵니다.

macOS 또는 Linux 예시:

source ~/.zshrc

source ~/.bashrc

Windows에서는 PowerShell을 완전히 닫았다가 다시 엽니다.

---

Claude Code 로그인하기

프로젝트 폴더가 아니라도 먼저 다음 명령을 실행할 수 있습니다.

claude

첫 실행 시 브라우저가 열리고 계정 인증을 요청합니다. Claude 구독을 사용하려면 일반 Claude에서 사용하는 계정으로 로그인합니다.

이미 API 키 방식으로 연결되어 있는데 Pro 또는 Max 구독으로 바꾸려면 Claude Code 안에서 다음 명령을 사용합니다.

/login

로그인 문제가 있을 때는 다음 순서로 정리합니다.

/logout

claude update

터미널을 다시 시작한 뒤 claude를 실행하고 올바른 계정을 선택합니다.

비용 주의

시스템에 ANTHROPIC_API_KEY 환경 변수가 설정되어 있으면 구독 사용량 대신 API 키가 우선 사용되어 별도 API 비용이 발생할 수 있습니다. 구독 한도 안에서만 사용하려면 인증 방식을 반드시 확인합니다.

현재 상태는 Claude Code 안에서 다음 명령으로 확인할 수 있습니다.

/status

모델을 확인하거나 바꾸려면 다음 명령을 사용합니다.

/model

---

첫 프로젝트에서 Claude Code 시작하기

작업할 프로젝트의 루트 폴더로 이동합니다.

cd /path/to/project

Windows 예시:

cd C:\Users\사용자이름\Documents\my-project

그다음 Claude Code를 실행합니다.

claude

처음부터 “버그를 고쳐줘”라고 하기보다 구조를 읽게 합니다.

이 코드베이스의 전체 구조를 먼저 파악해줘.

- 주요 폴더와 역할
- 실행 시작점
- 핵심 데이터 흐름
- 빌드와 테스트 명령
- 외부 서비스와 환경 변수

표로 정리하고 아직 파일은 수정하지 마.

그다음 관심 영역을 좁힙니다.

인증 기능이 어떻게 동작하는지 설명해줘.
관련 파일과 함수, 요청부터 응답까지의 흐름을 정리하고
보안상 확인할 부분을 알려줘.
아직 코드는 변경하지 마.

이 단계에서 Claude가 잘못된 폴더를 보고 있거나 프로젝트 구조를 오해했다면 바로 수정할 수 있습니다.

---

안전한 기본 작업 흐름

 

Claude Code는 다음 다섯 단계로 사용하면 안전합니다.

1. 탐색

저장소 구조, 관련 파일, 실행 방법과 테스트 명령을 찾게 합니다.

2. 계획

수정할 파일, 변경 이유, 예상 영향과 검증 방법을 먼저 보여 달라고 합니다.

오류 원인을 찾은 뒤 바로 수정하지 말고,
변경할 파일과 수정 계획, 예상 부작용과 테스트 방법을 먼저 보여줘.

3. 변경

확인한 계획을 기준으로 최소 범위만 수정합니다.

확인한 계획대로 진행해줘.
관련 없는 포맷 변경과 대규모 리팩터링은 하지 말고,
변경 이유가 드러나도록 작은 단위로 수정해줘.

4. 테스트

기존 테스트와 새 테스트를 실행하게 합니다.

수정한 기능과 관련된 테스트를 실행해줘.
실패하면 원인을 구분하고 필요한 최소 수정만 적용한 뒤 다시 테스트해줘.

5. 리뷰

마지막으로 변경 파일과 diff, 보안·예외 처리, 남은 위험을 요약합니다.

최종 변경 내용을 리뷰해줘.

- 변경 파일
- 핵심 diff
- 실행한 테스트와 결과
- 보안과 개인정보 영향
- 아직 확인하지 못한 위험
- 되돌리는 방법

---

초보자가 바로 쓰는 Claude Code 프롬프트

 

새 코드베이스 이해

이 저장소에 처음 참여했습니다.

1. 폴더 구조와 핵심 모듈
2. 애플리케이션 실행 흐름
3. 주요 데이터 모델
4. 인증과 권한 처리
5. 빌드·테스트·배포 명령

순서로 설명해줘.
아직 파일은 수정하지 마.

버그 수정

사용자가 로그아웃한 뒤 뒤로 가기를 누르면
이전 개인정보 화면이 잠깐 보이는 문제가 있습니다.

먼저 재현 경로와 원인을 찾아줘.
수정할 파일, 해결 방식과 테스트 계획을 제안하고
내가 확인하기 전에는 코드를 변경하지 마.

테스트 추가

auth 모듈에서 테스트되지 않은 분기와 예외 처리를 찾아줘.
우선 테스트 계획을 보여준 뒤,
기존 스타일을 유지해 테스트를 추가하고 실행해줘.
실패한 테스트는 원인과 수정 내용을 함께 기록해줘.

리팩터링

이 함수가 너무 길고 중복된 조건문이 많습니다.
동작을 바꾸지 않는 범위에서 리팩터링 계획을 세워줘.
기존 테스트를 먼저 실행하고,
작은 단계로 수정한 뒤 매 단계 테스트해줘.

문서 작성

현재 코드와 실제 명령을 기준으로 README를 업데이트해줘.
설치, 환경 변수, 로컬 실행, 테스트, 배포 순서로 작성하고
확인하지 못한 값은 임의로 만들지 말고 TODO로 표시해줘.

---

CLAUDE.md로 프로젝트 규칙 저장하기

Claude Code는 프로젝트의 CLAUDE.md 파일을 작업 지침과 메모리로 활용할 수 있습니다.

프로젝트 루트의 다음 위치 중 하나에 만들 수 있습니다.

./CLAUDE.md

./.claude/CLAUDE.md

처음에는 Claude Code에서 다음 명령으로 초안을 만들 수 있습니다.

/init

Claude가 코드베이스를 분석해 빌드와 테스트 명령, 발견한 프로젝트 규칙을 정리합니다. 생성된 내용은 그대로 두지 말고 실제 팀 규칙과 맞는지 검토해야 합니다.

CLAUDE.md에 넣기 좋은 내용

# Project commands
- Install: npm ci
- Dev server: npm run dev
- Test: npm test
- Lint: npm run lint

# Coding rules
- TypeScript strict mode를 유지한다.
- 기존 public API를 임의로 변경하지 않는다.
- 새 기능에는 테스트를 추가한다.
- 환경 변수와 비밀값을 코드에 넣지 않는다.

# Workflow
- 변경 전에 계획과 영향 파일을 먼저 제시한다.
- 관련 없는 포맷 변경을 하지 않는다.
- 수정 후 테스트 결과와 남은 위험을 요약한다.

공식 문서는 CLAUDE.md를 구체적이고 간결하게 작성하고, 가능하면 200줄 이내를 목표로 하라고 안내합니다. 너무 긴 지침은 컨텍스트를 많이 사용하고 중요한 규칙의 준수율을 떨어뜨릴 수 있습니다.

---

Git과 함께 사용할 때

Claude Code가 파일을 수정하기 전에 작업 브랜치를 만듭니다.

git checkout -b fix/login-cache

현재 상태를 확인합니다.

git status

Claude Code 작업 후에는 직접 diff를 검토합니다.

git diff

검토가 끝나면 커밋 메시지 초안을 요청할 수 있습니다.

현재 git diff를 기준으로
변경 목적과 테스트 결과가 드러나는 커밋 메시지를 작성해줘.
아직 커밋은 실행하지 마.

처음 사용하는 동안에는 자동 커밋과 자동 푸시를 맡기기보다 변경 내용을 직접 확인한 뒤 실행하는 편이 좋습니다.

---

Claude Code 사용량과 비용

Claude Pro와 Max 구독으로 Claude Code에 로그인할 수 있습니다. 이 경우 일반 Claude와 Claude Code 활동이 같은 사용량 한도에 포함될 수 있습니다.

사용량이 부족하면 다음 선택지가 있습니다.

• 한도 초기화까지 기다리기
• 상위 요금제로 변경
• 계정에서 사용량 크레딧 활성화
• Claude Console API 키로 사용하고 사용량만큼 결제

API 키 사용은 구독료와 별도의 과금 체계입니다. 자동 충전 설정이 켜져 있다면 Console 결제 설정도 함께 확인합니다.

Claude 요금제 선택은 Claude 무료·유료 요금제 비교, 일반 Claude와의 차이는 Claude vs ChatGPT 비교에서 확인할 수 있습니다.

---

보안과 개인정보 체크리스트

Claude Code는 실제 파일과 명령을 다룰 수 있으므로 다음 항목을 지킵니다.

• [ ] 작업 전 새 Git 브랜치를 만들었다.
• [ ] .env, 인증서, API 키와 비밀번호를 노출하지 않았다.
• [ ] 회사 저장소의 AI 사용 정책을 확인했다.
• [ ] 처음 보는 셸 명령은 실행 목적을 확인했다.
• [ ] 삭제, 배포, 결제와 권한 변경은 직접 승인했다.
• [ ] 대규모 수정 전에 계획과 영향 파일을 검토했다.
• [ ] 수정 후 git diff를 직접 확인했다.
• [ ] 테스트와 린트 결과를 확인했다.
• [ ] 생성된 의존성과 라이선스를 검토했다.
• [ ] 외부 전송 가능한 정보만 사용했다.

---

자주 묻는 질문

코딩 초보자도 Claude Code를 사용할 수 있나요?

가능합니다. 다만 생성된 코드를 무조건 실행하기보다 “먼저 설명하고 수정하지 마”, “변경 계획을 보여줘”, “테스트 결과를 알려줘” 같은 확인 단계를 넣어야 합니다.

Claude Code는 무료인가요?

일반적으로 Pro, Max, Team, Enterprise 구독 또는 Claude Console 계정이 필요합니다. 정확한 제공 범위와 요금은 계정과 시점에 따라 달라질 수 있으므로 공식 요금 페이지를 확인합니다.

Windows에서도 사용할 수 있나요?

Windows 10 1809 이상에서 네이티브 설치와 WinGet 설치를 지원합니다. PowerShell과 CMD의 설치 명령이 다르므로 현재 터미널에 맞는 명령을 사용해야 합니다.

VS Code에서만 사용할 수 있나요?

아닙니다. 터미널, VS Code, JetBrains IDE, 데스크톱 앱과 웹 등 여러 환경에서 사용할 수 있습니다.

Claude Code가 모든 명령을 자동 실행하나요?

작업과 권한 설정에 따라 명령 실행 전 승인을 요청할 수 있습니다. 삭제, 배포, 데이터 변경처럼 되돌리기 어려운 작업은 항상 직접 확인하는 방식으로 운영하는 것이 안전합니다.

CLAUDE.md와 일반 프롬프트의 차이는 무엇인가요?

CLAUDE.md는 프로젝트에서 반복되는 빌드 명령, 코딩 규칙과 작업 절차를 저장합니다. 이번 작업에만 필요한 요구 사항은 대화 프롬프트에 적는 편이 좋습니다.

---

마무리

Claude Code를 잘 쓰는 핵심은 더 많은 코드를 한 번에 생성하는 것이 아닙니다.

먼저 코드베이스를 이해하고, 변경 계획과 영향 범위를 검토한 뒤, 작은 단위로 수정하고 테스트하는 흐름을 만드는 것이 중요합니다. 처음에는 다음 세 문장만 기억해도 됩니다.

먼저 구조와 원인을 설명하고 아직 수정하지 마.

변경할 파일과 테스트 계획을 보여줘.

수정 후 diff, 테스트 결과와 남은 위험을 요약해줘.

Claude 자체가 처음이라면 Claude 사용법 완벽 가이드, 요청문을 개선하려면 Claude 프롬프트 작성법, 오류가 발생했을 때는 Claude 오류 해결 가이드를 함께 참고하세요.

---

공식 출처

• Claude Code Docs: Overview
• Claude Code Docs: Quickstart
• Claude Code Docs: Advanced setup
• Claude Code Docs: Common workflows
• Claude Code Docs: How Claude remembers your project
• Claude Help Center: Use Claude Code with your Pro or Max plan
• Claude Help Center: Troubleshoot Claude Code installation and authentication

이 글은 2026년 7월 28일 기준 Anthropic 공식 문서를 바탕으로 작성했습니다. 설치 명령, 지원 환경과 요금제 범위는 이후 변경될 수 있습니다.