Claude Code 개요

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

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

Claude Code의 주요 기능:

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

​

시작하기 전에

​

시스템 요구 사항 확인

• 운영 체제: 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 처리를 위한 인터넷 연결 필요
• 위치: 지원되는 국가에서만 사용 가능

​

설치 및 인증

​

핵심 기능 및 워크플로우

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

​

설계상의 보안 및 개인정보 보호

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

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

​

질문에서 해결책까지 몇 초 만에

# 코드베이스에 대해 질문하기
claude
> 인증 시스템은 어떻게 작동하나요?

# 한 번의 명령으로 커밋 생성
claude commit

# 여러 파일의 문제 수정
claude "auth 모듈의 타입 오류를 수정해주세요"

​

프로젝트 초기화

처음 사용하는 경우 다음을 권장합니다:

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

​

일반적인 작업에 Claude Code 사용

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

​

낯선 코드 이해하기

> 결제 처리 시스템은 무엇을 하나요?
> 사용자 권한이 어디서 확인되는지 찾아주세요
> 캐싱 레이어가 어떻게 작동하는지 설명해주세요

​

Git 작업 자동화

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

​

지능적인 코드 편집

> 회원가입 폼에 입력 유효성 검사를 추가해주세요
> 로거를 새로운 API를 사용하도록 리팩토링해주세요
> 워커 큐의 경쟁 상태를 수정해주세요

​

코드 테스트 및 디버깅

> auth 모듈의 테스트를 실행하고 실패한 테스트를 수정해주세요
> 보안 취약점을 찾아서 수정해주세요
> 이 테스트가 왜 실패하는지 설명해주세요

​

더 깊은 사고 유도

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

> 새로운 결제 서비스를 어떻게 설계해야 할지 생각해주세요
> 인증 플로우의 엣지 케이스에 대해 깊이 생각해주세요

Claude Code는 Claude(3.7 Sonnet)가 확장된 사고를 사용할 때 이를 표시합니다. 계획이 더 필요한 작업의 경우 사전에 Claude에게 “생각”하거나 “깊이 생각”하도록 요청할 수 있습니다. 먼저 Claude에게 작업에 대해 설명하고 프로젝트에서 컨텍스트를 수집하도록 한 다음, “생각”하여 계획을 세우도록 요청하는 것이 좋습니다.

​

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

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

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

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

export ANTHROPIC_API_KEY=sk_...
claude -p "README를 최신 변경사항으로 업데이트" --allowedTools "Bash(git diff:*)" "Bash(git log:*)" Edit

​

명령으로 Claude Code 제어

​

CLI 명령

CLI 플래그:

• --print: 대화형 모드 없이 응답 출력
• --verbose: 상세 로깅 활성화
• --dangerously-skip-permissions: 권한 프롬프트 건너뛰기 (인터넷이 없는 Docker 컨테이너에서만)

​

슬래시 명령

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

​

권한 및 보안 관리

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

​

Claude가 사용할 수 있는 도구

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

​

프롬프트 인젝션 방지

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

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

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

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

​

네트워크 액세스 구성

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

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

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

​

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>를 사용하세요:

​

자동 업데이터 권한 옵션

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 플래그 없이):

예시:

# 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/**"

​

터미널 설정 최적화

Claude Code는 터미널이 적절히 구성되었을 때 가장 잘 작동합니다. 최적의 경험을 위해 다음 지침을 따르세요.

지원되는 셸:

• Bash
• Zsh
• Fish

​

테마 및 외관

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

​

줄바꿈

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

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

터미널에서 Option+Enter 설정하기:

Mac Terminal.app의 경우:

1. 설정 → 프로필 → 키보드 열기
2. “Option을 Meta 키로 사용” 체크

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. “벨 음소거” 및 “유휴 시 알림 보내기” 활성화
4. 원하는 알림 지연 설정

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

​

대용량 입력 처리

방대한 코드나 긴 지침으로 작업할 때:

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

이러한 설정을 구성하면 Claude Code와 더 원활하고 효율적인 워크플로우를 만들 수 있습니다.

​

비용 효율적 관리

Claude Code는 각 상호작용에 토큰을 소비합니다. 일반적인 사용량은 개발자당 하루 $5-10이지만, 집중적인 사용 시 시간당$100를 초과할 수 있습니다.

​

비용 추적

• /cost를 사용하여 현재 세션 사용량 확인
• 종료 시 표시되는 비용 요약 검토
• Anthropic Console에서 과거 사용량 확인
• 지출 한도 설정

​

토큰 사용량 줄이기

• 대화 압축: 컨텍스트가 커지면 /compact 사용
• 구체적인 쿼리 작성: 불필요한 스캔을 유발하는 모호한 요청 피하기
• 복잡한 작업 분할: 큰 작업을 집중된 상호작용으로 나누기
• 작업 간 기록 지우기: /clear를 사용하여 컨텍스트 초기화

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

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

​

타사 API와 함께 사용

​

Amazon Bedrock에 연결

CLAUDE_CODE_USE_BEDROCK=1

기본 모델을 재정의하려면 ANTHROPIC_MODEL 환경 변수를 전달할 수 있습니다(기본적으로 Claude 3.7 Sonnet 사용):

ANTHROPIC_MODEL='us.anthropic.claude-3-7-sonnet-20250219-v1:0'

프록시를 통해 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에 프롬프트 캐싱을 문의하세요.

​

Google Vertex AI에 연결

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

기본 모델을 재정의하려면 ANTHROPIC_MODEL 환경 변수를 전달할 수 있습니다(기본적으로 Claude 3.7 Sonnet 사용):

ANTHROPIC_MODEL='us.anthropic.claude-3-7-sonnet-20250219-v1:0'

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

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

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

DISABLE_PROMPT_CACHING=1

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

gcloud auth application-default login

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

​

개발 컨테이너 참조 구현

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

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

​

주요 기능

• 프로덕션급 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. 메시지가 표시되면 “컨테이너에서 다시 열기” 클릭 (또는 명령 팔레트 사용: Cmd+Shift+P → “Remote-Containers: 컨테이너에서 다시 열기”)

​

구성 분석

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

• devcontainer.json: 컨테이너 설정, 확장 및 볼륨 마운트 제어
• Dockerfile: 컨테이너 이미지 및 설치된 도구 정의
• init-firewall.sh: 네트워크 보안 규칙 설정

​

보안 기능

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

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

​

사용자 지정 옵션

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

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

​

다음 단계

​

라이선스 및 데이터 사용

Claude Code는 Anthropic의 상업용 서비스 약관에 따라 베타 연구 프리뷰로 제공됩니다.

​

데이터 사용 방법

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

​

피드백 기록

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

​

개인정보 보호 장치

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

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

​

라이선스

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