NodeJS 18+를 설치한 다음 실행하세요:

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

권한 문제와 보안 위험을 초래할 수 있으므로 sudo npm install -g를 사용하지 마세요. 권한 오류가 발생하면 Claude Code 구성에서 권장 솔루션을 참조하세요.

Claude Code는 터미널에서 작동하고, 코드베이스를 이해하며, 자연어 명령을 통해 더 빠르게 코딩할 수 있도록 도와주는 에이전트 코딩 도구입니다. 개발 환경에 직접 통합되어 추가 서버나 복잡한 설정 없이 워크플로우를 간소화합니다.

Claude Code의 주요 기능은 다음과 같습니다:

  • 코드베이스 전체에서 파일 편집 및 버그 수정
  • 코드 아키텍처 및 로직에 대한 질문에 답변
  • 테스트, 린팅 및 기타 명령 실행 및 수정
  • git 기록 검색, 병합 충돌 해결, 커밋 및 PR 생성

연구 미리보기

Code는 연구 미리보기로 베타 버전입니다. AI 협업 선호도, AI 지원이 가장 많은 혜택을 주는 워크플로우, 에이전트 경험 개선 방법에 대한 개발자 피드백을 수집하고 있습니다.

이 초기 버전은 사용자 피드백을 기반으로 발전할 것입니다. 앞으로 몇 주 동안 도구 실행 안정성, 장기 실행 명령 지원, 터미널 렌더링, 그리고 Claude의 자체 기능에 대한 지식을 향상시킬 계획입니다.

버그는 /bug 명령을 통해 직접 보고하거나 GitHub 저장소를 통해 보고할 수 있습니다.


시작하기 전에

시스템 요구 사항 확인

  • 운영 체제: macOS 10.15+, Ubuntu 20.04+/Debian 10+, 또는 WSL을 통한 Windows
  • 하드웨어: 최소 4GB RAM
  • 소프트웨어:
    • Node.js 18+
    • git 2.23+ (선택 사항)
    • PR 워크플로우를 위한 GitHub 또는 GitLab CLI (선택 사항)
    • 향상된 파일 검색을 위한 ripgrep (rg) (선택 사항)
  • 네트워크: 인증 및 AI 처리를 위한 인터넷 연결 필요
  • 위치: 지원되는 국가에서만 사용 가능

WSL 설치 문제 해결

현재 Claude Code는 Windows에서 직접 실행되지 않으며 WSL이 필요합니다. WSL에서 문제가 발생하는 경우:

  1. OS/플랫폼 감지 문제: 설치 중 오류가 발생하면 WSL이 Windows npm을 사용하고 있을 수 있습니다. 다음을 시도해보세요:

    • 설치 전에 npm config set os linux 실행
    • npm install -g @anthropic-ai/claude-code --force --no-os-check로 설치 (sudo 사용하지 마세요)
  2. Node를 찾을 수 없는 오류: claude를 실행할 때 exec: node: not found 오류가 표시되면 WSL 환경이 Windows의 Node.js 설치를 사용하고 있을 수 있습니다. which npmwhich node로 확인할 수 있으며, 이는 /mnt/c/가 아닌 /usr/로 시작하는 Linux 경로를 가리켜야 합니다. 이 문제를 해결하려면 Linux 배포판의 패키지 관리자를 통해 또는 nvm을 통해 Node를 설치해 보세요.

설치 및 인증

1

Claude Code 설치

터미널에서 실행: npm install -g @anthropic-ai/claude-code

권한 문제와 보안 위험을 초래할 수 있으므로 sudo npm install -g를 사용하지 마세요. 권한 오류가 발생하면 Claude Code 구성에서 권장 솔루션을 참조하세요.

2

프로젝트로 이동

cd your-project-directory
3

Claude Code 시작

실행하려면 claude 입력
4

인증 완료

Claude Code는 두 가지 인증 옵션을 제공합니다:

  • Anthropic Console: 기본 옵션입니다. Anthropic Console을 통해 연결하고 OAuth 프로세스를 완료합니다. console.anthropic.com에서 활성 결제가 필요합니다.

  • Max 플랜: Claude의 Max 플랜을 구독하면 Claude Code와 웹 인터페이스를 모두 포함하는 단일 구독을 이용할 수 있습니다. 동일한 가격대에서 더 많은 가치를 얻으면서 한 곳에서 계정을 관리할 수 있습니다. Claude.ai 계정으로 로그인하세요. 시작 시 구독 유형과 일치하는 옵션을 선택하세요.


핵심 기능 및 워크플로우

Claude Code는 터미널에서 직접 작동하며, 프로젝트 컨텍스트를 이해하고 실제 작업을 수행합니다. 컨텍스트에 파일을 수동으로 추가할 필요가 없으며, Claude가 필요에 따라 코드베이스를 탐색합니다.

설계부터 보안 및 개인 정보 보호

코드의 보안은 가장 중요합니다. Claude Code의 아키텍처는 다음을 보장합니다:

  • 직접 API 연결: 쿼리가 중간 서버 없이 Anthropic의 API로 직접 전송됩니다
  • 당신이 일하는 곳에서 작동: 터미널에서 직접 작동합니다
  • 컨텍스트 이해: 전체 프로젝트 구조에 대한 인식을 유지합니다
  • 조치 취하기: 파일 편집 및 커밋 생성과 같은 실제 작업을 수행합니다

질문에서 솔루션까지 몇 초 만에

# 코드베이스에 대해 질문하기
claude
> how does our authentication system work?

# 한 명령으로 커밋 생성하기
claude commit

# 여러 파일에 걸친 문제 해결하기
claude "fix the type errors in the auth module"

프로젝트 초기화

처음 사용자의 경우 다음을 권장합니다:

  1. claude로 Claude Code 시작
  2. summarize this project와 같은 간단한 명령 시도
  3. /init으로 CLAUDE.md 프로젝트 가이드 생성
  4. Claude에게 생성된 CLAUDE.md 파일을 저장소에 커밋하도록 요청

일반적인 작업에 Claude Code 사용하기

Claude Code는 터미널에서 직접 작동하며, 프로젝트 컨텍스트를 이해하고 실제 작업을 수행합니다. 컨텍스트에 파일을 수동으로 추가할 필요가 없으며, Claude가 필요에 따라 코드베이스를 탐색합니다.

익숙하지 않은 코드 이해하기

> what does the payment processing system do?
> find where user permissions are checked
> explain how the caching layer works

Git 작업 자동화하기

> commit my changes
> create a pr
> which commit added tests for markdown back in December?
> rebase on main and resolve any merge conflicts

코드 지능적으로 편집하기

> add input validation to the signup form
> refactor the logger to use the new API
> fix the race condition in the worker queue

코드 테스트 및 디버깅하기

> run tests for the auth module and fix failures
> find and fix security vulnerabilities
> explain why this test is failing

더 깊은 사고 장려하기

복잡한 문제의 경우, Claude에게 더 깊이 생각하도록 명시적으로 요청하세요:

> think about how we should architect the new payment service
> think hard about the edge cases in our authentication flow

Claude Code는 Claude가 확장된 사고를 사용할 때 표시합니다(Claude Sonnet 3.7, Claude Opus 4에서 사용 가능). 계획이 더 필요한 작업에 대해 Claude에게 “think” 또는 “think deeply”라고 사전에 요청할 수 있습니다. 먼저 Claude에게 작업에 대해 알려주고 프로젝트에서 컨텍스트를 수집하도록 하는 것이 좋습니다. 그런 다음 계획을 세우기 위해 “think”라고 요청하세요.

Claude는 사용하는 단어에 따라 더 많이 생각할 것입니다. 예를 들어, “think hard”는 단순히 “think”라고 말하는 것보다 더 확장된 사고를 유발합니다.

더 많은 팁은 확장된 사고 팁을 참조하세요.

CI 및 인프라 워크플로우 자동화하기

Claude Code는 헤드리스 실행을 위한 비대화형 모드를 제공합니다. 이는 스크립트, 파이프라인, Github Actions와 같은 비대화형 컨텍스트에서 Claude Code를 실행할 때 특히 유용합니다.

비대화형 모드에서 실행하려면 --print (-p)를 사용하세요. 이 모드에서는 ANTHROPIC_API_KEY 환경 변수를 설정하여 사용자 지정 API 키를 제공할 수 있습니다.

비대화형 모드는 Claude가 사용할 수 있는 명령 세트를 미리 구성할 때 특히 유용합니다:

export ANTHROPIC_API_KEY=sk_...
claude -p "update the README with the latest changes" --allowedTools "Bash(git diff:*)" "Bash(git log:*)" Write --disallowedTools ...

명령으로 Claude Code 제어하기

CLI 명령

명령설명예시
claude대화형 REPL 시작claude
claude "query"초기 프롬프트로 REPL 시작claude "explain this project"
claude -p "query"일회성 쿼리 실행 후 종료claude -p "explain this function"
cat file | claude -p "query"파이프된 콘텐츠 처리cat logs.txt | claude -p "explain"
claude config설정 구성claude config set --global theme dark
claude update최신 버전으로 업데이트claude update
claude mcpModel Context Protocol 서버 구성튜토리얼의 MCP 섹션 참조

CLI 플래그:

  • --print (-p): 대화형 모드 없이 응답 출력
  • --json: --print 모드에서 JSON 출력 반환, 스크립팅 및 자동화에 유용
  • --verbose: 상세 로깅 활성화, 전체 턴별 출력 표시(인쇄 및 대화형 모드 모두에서 디버깅에 유용)
  • --dangerously-skip-permissions: 권한 프롬프트 건너뛰기

슬래시 명령

세션 내에서 Claude의 동작 제어:

명령목적
/bug버그 보고(대화를 Anthropic에 전송)
/clear대화 기록 지우기
/compact [instructions]선택적 집중 지침으로 대화 압축
/config구성 보기/수정
/cost토큰 사용 통계 표시
/doctorClaude Code 설치 상태 확인
/help사용 도움말 얻기
/initCLAUDE.md 가이드로 프로젝트 초기화
/loginAnthropic 계정 전환
/logoutAnthropic 계정에서 로그아웃
/memoryCLAUDE.md 메모리 파일 편집
/pr_comments풀 리퀘스트 댓글 보기
/review코드 리뷰 요청
/terminal-setup줄바꿈을 위한 Shift+Enter 키 바인딩 설치(iTerm2 및 VSCode만 해당)
/vim삽입 및 명령 모드를 번갈아 사용하는 vim 모드 진입

Claude의 메모리 관리하기

Claude Code는 스타일 가이드라인 및 워크플로우의 일반적인 명령과 같은 기본 설정을 세션 간에 기억할 수 있습니다.

메모리 유형 결정하기

Claude Code는 각각 다른 목적을 제공하는 세 가지 메모리 위치를 제공합니다:

메모리 유형위치목적사용 사례 예시
프로젝트 메모리./CLAUDE.md팀 공유 규칙 및 지식프로젝트 아키텍처, 코딩 표준, 일반적인 워크플로우
프로젝트 메모리(로컬)./CLAUDE.local.md개인 프로젝트별 기본 설정샌드박스 URL, 선호하는 테스트 데이터
사용자 메모리~/.claude/CLAUDE.md전역 개인 기본 설정코드 스타일 기본 설정, 개인 도구 단축키

모든 메모리 파일은 Claude Code가 시작될 때 자동으로 컨텍스트에 로드됩니다.

Claude가 메모리를 찾는 방법

Claude Code는 메모리를 재귀적으로 읽습니다: 현재 작업 디렉토리에서 시작하여 / 까지 재귀적으로 올라가며 발견한 CLAUDE.md 또는 CLAUDE.local.md 파일을 읽습니다. 이는 _foo/bar/_에서 Claude Code를 실행하고 _foo/CLAUDE.md_와 foo/bar/CLAUDE.md 모두에 메모리가 있을 때 특히 편리합니다.

# 단축키로 빠르게 메모리 추가하기

메모리를 추가하는 가장 빠른 방법은 입력을 # 문자로 시작하는 것입니다:

# Always use descriptive variable names

어떤 메모리 파일에 저장할지 선택하라는 메시지가 표시됩니다.

/memory로 직접 메모리 편집하기

세션 중에 /memory 슬래시 명령을 사용하여 시스템 편집기에서 메모리 파일을 열어 더 광범위한 추가 또는 구성을 할 수 있습니다.

메모리 모범 사례

  • 구체적으로 작성하세요: “Format code properly”보다 “Use 2-space indentation”이 더 좋습니다.
  • 구조를 사용하여 구성하세요: 각 개별 메모리를 글머리 기호로 형식화하고 관련 메모리를 설명적인 마크다운 제목 아래에 그룹화하세요.
  • 정기적으로 검토하세요: 프로젝트가 발전함에 따라 메모리를 업데이트하여 Claude가 항상 가장 최신 정보와 컨텍스트를 사용하도록 하세요.

권한 및 보안 관리하기

Claude Code는 권한과 안전성의 균형을 맞추기 위해 계층화된 권한 시스템을 사용합니다:

도구 유형예시승인 필요”Yes, don’t ask again” 동작
읽기 전용파일 읽기, LS, Grep아니오해당 없음
Bash 명령쉘 실행프로젝트 디렉토리 및 명령별로 영구적
파일 수정파일 편집/쓰기세션 종료까지

Claude가 사용할 수 있는 도구

Claude Code는 코드베이스를 이해하고 수정하는 데 도움이 되는 강력한 도구 세트에 액세스할 수 있습니다:

도구설명권한 필요
Agent복잡한 다단계 작업을 처리하기 위해 하위 에이전트를 실행합니다아니오
Bash환경에서 쉘 명령을 실행합니다
Glob패턴 매칭을 기반으로 파일을 찾습니다아니오
Grep파일 내용에서 패턴을 검색합니다아니오
LS파일 및 디렉토리를 나열합니다아니오
Read파일의 내용을 읽습니다아니오
Edit특정 파일에 대한 대상 편집을 수행합니다
Write파일을 생성하거나 덮어씁니다
NotebookEditJupyter 노트북 셀을 수정합니다
NotebookReadJupyter 노트북 내용을 읽고 표시합니다아니오
WebFetch지정된 URL에서 콘텐츠를 가져옵니다

권한 규칙은 /allowed-tools를 사용하거나 권한 설정에서 구성할 수 있습니다.

프롬프트 인젝션으로부터 보호하기

프롬프트 인젝션은 공격자가 악의적인 텍스트를 삽입하여 AI 어시스턴트의 지침을 재정의하거나 조작하려는 기술입니다. Claude Code는 이러한 공격에 대한 여러 가지 안전장치를 포함합니다:

  • 권한 시스템: 민감한 작업에는 명시적인 승인이 필요합니다
  • 컨텍스트 인식 분석: 전체 요청을 분석하여 잠재적으로 유해한 지침을 감지합니다
  • 입력 정제: 사용자 입력을 처리하여 명령 인젝션을 방지합니다
  • 명령 차단 목록: curlwget과 같이 웹에서 임의의 콘텐츠를 가져오는 위험한 명령을 차단합니다

신뢰할 수 없는 콘텐츠 작업을 위한 모범 사례:

  1. 승인하기 전에 제안된 명령 검토
  2. 신뢰할 수 없는 콘텐츠를 Claude에 직접 파이프하지 않기
  3. 중요한 파일에 대한 제안된 변경 사항 확인
  4. /bug로 의심스러운 동작 보고

이러한 보호 기능이 위험을 크게 줄이지만, 어떤 시스템도 모든 공격에 완전히 면역이 아닙니다. AI 도구로 작업할 때 항상 좋은 보안 관행을 유지하세요.

네트워크 액세스 구성

Claude Code는 다음에 대한 액세스가 필요합니다:

  • api.anthropic.com
  • statsig.anthropic.com
  • sentry.io

컨테이너화된 환경에서 Claude Code를 사용할 때 이러한 URL을 허용 목록에 추가하세요.

환경 변수

Claude Code는 동작을 제어하기 위해 다음 환경 변수를 지원합니다:

변수목적
DISABLE_AUTOUPDATER자동 업데이터를 비활성화하려면 1로 설정
DISABLE_BUG_COMMAND/bug 명령을 비활성화하려면 1로 설정
DISABLE_COST_WARNINGS비용 경고 메시지를 비활성화하려면 1로 설정
DISABLE_ERROR_REPORTINGSentry 오류 보고를 옵트아웃하려면 1로 설정
DISABLE_TELEMETRYStatsig 원격 측정을 옵트아웃하려면 1로 설정(Statsig 이벤트에는 코드, 파일 경로 또는 bash 명령과 같은 사용자 데이터가 포함되지 않음)
HTTP_PROXY네트워크 연결을 위한 HTTP 프록시 서버 지정
HTTPS_PROXY네트워크 연결을 위한 HTTPS 프록시 서버 지정
MCP_TIMEOUTMCP 서버 시작을 위한 타임아웃(밀리초)
MCP_TOOL_TIMEOUTMCP 도구 실행을 위한 타임아웃(밀리초)

Claude Code 구성하기

터미널에서 claude config를 실행하거나 대화형 REPL을 사용할 때 /config 명령을 사용하여 Claude Code를 구성하세요.

구성 옵션

Claude Code는 전역 및 프로젝트 수준 구성을 지원합니다.

구성을 관리하려면 다음 명령을 사용하세요:

  • 설정 나열: claude config list
  • 설정 보기: claude config get <key>
  • 설정 변경: claude config set <key> <value>
  • 설정에 추가(목록의 경우): claude config add <key> <value>
  • 설정에서 제거(목록의 경우): claude config remove <key> <value>

기본적으로 config는 프로젝트 구성을 변경합니다. 전역 구성을 관리하려면 --global(또는 -g) 플래그를 사용하세요.

전역 구성

전역 구성을 설정하려면 claude config set -g <key> <value>를 사용하세요:

설명
autoUpdaterStatusdisabled 또는 enabled자동 업데이터 활성화 또는 비활성화(기본값: enabled)
envJSON (예: '{"FOO": "bar"}')모든 세션에 적용될 환경 변수
preferredNotifChanneliterm2, iterm2_with_bell, terminal_bell, 또는 notifications_disabled알림을 받고 싶은 위치(기본값: iterm2)
themedark, light, light-daltonized, 또는 dark-daltonized색상 테마
verbosetrue 또는 false전체 bash 및 명령 출력을 표시할지 여부(기본값: false)

자동 업데이터 권한 옵션

Claude Code가 전역 npm 접두사 디렉토리에 쓰기 위한 충분한 권한이 없음을 감지하면(자동 업데이트에 필요), 이 문서 페이지를 가리키는 경고가 표시됩니다. 자동 업데이터 문제에 대한 자세한 해결책은 문제 해결 가이드를 참조하세요.

권장: 사용자가 쓸 수 있는 새 npm 접두사 생성

# 먼저, 나중에 마이그레이션할 기존 전역 패키지 목록 저장
npm list -g --depth=0 > ~/npm-global-packages.txt

# 전역 패키지를 위한 디렉토리 생성
mkdir -p ~/.npm-global

# 새 디렉토리 경로를 사용하도록 npm 구성
npm config set prefix ~/.npm-global

# 참고: ~/.bashrc를 쉘에 맞게 ~/.zshrc, ~/.profile 또는 다른 적절한 파일로 바꾸세요
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# 새 PATH 설정 적용
source ~/.bashrc

# 이제 새 위치에 Claude Code 재설치
npm install -g @anthropic-ai/claude-code

# 선택 사항: 이전 전역 패키지를 새 위치에 재설치
# ~/npm-global-packages.txt를 보고 유지하고 싶은 패키지 설치
# npm install -g package1 package2 package3...

이 옵션을 권장하는 이유:

  • 시스템 디렉토리 권한을 수정하지 않음
  • 전역 npm 패키지를 위한 깨끗하고 전용 위치 생성
  • 보안 모범 사례 준수

Claude Code가 적극적으로 개발 중이므로 위의 권장 옵션을 사용하여 자동 업데이트를 설정하는 것이 좋습니다.

자동 업데이터 비활성화하기

권한을 수정하는 대신 자동 업데이터를 비활성화하려면 다음을 사용할 수 있습니다:

claude config set -g autoUpdaterStatus disabled

프로젝트 구성

claude config set <key> <value>로 프로젝트 구성 관리(-g 플래그 없이):

설명
allowedTools도구 배열수동 승인 없이 실행할 수 있는 도구
ignorePatternsglob 문자열 배열도구 사용 시 무시되는 파일/디렉토리

예시:

# npm test가 승인 없이 실행되도록 허용
claude config add allowedTools "Bash(npm test)"

# npm test 및 모든 하위 명령이 승인 없이 실행되도록 허용
claude config add allowedTools "Bash(npm test:*)"

# Claude에게 node_modules를 무시하도록 지시
claude config add ignorePatterns node_modules
claude config add ignorePatterns "node_modules/**"

allowedTools 규칙 형식은 권한을 참조하세요.

터미널 설정 최적화하기

Claude Code는 터미널이 적절하게 구성되었을 때 가장 잘 작동합니다. 경험을 최적화하려면 다음 지침을 따르세요.

지원되는 쉘:

  • Bash
  • Zsh
  • Fish

테마 및 외관

Claude는 터미널의 테마를 제어할 수 없습니다. 이는 터미널 애플리케이션에서 처리됩니다. 온보딩 중이나 /config 명령을 통해 언제든지 Claude Code의 테마를 터미널에 맞출 수 있습니다.

줄 바꿈

Claude Code에 줄 바꿈을 입력하는 여러 옵션이 있습니다:

  • 빠른 이스케이프: \ 다음에 Enter를 입력하여 줄 바꿈 생성
  • 키보드 단축키: 적절한 구성으로 Option+Enter(Meta+Enter) 누르기

터미널에서 Option+Enter를 설정하려면:

Mac Terminal.app의 경우:

  1. 설정 → 프로필 → 키보드 열기
  2. “Use Option as Meta Key” 체크

iTerm2 및 VSCode 터미널의 경우:

  1. 설정 → 프로필 → 키 열기
  2. 일반에서 왼쪽/오른쪽 Option 키를 “Esc+“로 설정

iTerm2 및 VSCode 사용자를 위한 팁: Claude Code 내에서 /terminal-setup을 실행하여 Shift+Enter를 더 직관적인 대안으로 자동 구성하세요.

알림 설정

적절한 알림 구성으로 Claude가 작업을 완료할 때 놓치지 마세요:

터미널 벨 알림

작업이 완료될 때 소리 알림 활성화:

claude config set --global preferredNotifChannel terminal_bell

macOS 사용자의 경우: 시스템 설정 → 알림 → [터미널 앱]에서 알림 권한을 활성화하는 것을 잊지 마세요.

iTerm 2 시스템 알림

작업이 완료될 때 iTerm 2 알림을 위해:

  1. iTerm 2 환경설정 열기
  2. 프로필 → 터미널로 이동
  3. “Silence bell” 및 “Send notification when idle” 활성화
  4. 원하는 알림 지연 설정

이러한 알림은 iTerm 2에만 해당되며 기본 macOS 터미널에서는 사용할 수 없습니다.

대용량 입력 처리하기

광범위한 코드나 긴 지침으로 작업할 때:

  • 직접 붙여넣기 피하기: Claude Code는 매우 긴 붙여넣기 콘텐츠에 어려움을 겪을 수 있습니다
  • 파일 기반 워크플로우 사용: 콘텐츠를 파일에 작성하고 Claude에게 읽도록 요청
  • VS Code 제한 사항 인지: VS Code 터미널은 특히 긴 붙여넣기를 잘라내는 경향이 있습니다

Vim 모드

Claude Code는 /vim 또는 /config를 통해 활성화할 수 있는 Vim 키 바인딩의 하위 집합을 지원합니다.

지원되는 하위 집합에는 다음이 포함됩니다:

  • 모드 전환: Esc(NORMAL로), i/I, a/A, o/O(INSERT로)
  • 탐색: h/j/k/l, w/e/b, 0/$/^, gg/G
  • 편집: x, dw/de/db/dd/D, cw/ce/cb/cc/C, .(반복)

비용 효율적으로 관리하기

Claude Code는 각 상호 작용에 토큰을 소비합니다. 평균 비용은 개발자당 하루에 $6이며, 사용자의 90%는 일일 비용이 $12 미만입니다.

비용 추적하기

  • /cost를 사용하여 현재 세션 사용량 확인
  • Anthropic Console 사용자:
  • Max 플랜 사용자: 사용량은 Max 플랜 구독에 포함되어 있습니다

토큰 사용량 줄이기

  • 대화 압축:

    • Claude는 컨텍스트가 용량의 95%를 초과할 때 기본적으로 자동 압축을 사용합니다

    • 자동 압축 토글: /config를 실행하고 “Auto-compact enabled”로 이동

    • 컨텍스트가 커지면 수동으로 /compact 사용

    • 사용자 지정 지침 추가: /compact Focus on code samples and API usage

    • CLAUDE.md에 추가하여 압축 사용자 지정:

      # Summary instructions
      
      When you are using compact, please focus on test output and code changes
      
  • 구체적인 쿼리 작성: 불필요한 스캔을 유발하는 모호한 요청 피하기

  • 복잡한 작업 분해: 대규모 작업을 집중된 상호 작용으로 분할

  • 작업 간 기록 지우기: /clear를 사용하여 컨텍스트 재설정

비용은 다음에 따라 크게 달라질 수 있습니다:

  • 분석 중인 코드베이스 크기
  • 쿼리의 복잡성
  • 검색 또는 수정 중인 파일 수
  • 대화 기록 길이
  • 대화 압축 빈도

팀 배포의 경우, 더 넓은 출시 전에 사용 패턴을 설정하기 위해 소규모 파일럿 그룹으로 시작하는 것이 좋습니다.


모델 구성

기본적으로 Claude Code는 claude-opus-4-20250514를 사용합니다. 다음 환경 변수를 사용하여 이를 재정의할 수 있습니다:

# Anthropic API
ANTHROPIC_MODEL='claude-opus-4-20250514'
ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku-20241022'

# Amazon Bedrock
ANTHROPIC_MODEL='us.anthropic.claude-opus-4-20250514-v1:0'
ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-3-5-haiku-20241022-v1:0'

# Google Vertex AI
ANTHROPIC_MODEL='claude-opus-4@20250514'
ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

전역 구성을 사용하여 이러한 변수를 설정할 수도 있습니다:

# Anthropic API 구성
claude config set --global env '{"ANTHROPIC_MODEL": "claude-opus-4-20250514"}'

# Bedrock 구성
claude config set --global env '{"CLAUDE_CODE_USE_BEDROCK": "true", "ANTHROPIC_MODEL": "us.anthropic.claude-opus-4-20250514-v1:0"}'

# Vertex AI 구성
claude config set --global env '{"CLAUDE_CODE_USE_VERTEX": "true", "ANTHROPIC_MODEL": "claude-opus-4@20250514"}'

다양한 제공업체에서 사용 가능한 모든 모델은 모델 이름 참조를 참조하세요.

타사 API와 함께 사용하기

Claude Code는 사용하는 API 제공업체에 관계없이 Claude Sonnet 3.7 및 Claude Haiku 3.5 모델 모두에 액세스해야 합니다.

Amazon Bedrock에 연결하기

CLAUDE_CODE_USE_BEDROCK=1

프록시를 통해 Claude Code에 액세스하려면 ANTHROPIC_BEDROCK_BASE_URL 환경 변수를 사용할 수 있습니다:

ANTHROPIC_BEDROCK_BASE_URL='https://your-proxy-url'

프롬프트 캐싱이 활성화되어 있지 않은 경우 다음도 설정하세요:

DISABLE_PROMPT_CACHING=1

표준 AWS SDK 자격 증명(예: ~/.aws/credentials 또는 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY와 같은 관련 환경 변수)이 필요합니다. AWS 자격 증명을 설정하려면 다음을 실행하세요:

aws configure

비용 절감 및 더 높은 속도 제한을 위한 프롬프트 캐싱은 Amazon Bedrock에 문의하세요.

사용자는 AWS 계정에서 Claude Sonnet 3.7 및 Claude Haiku 3.5 모델 모두에 액세스할 수 있어야 합니다. 모델 액세스 역할이 있는 경우, 이러한 모델이 아직 사용 가능하지 않다면 액세스를 요청해야 할 수 있습니다. 추론 프로필은 지역 간 기능이 필요하므로 각 지역의 Bedrock에 대한 액세스가 필요합니다.

Google Vertex AI에 연결하기

CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

프록시를 통해 Claude Code에 액세스하려면 ANTHROPIC_VERTEX_BASE_URL 환경 변수를 사용할 수 있습니다:

ANTHROPIC_VERTEX_BASE_URL='https://your-proxy-url'

프롬프트 캐싱이 활성화되어 있지 않은 경우 다음도 설정하세요:

DISABLE_PROMPT_CACHING=1

Vertex AI의 Claude Code는 현재 us-east5 지역만 지원합니다. 프로젝트에 이 특정 지역에 할당된 할당량이 있는지 확인하세요.

사용자는 Vertex AI 프로젝트에서 Claude Sonnet 3.7 및 Claude Haiku 3.5 모델 모두에 액세스할 수 있어야 합니다.

google-auth-library를 통해 구성된 표준 GCP 자격 증명이 필요합니다. GCP 자격 증명을 설정하려면 다음을 실행하세요:

gcloud auth application-default login

최상의 경험을 위해 높은 속도 제한을 위해 Google에 문의하세요.

프록시를 통해 연결하기

LLM 프록시(LiteLLM과 같은)와 함께 Claude Code를 사용할 때 다음 환경 변수와 구성을 사용하여 인증 동작을 제어할 수 있습니다. 이러한 설정은 Bedrock 및 Vertex 관련 설정과 혼합하여 사용할 수 있습니다.

환경 변수

  • ANTHROPIC_AUTH_TOKEN: AuthorizationProxy-Authorization 헤더의 사용자 지정 값(여기에 설정한 값 앞에 Bearer 가 붙습니다)
  • ANTHROPIC_CUSTOM_HEADERS: 요청에 추가하려는 사용자 지정 헤더(Name: Value 형식)
  • HTTP_PROXY: HTTP 프록시 URL 설정
  • HTTPS_PROXY: HTTPS 프록시 URL 설정

환경 변수 대신 파일을 통해 구성하려면 전역 Claude 구성(~/.claude.json)의 env 객체에 이러한 변수를 추가할 수 있습니다.

전역 구성 옵션

  • apiKeyHelper: API 키를 가져오기 위한 사용자 지정 쉘 스크립트(시작 시 한 번 호출되며 각 세션 기간 동안 캐시됨)

개발 컨테이너 참조 구현

Claude Code는 일관되고 안전한 환경이 필요한 팀을 위한 개발 컨테이너 구성을 제공합니다. 이 사전 구성된 devcontainer 설정은 VS Code의 Remote - Containers 확장 및 유사한 도구와 원활하게 작동합니다.

컨테이너의 향상된 보안 조치(격리 및 방화벽 규칙)를 통해 무인 작업을 위해 권한 프롬프트를 우회하기 위해 claude --dangerously-skip-permissions를 실행할 수 있습니다. 필요에 맞게 사용자 지정할 수 있는 참조 구현을 포함했습니다.

devcontainer가 상당한 보호를 제공하지만, 어떤 시스템도 모든 공격에 완전히 면역이 아닙니다. 항상 좋은 보안 관행을 유지하고 Claude의 활동을 모니터링하세요.

주요 기능

  • 프로덕션 준비 Node.js: 필수 개발 종속성이 있는 Node.js 20 기반
  • 설계부터 보안: 필요한 서비스에만 네트워크 액세스를 제한하는 사용자 지정 방화벽
  • 개발자 친화적 도구: git, 생산성 향상 기능이 있는 ZSH, fzf 등 포함
  • 원활한 VS Code 통합: 사전 구성된 확장 및 최적화된 설정
  • 세션 지속성: 컨테이너 재시작 간에 명령 기록 및 구성 유지
  • 어디서나 작동: macOS, Windows 및 Linux 개발 환경과 호환

4단계로 시작하기

  1. VS Code 및 Remote - Containers 확장 설치
  2. Claude Code 참조 구현 저장소 복제
  3. VS Code에서 저장소 열기
  4. 메시지가 표시되면 “Reopen in Container” 클릭(또는 명령 팔레트 사용: Cmd+Shift+P → “Remote-Containers: Reopen in Container”)

구성 분석

devcontainer 설정은 세 가지 주요 구성 요소로 구성됩니다:

보안 기능

컨테이너는 방화벽 구성으로 다층 보안 접근 방식을 구현합니다:

  • 정밀한 액세스 제어: 허용 목록에 있는 도메인(npm 레지스트리, GitHub, Anthropic API 등)에만 아웃바운드 연결 제한
  • 기본 거부 정책: 다른 모든 외부 네트워크 액세스 차단
  • 시작 시 확인: 컨테이너 초기화 시 방화벽 규칙 검증
  • 격리: 주 시스템과 분리된 안전한 개발 환경 생성

사용자 지정 옵션

devcontainer 구성은 필요에 맞게 조정할 수 있도록 설계되었습니다:

  • 워크플로우에 따라 VS Code 확장 추가 또는 제거
  • 다양한 하드웨어 환경에 맞게 리소스 할당 수정
  • 네트워크 액세스 권한 조정
  • 쉘 구성 및 개발자 도구 사용자 지정

다음 단계


라이선스 및 데이터 사용

Claude Code는 Anthropic의 상업적 서비스 약관에 따라 베타 연구 미리보기로 제공됩니다.

데이터 사용 방법

우리는 데이터 사용 방법에 대해 완전히 투명하게 공개하고자 합니다. 피드백을 사용하여 제품과 서비스를 개선할 수 있지만, Claude Code에서 받은 피드백을 사용하여 생성 모델을 훈련하지는 않을 것입니다. 잠재적으로 민감한 특성을 고려하여 사용자 피드백 기록을 30일 동안만 저장합니다.

피드백 기록

Claude Code에 대한 피드백(예: 사용 기록)을 보내기로 선택한 경우, Anthropic은 해당 피드백을 사용하여 관련 문제를 디버깅하고 Claude Code의 기능을 개선할 수 있습니다(예: 유사한 버그가 발생할 위험을 줄이기 위해). 이 피드백을 사용하여 생성 모델을 훈련하지는 않을 것입니다.

개인 정보 보호 장치

민감한 정보에 대한 제한된 보존 기간, 사용자 세션 데이터에 대한 제한된 액세스, 모델 훈련을 위한 피드백 사용에 대한 명확한 정책 등 데이터를 보호하기 위한 여러 안전장치를 구현했습니다.

자세한 내용은 상업적 서비스 약관개인정보 보호정책을 검토하세요.

라이선스

© Anthropic PBC. 모든 권리 보유. 사용은 Anthropic의 상업적 서비스 약관에 따릅니다.