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 제어하기

​

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 prefix 디렉토리에 쓰기 권한이 충분하지 않음을 감지하면 (자동 업데이트에 필요), 이 문서 페이지를 가리키는 경고가 표시됩니다.

​

권장: 새로운 사용자 쓰기 가능 npm prefix 생성

# 먼저 기존 전역 패키지 목록을 나중에 마이그레이션하기 위해 저장
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

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

이 옵션을 권장하는 이유:

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

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

​

프로젝트 구성

프로젝트 구성은 -g 플래그 없이 claude config set <key> <value>로 관리합니다:

예시:

# 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

선택사항: 기본 모델 재정의 (기본적으로 Claude 3.7 Sonnet 사용):

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

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

DISABLE_PROMPT_CACHING=1

표준 AWS SDK 자격 증명이 필요합니다(예: ~/.aws/credentials 또는 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY와 같은 관련 환경 변수). 비용 절감과 더 높은 속도 제한을 위한 프롬프트 캐싱은 Amazon Bedrock에 문의하세요.

​

Google Vertex AI에 연결

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

google-auth-library를 통해 구성된 표준 GCP 자격 증명이 필요합니다. 최상의 경험을 위해 더 높은 속도 제한은 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: Reopen in Container”)

​

구성 분석

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의 상업용 서비스 약관에 따릅니다.