Claude Code CLI 설정 방법: 5분 빠른 시작 가이드
ServiceNow의 29,000명 이상의 개발자가 현재 매일 Claude Code를 사용하고 있으며, Allianz는 2026년 초에 회사 전체에 도입했습니다. 이 도구의 도입 곡선은 하나의 패턴을 보여줍니다. 개발자들이 자신의 터미널에서 에이전트 코딩을 한번 경험하면, 더 이상 채팅 창에서 복사-붙여넣기하는 방식으로 돌아가지 않습니다. 이 빠른 시작 가이드는 약 5분 만에 Claude Code 세션을 처음부터 실행하는 방법을 안내하며, 이후에도 계속 사용할 수 있는 실제 설정을 포함합니다.
요약: npm install -g @anthropic-ai/claude-code로 Claude Code를 설치하고, 브라우저를 통해 인증하고, 프로젝트 컨텍스트가 포함된 CLAUDE.md 파일을 생성하고, .claude/settings.json에서 권한을 설정합니다. 모든 편집 후 파일을 자동 포맷하는 Prettier 훅을 추가합니다. 전체 설정은 5분 이내에 완료되며, 설정은 세션 간에 유지됩니다.
핵심 요약
- 개인 개발자: CLAUDE.md와 포맷팅 훅만으로 필요한 것의 80%를 충족합니다. 기본 권한으로 시작하고, 신뢰를 쌓아가며 도구를 사전 승인하세요.
- 팀 리더:
.claude/settings.json을 저장소에 커밋하여 전체 팀이 동일한 권한 허용 목록과 훅을 공유할 수 있도록 하세요. - 보안 엔지니어: 3단계 권한 모델(기본, 사전 승인, 건너뛰기)은 신뢰 수준에 직접 매핑됩니다. 기본 모드에서는 모든 쓰기 작업과 모든 명령에 대해 명시적 승인이 필요합니다.
사전 요구 사항
Claude Code를 설치하기 전에 세 가지가 필요합니다:
Node.js 18 이상. Claude Code는 npm 패키지로 제공됩니다. 버전을 확인하세요:
node --version
# v18.0.0 or higher
Node.js를 설치하거나 업그레이드해야 하는 경우, nvm을 사용하거나 nodejs.org에서 직접 다운로드하세요.
API 접근 권한이 있는 Anthropic 계정. console.anthropic.com의 Settings > API Keys에서 API 키를 생성하세요. Claude Code는 API 잔액 또는 Max 구독 플랜에서 요금이 청구됩니다. 인증 단계를 위해 키를 준비해 두세요.
터미널. Claude Code는 모든 터미널 에뮬레이터에서 실행됩니다: Terminal.app, iTerm2, Windows Terminal, Alacritty, 또는 VS Code의 통합 터미널. Claude Code는 파일 diff와 도구 출력을 표시하므로 가로 공간이 넓을수록 유리하기 때문에, 최소 120열 너비의 터미널을 권장합니다.
설치
npm을 통해 Claude Code를 전역으로 설치합니다:
npm install -g @anthropic-ai/claude-code
설치가 성공적으로 완료되었는지 확인합니다:
claude --version
버전 번호가 stdout에 출력되어야 합니다. “command not found” 오류가 발생하면, npm 전역 bin 디렉토리가 PATH에 포함되어 있는지 확인하세요. npm config get prefix를 실행하고 해당 출력의 /bin 하위 디렉토리를 PATH에 추가하세요.
처음 실행 시, Claude Code는 OAuth 인증을 위해 브라우저에서 Anthropic 콘솔을 엽니다. 로그인하고 권한을 부여하면 토큰이 ~/.claude/에 로컬로 저장됩니다. 또는 실행 전에 ANTHROPIC_API_KEY 환경 변수를 설정할 수도 있습니다. 어느 방법이든 자격 증명은 사용자의 컴퓨터에 남아 있으며 API 요청 인증에만 사용됩니다.
첫 번째 세션
프로젝트 디렉토리로 이동하여 실행합니다:
cd ~/Projects/my-app
claude
Claude Code가 대화형 REPL 세션을 시작합니다. 새 프로젝트에서 처음 실행하면 자동으로 여러 작업을 수행합니다:
- 디렉토리 구조를 스캔하여 프로젝트 레이아웃을 파악합니다
- 설정 파일을 읽어
package.json,pyproject.toml,Cargo.toml등에서 기술 스택을 식별합니다 - 프로젝트 루트에서 CLAUDE.md 파일을 찾아 프로젝트별 지침을 확인합니다
모든 것이 정상적으로 작동하는지 확인하기 위해 간단한 프롬프트를 입력해 보세요:
> Explain the structure of this project
Claude가 파일을 읽고 아키텍처를 분석한 후 터미널에서 응답합니다. 도구 호출(각 파일 읽기, 각 명령 실행)이 실시간으로 표시되며, 모든 쓰기 작업 전에 권한 요청이 나타납니다.
CLAUDE.md 설정하기
CLAUDE.md는 효과적인 Claude Code 사용을 위한 가장 중요한 파일입니다. 프로젝트 루트에 위치하며, Claude가 모든 세션 시작 시 읽는 지침을 포함합니다. AI 협업자를 위한 README라고 생각하면 됩니다.
파일을 생성합니다:
touch CLAUDE.md
다음은 실용적인 시작 템플릿입니다:
# My App
## Project Context
Express.js API with React frontend. PostgreSQL database.
## Stack
- Backend: Node.js 20, Express 4, TypeScript
- Frontend: React 18, Vite
- Database: PostgreSQL 16, Prisma ORM
- Testing: Vitest for unit tests, Playwright for e2e
## Code Standards
- Use async/await, never raw Promises
- All API endpoints need input validation with Zod
- Tests required for new endpoints before merging
## Commands
- `npm run dev` starts the dev server on port 3000
- `npm test` runs the test suite
- `npx prisma migrate dev` runs database migrations
경험상, 가장 가치 있는 섹션은 반복적인 실수를 방지하는 부분입니다. Claude가 프로젝트에서 ESM을 사용하는데 계속 CommonJS를 사용한다면, 이를 CLAUDE.md에 추가하세요. 특정 테스트 명령어나 데이터베이스 설정 단계가 있다면 문서화하세요. Claude는 매 세션마다 CLAUDE.md를 읽으므로, 여기에 작성한 모든 내용이 영구적인 지침이 됩니다.
홈 디렉토리(~/.claude/CLAUDE.md)에 CLAUDE.md를 배치하여 모든 프로젝트에 적용되는 전역 지침을 설정할 수도 있고, 모노레포의 특정 부분에만 적용되는 컨텍스트를 위해 하위 디렉토리에 배치할 수도 있습니다.
권한 기본 사항
Claude Code는 에이전트에게 부여하는 자율성 수준을 결정하는 세 가지 권한 계층으로 운영됩니다:
기본 모드는 모든 파일 쓰기, 명령 실행, 또는 파괴적 작업 전에 권한을 요청합니다. Claude가 수행하려는 작업을 정확히 확인하고 각 단계를 승인하거나 거부할 수 있습니다. 이 모드로 시작하는 것을 권장합니다.
사전 승인 권한을 사용하면 특정 도구와 패턴을 허용 목록에 추가하여 Claude가 매번 묻지 않도록 설정할 수 있습니다. 프로젝트의 .claude/settings.json에서 설정합니다:
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(npm test)",
"Bash(npx prisma migrate dev)"
]
}
}
이 예시는 Claude가 파일 읽기, 코드베이스 검색, 테스트 및 마이그레이션 명령을 묻지 않고 실행하도록 허용합니다. 파일 쓰기나 다른 bash 명령 실행 시에는 여전히 확인을 요청합니다.
권한 건너뛰기 위험 모드(--dangerously-skip-permissions)는 모든 확인 프롬프트를 비활성화합니다. 이 플래그는 승인할 사람이 없는 CI/CD 파이프라인과 자동화된 워크플로우에서만 사용해야 합니다. 중요한 코드베이스에서의 대화형 세션에서는 절대 사용하지 마세요.
권한 시스템이 Claude Code를 실제 프로젝트에서 안전하게 사용할 수 있게 만드는 핵심입니다. 기본 모드로 시작하고, 어떤 승인이 반복적인지 관찰한 후, 해당 특정 작업만 선택적으로 사전 승인하세요.
첫 번째 훅
훅은 Claude Code의 생명주기에서 특정 시점에 실행되는 셸 명령입니다. LLM의 확률적 행동 위에 결정론적 보장을 제공합니다. 실용적인 첫 번째 훅을 소개합니다: Claude가 파일을 편집한 후 자동으로 포맷팅하는 것입니다.
프로젝트의 .claude/settings.json을 생성하거나 편집합니다:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
}
]
}
]
}
}
이 훅은 모든 Edit 또는 Write 도구 호출 후에 실행됩니다. Claude Code는 $FILE_PATH를 수정된 파일로 설정합니다. Prettier가 해당 파일을 인라인으로 포맷하며, || true는 Prettier가 설치되지 않았거나 파일 유형이 지원되지 않는 경우에도 훅이 Claude를 차단하지 않도록 보장합니다.
그 외 권장하는 실용적인 초기 훅:
- Bash에 대한 PreToolUse:
rm -rf /나git push --force같은 위험한 명령을 차단합니다 - SessionStart: 현재 날짜, 활성 git 브랜치, 또는 환경 변수를 컨텍스트에 주입합니다 (SessionStart 훅의 stdout은 Claude의 컨텍스트에 전달됩니다)
- Stop: Claude가 작업을 완료하면 자동으로 테스트 스위트를 실행합니다
훅은 Claude Code를 대화형 도구에서 관리된 개발 환경으로 변환합니다. 잘 선택된 하나 또는 두 개의 훅만으로도 전체 카테고리의 실수를 방지할 수 있습니다.
다음 단계
이 빠른 시작 가이드는 설치, 첫 세션, 프로젝트 설정, 권한, 시작 훅 등 필수 사항을 다루었습니다. 5가지 핵심 시스템(CLAUDE.md 계층 구조, 전체 권한 모델, 훅 아키텍처, 커스텀 슬래시 명령, 멀티 에이전트 워크플로우)을 다루는 완전한 레퍼런스는 Claude Code 완전 가이드를 참고하세요.
이 가이드는 컨텍스트 윈도우 관리, 서브에이전트 위임, 스킬 자동 활성화, 그리고 수개월간 Claude Code를 매일 사용하면서 나타나는 패턴을 다룹니다. 이 빠른 시작 가이드가 유용했다면, 전체 가이드가 자연스러운 다음 단계입니다.
FAQ
Claude Code의 비용은 얼마인가요?
Claude Code는 두 가지 과금 모델을 지원합니다. API 종량제 모델은 표준 Anthropic API 요금으로 토큰당 과금됩니다. 일반적인 30~60분 세션은 코드베이스 크기와 생성량에 따라 $0.50~$3.00의 비용이 발생합니다. 또는 Anthropic의 Max 플랜($100/월 개인, $200/월 팀)에는 더 높은 요청 제한과 함께 Claude Code 사용이 포함됩니다. API 사용량은 console.anthropic.com에서 모니터링할 수 있습니다.
VS Code에서 Claude Code를 사용할 수 있나요?
네. Claude Code는 VS Code의 통합 터미널을 포함한 모든 터미널에서 작동합니다. VS Code에서 터미널 패널을 열고, 프로젝트 디렉토리로 이동한 후, 독립 터미널에서와 동일하게 claude를 실행하면 됩니다. Claude Code는 디스크의 파일을 읽고 편집하므로, 변경 사항이 VS Code 편집기 탭에 즉시 반영됩니다. 별도의 VS Code 확장 프로그램은 필요하지 않습니다. 일부 개발자들은 편집기 옆에 Claude Code 전용 터미널 분할 창을 유지하는데, 변경 사항을 실시간으로 검토하는 데 효과적입니다.
프로덕션 코드베이스에서 Claude Code를 사용해도 안전한가요?
Claude Code의 기본 권한 모드는 모든 파일 쓰기와 모든 명령 실행 전에 명시적 승인을 요청합니다. 사용자의 확인 없이는 디스크에 아무것도 변경되지 않습니다. 권한 시스템과 함께 강제 푸시나 파괴적 셸 명령 같은 위험한 작업을 차단할 수 있는 훅을 결합하면, 프로덕션 환경에서도 실용적으로 사용할 수 있습니다. 저는 실제 사용자에게 서비스하는 프로젝트에서 매일 Claude Code를 사용하고 있습니다. 핵심은 기본 모드로 시작하고, 승인하기 전에 각 도구 호출이 무엇을 하는지 이해하고, 신뢰하는 작업만 점진적으로 사전 승인하는 것입니다. 버전 관리가 최종 안전망입니다: 중요한 Claude Code 세션을 시작하기 전에 커밋하여 언제든지 되돌릴 수 있도록 하세요.