Claude Code를 설치하고 기본 설정을 완료한 뒤, 첫 번째 대화형 세션을 실행하는 과정을 단계별로 안내합니다.
Claude Code를 설치하기 전에 다음 요구사항이 충족되어야 합니다.
필수 요건:
계정 요건 (택 1):
Node.js가 설치되어 있는지 확인하려면 터미널에서 다음 명령어를 실행합니다.
node --version
# v20.x.x 이상이면 정상Claude Code는 npm을 통해 전역으로 설치합니다.
npm install -g @anthropic-ai/claude-code설치가 완료되면 버전을 확인합니다.
claude --versionpnpm이나 yarn을 사용하는 경우에도 전역 설치는 npm으로 하는 것을 권장합니다. Claude Code는 시스템 전역에서 사용하는 도구이므로 프로젝트 패키지 매니저와 무관합니다.
Claude Code는 터미널 단독으로 충분히 사용할 수 있지만, VS Code나 JetBrains IDE에서 통합된 경험을 원한다면 네이티브 확장을 설치할 수 있습니다.
VS Code / Cursor / Windsurf: Extensions 패널에서 "Claude Code"를 검색하여 Anthropic 공식 확장을 설치합니다. 설치 후 에디터 하단 패널에서 Claude Code 터미널에 바로 접근할 수 있습니다.
JetBrains: Settings > Plugins > Marketplace에서 "Claude Code"를 검색하여 설치합니다.
Claude Code를 처음 실행하면 인증을 요청합니다. 두 가지 방식 중 하나를 선택합니다.
Claude Pro 또는 Max 구독이 있다면 가장 간편한 방법입니다.
claude첫 실행 시 브라우저가 열리며 claude.ai 로그인을 요청합니다. 로그인하면 인증이 자동으로 완료됩니다.
Anthropic Console 계정이 있다면 API 키로 인증할 수 있습니다.
export ANTHROPIC_API_KEY="sk-ant-..."
claudeAPI 키를 영구적으로 설정하려면 셸 설정 파일에 추가합니다.
export ANTHROPIC_API_KEY="sk-ant-your-key-here"API 키는 절대 Git에 커밋하거나 공개 저장소에 노출하지 않도록 주의합니다. 환경 변수나 시크릿 매니저를 통해 관리하는 것이 좋습니다.
Claude Code는 여러 계층의 설정 파일을 지원합니다. 우선순위가 높은 순서대로 나열하면 다음과 같습니다.
| 범위 | 경로 | 용도 |
|---|---|---|
| 로컬 | .claude/settings.local.json | 개인 프로젝트 설정 (Git 무시) |
| 프로젝트 | .claude/settings.json | 팀 공유 설정 (Git 포함) |
| 사용자 | ~/.claude/settings.json | 전역 개인 설정 |
| 관리형 | 조직 설정 파일 | 기업 정책 |
/config 명령어를 사용하면 대화형으로 설정을 관리할 수 있습니다.
/config주요 설정 항목은 다음과 같습니다.
모델 선택: 기본 모델을 변경할 수 있습니다. 대부분의 경우 기본값이 최적이지만, 특정 용도에 맞게 조정할 수 있습니다.
테마: 터미널 색상 테마를 설정합니다.
권한: 자동 허용할 도구와 명령어를 관리합니다.
Claude Code는 안전을 위해 파일 수정이나 명령어 실행 전에 승인을 요청합니다. 자주 사용하는 명령어는 허용 목록에 추가하여 편의성을 높일 수 있습니다.
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test)",
"Bash(pnpm build)",
"Bash(git status)",
"Bash(git diff)"
]
}
}권한 설정에서 명령어 패턴은 접두사 매칭 방식으로 동작합니다. 예를 들어 Bash(git) 을 허용하면 git status, git diff, git log 등 git으로 시작하는 모든 명령어가 자동 허용됩니다. 범위를 좁게 설정하는 것이 보안상 권장됩니다.
설치와 인증이 완료되었으니 첫 번째 세션을 실행해 보겠습니다. 먼저 작업할 프로젝트 디렉토리로 이동합니다.
cd ~/my-project
claudeClaude Code가 시작되면 프로젝트 구조를 자동으로 스캔합니다. 터미널에 프롬프트가 표시되면 자연어로 지시를 입력합니다.
다음 예제를 순서대로 시도해 보면 Claude Code의 핵심 기능을 빠르게 체험할 수 있습니다.
프로젝트 구조 파악:
이 프로젝트의 전체 구조와 사용된 기술 스택을 설명해 줘
특정 파일 분석:
src/app/layout.tsx 파일의 역할과 구조를 설명해 줘
코드 검색:
이 프로젝트에서 인증 관련 코드가 어디에 있는지 찾아 줘
간단한 코드 수정:
README.md에 프로젝트 설치 방법 섹션을 추가해 줘
Claude Code 세션 내에서 사용할 수 있는 주요 슬래시 명령어입니다.
| 명령어 | 설명 |
|---|---|
/help | 사용 가능한 명령어 목록 |
/config | 설정 관리 |
/clear | 컨텍스트 초기화 |
/compact | 대화 요약으로 컨텍스트 절약 |
/cost | 현재 세션의 토큰 사용량 확인 |
/status | 현재 세션 상태 확인 |
/quit | 세션 종료 (Ctrl+C 두 번도 가능) |
대화형 세션 외에도, -p 플래그를 사용하면 단일 프롬프트를 실행하고 즉시 결과를 반환하는 비대화형 모드를 사용할 수 있습니다. 스크립트나 자동화에 유용합니다.
# 단일 프롬프트 실행
claude -p "이 프로젝트의 package.json에서 사용 중인 프레임워크를 알려줘"
# 파이프 입력과 결합
git diff --staged | claude -p "이 변경사항을 요약하고 적절한 커밋 메시지를 제안해 줘"새로운 프로젝트에서 Claude Code를 최적으로 활용하려면 프로젝트 루트에 .claude 디렉토리와 기본 설정 파일을 준비하는 것이 좋습니다.
mkdir -p .claude{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test)",
"Bash(npm run build)"
]
}
}.gitignore에 로컬 설정 파일을 추가합니다.
.claude/settings.local.json.claude/settings.json은 팀원과 공유할 수 있는 프로젝트 설정이므로 Git에 포함합니다. 개인적인 설정은 .claude/settings.local.json에 작성하여 Git에서 제외합니다.
인증 실패: 브라우저 인증 후에도 연결되지 않는 경우, claude logout 후 다시 claude를 실행하여 재인증합니다.
Node.js 버전 문제: node --version으로 18 이상인지 확인합니다. nvm 사용자는 nvm use 20으로 전환합니다.
권한 오류: 전역 설치 시 권한 문제가 발생하면 sudo를 사용하기보다 nvm이나 volta 같은 Node.js 버전 매니저를 통해 설치하는 것을 권장합니다.
프록시 환경: 기업 프록시 환경에서는 HTTPS_PROXY 환경 변수를 설정합니다.
export HTTPS_PROXY="http://proxy.company.com:8080"이 장에서는 Claude Code의 설치, 인증, 기본 설정, 첫 세션 실행까지의 과정을 다루었습니다. 핵심 내용을 정리하면 다음과 같습니다.
/config로 대화형 설정이 가능합니다claude를 실행하면 자동으로 프로젝트를 인식합니다-p 플래그로 비대화형 모드를 사용할 수 있습니다다음 장에서는 Claude Code의 강력한 기능 중 하나인 CLAUDE.md 파일을 활용하여 프로젝트별 컨텍스트를 체계적으로 설계하는 방법을 다룹니다.
이 글이 도움이 되셨나요?
CLAUDE.md 파일을 활용하여 프로젝트의 기술 스택, 코딩 컨벤션, 아키텍처 정보를 Claude Code에 효과적으로 전달하는 방법을 알아봅니다.
Claude Code가 무엇이고 왜 필요한지, 기존 AI 코딩 도구와 어떻게 다른지 핵심 아키텍처와 함께 살펴봅니다.
Claude Code로 코드를 작성하고, 리뷰하고, 리팩터링하는 핵심 워크플로우를 실전 예제와 함께 익힙니다.