이 글에선 이론을 넘어 실제 프로젝트에 Claude Code를 도입하고 활용하는 구체적인 방법을 다룹니다.
설치부터 MCP 서버 확장까지, 단계별로 따라 하면서 여러분만의 AI 개발 워크플로우를 구축할 수 있습니다.
.
.
.
Claude Code 설치 및 초기 설정
설치 방법
npm install -g @anthropic-ai/claude-code
claude # 명령어로 실행
로그인 방법을 선택해야 합니다. 첫번째는 Claude 계정 구독자(Pro 이상)에게 주어지는 API로 로그인 하는 것이고, 두번째는 선/후불 요금제로 API를 사용하는 것입니다. 본인에게 적합한 방식으로 결제해서 사용할 수 있습니다.
| 1. $20 Pro 구독 방식 | 2. API 종량제 방식 | |
| 누가 | 오직 claude-code 터미널만 매우 활발하게 사용하는 개발자 | claude-code를 가끔 쓰거나, 자신만의 프로그램에 Claude를 연동하고 싶은 개발자 |
| 장점 | 압도적인 비용 효율성 | 무한한 유연성과 확장성 |
| 단점 | 프로그래밍 접근 불가 (오직 claude-code에서만 사용) | 예측 불가능한 비용 (사용량에 따라 증가) |
2025.08.06 기준 Pro 요금제에선 Opus 모델을 사용할 수 없고, Sonet 모델만 사용 가능합니다.
프로젝트 초기화 (/init)
새로운 프로젝트에서 Claude Code를 처음 실행할 때는 /init 명령어를 사용하는 것이 필수입니다. 이 명령어는 Claude Code가 코드베이스 전체를 분석하여 다음과 같은 정보를 파악하게 합니다.
- 프로젝트의 목적과 일반적인 아키텍처
- 주요 기술 스택과 의존성
- 일반적으로 사용되는 명령어들
- 중요한 파일들과 디렉토리 구조
분석 결과는 [프로젝트]/CLAUDE.md 파일에 자동으로 저장되며, 이후 모든 작업의 맥락(Context)으로 활용됩니다.
프로젝트 규모에 따라 초기 분석 비용이 높을 수 있지만, 이 초기 투자는 향후 Claude Code 활용 효율성을 크게 향상시키는 중요한 기반이 됩니다.
Claude Code는 아래 표와 같이, 범위와 목적이 서로 다른 3단계의 마크다운 맥락(Context) 파일을 사용해 자동으로 필요한 정보만 골라 LLM에 전달합니다. 덕분에 토큰 비용을 최소화하면서도 전역 규칙·프로젝트 규칙·개인 규칙을 세분화해 관리할 수 있습니다.
| 구분 | ~/.claude/CLAUDE.md | [프로젝트]/CLAUDE.md | [프로젝트]/CLAUDE.local.md |
| 핵심 역할 | 전역 설정 (Global Settings) | 프로젝트 설정 (Project Settings) | 개인 설정 (Personal Settings) |
| 비유 | 전사 공통 업무 규정집 | 팀 전용 프로젝트 가이드북 | 나만 보는 포스트잇 메모 |
| 적용 범위 | 내 컴퓨터의 모든 프로젝트 | 해당 프로젝트에만 적용 | 해당 프로젝트 & 나에게만 적용 |
| 주요 내용 | - 개인적인 코딩 철학 - 모든 프로젝트에 적용될 스타일 가이드 - AI의 말투나 성격 설정 | - `/init`으로 분석된 프로젝트 아키텍처 - 주요 개발 명령어 - 기술 스택, 핵심 로직 요약 | - 나만의 코드 스타일 선호도 - 팀 규칙과 다른 개인적인 규칙 - 실험적인 프롬프트나 지시사항 |
| 공유 여부 | 공유 안 함 (내 컴퓨터에만 존재) | 팀원 전체와 공유 (Git에 커밋) | 공유 안 함 (반드시 .gitignore 처리) |
| 생성 방법 | 사용자가 직접 생성 및 편집 | `/init`으로 자동 생성 후 수동 편집 가능 | 사용자가 직접 생성 및 편집 |
핵심 단축키와 특수 명령어
특수 명령어: 기호로 시작하는 강력한 도구들
| 기호 | 이름 | 설명 | 예시 |
| ! | Bash 모드 | 터미널 명령어를 Claude에게 직접 실행시킬 때 사용 | !ls -al |
| / | 슬래시 명령어 | Claude Code의 내장 기능을 호출할 때 사용 | /init, /config |
| @ | 파일 맨션 | 특정 파일에만 집중해서 작업하도록 지시할 때 사용 | @src/index.js |
| # | 기억 주입 | AI에게 새로운 규칙을 가르치고 저장할 때 사용 | # 항상 한국어로 설명해줘 |
키보드 단축키(Windows 11)
| 단축키 | 기능 | 설명 |
| ESC 두 번 | 입력 초기화 | 현재 입력창에 쓰고 있는 내용을 전부 지웁니다 |
| Alt + M | 자동 승인 모드 전환 | AI의 모든 제안을 자동으로 수락하는 모드를 켜고 끕니다 (Planning mode ↔ Auto-Accept) |
| Ctrl + R | 상세 출력 (Verbose) | AI가 백그라운드에서 무슨 도구를 쓰고, 어떤 생각을 하는지 더 자세한 로그를 봅니다 |
| Shift + Enter | 줄바꿈 (Newline) | 프롬프트를 입력할 때, 여러 줄로 길게 입력하고 싶을 때 사용 |
| Ctrl + _ | 실행 취소 (Undo) | 바로 이전에 했던 작업을 취소하고 싶을 때 사용 |
단축키는 운영체제마다 다를 수 있으니 ? 로 단축키를 확인하는 것이 가장 좋습니다.
고급 활용 기능
계획 모드
Alt + m(Windows11 VSC)을 누를 때 마다 3가지 모드가 순환됩니다. 이 중, 계획 모드를 활성화하면 Claude가 작업을 수행하기 전, 단계별 계획을 텍스트로 먼저 제시합니다. 사용자는 이 계획을 검토하고 필요에 따라 수정한 후 실행을 승인할 수 있습니다.
기본 모드(OFF)
- Claude가 바로 도구를 실행하고 결과를 제안합니다.
계획 모드(plan mode on)
- Claude가 “1단계, 2단계…” 식의 실행 계획부터 텍스트로 보여주고 사용자가 수락(Enter) or 수정 후 승인해야 실제 작업을 시작합니다.
자동 승인 모드(auto-accept edits on)
- Claude가 코드 변경 제안까지 스스로 “확정”해 버립니다.
- 사용자는 따로 승인하지 않아도 제안이 바로 적용됩니다.
Thinking Modes (추론 모드)
- 상세한 지시: "이 문제를 단계별로 분석하고 각 단계의 이유를 설명해줘"
- 계획 모드 활용: Alt + M으로 계획 모드를 켜서 Claude가 체계적인 접근 계획을 먼저 세우도록 하기
- 맥락 제공: 관련 파일들을 @멘션으로 명시하여 충분한 정보 제공 이런 접근법들은 토큰 사용량을 증가시키지만, 더 정확하고 체계적인 결과를 얻을 수 있습니다.
이 기능은 까다로운 로직 구현이나 어려운 버그 해결 시 특히 유용합니다. 단 토큰수가 올라 API 사용량이 더 높아집니다.
과거 세션으로 돌아가기 (ESC)
- ESC 한 번: 현재 작업을 중단하여 실시간으로 방향을 조정할 수 있습니다
- ESC 두 번: 모든 대화 기록을 확인하고, 특정 시점으로 돌아가서 새로운 지시를 내릴 수 있습니다
과거로 돌아가서 새 지시를 내리면 그 시점부터 새로운 분기가 시작되며, 이전의 잘못된 흐름은 모두 버려집니다. 이는 비용 절약과 불필요한 대화 기록 정리에 매우 유용합니다.
세션 관리 명령어
/compact: 스마트한 대화 압축
=> 현재까지의 긴 대화 내용을 AI가 스스로 요약하여 핵심만 남기고 세부사항은 제거하는 기능입니다. 전체 대화 토큰 수를 줄이면서도 중요한 맥락은 유지할 수 있습니다.
/clear: 완전한 새 시작
=> 하나의 작업이 완전히 끝나고 이전과 관련 없는 새로운 작업을 시작할 때, 모든 대화 기록을 지우고 처음부터 다시 시작할 수 있게 합니다.
claude --resume: 이전 세션 복구 (Claude Code 실행환경이 아닌 터미널에서)
=> 특정 이전 세션을 선택하여 중단된 대화를 이어서 진행할 수 있습니다.
사용자 정의 명령어
`/` 를 입력하면 Claude Code에 내장된 다양한 명령을 확인할 수 있습니다. 더 나아가, 사용자만의 명령어를 정의할 수도 있습니다.
- 프로젝트 디렉터리에 .claude/commands 디렉터리를 생성
- 마크다운(.md) 파일로 명령어 파일을 작성
- Claude Code를 재시작
- `/명령어 파일명` 으로 실행
파일명: .claude/commands/create_component.md
$ARGUMENTS에 대한 완전한 React 컴포넌트를 생성해주세요.
요구사항:
- TypeScript 사용
- Tailwind CSS로 스타일링
- Props 인터페이스 정의
- 기본 상태 관리 포함
컴포넌트는 src/components/ 디렉터리에 저장해주세요.사용 예시
/create_component 사용자 프로필 카드 컴포넌트
이때 `$ARGUMENTS` 자리에 "사용자 프로필 카드 컴포넌트"가 들어가며, 정확한 경로가 아닌 자연어로 지시해도 잘 동작합니다.
MCP 서버를 통한 기능 확장
MCP(Model Context Protocol) 서버를 추가하면 Claude Code의 기능을 대폭 확장할 수 있습니다. 이 서버들은 로컬 또는 원격에서 실행되며, 일반적으로 제공되지 않는 새로운 도구와 기능을 제공합니다. 로컬 vs 원격 실행의 차이는 다음과 같습니다.
- 로컬 실행: 사용자의 화면을 캡처하거나 로컬 파일 시스템을 제어하는 도구
- 원격 실행: 중앙 데이터베이스 서버나 클라우드 서비스와 연결되는 고성능 도구
웹 브라우저 제어에 가장 많이 사용되는 Playwright MCP 서버 설치 방법
# macOS/Linux
claude mcp add playwright npx @playwright/mcp@latest
# Windows 11
claude mcp add playwright -- cmd /c "npx @playwright/mcp@latest"
권한 설정
=> .claude/settings.local.json 파일에서 MCP 서버 사용을 허용합니다. 이 설정으로 Claude Code는 권한 요청 없이 Playwright를 신뢰할 수 있는 도구로 사용할 수 있게 됩니다.
{
"permissions": {
"allow": ["mcp__playwright"],
"deny": []
}
}기존에는 웹 브라우저와 직접적인 상호작용이 불가능했지만, Playwright MCP를 통해 브라우저를 직접 제어하고 시각적 분석을 진행하여 훨씬 효과적인 작업 처리가 가능해집니다.
아래 명령어로 Claude를 실행하면 모든 권한을 풀어주어 중간중간 사용자에게 물어보지 않고 자동으로 진행해줍니다.
claude --dangerously-skip-permissions
한국어 설정
Claude Code와의 대화는 모두 영어이다. 한국어로 말을 해도 영어로만 답변과 설명, 주석이 달릴 수 있는데 CLAUDE.md 파일에 아래 내용을 추가해주면 한국어 설명과 주석으로 활용할 수 있다.
## Claude 활용 가이드
- 코드 생성, 코드 리뷰, 질문 시 모든 답변은 한국어로 작성해 주세요.
- 코드 설명, 오류 지적, TODO 리스트 등도 반드시 한국어로 출력하게 해주세요.이렇게 해도 한글 답변이 나오지 않을 경우 프롬포트 첫 줄에
"이후 모든 답변은 한국어로 해주세요. 앞으로 코드 설명, 실수 지적, TODO도 한글로 부탁합니다."
이런식으로 추가해준다.
'AI > Claude' 카테고리의 다른 글
| Claude Code Hooks 활용 (3) | 2025.08.06 |
|---|---|
| 최고의 AI 파트너, Claude Code (4) | 2025.08.04 |