[Claude Code] Claude Code 설치부터 실전 활용까지

들어가며

터미널에서 AI와 직접 코딩할 수 있다는 게 처음엔 잘 와닿지 않았다. 그냥 또 다른 챗봇 아닌가 싶었는데, 실제로 써보니 달랐다. 파일을 직접 읽고 수정하고, Git 커밋까지 해준다. 프로젝트 전체를 이해한 상태에서 대화가 진행된다.

이 글에서 다루는 내용은 다음과 같다.

설치: macOS, Linux, Windows 각각
기본 사용법: 실행 모드와 슬래시 명령어
CLAUDE.md: 프로젝트에 맞게 Claude를 세팅하는 방법
커스텀 명령어: 자주 쓰는 작업을 슬래시 명령어로 등록하기
MCP: 외부 도구(GitHub, Notion 등)와 연결하기

모든 명령어는 바로 복사해서 쓸 수 있도록 정리했다.

1. 사전 준비 — 요금제 확인

Claude Code를 쓰려면 Claude 계정이 필요하다. 무료 플랜은 지원하지 않는다.

플랜	가격	Claude Code	주요 특징
Pro	$20/월	O	가볍게 시작하기에 충분
Max 5x	$100/월	O	Pro 대비 5배 사용량, 1M 토큰 컨텍스트
Max 20x	$200/월	O	Pro 대비 20배 사용량, Agent Teams
API (종량제)	토큰당	O	자동화/CI 파이프라인에 적합

처음 시작한다면 Pro($20)로 충분하다. 사용량이 늘면 Max로 업그레이드하면 된다.
요금은 작성 시점 기준이며 변동될 수 있다. 최신 정보는 claude.com/pricing 에서 확인.

2. 설치하기

2-1. macOS / Linux (권장)

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

자동 업데이트가 지원되므로 항상 최신 버전을 유지할 수 있다. macOS에서는 이 방법을 가장 먼저 추천한다.

2-2. macOS — Homebrew

brew install --cask claude-code

Homebrew를 선호한다면 이 방법을 써도 된다. 다만 자동 업데이트는 지원되지 않아서 직접 업그레이드해야 한다.

# 업데이트할 때
brew upgrade claude-code

2-3. Windows

PowerShell:

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

WinGet:

winget install Anthropic.ClaudeCode

2-4. 설치 확인

# 버전 확인
claude --version

# 설치 진단 (API 연결, 환경 설정 등 자동 체크)
claude doctor

claude doctor를 실행하면 설치 상태를 한 번에 점검해준다. 문제가 있으면 해결 방법도 안내해주므로 설치 후 한 번 꼭 실행해보자.

3. 첫 번째 실행 — 로그인부터 대화까지

3-1. 프로젝트 디렉토리에서 시작

cd your-project
claude

Claude Code는 현재 디렉토리를 기준으로 프로젝트 전체를 파악한다. 프로젝트 루트에서 실행하는 게 기본이다.

3-2. 최초 로그인

처음 실행하면 로그인 안내가 나온다. 대화 중에서도 아래 명령어로 언제든 로그인/계정 전환이 가능하다.

/login

브라우저가 열리고 Claude 계정으로 인증하면 된다. 이후에는 자동으로 인증 상태가 유지된다.

3-3. 프로젝트 파악시키기

로그인 후 바로 프로젝트를 파악시켜보자. Claude는 현재 디렉토리의 파일 구조와 코드를 읽는다.

이 프로젝트 구조를 설명해줘

src/auth 폴더에 있는 코드를 분석해줘

3-4. 파일 수정 요청

코드 수정을 요청하면 Claude가 변경 내용을 보여주고 승인을 기다린다.

UserController.java에서 로그인 실패 시 에러 메시지를 더 구체적으로 바꿔줘

변경 전/후 diff가 출력되고, y를 누르면 실제 파일에 반영된다.

4. 실행 모드 정리

# 대화형 모드 (기본 — 가장 많이 쓰는 모드)
claude

# 단발 작업 (한 가지 일 시키고 종료)
claude "빌드 에러 고쳐줘"

# 파이프 모드 (결과만 출력하고 종료 — 스크립트/파이프라인용)
claude -p "이 함수의 역할을 설명해줘"

# 마지막 대화 이어하기
claude -c

# 이전 대화 선택하여 재개
claude -r

claude -c는 생각보다 자주 쓰게 된다. 터미널을 닫았다가 다시 열어서 이전 작업을 이어할 때 편하다.

5. 슬래시 명령어 정리

대화 중에 /로 시작하는 명령어를 쓸 수 있다.

명령어	설명
`/help`	사용 가능한 명령어 목록
`/clear`	대화 히스토리 초기화
`/compact`	컨텍스트 압축 (대화가 길어졌을 때)
`/cost`	토큰 사용량 및 비용 확인
`/model`	모델 전환 (Sonnet ↔ Opus)
`/vim`	Vim 모드 토글
`/review`	코드 리뷰 요청
`/doctor`	설치 진단
`/login`	계정 로그인 / 전환
`/terminal-setup`	Shift+Enter 멀티라인 입력 설정

핵심 포인트

/compact는 꼭 알아두자. 대화가 길어지면 컨텍스트 한도에 가까워진다. /compact를 쓰면 대화 내용을 요약해서 컨텍스트를 확보한다. 안 쓰면 나중에 응답이 잘리거나 이전 내용을 잊어버리는 경우가 생긴다.

/cost로 사용량 파악. 얼마나 쓰고 있는지 감이 안 잡힐 때 /cost를 치면 토큰 사용량과 예상 비용이 바로 나온다.

6. Git 연동

Claude Code는 Git 작업을 자연어로 처리할 수 있다. 터미널에서 직접 쓸 수 있는 단축 명령어도 있다.

# 변경 사항 분석해서 커밋 메시지 자동 생성 + 커밋
claude commit

대화 중에는 자연어로 Git 작업을 시킬 수 있다.

변경 사항에 맞는 커밋 메시지를 만들어서 커밋해줘
feature/login 브랜치를 만들어줘
마지막 5개 커밋을 보여줘
머지 충돌을 해결해줘

파이프라인과 결합하면 이렇게도 활용할 수 있다.

# 변경 파일 목록을 Claude에게 넘겨서 보안 이슈 점검
git diff main --name-only | claude -p "변경된 파일에서 보안 이슈를 점검해줘"

7. CLAUDE.md — 프로젝트에 맞게 세팅하기

CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일이다. Claude Code를 실행할 때마다 자동으로 읽어서 프로젝트 컨텍스트로 활용한다. 한 번 잘 써두면 매번 설명을 반복하지 않아도 된다.

7-1. 빠르게 생성하기

# Claude Code가 현재 프로젝트를 분석해서 CLAUDE.md 초안을 만들어줌
claude

대화 중:

/init

7-2. 직접 작성 예시

프로젝트 루트에 CLAUDE.md 파일을 만들고 아래처럼 작성한다.

# 프로젝트 가이드

## 프로젝트 개요
Spring Boot 기반 REST API 서버.
Java 17, Spring Boot 3.x, MyBatis, MariaDB 사용.

## 프로젝트 구조
- src/main/java/com/example/api/ -- API 모듈
- src/main/java/com/example/core/ -- 공통 모듈

## 빌드 & 실행
- 빌드: ./gradlew build
- 실행: ./gradlew bootRun
- 테스트: ./gradlew test

## 코딩 컨벤션
- 변수명: camelCase
- 클래스명: PascalCase
- 들여쓰기: 4칸 스페이스
- 응답 래퍼: ApiResponse<T> 사용
- 예외 처리: BusinessException(ErrorMessage.XXX) 패턴

## 커밋 메시지
- 형식: [모듈명] 변경 내용 설명
- 예시: [API] 로그인 비밀번호 검증 로직 수정

핵심 포인트

어떤 내용을 넣으면 좋을까. 크게 네 가지를 넣으면 효과적이다.

프로젝트 구조: 어떤 디렉토리에 뭐가 있는지
빌드/실행 명령어: ./gradlew build, npm start 같은 명령어
코딩 컨벤션: 네이밍 규칙, 코드 스타일
아키텍처 결정: 중요한 설계 결정이나 패턴

이것만 있어도 Claude가 프로젝트에 맞는 코드를 훨씬 잘 작성한다.

8. 커스텀 슬래시 명령어 만들기

.claude/commands/ 디렉토리에 마크다운 파일을 만들면 자동으로 슬래시 명령어로 등록된다.

8-1. 프로젝트 수준 명령어

mkdir -p .claude/commands

파일 경로: .claude/commands/review.md

코드 리뷰를 수행해줘.

다음 기준으로 검토해줘:
1. 보안 취약점이 있는지
2. 성능 문제가 될 수 있는 부분
3. 네이밍 컨벤션 위반
4. 에러 처리가 누락된 곳

검토 대상: $ARGUMENTS

사용할 때:

/review src/main/java/com/example/api/UserController.java

$ARGUMENTS에 명령어 뒤에 입력한 경로가 들어간다.

8-2. 전역(글로벌) 명령어

모든 프로젝트에서 쓰고 싶은 명령어는 홈 디렉토리에 만든다.

mkdir -p ~/.claude/commands

파일 경로: ~/.claude/commands/security-check.md

코드에서 보안 취약점을 OWASP Top 10 기준으로 분석해줘.

각 항목별로 취약 여부와 개선 방법을 알려줘.

대상: $ARGUMENTS

8-3. 유용한 명령어 예시

PR 체크 (.claude/commands/pr-check.md):

이 PR의 변경사항을 요약하고,
잠재적인 버그나 개선점을 알려줘.

사용:

/pr-check

테스트 작성 (.claude/commands/write-test.md):

$ARGUMENTS 파일에 대한 단위 테스트를 작성해줘.

- 정상 케이스와 예외 케이스를 모두 포함해줘
- JUnit 5, Mockito 사용
- 테스트 메서드명은 한국어로 작성해줘

9. MCP 서버 연결하기

MCP(Model Context Protocol)를 통해 Claude Code에 외부 도구를 연결할 수 있다. GitHub PR 관리, Notion 문서 읽기, Slack 메시지 전송 등이 가능해진다.

9-1. 명령어로 추가하기

# GitHub MCP 서버 추가
claude mcp add github --scope user

# HTTP 방식으로 MCP 서버 추가
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 등록된 MCP 서버 목록 확인
claude mcp list

9-2. 설정 파일 직접 편집하기

복잡한 설정이 필요한 경우 ~/.claude/settings.json을 직접 편집한다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

GITHUB_TOKEN 자리에 실제 GitHub Personal Access Token을 넣으면 된다.

핵심 포인트

추천 MCP 서버 3가지:

MCP 서버	용도	특징
GitHub	PR 생성, 이슈 관리	코드 리뷰 자동화에 유용
Sequential Thinking	복잡한 문제를 단계별로 분해	설계 작업할 때 효과적
Context7	라이브러리 최신 문서 참조	버전별 API 변경사항 파악

10. 실전 활용 팁

10-1. 구체적으로 요청하기

모호한 요청보다 구체적인 요청이 훨씬 좋은 결과를 낸다.

# 좋지 않은 예
버그 고쳐줘

# 좋은 예
로그인 후 메인 화면이 빈 화면으로 나오는 버그를 고쳐줘.
UserController.java의 getMainPage() 메서드부터 확인해줘.

10-2. Git 브랜치 먼저 만들고 시작하기

Claude가 파일을 직접 수정하므로 실험적인 작업은 브랜치를 먼저 만드는 게 안전하다.

git checkout -b feature/try-refactoring
claude

10-3. 파이프라인 활용

claude -p를 파이프와 조합하면 강력해진다.

# 로그 에러 패턴 분석
tail -100 app.log | claude -p "에러 패턴을 분석하고 원인을 추정해줘"

# 테스트 실패 원인 분석
./gradlew test 2>&1 | claude -p "테스트 실패 원인과 수정 방법 알려줘"

# 변경 파일 보안 점검
git diff main --name-only | claude -p "변경된 파일에서 보안 이슈를 점검해줘"

# i18n 번역 자동화
claude -p "src/i18n/ko.json의 새로운 키를 영어로 번역해서 en.json에 추가해줘"

10-4. 단계별로 나눠서 요청하기

큰 작업은 한 번에 시키기보다 단계별로 나누는 게 결과가 좋다.

# 한 번에 시키는 것보다
인증 시스템 전체를 JWT로 리팩토링해줘

# 단계별로 나누는 게 낫다
1단계: 현재 인증 코드 구조를 분석해줘
2단계: JWT 도입 시 변경이 필요한 파일 목록을 정리해줘
3단계: UserService.java부터 수정해줘

11. 다른 환경에서 쓰기

터미널 CLI 외에도 여러 환경에서 Claude Code를 쓸 수 있다.

환경	특징	설치/접속 방법
터미널 CLI	풀 기능, 파일 편집/명령 실행/Git 통합	`curl` 또는 `brew`
VS Code	인라인 diff, 대화 히스토리, 멀티 세션	Extensions에서 "Claude Code" 검색
JetBrains	IntelliJ/PyCharm/WebStorm 지원	JetBrains Marketplace에서 설치
Desktop 앱	독립 실행, 시각적 diff 리뷰	공식 사이트에서 다운로드
Web	브라우저에서 실행, 로컬 설치 불필요	claude.ai/code 접속
Slack	버그 리포트 → PR 자동 생성	Slack 앱 추가

터미널이 익숙한 개발자라면 CLI가 가장 강력하다. IDE를 주로 쓴다면 VS Code나 JetBrains 플러그인이 워크플로우에 잘 맞는다.

마치며

처음엔 터미널에서 AI를 쓴다는 게 낯설게 느껴졌는데, 몇 번 써보면 금방 익숙해진다. 특히 CLAUDE.md를 잘 써두면 매번 설명을 반복하지 않아도 되는 게 생각보다 편하다.

이런 개발자에게 추천한다.

AI 코딩 도구를 써보고 싶은데 어디서 시작해야 할지 모르겠는 개발자
GitHub Copilot이나 Cursor를 써봤는데 터미널 기반 도구를 탐색 중인 개발자
반복적인 코드 리뷰, 커밋 메시지 작성 같은 작업을 자동화하고 싶은 개발자

설치부터 MCP 연결까지 한 번 따라해보면 감이 잡힐 것이다.

참고 링크

[Claude Code] Claude Code 설치부터 실전 활용까지 - 바이브 코딩

들어가며

1. 사전 준비 — 요금제 확인

2. 설치하기

2-1. macOS / Linux (권장)

2-2. macOS — Homebrew

2-3. Windows

2-4. 설치 확인

3. 첫 번째 실행 — 로그인부터 대화까지

3-1. 프로젝트 디렉토리에서 시작

3-2. 최초 로그인

3-3. 프로젝트 파악시키기

3-4. 파일 수정 요청

4. 실행 모드 정리

5. 슬래시 명령어 정리

핵심 포인트

6. Git 연동

7. CLAUDE.md — 프로젝트에 맞게 세팅하기

7-1. 빠르게 생성하기

7-2. 직접 작성 예시

핵심 포인트

8. 커스텀 슬래시 명령어 만들기

8-1. 프로젝트 수준 명령어

8-2. 전역(글로벌) 명령어

8-3. 유용한 명령어 예시

9. MCP 서버 연결하기

9-1. 명령어로 추가하기

9-2. 설정 파일 직접 편집하기

핵심 포인트

10. 실전 활용 팁

10-1. 구체적으로 요청하기

10-2. Git 브랜치 먼저 만들고 시작하기

10-3. 파이프라인 활용

10-4. 단계별로 나눠서 요청하기

11. 다른 환경에서 쓰기

마치며

댓글

이 글 공유하기

티스토리툴바

들어가며

1. 사전 준비 — 요금제 확인

2. 설치하기

2-1. macOS / Linux (권장)

2-2. macOS — Homebrew

2-3. Windows

2-4. 설치 확인

3. 첫 번째 실행 — 로그인부터 대화까지

3-1. 프로젝트 디렉토리에서 시작

3-2. 최초 로그인

3-3. 프로젝트 파악시키기

3-4. 파일 수정 요청

4. 실행 모드 정리

5. 슬래시 명령어 정리

핵심 포인트

6. Git 연동

7. CLAUDE.md — 프로젝트에 맞게 세팅하기

7-1. 빠르게 생성하기

7-2. 직접 작성 예시

핵심 포인트

8. 커스텀 슬래시 명령어 만들기

8-1. 프로젝트 수준 명령어

8-2. 전역(글로벌) 명령어

8-3. 유용한 명령어 예시

9. MCP 서버 연결하기

9-1. 명령어로 추가하기

9-2. 설정 파일 직접 편집하기

핵심 포인트

10. 실전 활용 팁

10-1. 구체적으로 요청하기

10-2. Git 브랜치 먼저 만들고 시작하기

10-3. 파이프라인 활용

10-4. 단계별로 나눠서 요청하기

11. 다른 환경에서 쓰기

마치며

댓글

이 글 공유하기

다른 글

티스토리툴바