Claude Code 초기 설정 완전 가이드 - 설치부터 CLAUDE.md, MCP 서버, 슬래시 커맨드까지
Claude Code 초기 설정 완전 가이드
Claude Code는 Anthropic이 제공하는 터미널 기반 AI 코딩 에이전트입니다. 파일 읽기·편집, 명령어 실행, Git 관리까지 개발 워크플로우 전반을 지원합니다. 이 가이드에서는 설치부터 CLAUDE.md 작성, MCP 서버 연동, 커스텀 슬래시 커맨드 구성까지 실무에 필요한 모든 설정을 단계별로 다룹니다.
1단계: Claude Code 설치
Claude Code는 Node.js 18 이상이 필요합니다. npm을 통해 전역으로 설치합니다.
# Node.js 버전 확인
node —version
Claude Code 전역 설치
npm install -g @anthropic-ai/claude-code
설치 확인
claude —version
최초 실행 및 인증
claude
최초 실행 시 브라우저가 열리며 Anthropic 계정으로 로그인합니다. API 키 방식을 사용하려면 환경 변수를 설정하세요.
# API 키 직접 설정 (Linux/macOS)
export ANTHROPIC_API_KEY=YOUR_API_KEY
Windows PowerShell
$env:ANTHROPIC_API_KEY=“YOUR_API_KEY”
.bashrc 또는 .zshrc에 영구 등록
echo ‘export ANTHROPIC_API_KEY=YOUR_API_KEY’ >> ~/.bashrc
2단계: CLAUDE.md 작성으로 프로젝트 컨텍스트 설정
CLAUDE.md는 Claude Code가 매 대화 시작 시 자동으로 읽는 설정 파일입니다. 프로젝트의 컨벤션, 기술 스택, 작업 규칙을 정의합니다.
CLAUDE.md 계층 구조
| 위치 | 범위 | 용도 |
|---|---|---|
~/.claude/CLAUDE.md | 전역 (모든 프로젝트) | 개인 환경 설정, 선호 스타일 |
프로젝트루트/CLAUDE.md | 프로젝트 전체 | 기술 스택, 코딩 컨벤션 |
하위폴더/CLAUDE.md | 해당 디렉토리 | 모듈별 세부 규칙 |
# 프로젝트 설정
기술 스택
- Frontend: React 18 + TypeScript + Tailwind CSS
- Backend: Node.js + Express
- DB: PostgreSQL with Prisma ORM
- Test: Vitest + Testing Library
코딩 컨벤션
- 함수형 컴포넌트만 사용, class 컴포넌트 금지
- 변수명은 camelCase, 컴포넌트는 PascalCase
- 모든 API 함수에 에러 핸들링 필수
- import 순서: 외부 라이브러리 → 내부 모듈 → 상대 경로
테스트 규칙
- 새 기능 추가 시 반드시 단위 테스트 작성
- 테스트 실행: npm run test
- 린트 체크: npm run lint
브랜치 전략
- feature/기능명 형식으로 브랜치 생성
main 직접 push 금지
3단계: MCP 서버 연동
MCP(Model Context Protocol) 서버를 연동하면 Claude Code가 외부 도구와 데이터에 접근할 수 있습니다. 설정 파일은 ~/.claude/settings.json에 위치합니다.
MCP 서버 설정 방법
# 대화형으로 MCP 서버 추가
claude mcp add
직접 명령어로 추가 (stdio 타입)
claude mcp add context7 — npx -y @upstash/context7-mcp
SSE 타입 서버 추가
claude mcp add my-server —transport sse https://my-server.example.com/sse
등록된 MCP 서버 목록 확인
claude mcp list
특정 MCP 서버 제거
claude mcp remove context7
settings.json 직접 편집
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_API_KEY"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
}
}
}프로젝트 단위로 MCP를 설정하려면 프로젝트 루트에 .claude/settings.json을 생성합니다.
4단계: 커스텀 슬래시 커맨드 구성
반복 작업을 슬래시 커맨드로 등록하면 효율이 크게 향상됩니다. .claude/commands/ 디렉토리에 Markdown 파일로 정의합니다.
커맨드 파일 구조
# 프로젝트 커맨드 (팀 공유)
프로젝트루트/.claude/commands/커맨드명.md
개인 전역 커맨드
~/.claude/commands/커맨드명.md
예시: 코드 리뷰 커맨드
# .claude/commands/review.md
현재 Git diff를 분석하고 다음 기준으로 코드 리뷰를 수행하세요:
1. 보안 취약점 (SQL 인젝션, XSS 등)
2. 성능 이슈
3. 코딩 컨벤션 위반
4. 테스트 커버리지 누락
각 항목별로 심각도(높음/중간/낮음)를 표시하고 개선안을 제시하세요.예시: 커밋 메시지 생성 커맨드
# .claude/commands/commit.md
Git 스테이징된 변경사항을 분석하여 Conventional Commits 형식으로
커밋 메시지를 작성하세요.
형식: type(scope): description
타입: feat, fix, docs, style, refactor, test, chore
$ARGUMENTS 내용이 있으면 해당 컨텍스트를 반영하세요.사용 시 Claude Code 대화창에서 /review 또는 /commit 로그인 기능 추가처럼 입력합니다. $ARGUMENTS는 슬래시 커맨드 뒤에 입력한 텍스트로 치환됩니다.
5단계: 권한 및 보안 설정
# 허용 도구 설정 (자동 실행 허용)
claude config set allowedTools “Edit,Write,Bash(npm test),Bash(npm run lint)“
파일 편집 자동 승인, 나머지는 확인
claude config set autoApprove edit
Pro Tips: 파워 유저를 위한 팁
- Headless 모드 활용: CI/CD 파이프라인에서
claude -p “테스트 실행 후 결과 요약”으로 비대화형 실행이 가능합니다.- 멀티 파일 컨텍스트: 대화 시작 시claude “@src/api/ 디렉토리의 에러 핸들링 패턴 분석”처럼 디렉토리를 지정하면 관련 파일을 자동 탐색합니다.- 메모리 시스템:~/.claude/projects/에 메모리 파일을 구성하면 대화 간 컨텍스트가 유지됩니다.- 모델 전환: 대화 중/memory/ /model로 모델을 변경하거나/fast로 빠른 모드를 토글할 수 있습니다.- CLAUDE.md 디버깅: 대화 시작 시/cost로 토큰 사용량을 모니터링하여 CLAUDE.md가 과도하게 크지 않은지 확인하세요.
Troubleshooting: 자주 발생하는 오류
| 오류 | 원인 | 해결 방법 |
|---|---|---|
ANTHROPIC_API_KEY not set | API 키 미설정 | 환경 변수 설정 또는 claude 실행 후 브라우저 인증 |
MCP server failed to start | MCP 서버 패키지 미설치 | npx 캐시 초기화: npx clear-npx-cache 후 재시도 |
Permission denied | 도구 실행 권한 부족 | claude config set allowedTools로 허용 도구 등록 |
| CLAUDE.md 미인식 | 파일 위치 오류 | 프로젝트 루트에 정확히 CLAUDE.md 이름으로 존재하는지 확인 |
| 슬래시 커맨드 미표시 | 파일 확장자 또는 경로 오류 | .claude/commands/이름.md 경로와 .md 확장자 확인 |
Q1: CLAUDE.md 파일의 최적 크기는 얼마인가요?
CLAUDE.md는 매 대화 시작 시 컨텍스트에 로드되므로 간결하게 유지하는 것이 중요합니다. 500줄 이내로 핵심 규칙만 포함하세요. 세부 문서는 별도 파일로 분리하고 필요할 때 참조하도록 안내하는 방식이 토큰 효율적입니다. 전역 CLAUDE.md는 100줄 이내, 프로젝트 CLAUDE.md는 300줄 이내를 권장합니다.
Q2: MCP 서버를 여러 개 동시에 사용할 수 있나요?
네, settings.json의 mcpServers 객체에 여러 서버를 등록하면 모두 동시에 활성화됩니다. 각 서버는 독립적으로 실행되며 Claude Code가 상황에 맞는 도구를 자동으로 선택합니다. 다만 너무 많은 MCP 서버를 등록하면 초기 로딩 시간이 늘어날 수 있으므로 실제 사용하는 서버만 등록하세요.
Q3: 커스텀 슬래시 커맨드에서 외부 파일 내용을 참조할 수 있나요?
커맨드 파일(.md) 내에서 직접적인 파일 include 구문은 지원되지 않지만, 커맨드 본문에 특정 파일을 읽으라는 지시를 포함할 수 있습니다. 예를 들어 “src/config.ts 파일을 읽고 설정값을 분석하세요”와 같이 작성하면 Claude Code가 해당 파일을 자동으로 읽어 처리합니다. $ARGUMENTS 변수를 활용하면 실행 시점에 동적으로 파일 경로를 전달할 수도 있습니다.