Claude Code 빠른 시작 가이드

Claude Code를 사용해 주셔서 감사합니다! 이 강력한 AI 프로그래밍 어시스턴트는 프로그래밍 효율성을 향상시키고 개발 작업을 자동화하는 데 도움이 됩니다.

1. 설치 및 구성

1.1 시스템 요구사항

운영 체제: macOS 10.15+, Ubuntu 20.04+/Debian 10+, 또는 Windows via WSL
하드웨어: 4GB+ RAM
소프트웨어: Node.js 18+
네트워크: 인증 및 AI 처리를 위한 인터넷 연결 필요

1.2 설치 단계

npm을 사용하여 전역 설치:

bash

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

중요: sudo npm install -g를 사용하지 마세요. 권한 문제와 보안 위험을 일으킬 수 있습니다.

설치 완료 후, 프로젝트 디렉터리로 이동하여 Claude Code를 시작하세요:

bash

cd your-awesome-project
claude

2. API 키 획득 및 구성

2.1 계정 등록

https://coultra.blueshirtmap.com 방문
등록 버튼을 클릭하여 새 계정 생성
필요한 등록 정보 작성

계정 등록

2.2 API 키 생성

로그인 성공 후, API 키 관리 페이지로 이동
새 API 키 그룹 생성
그룹 이름으로 "ClaudeCode" 선택
API 키 생성 후 복사

토큰 생성

3. 구성 파일 설정

3.1 API 키 구성

구성 파일 설정 방법

구성 파일 생성 또는 편집:

bash

# 사용자 설정 (전역)
~/.claude/settings.json

# 프로젝트 설정 (프로젝트 수준)
.claude/settings.json

구성 파일 예시:

json

{
    "env": {
      "ANTHROPIC_API_KEY": "귀하의_API키",
      "ANTHROPIC_BASE_URL": "https://coultra.blueshirtmap.com",
      "CLAUDE_CODE_MAX_OUTPUT_TOKENS":64000,
      "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":1,
      "CLAUDE_MODEL": "Claude모델명"
    },
    "permissions": {
      "allow": [],
      "deny": []
    }
  }

3.2 권한 설정 (선택사항)

Claude Code는 보수적인 권한 정책을 채택하여, 기본적으로 시스템을 수정할 수 있는 작업에 대한 사용자 확인이 필요합니다. 허용된 도구 목록을 사용자 정의할 수 있습니다:

/permissions 명령을 사용하여 도구 추가 또는 제거
settings.json 파일을 편집하여 일괄 구성
--allowedTools CLI 플래그를 사용하여 세션별 권한 설정

3.3 작업 디렉터리 구성 (선택사항)

Claude가 액세스할 수 있는 추가 작업 디렉터리 구성:

json

{
  "permissions": {
    "additionalDirectories": ["../docs/", "../shared/"]
  }
}

3.4 간편 설정 - 원클릭 스크립트

API를 구매한 후, 이 스크립트의 8번째 줄 readonly API_KEY=""만 수정하여 API 키(토큰)를 입력하고, 이 스크립트를 claudecode.sh로 저장한 다음 터미널을 열어:

bash

chmod +x claudecode.sh
./claudecode.sh

안내를 따라 진행하면 됩니다.

bash

#!/bin/bash

# ==============================================================================
# 🔧 설정 영역 - 여기에 API 설정을 입력하세요
# ==============================================================================

# 🔑 API 키 - API 키를 입력하세요
readonly API_KEY=""

# 🌐 API 기본 URL - API 기본 주소를 입력하세요 (예: "https://coultra.blueshirtmap.com")
readonly API_BASE_URL="https://coultra.blueshirtmap.com"

# ==============================================================================
# 아래 내용은 수정하지 마세요
# ==============================================================================

# 스크립트 상수
readonly CLAUDE_COMMAND="claude"
readonly NPM_PACKAGE="@anthropic-ai/claude-code"
readonly CLAUDE_DIR="$HOME/.claude"
readonly SETTINGS_FILE="$CLAUDE_DIR/settings.json"

# 운영체제 감지
detect_os() {
    case "$(uname -s)" in
        Darwin)
            echo "macos"
            ;;
        Linux)
            echo "linux"
            ;;
        *)
            echo "unknown"
            ;;
    esac
}

# 설정 완성도 확인
check_config() {
    if [ -z "$API_KEY" ] || [ -z "$API_BASE_URL" ]; then
        echo "❌ 설정이 불완전합니다! 스크립트를 편집하고 다음 정보를 입력하세요:"
        echo "  - API_KEY: API 키"
        echo "  - API_BASE_URL: API 기본 주소 (예: https://coultra.blueshirtmap.com )"
        exit 1
    fi
}

# Homebrew 설치 (macOS 전용)
install_homebrew() {
    if ! command -v brew &> /dev/null; then
        echo "Homebrew 설치 중..."
        /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
        
        # Homebrew를 PATH에 추가
        if [[ -f "/opt/homebrew/bin/brew" ]]; then
            eval "$(/opt/homebrew/bin/brew shellenv)"
        elif [[ -f "/usr/local/bin/brew" ]]; then
            eval "$(/usr/local/bin/brew shellenv)"
        fi
        
        echo "✅ Homebrew 설치 완료"
    else
        echo "ℹ️ Homebrew가 이미 설치되어 있습니다"
    fi
}

# macOS에서 패키지 설치
install_macos_packages() {
    install_homebrew
    
    # Node.js 설치 (npm 포함)
    if ! command -v node &> /dev/null; then
        echo "Node.js 설치 중..."
        brew install node
        echo "✅ Node.js 설치 완료"
    else
        echo "ℹ️ Node.js가 이미 설치되어 있습니다"
    fi
    
    # jq 설치
    if ! command -v jq &> /dev/null; then
        echo "jq 설치 중..."
        brew install jq
        echo "✅ jq 설치 완료"
    else
        echo "ℹ️ jq가 이미 설치되어 있습니다"
    fi
    
    # Python3 설치
    if ! command -v python3 &> /dev/null; then
        echo "Python3 설치 중..."
        brew install python3
        echo "✅ Python3 설치 완료"
    else
        echo "ℹ️ Python3가 이미 설치되어 있습니다"
    fi
}

# Linux에서 패키지 설치
install_linux_packages() {
    # Linux 배포판 감지
    if command -v apt-get &> /dev/null; then
        # Ubuntu/Debian
        echo "Ubuntu/Debian 시스템 감지됨"
        
        # 패키지 관리자 업데이트
        echo "패키지 관리자 업데이트 중..."
        sudo apt-get update
        
        # Node.js 설치
        if ! command -v node &> /dev/null; then
            echo "Node.js 설치 중..."
            # NodeSource 저장소 설치
            curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
            sudo apt-get install -y nodejs
            echo "✅ Node.js 설치 완료"
        else
            echo "ℹ️ Node.js가 이미 설치되어 있습니다"
        fi
        
        # jq 설치
        if ! command -v jq &> /dev/null; then
            echo "jq 설치 중..."
            sudo apt-get install -y jq
            echo "✅ jq 설치 완료"
        else
            echo "ℹ️ jq가 이미 설치되어 있습니다"
        fi
        
        # Python3 설치
        if ! command -v python3 &> /dev/null; then
            echo "Python3 설치 중..."
            sudo apt-get install -y python3 python3-pip
            echo "✅ Python3 설치 완료"
        else
            echo "ℹ️ Python3가 이미 설치되어 있습니다"
        fi
        
    elif command -v yum &> /dev/null; then
        # CentOS/RHEL
        echo "CentOS/RHEL 시스템 감지됨"
        
        # Node.js 설치
        if ! command -v node &> /dev/null; then
            echo "Node.js 설치 중..."
            curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
            sudo yum install -y nodejs
            echo "✅ Node.js 설치 완료"
        else
            echo "ℹ️ Node.js가 이미 설치되어 있습니다"
        fi
        
        # jq 설치
        if ! command -v jq &> /dev/null; then
            echo "jq 설치 중..."
            sudo yum install -y jq
            echo "✅ jq 설치 완료"
        else
            echo "ℹ️ jq가 이미 설치되어 있습니다"
        fi
        
        # Python3 설치
        if ! command -v python3 &> /dev/null; then
            echo "Python3 설치 중..."
            sudo yum install -y python3 python3-pip
            echo "✅ Python3 설치 완료"
        else
            echo "ℹ️ Python3가 이미 설치되어 있습니다"
        fi
        
    elif command -v pacman &> /dev/null; then
        # Arch Linux
        echo "Arch Linux 시스템 감지됨"
        
        # Node.js 설치
        if ! command -v node &> /dev/null; then
            echo "Node.js 설치 중..."
            sudo pacman -S --noconfirm nodejs npm
            echo "✅ Node.js 설치 완료"
        else
            echo "ℹ️ Node.js가 이미 설치되어 있습니다"
        fi
        
        # jq 설치
        if ! command -v jq &> /dev/null; then
            echo "jq 설치 중..."
            sudo pacman -S --noconfirm jq
            echo "✅ jq 설치 완료"
        else
            echo "ℹ️ jq가 이미 설치되어 있습니다"
        fi
        
        # Python3 설치
        if ! command -v python3 &> /dev/null; then
            echo "Python3 설치 중..."
            sudo pacman -S --noconfirm python python-pip
            echo "✅ Python3 설치 완료"
        else
            echo "ℹ️ Python3가 이미 설치되어 있습니다"
        fi
        
    else
        echo "❌ 지원되지 않는 Linux 배포판입니다. 다음 패키지를 수동으로 설치해주세요:"
        echo "  - Node.js (npm 포함)"
        echo "  - jq"
        echo "  - python3"
        exit 1
    fi
}

# Claude Code 설치
install_claude_code() {
    if command -v "$CLAUDE_COMMAND" &> /dev/null; then
        echo "ℹ️ Claude Code가 이미 설치되어 있습니다"
    else
        echo "Claude Code 설치 중..."
        
        if ! command -v npm &> /dev/null; then
            echo "❌ npm이 설치되지 않아 Claude Code를 설치할 수 없습니다"
            exit 1
        fi
        
        if ! npm install -g "$NPM_PACKAGE"; then
            echo "❌ Claude Code 설치 실패"
            exit 1
        fi
        
        echo "✅ Claude Code 설치 완료"
    fi
}

# Claude Code 설정
configure_claude_code() {
    echo "Claude Code 설정 중..."
    
    # .claude 디렉터리 생성
    if [ ! -d "$CLAUDE_DIR" ]; then
        mkdir -p "$CLAUDE_DIR"
    fi
    
    # 기존 설정 백업 (존재하는 경우)
    if [ -f "$SETTINGS_FILE" ]; then
        cp "$SETTINGS_FILE" "$SETTINGS_FILE.backup"
        echo "ℹ️ 기존 설정이 settings.json.backup으로 백업되었습니다"
    fi
    
    # 새 설정 파일 생성
    cat > "$SETTINGS_FILE" << EOF
{
  "env": {
    "ANTHROPIC_API_KEY": "$API_KEY",
    "ANTHROPIC_BASE_URL": "$API_BASE_URL",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 64000,
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  },
  "permissions": {
    "allow": [],
    "deny": []
  },
  "apiKeyHelper": "echo '$API_KEY'"
}
EOF
    
    echo "✅ 설정 파일 생성 완료"
}

# 메인 함수
main() {
    echo "🚀 Claude Code 자동 설치 및 설정 스크립트"
    echo "========================================"
    
    # 설정 확인
    check_config
    
    # 운영체제 감지
    OS=$(detect_os)
    echo "감지된 운영체제: $OS"
    
    # 운영체제에 따른 의존성 설치
    case "$OS" in
        "macos")
            install_macos_packages
            ;;
        "linux")
            install_linux_packages
            ;;
        *)
            echo "❌ 지원되지 않는 운영체제: $OS"
            exit 1
            ;;
    esac
    
    # Claude Code 설치
    install_claude_code
    
    # Claude Code 설정
    configure_claude_code
    
    echo "🎉 모든 설정이 완료되었습니다!"
    echo "설정 파일 위치: $SETTINGS_FILE"
    echo "이제 'claude' 명령어를 사용할 수 있습니다!"
}

# 메인 함수 실행
main "$@"

4. 기본 사용법

4.1 시작 방법

대화형 모드

bash

claude

Claude 진입 인터페이스

초기 프롬프트와 함께 시작

bash

claude "explain this project"

비대화형 모드

bash

claude -p "explain this function"

파이프라인 입력 처리

bash

cat logs.txt | claude -p "explain"

4.2 일반적인 명령어

claude update - 최신 버전으로 업데이트
claude -c - 최근 대화 계속
claude -r <session-id> - 특정 세션 복원
claude mcp - MCP 서버 구성

4.3 단축키

일반 제어

Ctrl+C: 현재 입력 또는 생성 취소
Ctrl+D: Claude Code 세션 종료
Ctrl+L: 터미널 화면 지우기
Up/Down: 명령 기록 탐색
Esc + Esc: 이전 메시지 편집

여러 줄 입력

\ + Enter: 모든 터미널에 적용
Option+Enter: macOS 기본값
Shift+Enter: /terminal-setup 실행 후 사용 가능

5. 고급 기능

5.1 CLI 참조

Claude Code는 행동을 사용자 정의할 수 있는 풍부한 명령줄 옵션을 제공합니다:

기본 CLI 명령

명령	설명	예시
`claude`	대화형 REPL 시작	`claude`
`claude "query"`	초기 프롬프트와 함께 REPL 시작	`claude "explain this project"`
`claude -p "query"`	SDK를 통해 쿼리 후 종료	`claude -p "explain this function"`
`claude -c`	최근 대화 계속	`claude -c`
`claude update`	최신 버전으로 업데이트	`claude update`

중요한 CLI 플래그

플래그	설명	예시
`--allowedTools`	허용된 도구 목록	`--allowedTools "Bash(git log:*)" "Read"`
`--verbose`	상세 로그 활성화	`claude --verbose`
`--model`	사용할 모델 설정	`claude --model claude-sonnet-4`
`--permission-mode`	권한 모드 지정	`claude --permission-mode plan`
`--dangerously-skip-permissions`	권한 프롬프트 건너뛰기 (신중히 사용)	`claude --dangerously-skip-permissions`

5.2 대화형 모드

Vim 모드

vim 스타일 편집 활성화:

bash

/vim

모드 전환

Esc: NORMAL 모드 진입
i: 커서 앞에 삽입
a: 커서 뒤에 삽입
o: 아래에 새 줄 생성

네비게이션 (NORMAL 모드)

h/j/k/l: 왼쪽/아래/위/오른쪽 이동
w: 다음 단어
0: 줄 시작
$: 줄 끝
gg: 텍스트 시작
G: 텍스트 끝

5.3 슬래시 명령

Claude Code는 상호작용 경험을 향상시키기 위한 다양한 슬래시 명령을 제공합니다:

기본 명령

명령	설명	예시
`/help`	도움말 정보 표시	`/help`
`/clear`	대화 기록 지우기	`/clear`
`/config`	구성 관리	`/config`
`/permissions`	권한 관리	`/permissions`
`/vim`	vim 모드 활성화	`/vim`

고급 명령

명령	설명	기능
`/init`	프로젝트 초기화	CLAUDE.md 파일 자동 생성
`/terminal-setup`	터미널 설정	키보드 단축키 구성
`/project:<command>`	프로젝트별 명령	프로젝트 사용자 정의 명령 실행

사용자 정의 슬래시 명령

사용자 정의 슬래시 명령을 생성할 수 있습니다:

.claude/commands/ 디렉터리에 Markdown 파일 생성
파일명이 명령명이 됩니다
내용은 명령 템플릿이며, $ARGUMENTS 플레이스홀더 사용 가능

예시: .claude/commands/fix-github-issue.md

markdown

GitHub issue 분석 및 수정: $ARGUMENTS.

다음 단계를 따라 진행하세요:
1. `gh issue view`를 사용하여 issue 세부사항 가져오기
2. 문제 설명 이해
3. 관련 코드 파일 검색
4. 필요한 수정 구현
5. 테스트 작성 및 실행
6. 코드가 lint 검사를 통과하는지 확인
7. 설명적인 커밋 메시지 작성
8. 푸시 및 PR 생성

6. 실전 튜토리얼

6.1 새로운 코드베이스 이해

코드베이스 개요 빠르게 파악

새 프로젝트에 합류했을 때 구조를 빠르게 이해하려면 다음 단계를 따르세요:

프로젝트 루트 디렉터리로 이동: cd /path/to/project
Claude Code 시작: claude
코드베이스 개요 요청: > 코드베이스 개요를 알려주세요
특정 구성 요소에 대해 자세히 알아보기:
- > 여기서 사용되는 주요 아키텍처 패턴을 설명해주세요
- > 핵심 데이터 모델은 무엇인가요?
- > 인증은 어떻게 처리되나요?

팁:

광범위한 질문으로 시작한 다음 점진적으로 특정 영역에 집중
프로젝트에서 사용되는 코딩 관례와 패턴에 대해 문의
프로젝트 특정 용어의 용어집 요청

6.2 효율적인 버그 수정

오류 메시지 진단

오류가 발생했을 때 다음 방법으로 문제를 찾고 수정할 수 있습니다:

Claude와 오류 메시지 공유: > npm test 실행 시 오류가 발생했습니다
수정 제안 요청: > user.ts의 @ts-ignore를 수정하는 방법을 제안해주세요
수정 적용: > user.ts를 업데이트하여 제안하신 null 검사를 추가해주세요

팁:

문제를 재현하는 명령과 스택 트레이스를 Claude에게 알려주세요
오류를 재현하는 단계가 있다면 언급
오류가 간헐적인지 일관적인지 명시

6.3 코드 리팩토링

기존 코드 현대화

기존 코드를 업데이트하여 현대적인 프로그래밍 패턴을 채택할 때는 다음 단계를 따르세요:

리팩토링할 기존 코드 식별: > 코드베이스에서 폐기된 API를 찾아주세요
리팩토링 제안 요청: > utils.js를 현대적인 JavaScript 기능을 사용하여 리팩토링하는 방법을 제안해주세요
안전하게 변경 적용: > utils.js를 ES2024 기능을 사용하여 리팩토링하되 기존 동작을 유지해주세요
리팩토링 검증: > 리팩토링된 코드에 대해 테스트를 실행해주세요

팁:

Claude에게 현대적 접근 방식의 이점에 대해 문의
필요시 하위 호환성 유지 요청
작고 테스트 가능한 증분 리팩토링 수행

6.4 테스트 처리

테스트 커버리지 추가

커버되지 않은 코드에 테스트를 추가해야 할 때는 다음 단계를 따르세요:

테스트되지 않은 코드 식별: > NotificationsService.swift에서 커버되지 않은 함수를 찾아주세요
테스트 프레임워크 생성: > 알림 서비스에 대한 테스트를 추가해주세요
의미 있는 테스트 케이스 추가: > 알림 서비스의 엣지 케이스에 대한 테스트 케이스를 추가해주세요
테스트 실행 및 검증: > 새 테스트를 실행하고 실패한 것이 있으면 수정해주세요

팁:

엣지 케이스와 오류 조건을 다루는 테스트 요청
필요에 따라 단위 테스트와 통합 테스트 요청
Claude에게 테스트 전략 설명 요청

6.5 Pull Request 생성

포괄적인 PR 생성

변경사항에 대한 문서화가 잘 된 pull request를 생성해야 할 때는 다음 단계를 따르세요:

변경사항 요약: > 인증 모듈에 대한 제 변경사항을 요약해주세요
Claude를 사용하여 PR 생성: > PR을 생성해주세요
설명 검토 및 개선: > 보안 개선에 대한 더 많은 정보를 포함하여 PR 설명을 개선해주세요
테스트 정보 추가: > 이러한 변경사항을 테스트하는 방법에 대한 정보를 추가해주세요

팁:

Claude에게 직접 PR 생성 요청
제출 전에 Claude가 생성한 PR 검토
Claude에게 잠재적 위험이나 주의사항 강조 요청

6.6 문서화 처리

코드 문서 생성

코드 문서를 추가하거나 업데이트해야 할 때는 다음 단계를 따르세요:

적절한 JSDoc 주석이 없는 코드 식별: > auth 모듈에서 적절한 JSDoc 주석이 없는 함수를 찾아주세요
문서 생성: > auth.js의 주석이 없는 함수에 JSDoc 주석을 추가해주세요
문서 검토 및 개선: > 생성된 문서를 개선하여 더 많은 컨텍스트와 예시를 추가해주세요
문서 검증: > 문서가 우리 프로젝트의 표준을 준수하는지 확인해주세요

팁:

필요한 문서 스타일 지정 (예: JSDoc, docstrings 등)
문서에 예시 포함 요청
공개 API, 인터페이스 및 복잡한 로직에 대한 문서 요청

6.7 이미지 사용

이미지 및 스크린샷 분석

코드베이스에서 이미지를 사용하거나 Claude가 이미지 내용을 분석하도록 해야 할 때는 다음 단계를 따르세요:

대화에 이미지 추가:
- 이미지를 Claude Code 창으로 드래그
- 이미지를 복사하여 CLI에 붙여넣기 (ctrl+v)
- 이미지 경로 제공: > 이 이미지를 분석해주세요: /path/to/your/image.png
Claude에게 이미지 분석 요청:
- > 이 이미지에 무엇이 표시되어 있나요?
- > 이 스크린샷의 UI 요소를 설명해주세요
- > 이 차트에 문제가 있나요?
컨텍스트를 위해 이미지 사용:
- > 이것은 오류 스크린샷입니다. 무엇이 원인인가요?
- > 이것은 현재 데이터베이스 아키텍처입니다. 새 기능을 지원하기 위해 어떻게 수정해야 하나요?
이미지에서 코드 제안 얻기:
- > 이 디자인 스케치와 일치하는 CSS를 생성해주세요
- > 이 구성 요소를 재구성할 수 있는 HTML 구조는 무엇인가요?

팁:

텍스트 설명이 불분명하거나 번거로울 때 이미지 사용
더 나은 컨텍스트를 위해 오류, UI 디자인 또는 차트 스크린샷 제공
대화에서 여러 이미지 사용 가능

6.8 프로젝트 메모리 설정

효과적인 CLAUDE.md 파일 생성

중요한 프로젝트 정보, 관례 및 자주 사용하는 명령을 저장하기 위해 CLAUDE.md 파일을 설정할 수 있습니다:

코드베이스용 CLAUDE.md 파일 초기화: > /init

팁:

반복 검색을 피하기 위해 자주 사용하는 명령 (빌드, 테스트, 검사) 포함
코드 스타일 선호도 및 명명 규칙 문서화
프로젝트별 중요한 아키텍처 패턴 추가

CLAUDE.md 파일은 Claude를 실행하는 폴더, 부모 디렉터리(Claude가 자동으로 읽음) 또는 하위 디렉터리(Claude가 필요에 따라 가져옴)에 추가할 수 있습니다.

6.9 Unix 스타일 유틸리티

검증 프로세스에 추가

빌드 스크립트에 Claude 추가:

json

// package.json
{
  ...
  "scripts": {
    ...
    "lint:claude": "claude -p '당신은 코드 검사 도구입니다. 메인 브랜치와의 차이를 확인하고 맞춤법 오류와 관련된 문제를 보고해주세요. 각 문제의 파일명과 행 번호는 한 줄에, 설명은 두 번째 줄에 작성하세요. 다른 텍스트는 반환하지 마세요.'"
  }
}

파이프라인 입력 출력

Claude를 통해 데이터 파이프라인 처리:

bash

cat build-error.txt | claude -p '이 빌드 오류의 근본 원인을 간결하게 설명해주세요' > output.txt

6.10 MCP 서버 구성

MCP 서버 구성

Claude를 전용 도구 및 외부 서버에 연결하여 기능을 향상시키려면 다음 단계를 따르세요:

MCP Stdio 서버 추가:
- 기본 구문: claude mcp add <name> <command> [args...]
- 예시: 로컬 서버 추가: claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1 arg2
MCP 서버 관리:
- 모든 구성된 서버 목록: claude mcp list
- 특정 서버의 세부 정보 가져오기: claude mcp get my-server
- 서버 제거: claude mcp remove my-server

팁:

-s 또는 --scope 플래그를 project(기본값) 또는 global과 함께 사용하여 구성 저장 위치 지정
-e 또는 --env 플래그를 사용하여 환경 변수 설정 (예: -e KEY=value)
MCP는 클라이언트-서버 아키텍처를 따르며, Claude Code(클라이언트)는 여러 전용 서버에 연결 가능

Postgres MCP 서버에 연결

Claude가 PostgreSQL 데이터베이스를 쿼리하고 스키마를 검사할 수 있는 읽기 전용 권한을 원한다면 다음 단계를 따르세요:

Postgres MCP 서버 추가:

bash

   claude mcp add postgres-server /path/to/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/mydb"

Claude를 사용하여 데이터베이스 쿼리:
- > 사용자 테이블의 스키마를 설명해주세요
- > 시스템의 최신 주문은 무엇인가요?
- > 고객과 송장 간의 관계를 보여주세요

팁:

Postgres MCP 서버는 읽기 전용 액세스를 제공하여 보안 보장
Claude는 데이터베이스 구조를 탐색하고 분석 쿼리를 실행하는 데 도움
낯선 프로젝트의 데이터베이스 아키텍처를 빠르게 이해하는 데 사용
연결 문자열이 필요한 최소 권한을 가진 자격 증명을 사용하는지 확인

7. 고급 기능

7.1 IDE 통합

Claude Code는 주요 IDE 연결을 지원합니다:

IDE에서 직접 Claude Code의 변경사항을 확인하고 상호작용 가능
Claude Code는 현재 VSCode와 JetBrains 지원
Linux/macOS 사용자는 플러그인을 직접 사용할 수 있습니다
- VSCode 사용시, VSCode 내장 터미널에서 Claude Code를 호출하면 플러그인이 자동 설치됩니다
- JetBrains 사용시, 다음 링크에서 다운로드: Claude Code [Beta] - IntelliJ IDEs Plugin
IDE 수동 지정 또는 IDE 연결 확인이 필요할 수 있습니다. 다음 명령으로 테스트: > /ide
VSCode+WSL 사용시, VSCode 플러그인 스토어에서 WSL 플러그인을 미리 설치하세요
더 많은 사용법은 Claude Code 공식 문서를 참조하세요

7.2 모델 전환 및 구성

Claude Code는 Claude 4 Opus와 Claude 4 Sonnet 간 유연한 전환을 지원합니다:

Claude 4 Sonnet 사용을 강력히 권장합니다. Claude 4 Opus와 비슷한 사용 경험이지만 요금은 1/5 수준입니다
기본적으로 Claude 4 Sonnet을 선택했으며, 로그인 후 구성에서 수정할 수 있습니다
사이트에서 "Sonnet 강제 사용"을 비활성화하지 않으면 /model에서 전환한 모델이 적용되지 않습니다
Claude Code에서 다음 명령으로 모델 전환: > /model

7.3 컨텍스트 관리

Claude Code는 포인트를 절약하기 위한 컨텍스트 압축을 지원합니다:

Claude Code는 일반적으로 긴 컨텍스트를 가지므로, 포인트를 절약하기 위해 다음 슬래시 명령을 사용하여 압축하는 것을 권장합니다. 긴 컨텍스트는 종종 더 많은 포인트가 필요합니다
/compact [귀하의 설명]

7.4 대화 복원

Claude Code는 이전 대화를 복원할 수 있습니다:

다음 명령으로 마지막 대화를 복원할 수 있습니다: claude --continue
이는 프롬프트 없이 최근 대화를 즉시 복원합니다
시간을 표시해야 하는 경우 다음 명령을 입력하세요: claude --resume
이는 다음을 표시하는 대화형 대화 선택기를 표시합니다:
- 대화 시작 시간
- 초기 프롬프트 또는 대화 요약
- 메시지 수
화살표 키로 탐색하고 Enter를 눌러 대화를 선택하면, 이 방법으로 컨텍스트를 선택할 수 있습니다

7.5 이미지 처리

Claude Code는 이미지 정보를 처리할 수 있습니다:

다음 방법 중 하나를 사용할 수 있습니다:
- 이미지를 Claude Code 창으로 드래그 앤 드롭 (macOS에서)
- 이미지를 복사하여 CLI에 Ctrl+v로 붙여넣기 (macOS에서)
- 이미지 경로 제공: > 이 이미지를 분석해주세요: /path/to/your/image.png
자연어로 완전히 작업을 요청할 수 있습니다:
- > 이것은 오류 스크린샷입니다. 무엇이 원인인가요?
- > 이 이미지에 무엇이 표시되어 있나요?
- > 이 스크린샷의 UI 요소를 설명해주세요
- > 이 디자인 모델과 일치하는 CSS를 생성해주세요
- > 이 구성 요소를 재생성할 수 있는 HTML 구조는 무엇인가요?

7.6 심층 사고

Claude Code는 심층 사고를 지원합니다:

자연어로 심층 사고를 요청해야 합니다
> OAuth2를 사용하여 API용 새 인증 시스템을 구현해야 합니다. 코드베이스에서 이를 구현하는 최적의 방법에 대해 심층적으로 생각해주세요.
> 이 접근 방식의 잠재적 보안 취약점에 대해 생각해주세요
> 처리해야 할 엣지 케이스에 대해 더 깊이 생각해주세요
복잡한 문제를 사용할 때 이 기능을 사용하는 것을 권장하며, 이는 많은 크레딧 포인트를 소모합니다

7.7 Git 고급 작업

Claude Code는 자연어를 사용한 Git 작업을 지원합니다:

> 변경사항을 커밋해주세요
> PR을 생성해주세요
> 작년 12월에 마크다운 테스트를 추가한 커밋은 무엇인가요?
> main 브랜치에서 리베이스하고 병합 충돌을 해결해주세요

Git 작업 트리 사용

작업 트리를 사용하여 격리된 코딩 환경을 만들 수 있습니다:

여러 작업을 동시에 처리하고 Claude Code 인스턴스 간에 코드를 완전히 격리해야 하는 경우 이 기능을 사용할 수 있습니다
Git 작업 트리를 사용하면 동일한 저장소에서 여러 브랜치를 별도의 디렉터리로 체크아웃할 수 있습니다. 각 작업 트리는 자체 작업 디렉터리를 가지며 파일이 격리되면서 동일한 Git 히스토리를 공유합니다
새 작업 트리 생성:

bash

  # 새 브랜치로 작업 트리 생성
  git worktree add ../project-feature-a -b feature-a
  
  # 기존 브랜치로 작업 트리 생성
  git worktree add ../project-bugfix bugfix-123

각 작업 트리에서 Claude Code 실행:

bash

  # 작업 트리로 이동
  cd ../project-feature-a
  
  # 이 격리된 환경에서 Claude Code 실행
  claude

7.8 기타 고급 기능

Claude Code는 다양한 고급 기능을 지원합니다:

Claude Code는 Unix 유사 도구로 사용 가능
Claude Code는 사용자 정의 슬래시 명령 지원
Claude Code는 $ARGUMENTS를 사용한 명령 매개변수 추가 지원
Claude Code는 고급 설정 구성 지원
Claude Code는 GitHub Actions 통합 지원
Claude Code는 SDK 개발 지원
Claude Code는 모델 컨텍스트 프로토콜(MCP) 지원

8. 일반적인 문제 해결

8.1 메모리 저장 문제

Claude Code는 메모리를 어떻게 저장하나요?

Claude Code는 ~/.claude에 메모리를 저장합니다. 특별한 요구사항이 없다면 이 디렉터리를 삭제하지 마세요.

8.2 모델명 문제

가끔 잘못된 모델명으로 응답하는 이유는?

TryAllAI는 요청하신 모델을 대체하지 않고 다른 모델을 섞지 않는다고 약속드립니다. 이는 Claude Code가 간단한 작업을 사용할 때 Claude 4 시리즈 모델을 사용하지 않기 때문입니다.

8.3 명령줄 오류

명령줄 매개변수 실행 오류는 어떻게 해결하나요?

이러한 문제는 WSL에서 흔히 발생하며, Agent 자체의 오류입니다. macOS/Ubuntu 사용을 권장하며, 이러한 환경에서는 문제가 적습니다.

8.4 Claude Code 정리

Claude Code를 완전히 정리하는 방법은?

다음 명령을 실행하여 Claude Code의 로그인 정보를 정리할 수 있습니다:

bash

rm ~/.claude* -rf

8.5 API 오류

API Error, Tools Error가 발생하면 어떻게 하나요?

이는 일반적으로 네트워크 문제입니다. 종료 후 claude -c를 사용하여 다시 실행하세요. 문제가 지속되면 애프터서비스 지원에 문의하세요.

8.6 OAuth 인증 오류

OAuth 인증 오류 해결 방법

로그인 인증 전에 환경 변수에 프록시가 구성되어 있지 않은지 확인하세요
문제가 지속되면 팝업되는 브라우저를 무시하고 터미널의 링크를 복사하여 열고 인증 코드 방식으로 인증하세요

8.7 응답 시간 초과 문제

오랫동안 응답이 없으면 어떻게 하나요?

ctrl+c를 누르고 Claude Code를 재시작하는 것을 권장합니다. 이는 종종 네트워크 문제입니다
명령줄이 여전히 응답하지 않으면 프로세스를 종료하고 새 세션을 시작하는 것을 권장합니다. 이는 작업 진행에 영향을 주지 않습니다
다음 명령으로 마지막 세션을 복원할 수 있습니다: claude -c

9. 결론

Claude Code는 강력한 AI 프로그래밍 어시스턴트로, 적절한 구성과 사용을 통해 개발 효율성을 크게 향상시킬 수 있습니다. 다음을 권장합니다:

기본 기능부터 시작하여 점진적으로 고급 기능 탐색
프로젝트 요구사항에 따른 구성 사용자 정의
CLAUDE.md 파일을 활용하여 프로젝트별 정보 기록
보안을 위한 적절한 권한 관리 사용
MCP 및 사용자 정의 명령으로 기능 확장 탐색

즐거운 사용되시기 바랍니다! 문제가 있으시면 공식 문서 또는 커뮤니티 지원을 참조하세요.

Claude Code 빠른 시작 가이드 ​

1. 설치 및 구성 ​

1.1 시스템 요구사항 ​

1.2 설치 단계 ​

2. API 키 획득 및 구성 ​

2.1 계정 등록 ​

2.2 API 키 생성 ​

3. 구성 파일 설정 ​

3.1 API 키 구성 ​

구성 파일 설정 방법 ​

3.2 권한 설정 (선택사항) ​

3.3 작업 디렉터리 구성 (선택사항) ​

3.4 간편 설정 - 원클릭 스크립트 ​

4. 기본 사용법 ​

4.1 시작 방법 ​

대화형 모드 ​

초기 프롬프트와 함께 시작 ​

비대화형 모드 ​

파이프라인 입력 처리 ​

4.2 일반적인 명령어 ​

4.3 단축키 ​

일반 제어 ​

여러 줄 입력 ​

5. 고급 기능 ​

5.1 CLI 참조 ​

기본 CLI 명령 ​

중요한 CLI 플래그 ​

5.2 대화형 모드 ​

Vim 모드 ​

모드 전환 ​

네비게이션 (NORMAL 모드) ​

5.3 슬래시 명령 ​

기본 명령 ​

고급 명령 ​

사용자 정의 슬래시 명령 ​

6. 실전 튜토리얼 ​

6.1 새로운 코드베이스 이해 ​

코드베이스 개요 빠르게 파악 ​

관련 코드 찾기 ​

6.2 효율적인 버그 수정 ​

오류 메시지 진단 ​

6.3 코드 리팩토링 ​

기존 코드 현대화 ​

6.4 테스트 처리 ​

테스트 커버리지 추가 ​

6.5 Pull Request 생성 ​

포괄적인 PR 생성 ​

6.6 문서화 처리 ​

코드 문서 생성 ​

6.7 이미지 사용 ​

이미지 및 스크린샷 분석 ​

6.8 프로젝트 메모리 설정 ​

효과적인 CLAUDE.md 파일 생성 ​

6.9 Unix 스타일 유틸리티 ​

검증 프로세스에 추가 ​

파이프라인 입력 출력 ​

6.10 MCP 서버 구성 ​

MCP 서버 구성 ​

Postgres MCP 서버에 연결 ​

7. 고급 기능 ​

7.1 IDE 통합 ​

7.2 모델 전환 및 구성 ​

7.3 컨텍스트 관리 ​

7.4 대화 복원 ​

7.5 이미지 처리 ​

7.6 심층 사고 ​

7.7 Git 고급 작업 ​

Git 작업 트리 사용 ​

7.8 기타 고급 기능 ​

8. 일반적인 문제 해결 ​

8.1 메모리 저장 문제 ​

Claude Code는 메모리를 어떻게 저장하나요? ​

8.2 모델명 문제 ​

가끔 잘못된 모델명으로 응답하는 이유는? ​

8.3 명령줄 오류 ​

명령줄 매개변수 실행 오류는 어떻게 해결하나요? ​

8.4 Claude Code 정리 ​

Claude Code를 완전히 정리하는 방법은? ​

8.5 API 오류 ​

API Error, Tools Error가 발생하면 어떻게 하나요? ​

Claude Code 빠른 시작 가이드

1. 설치 및 구성

1.1 시스템 요구사항

1.2 설치 단계

2. API 키 획득 및 구성

2.1 계정 등록

2.2 API 키 생성

3. 구성 파일 설정

3.1 API 키 구성

구성 파일 설정 방법

3.2 권한 설정 (선택사항)

3.3 작업 디렉터리 구성 (선택사항)

3.4 간편 설정 - 원클릭 스크립트

4. 기본 사용법

4.1 시작 방법

대화형 모드

초기 프롬프트와 함께 시작

비대화형 모드

파이프라인 입력 처리

4.2 일반적인 명령어

4.3 단축키

일반 제어

여러 줄 입력

5. 고급 기능

5.1 CLI 참조

기본 CLI 명령

중요한 CLI 플래그

5.2 대화형 모드

Vim 모드

모드 전환

네비게이션 (NORMAL 모드)

5.3 슬래시 명령

기본 명령

고급 명령

사용자 정의 슬래시 명령

6. 실전 튜토리얼

6.1 새로운 코드베이스 이해

코드베이스 개요 빠르게 파악

관련 코드 찾기

6.2 효율적인 버그 수정

오류 메시지 진단

6.3 코드 리팩토링

기존 코드 현대화

6.4 테스트 처리

테스트 커버리지 추가

6.5 Pull Request 생성

포괄적인 PR 생성

6.6 문서화 처리

코드 문서 생성

6.7 이미지 사용

이미지 및 스크린샷 분석

6.8 프로젝트 메모리 설정

효과적인 CLAUDE.md 파일 생성

6.9 Unix 스타일 유틸리티

검증 프로세스에 추가

파이프라인 입력 출력

6.10 MCP 서버 구성

MCP 서버 구성

Postgres MCP 서버에 연결

7. 고급 기능

7.1 IDE 통합

7.2 모델 전환 및 구성

7.3 컨텍스트 관리

7.4 대화 복원

7.5 이미지 처리

7.6 심층 사고

7.7 Git 고급 작업

Git 작업 트리 사용

7.8 기타 고급 기능

8. 일반적인 문제 해결

8.1 메모리 저장 문제

Claude Code는 메모리를 어떻게 저장하나요?

8.2 모델명 문제

가끔 잘못된 모델명으로 응답하는 이유는?

8.3 명령줄 오류

명령줄 매개변수 실행 오류는 어떻게 해결하나요?

8.4 Claude Code 정리

Claude Code를 완전히 정리하는 방법은?

8.5 API 오류

API Error, Tools Error가 발생하면 어떻게 하나요?