Claude Code 사용법 완벽 가이드 - 설치부터 MCP 서버, CLAUDE.md 설정까지

⚠️ 이 문서는 생성형 AI를 통해 작성되었으며, 내용에 오류가 있을 수 있습니다.

⚠️ This article was drafted by an AI-assisted triage tool and may contain mistakes.

AI 요약 & 가이드

Claude Code를 처음 써보는 사람이 설치부터 실제 협업 흐름까지 한 번에 따라갈 수 있게 정리했습니다. 터미널에서 코드를 읽고 수정하는 기본 사용법뿐 아니라, CLAUDE.md로 프로젝트 규칙을 주는 방법과 MCP 서버를 붙여 확장하는 흐름까지 함께 다룹니다.

• Claude Code가 무엇인지: 일반 채팅형 AI와 다른 에이전트형 도구의 특징을 먼저 설명합니다.
• 어디서 사용할 수 있는지: CLI, IDE 확장, 웹 환경 차이를 간단히 비교합니다.
• 시작 방법: 설치, 로그인, 프로젝트 디렉터리 실행, 첫 요청 예시까지 이어집니다.
• 슬래시 커맨드: 자주 쓰는 명령어와 작업 속도를 높이는 패턴을 정리합니다.
• CLAUDE.md 설정: 코드 규칙, 수정 금지 조건, 프로젝트 맥락을 전달하는 방법을 설명합니다.
• MCP 서버 연동: 외부 도구와 연결해 Claude Code를 더 실무형으로 쓰는 방법을 다룹니다.

AI 코딩 도구가 빠르게 늘어나고 있는데, 그 중에서도 에이전트형 도구는 단순 자동완성과 꽤 다른 범주입니다. 채팅창에서 코드 일부를 물어보는 도구가 "코드를 설명해주는 도우미"라면, Claude Code는 "실제 작업을 맡기고 결과를 검토하는 협업 상대"에 더 가깝습니다.

예를 들어 "이 버그를 고쳐줘", "테스트를 추가해줘", "이 함수를 리팩터링해줘" 같은 요청을 주면, Claude Code는 프로젝트 파일을 읽고, 필요한 명령을 실행하고, 실제 변경안까지 만들어낼 수 있습니다. 이번 글에서는 Claude Code를 처음 접하는 분도 바로 시작할 수 있도록 기본 개념부터 실제 사용 흐름까지 정리해봤습니다.

Claude Code는 무엇인가 #

Claude Code by Anthropic | AI Coding Agent, Terminal, IDE

Anthropic's agentic coding tool for developers. Claude Code understands your codebase, edits files, runs commands, …

claude.com

Anthropic이 만든 Claude Code는 터미널에서 동작하는 AI 코딩 에이전트입니다. 단순히 질문에 답하는 수준을 넘어서, 실제 코드를 읽고 수정하고 명령을 실행하는 개발 작업을 처리할 수 있습니다.

이 점 때문에 Claude Code는 아래 같은 일에 특히 잘 맞습니다.

• 현재 프로젝트 구조 파악
• 버그 원인 분석 및 수정
• 특정 파일이나 함수 리팩터링
• 테스트 코드 작성
• 반복적인 문서화 작업
• Git 커밋 메시지 작성

중요한 점은 Claude Code를 "결과를 바로 신뢰하는 도구"라기보다, 실행 가능한 변경안을 빠르게 만드는 도구로 접근해야 한다는 것입니다. 개발자가 검토하고 승인하는 흐름과 함께 써야 가장 효율이 좋습니다.

Claude Code는 어디서 사용할 수 있는가 #

Claude Code는 CLI, IDE 확장, 웹 세 가지 환경에서 사용할 수 있습니다.

1. Claude Code CLI #

CLI는 터미널에서 직접 실행하는 방식입니다. 로컬 디렉터리 안에서 파일을 읽고, 수정하고, 명령을 실행하는 흐름에 가장 자연스럽습니다.

터미널 중심으로 일하는 개발자라면 가장 먼저 익히기 좋은 인터페이스입니다. 특히 아래 같은 작업과 궁합이 좋습니다.

• 현재 레포 구조 설명 요청
• 테스트 실행과 실패 원인 분석
• 작은 범위의 버그 수정
• 여러 파일을 건드리는 리팩터링 초안

2. IDE 확장 #

IDE 확장은 VS Code나 JetBrains 계열 IDE 안에서 Claude Code를 쓰는 방식입니다. VS Code Extension Marketplace에서 "Claude Code"를 검색해 설치할 수 있습니다.

이 방식의 장점은 코드와 대화 창이 같은 화면에 있다는 점입니다. 파일을 열어둔 채 질문하고, 변경 사항을 바로 비교하고, 필요한 부분만 적용하기 편합니다.

3. Claude.ai 웹 #

claude.ai/code에서 웹 브라우저로도 Claude Code를 사용할 수 있습니다. 로컬 환경 없이 간단한 작업을 맡기거나 데모를 먼저 경험해보고 싶을 때 유용합니다.

Claude Code 시작하기 #

1. 설치하기 #

Claude Code CLI는 npm으로 설치합니다.

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

설치 후 버전을 확인해볼 수 있습니다.

% claude --version
1.x.x

2. 로그인하기 #

처음 실행하면 Anthropic 계정으로 로그인하거나 API 키를 입력하라는 안내가 나옵니다.

claude

또는 환경 변수에 API 키를 설정해두면 바로 시작할 수 있습니다.

export ANTHROPIC_API_KEY=sk-ant-...

3. 프로젝트 디렉터리에서 실행하기 #

작업하려는 프로젝트 루트 디렉터리로 이동한 뒤 claude 명령어를 실행합니다.

cd my-project
claude

이후부터는 Claude Code가 현재 디렉터리를 기준으로 파일을 읽고 명령을 실행합니다.

4. 첫 작업 지시해보기 #

터미널 안에서 자연어로 작업을 지시하면 됩니다.

이 프로젝트 구조를 간략하게 설명해줘.

src/utils/parser.ts 파일에서 parseDate 함수를 찾아 리팩터링해줘.

명령줄에서 바로 실행하고 싶다면 -p 옵션을 사용할 수 있습니다.

claude -p "README.md 파일을 읽고 누락된 섹션이 있으면 알려줘"

슬래시 커맨드 활용하기 #

Claude Code 대화 중에는 /로 시작하는 슬래시 커맨드를 사용할 수 있습니다. 자주 쓰는 커맨드를 알아두면 흐름이 훨씬 빨라집니다.

슬래시 커맨드 외에도 # 기호를 붙이면 특정 파일을 컨텍스트에 추가할 수 있습니다.

#src/auth/login.ts 이 파일의 인증 흐름을 설명해줘

CLAUDE.md로 프로젝트 맥락 주기 #

Claude Code는 프로젝트 루트에 CLAUDE.md 파일이 있으면 자동으로 읽어서 컨텍스트로 활용합니다. 팀 규칙, 아키텍처 개요, 금지 패턴, 자주 쓰는 명령어 등을 여기에 적어두면 매번 설명하지 않아도 Claude Code가 프로젝트 맥락을 이해하고 작동합니다.

/init 커맨드를 실행하면 현재 프로젝트를 분석해 CLAUDE.md 초안을 자동으로 만들어줍니다.

/init

직접 작성하고 싶다면 아래처럼 구성하는 것을 추천합니다.

# 프로젝트 개요

Python 기반 REST API 서버입니다. FastAPI를 사용하며 PostgreSQL과 연동됩니다.

## 주요 명령어

- 서버 실행: `uvicorn main:app --reload`
- 테스트: `pytest tests/`
- 린트: `ruff check .`

## 코드 규칙

- 모든 함수에는 타입 힌트를 작성합니다.
- 새로운 엔드포인트를 추가할 때는 테스트도 함께 작성합니다.
- 절대로 `print()`를 로깅 목적으로 사용하지 않습니다.

## 수정 금지 목록

- `config/secrets.py`는 수정하지 마세요.
- `migrations/` 폴더 안의 파일은 수동으로 관리합니다.

MCP 서버 연동 #

Claude Code는 MCP(Model Context Protocol)를 통해 외부 서비스와 연결할 수 있습니다. GitHub, Slack, 데이터베이스, 사내 API 등을 MCP 서버로 등록하면 Claude Code가 해당 서비스의 데이터를 직접 읽고 활용할 수 있습니다.

MCP 서버 설정은 /config를 열거나 ~/.claude/settings.json을 직접 수정하면 됩니다.

예를 들어 GitHub MCP 서버를 추가하면 아래처럼 PR 정보를 직접 물어볼 수 있습니다.

현재 열린 PR 중에서 리뷰가 아직 안 된 것들을 알려줘.

공식적으로 지원하는 MCP 서버 목록은 Anthropic 공식 문서에서 확인할 수 있습니다.

처음 보낼 만한 요청 예시 #

처음부터 너무 큰 작업을 주면 결과 검토가 오히려 어려워질 수 있습니다. 아래처럼 작고 검증 가능한 요청부터 시작하는 편이 좋습니다.

이 프로젝트 구조를 10줄 안으로 요약해줘.

테스트가 없는 핵심 함수를 3개만 찾아줘.

이 에러 로그의 원인을 추정하고 수정 후보를 제안해줘.

현재 동작은 유지하면서 이 함수만 리팩터링해줘.

핵심은 작업 범위와 검토 기준이 명확해야 한다는 점입니다. "전부 고쳐줘"보다 "이 파일만", "테스트 포함", "동작 유지"처럼 제약을 명확히 줄수록 결과가 좋습니다.

Claude Code 프롬프트 잘 쓰는 방법 #

Claude Code는 단순 질의응답보다 작업 수행에 강한 도구라서, 프롬프트를 쓸 때도 "무엇을", "어디까지", "어떤 기준으로" 할지 명시해주는 것이 중요합니다.

1. 범위를 먼저 제한하기 #

좋지 않은 예시:

버그를 고쳐줘.

더 좋은 예시:

로그인 실패 시 500이 나는 문제를 찾아줘.
수정 범위는 auth 모듈 안으로 제한하고, 공개 API 응답 형식은 바꾸지 마.

2. 성공 기준을 함께 적기 #

이 함수의 동작은 유지하면서 가독성을 개선해줘.
중첩 조건문을 줄이고, 기존 테스트가 통과하도록 해줘.

3. 검토 방식을 요청하기 #

바로 수정하지 말고,
먼저 원인 분석 -> 수정 계획 -> 실제 변경 순서로 진행해줘.

Claude Code는 꽤 적극적으로 움직이는 편이기 때문에, 중요한 작업에서는 이런 식으로 중간 점검 단계를 요구하는 것이 유용합니다.

4. 변경 금지 조건 적기 #

다른 파일은 수정하지 말고,
새 패키지는 추가하지 말고,
테스트 파일만 새로 만들어줘.

AI 에이전트는 할 수 있는 일이 많을수록 넓게 움직이기 쉬워서, 금지 조건이 있어야 검토 비용이 줄어듭니다.

이런 상황에서 특히 유용하다 #

레거시 코드 파악 #

낯선 프로젝트를 처음 열었을 때 "엔트리포인트가 어디인지", "핵심 비즈니스 로직이 어느 파일에 있는지", "테스트가 어느 수준까지 깔려 있는지"를 빠르게 파악하는 데 유용합니다.

작은 버그 수정 #

재현 가능한 에러 메시지와 수정 범위를 같이 주면 원인 후보를 좁히고 패치를 제안받는 흐름이 꽤 효율적입니다.

테스트 코드 보완 #

기존 함수에 대한 테스트 초안을 만들고, 빠진 엣지 케이스를 함께 정리하는 데 시간을 많이 줄여줍니다.

Git 작업 자동화 #

커밋 메시지 초안 작성, PR 설명 생성, 변경사항 요약 같은 반복 작업에도 잘 맞습니다.

현재 스테이징된 변경사항을 보고 적절한 커밋 메시지를 제안해줘.

한계도 분명히 있다 #

Claude Code가 강력한 도구인 것은 맞지만, 아래 부분은 여전히 사람이 직접 판단해야 합니다.

1. 그럴듯하지만 틀린 수정 #

컴파일은 되지만 요구사항을 어기는 변경, 테스트는 통과하지만 장기적으로 유지보수성이 떨어지는 수정이 나올 수 있습니다.

2. 프로젝트의 숨은 맥락은 완전히 알지 못함 #

팀 규칙, 배포 관례, 비즈니스 우선순위, 문서에 없는 제약까지 Claude Code가 스스로 완전히 이해한다고 기대하면 곤란합니다. CLAUDE.md를 잘 구성해두는 것이 이 한계를 줄이는 가장 현실적인 방법입니다.

3. 큰 작업은 쪼개야 잘 된다 #

"서비스 전체 구조를 개선해줘" 같은 요청보다 "API 레이어 중복 제거", "이 함수 테스트 추가", "이 경고 수정"처럼 작업을 분할했을 때 훨씬 안정적으로 결과가 나옵니다.

추천 사용 흐름 #

처음 Claude Code를 도입한다면 아래 순서를 추천합니다.

1. 프로젝트 요약과 구조 설명부터 시켜보기
2. 읽기 위주 작업으로 버그 원인 분석 맡기기
3. 작은 파일 한두 개만 수정하게 해보기
4. /init으로 CLAUDE.md 초안 만들어 프로젝트 맥락 설정하기
5. 테스트 추가나 리팩터링 초안 작성 맡기기
6. 익숙해지면 MCP 서버로 외부 서비스까지 연동해보기

터미널에서 빠르게 지시하고 결과를 보는 CLI가 잘 맞는 사람도 있고, IDE 안에서 바로 대화하며 수정하는 흐름이 편한 사람도 있습니다. 본인 작업 스타일에 맞는 인터페이스를 먼저 찾는 것이 중요합니다.

마무리 #

Claude Code는 "코드를 대신 써주는 자동완성"보다 한 단계 더 나아간 도구입니다. 읽고, 실행하고, 수정하고, 경우에 따라 작업을 위임하는 흐름까지 포함하는 AI 코딩 에이전트라고 보는 편이 더 정확합니다.

처음에는 거창한 자동화보다, "이 프로젝트를 설명해줘", "이 함수만 수정해줘", "테스트 초안을 만들어줘"처럼 작은 작업부터 맡겨보는 것이 좋습니다. 그렇게 써보면 Claude Code의 핵심은 마법 같은 정답 생성보다, 개발자가 검토 가능한 속도로 작업을 앞당겨주는 것이라는 점이 분명하게 보입니다.

CLI, VS Code 확장, 웹 환경을 모두 지원하므로 자신의 개발 습관에 가장 잘 맞는 진입점을 골라 시작하면 됩니다.