Claude Code 세팅 가이드 — CLAUDE.md부터 MCP, 커스텀 에이전트까지 (2026)

Claude Code 설치/설정 완벽 가이드 (2026)

터미널에서 AI와 함께 코딩하는 실전 세팅법

CLI 도구 Claude Code 가이드

Claude Code란?

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 도구입니다. 에디터 없이 터미널에서 바로 AI와 대화하며 코드를 작성, 수정, 분석할 수 있습니다.

• 파일 읽기/쓰기/수정을 직접 수행
• Git 작업, 빌드, 테스트 등 터미널 명령 실행
• CLAUDE.md로 프로젝트별 맞춤 지시 가능
• MCP 서버 연동으로 외부 도구 통합
• 커스텀 슬래시 명령어(Skill)로 반복 작업 자동화

설치 방법

OS에 맞는 설치 스크립트를 실행하면 됩니다.

macOS / Linux / WSL

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

Windows (PowerShell)

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

참고: npm install -g @anthropic-ai/claude-code로도 설치 가능하지만, 자동 업데이트가 지원되지 않아 더 이상 권장되지 않습니다.

설치 후 프로젝트 디렉토리에서 실행합니다.

cd my-project
claude

처음 실행 시 Anthropic 계정 인증이 진행됩니다. 브라우저가 열리면 로그인하면 끝입니다.

핵심 설정: CLAUDE.md 작성법

CLAUDE.md는 Claude Code의 행동을 제어하는 가장 중요한 설정 파일입니다. 프로젝트 루트에 생성하면 매 세션마다 자동으로 읽힙니다.

파일 위치와 우선순위

위치	범위	용도
~/.claude/CLAUDE.md	전역	모든 프로젝트에 적용할 개인 설정
프로젝트/.claude/CLAUDE.md	프로젝트	팀 공유용 프로젝트 규칙 (Git 커밋)
프로젝트/CLAUDE.md	프로젝트	프로젝트 루트에 직접 배치 가능

효과적인 CLAUDE.md 작성 예시

# 프로젝트 개요
이 프로젝트는 Spring Boot + React 기반 관리자 포탈입니다.

## 기술 스택
- Backend: Java 17, Spring Boot 3.x, JPA
- Frontend: TypeScript, React, Vite, Tailwind

## 코딩 컨벤션
- 한국어로 응답할 것
- 기존 패턴을 먼저 분석하고 따를 것
- 커밋 메시지는 한국어로, feat/fix/refactor 접두사 사용

## 브랜치 전략
- 기준 브랜치: dev
- 작업 브랜치: feature/기능명

## 빌드/테스트 명령어
- Backend: ./gradlew build
- Frontend: npm run build

핵심 포인트: Claude Code는 CLAUDE.md의 지시를 높은 우선순위로 따릅니다. 프로젝트의 규칙, 선호하는 패턴, 빌드 명령어 등을 명시하면 매번 반복 설명할 필요가 없습니다.

MCP 서버 연동

MCP(Model Context Protocol)를 통해 Claude Code에 외부 도구를 연결할 수 있습니다. CLI 명령어 또는 프로젝트 루트의 .mcp.json 파일로 설정합니다.

CLI 명령어로 추가

claude mcp add 명령어로 MCP 서버를 추가할 수 있습니다.

# stdio 방식 서버 추가
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

# HTTP 방식 서버 추가
claude mcp add --transport http my-server https://example.com/mcp

.mcp.json 파일로 설정

프로젝트 루트에 .mcp.json 파일을 만들어 팀과 공유할 수도 있습니다.

// .mcp.json 예시
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"
      }
    }
  }
}

활용도 높은 MCP 서버

MCP 서버	용도
server-github	GitHub PR/Issue 관리
server-filesystem	특정 디렉토리 파일 접근
server-postgres	PostgreSQL DB 쿼리 실행
Figma MCP	Figma 디자인을 코드로 변환

슬래시 명령어 & 커스텀 에이전트

Claude Code는 .claude/agents/ 폴더에 마크다운 파일을 만들어 커스텀 슬래시 명령어를 정의할 수 있습니다.

에이전트 파일 구조

프로젝트/
├── .claude/
│   ├── CLAUDE.md          # 프로젝트 규칙
│   ├── settings.json      # 권한/설정
│   └── agents/
│       ├── work.md        # /work 명령어
│       ├── code-review.md # /code-review 명령어
│       └── debug.md       # /debug 명령어

에이전트 작성 예시

# Code Review Agent

현재 브랜치의 변경사항을 분석하여 코드 리뷰를 수행한다.

## 실행 절차
1. git diff로 변경 파일 목록 확인
2. 각 파일의 변경 내용 분석
3. 잠재적 문제점, 개선사항 정리
4. 리뷰 결과를 마크다운으로 출력

활용 팁: 반복적인 작업 프로세스(커밋, 배포, 코드 리뷰 등)를 에이전트로 만들어두면 /명령어 한 번으로 자동화할 수 있습니다.

자주 쓰는 기능 & 팁

명령/기능	설명
/help	도움말 확인
/clear	대화 컨텍스트 초기화
/compact	대화를 요약하여 컨텍스트 절약
/model	사용할 모델 변경 (Opus, Sonnet, Haiku)
Shift+Tab	권한 모드 전환 (Auto-Accept ↔ Plan ↔ Normal)
Ctrl+C	진행 중인 응답 중단

실전 활용 팁

• 큰 작업은 플랜 모드부터 — Shift+Tab으로 Plan 모드로 전환하면 코드 변경 없이 계획만 먼저 세울 수 있어 불필요한 수정을 줄일 수 있습니다.
• 컨텍스트가 길어지면 /compact — 긴 대화는 토큰을 소모하므로, 주기적으로 요약하면 응답 품질이 유지됩니다.
• CLAUDE.md에 빌드 명령어 명시 — 빌드/테스트 명령어를 적어두면 Claude가 자동으로 검증까지 수행합니다.
• Git 작업은 Claude에게 맡기기 — 브랜치 생성, 커밋, PR 작성을 자연어로 요청하면 알아서 처리합니다.

흔한 문제 해결

설치 스크립트 실행 시 권한 에러

macOS/Linux에서 권한 문제가 발생하면 아래처럼 실행하세요.

# sudo로 설치 스크립트 실행
curl -fsSL https://claude.ai/install.sh | sudo bash

인증이 만료되었거나 실패

인증 토큰이 만료되면 Claude Code 실행 후 /login 슬래시 명령어로 재로그인할 수 있습니다.

# Claude Code 실행 후 내부에서
/login

CLAUDE.md가 인식되지 않음

파일이 프로젝트 루트 또는 .claude/ 폴더에 있는지 확인하세요. Claude Code를 실행한 디렉토리 기준으로 인식합니다.

응답이 느리거나 토큰 초과

/compact로 대화를 요약하거나, /clear로 새 세션을 시작하세요. 큰 프로젝트에서는 CLAUDE.md에 불필요한 파일/폴더를 명시하거나, 권한 설정으로 특정 경로를 제외할 수 있습니다.