Claude Code CLI 설치하기: 5분 만에 끝내는 셋업 가이드 (2026)

Q: Claude Code는 비용이 얼마나 듭니까?

Claude Code는 두 가지 과금 모델을 지원합니다. API 종량제 모델은 Anthropic의 표준 API 요율로 토큰당 요금을 부과합니다. 30~60분짜리 일반적인 세션이라면 코드베이스 규모와 생성량에 따라 0.50~3.00달러 정도입니다. 다른 하나는 Anthropic의 Max 플랜(2026년 중반 기준 Max 5x는 월 100달러, Max 20x는 월 200달러이며 둘 다 개인 등급)으로, 더 높은 사용량 한도와 함께 Claude Code 사용이 포함됩니다. API 사용량은 console.anthropic.com에서 확인할 수 있습니다.

Blake Crosley 14분 소요

Part 1 of New to Claude Code

가이드에서: Claude Code Comprehensive Guide

Claude Code는 어떻게 설정합니까? 네이티브 설치 프로그램인 curl -fsSL https://claude.ai/install.sh | bash 명령으로 CLI를 설치하고, 브라우저에서 인증한 다음, 프로젝트 루트에 CLAUDE.md 파일을 만들어 기술 스택과 코딩 규칙을 적어 두세요. 권한은 .claude/settings.json에서 설정하고, 파일을 편집할 때마다 스타일을 자동으로 고쳐 주는 포매팅 훅을 추가하면 됩니다. 전체 설정에 5분도 걸리지 않습니다. {.answer-block}

ServiceNow는 29,000명이 넘는 임직원에게 Claude Code를 배포했고¹, Allianz는 2026년 초 전 직원이 Claude를 쓸 수 있게 하는 파트너십을 발표했습니다². 이런 도입 곡선에는 하나의 패턴이 담겨 있습니다. 자기 터미널에서 에이전트 방식의 코딩을 한 번 경험한 개발자는 채팅 창에서 복사해 붙여 넣던 방식으로 다시 돌아가지 않는다는 것입니다. 아래 안내를 따라가면 아무것도 없는 상태에서 약 5분 만에 실제로 동작하는 Claude Code 세션까지 도달할 수 있습니다. 게다가 그 뒤로도 계속 쓸 수 있는 진짜 설정이 함께 남습니다.

요약: 네이티브 설치 프로그램(curl -fsSL https://claude.ai/install.sh | bash)으로 Claude Code를 설치하고, 브라우저로 인증하고, 프로젝트 맥락을 담은 CLAUDE.md 파일을 만든 다음, .claude/settings.json에서 권한을 설정하세요. 여기에 Prettier 훅을 더하면 편집할 때마다 파일이 자동으로 포매팅됩니다. 전체 과정은 5분이 채 걸리지 않고, 설정은 세션이 바뀌어도 그대로 유지됩니다.

핵심 요약

1인 개발자: CLAUDE.md와 포매팅 훅만 있어도 필요한 것의 80%는 해결됩니다. 기본 권한으로 시작한 다음, 신뢰가 쌓이는 만큼 도구를 하나씩 미리 승인해 두세요.
팀 리드: .claude/settings.json을 저장소에 커밋해 두면 팀 전체가 동일한 권한 허용 목록과 훅을 공유하게 됩니다.
보안 엔지니어: 권한 모델⁴(Ask/Manual, 허용 목록, auto 모드의 분류기, --dangerously-skip-permissions)은 신뢰 수준과 그대로 대응됩니다. Ask 모드는 모든 쓰기 작업과 모든 명령 실행마다 명시적인 승인을 요구합니다. 다만 2026년 8월 14일부터 Pro/Max/Team 세션은 기본값이 auto 모드로 바뀌었습니다. 승인마다 사람이 개입해야 하는 위협 모델이라면 "defaultMode": "manual"로 고정해 두세요.

사전 준비물

Claude Code를 설치하기 전에 필요한 것은 두 가지입니다.

Anthropic 계정. Claude Code를 쓰려면 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하고, 무료 Claude.ai 플랜에는 사용 권한이 포함되지 않습니다³. 구독 플랜에는 Claude Code 사용이 포함되어 있고(2026년 중반 기준으로 Max 5x는 월 100달러, Max 20x는 월 200달러이며 둘 다 개인 등급입니다)⁶, 아니면 console.anthropic.com에서 발급한 API 키로 토큰 단위 과금을 선택할 수도 있습니다. 인증은 설치가 끝난 뒤 브라우저에서 하기 때문에, 지금 미리 복사해 둘 것은 없습니다.

터미널. Claude Code는 어떤 터미널 에뮬레이터에서도 동작합니다. Terminal.app, iTerm2, Windows Terminal, Alacritty, VS Code의 통합 터미널 모두 괜찮습니다. 가로 폭이 최소 120칸인 터미널을 권합니다. Claude Code는 파일 차이와 도구 출력을 보여 주는데, 가로 공간이 넉넉할수록 훨씬 보기 편하기 때문입니다.

권장 설치 방식에는 Node.js가 필요하지 않습니다. Node.js가 필요한 경우는 아래에 나오는 npm 대안을 선택했을 때뿐이고, v2.1.198 기준으로는 Node.js 22 이상이 필요합니다.

설치

Anthropic이 권장하는 네이티브 설치 프로그램으로 Claude Code를 설치하세요³.

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

Windows에서는 대신 PowerShell에서 irm https://claude.ai/install.ps1 | iex를 실행하세요. 설치 프로그램은 바이너리를 ~/.local/bin/claude에 배치하고, 네이티브로 설치한 경우에는 백그라운드에서 자동으로 업데이트되기 때문에 직접 업그레이드하지 않아도 최신 상태가 유지됩니다.

설치가 제대로 됐는지 확인해 보겠습니다.

claude --version

표준 출력에 버전 번호가 찍히면 정상입니다. “command not found” 오류가 난다면 ~/.local/bin이 PATH에 없는 겁니다. 셸 프로필에 추가하고 다시 읽어들이세요.

# Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

설치 상태와 설정을 더 깊이 진단하고 싶다면 claude doctor를 실행해 보세요. 바이너리와 PATH, 자동 업데이트 상태를 점검하고, 충돌하는 설치(예를 들어 네이티브 버전 옆에 남아 있는 npm 전역 설치본 같은 것)를 짚어 줍니다.

다른 설치 방법. 관리형 cask를 선호한다면 Homebrew도 쓸 수 있습니다. brew install --cask claude-code로 설치하고 brew upgrade --cask claude-code로 업데이트합니다(v2.1.129부터는 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1을 설정하면 패키지 매니저를 통한 백그라운드 업데이트가 동작합니다). npm 패키지도 여전히 동작하지만 레거시 방식이고 v2.1.15부터 지원 중단됐습니다. npm install -g @anthropic-ai/claude-code(Node.js 22 이상이 필요하고, sudo는 절대 쓰지 마세요⁷)를 실행해도 내부적으로는 똑같은 네이티브 바이너리가 설치됩니다. npm으로 시작했는데 권장 구성으로 옮기고 싶다면, 네이티브 빌드를 설치한 다음 npm uninstall -g @anthropic-ai/claude-code로 npm 사본을 제거해서 버전 충돌을 피하세요.

처음 실행하면 Claude Code가 OAuth 인증을 위해 브라우저를 엽니다. 로그인하고 권한을 승인하면 Claude Code가 런타임 인증 상태를 ~/.claude.json에 로컬로 저장합니다. 아니면 실행하기 전에 ANTHROPIC_API_KEY 환경 변수를 설정하는 방법도 있습니다. 어느 쪽이든 자격 증명은 내 컴퓨터에만 남고, API 요청을 인증하는 용도로만 쓰입니다.

첫 세션

아무 프로젝트 디렉터리로 이동한 다음 실행하세요.

cd ~/Projects/my-app
claude

Claude Code는 대화형 REPL 세션을 시작하면서 CLAUDE.md와 설정을 함께 읽어들입니다. 새 프로젝트에서 첫 프롬프트를 보내면 Claude는 필요한 정보를 스스로 탐색합니다.

디렉터리 구조를 훑어보며 프로젝트 레이아웃을 파악합니다
package.json, pyproject.toml, Cargo.toml 같은 설정 파일을 읽어 기술 스택을 확인합니다
시작할 때 이미 읽어 둔, 프로젝트 루트의 CLAUDE.md 지시사항을 적용합니다

모든 게 잘 도는지 간단한 프롬프트로 확인해 보세요.

> Explain the structure of this project

Claude가 파일을 읽고 아키텍처를 정리해서 터미널에 답을 보여 줍니다. 도구 호출(파일 하나를 읽을 때마다, 명령 하나를 실행할 때마다)이 실시간으로 표시되고, 쓰기 작업 전에는 권한을 요청하는 창이 뜹니다.

첫 세션에서 눈여겨볼 것. 두 가지에 주목하세요. 각 동작 직전에 실시간으로 표시되는 도구 호출, 그리고 권한 요청 프롬프트입니다. 도구 호출을 보면 Claude가 코드베이스를 어떻게 탐색하는지가 드러납니다. 내가 확인해 볼 생각조차 못 했던 파일까지 읽는 걸 보게 되는데, 거기서 쓸모 있는 맥락이 나오는 경우도 많습니다. 권한 프롬프트는 디스크에 무언가 닿기 전에 Claude가 무엇을 바꾸려 하는지 정확히 보여 줍니다. 제안된 편집이 잘못돼 보이면 거절하고 설명을 덧붙이세요. Claude는 세션 안에서 받은 피드백에 맞춰 접근 방식을 조정합니다⁸.

CLAUDE.md 설정하기

CLAUDE.md는 Claude Code를 제대로 쓰는 데 가장 중요한 파일입니다. 이 파일이 없으면 Claude는 파일 내용을 보고 스택을 추론해서 그럭저럭 그럴듯한 추측을 합니다. 이 파일이 있으면 첫 프롬프트부터 내가 정한 규칙을 그대로 따릅니다. 이 차이가 중요한 이유는 추론에 기댄 동작이 계속 흔들리기 때문입니다. ESM 프로젝트에서 CommonJS를 쓰거나, 엉뚱한 테스트 러너를 고르거나, 데이터베이스 마이그레이션 절차를 무시할 수도 있습니다. CLAUDE.md는 그런 흔들림을 없애 줍니다.

프로젝트 루트에 파일을 만드세요.

touch CLAUDE.md

Python 프로젝트에서 바로 쓸 만한 출발점 템플릿은 이렇습니다.

# My App

## Project Context
FastAPI backend with HTMX frontend. PostgreSQL database.

## Stack
- Backend: Python 3.11, FastAPI, SQLAlchemy 2.0 (async)
- Frontend: HTMX + Alpine.js, Jinja2 templates
- Database: PostgreSQL 16, Alembic migrations
- Testing: pytest with pytest-asyncio

## Code Standards
- Type hints on all function signatures
- Pydantic v2 models for request/response validation
- Async database operations only (no sync SQLAlchemy)

## Commands
- `source venv/bin/activate` before any Python command
- `uvicorn app.main:app --reload` starts the dev server
- `python -m pytest -v` runs the test suite
- `alembic upgrade head` applies database migrations

JavaScript/TypeScript 프로젝트라면 구조가 비슷합니다.

# My App

## Stack
- Backend: Node.js 20, Express 4, TypeScript
- Frontend: React 18, Vite
- Database: PostgreSQL 16, Prisma ORM
- Testing: Vitest for unit, Playwright for e2e

## Code Standards
- ESM imports only (no require())
- 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.md에서 가장 값어치를 하는 항목은 같은 실수가 반복되는 것을 막아 주는 부분입니다. Claude가 import 대신 자꾸 require()로 가져온다면 Code Standards에 “ESM imports only”를 추가하세요. 테스트 명령을 실행하기 전에 virtualenv를 활성화해야 한다면 그 순서를 문서로 남기세요. Claude는 모든 세션이 시작될 때 CLAUDE.md를 읽기 때문에, 한 줄 한 줄이 계속 살아 있는 지시가 되어 수백 번의 상호작용에 걸쳐 효과가 쌓입니다. CLAUDE.md 파일을 효과적으로 만드는 패턴은 AGENTS.md 패턴에서 다뤘고, 더 넓은 원리인 맥락이 곧 아키텍처라는 관점도 따로 정리해 두었습니다. 개방형 명세인 AGENTS.md⁹도 다른 에이전트 도구를 위해 비슷한 패턴을 따르지만, CLAUDE.md는 스킬이나 룰 디렉터리처럼 더 풍부한 기능을 지원합니다.

계층 구조가 중요합니다. CLAUDE.md는 세 곳에 둘 수 있고, Claude는 구체적인 순서대로 이들을 병합합니다.

~/.claude/CLAUDE.md: 모든 프로젝트에 적용되는 전역 지시사항(개인적인 코딩 취향)
./CLAUDE.md: 프로젝트 단위 지시사항(저장소에 커밋해 팀과 공유)
./src/CLAUDE.md: 디렉터리 단위 지시사항(모노레포의 모듈이나 서브시스템에 한정)

버전 관리에 커밋하는 것은 프로젝트 단위 CLAUDE.md입니다. Claude Code를 쓰는 팀원들은 자동으로 내 규칙을 물려받게 됩니다.

권한의 기본

Claude Code는 에이전트에게 얼마나 많은 자율성을 줄지 결정하는 세 단계 권한 등급⁴으로 동작합니다. 어떤 등급을 고르느냐가 근본적인 절충을 좌우합니다. 자율성이 커질수록 세션은 빨라지지만, 무엇이 바뀌는지는 그만큼 덜 보이게 됩니다.

Ask 모드(v2.1.200부터 CLI에서는 “Manual”로 표시됩니다)는 파일 쓰기, 명령 실행, 파괴적인 동작 하나하나마다 승인을 요구합니다. Claude가 무엇을 하려는지 정확히 확인하고 단계마다 승인하거나 거절할 수 있습니다. 다만 2026년 8월 14일에 기본값이 바뀐 점에 유의하세요. Pro, Max, Team 세션은 이제 auto 모드로 시작하고, 매번 물어보는 대신 안전 분류기가 각 동작을 검토합니다. Shift+Tab을 눌러 Manual로 되돌릴 수 있고, 설정에서 "defaultMode": "manual"로 고정할 수도 있습니다. 그래도 저는 Manual로 시작하길 권합니다. 승인 프롬프트 자체가 Claude Code의 작동 방식을 알려 주기 때문입니다. 몇 세션만 지나면 어떤 작업을 미리 승인해도 안전한지, 어떤 작업은 매번 꼼꼼히 봐야 하는지 감이 생깁니다.

허용 목록 권한을 쓰면 특정 도구와 패턴을 미리 승인해 두어 Claude가 매번 묻지 않도록 할 수 있습니다. 설정은 프로젝트의 .claude/settings.json에 넣습니다.

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(python -m pytest:*)",
      "Bash(alembic upgrade head)"
    ]
  }
}

위 설정은 Claude가 파일을 읽고, 코드베이스를 검색하고, 테스트와 마이그레이션 명령을 실행하는 일을 묻지 않고 허용합니다. 그래도 파일을 쓰거나 다른 bash 명령을 실행하기 전에는 여전히 물어봅니다. 패턴에 주목하세요. 읽기 작업과 안전하다고 알려진 명령만 허용 목록에 넣었습니다. 쓰기 작업은 Ask 모드에 그대로 둡니다. Claude가 쓴 내용이 디스크에 닿기 전에 직접 검토하고 싶기 때문입니다.

위험한 권한 건너뛰기(--dangerously-skip-permissions)는 확인 프롬프트를 비활성화합니다(v2.1.126부터는 안전장치로, 치명적인 삭제 명령에 대해서는 여전히 확인을 요구합니다). 이 플래그는 승인할 사람이 없는 CI/CD 파이프라인과 자동화 워크플로만을 위해 존재합니다. 소중한 코드베이스에서 대화형 세션을 할 때는 절대 쓰지 마세요.

권한 시스템 덕분에 실제 프로젝트에서도 Claude Code를 안심하고 쓸 수 있습니다. 진행 순서는 의도적으로 설계돼 있습니다. Ask 모드로 시작해 이해를 쌓고, 반복되기 시작한 작업을 허용 목록에 넣고, 쓰기 작업에는 관문을 남겨 두어 변경이 확정되기 전에 항상 검토하는 것입니다.

첫 훅 만들기

훅은 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"
          }
        ]
      }
    ]
  }
}

PostToolUse 훅⁵은 Edit 또는 Write 도구 호출이 끝날 때마다 실행됩니다. Claude Code는 $FILE_PATH에 수정된 파일의 경로를 넣어 줍니다. Prettier가 그 자리에서 파일을 포매팅하고, || true가 붙어 있어서 Prettier가 설치되어 있지 않거나 지원하지 않는 파일 형식이라 종료 코드가 0이 아니어도 Claude가 멈추지 않습니다⁵.

처음에 함께 넣어 두면 좋은 훅을 몇 가지 더 소개하겠습니다.

Bash에 대한 PreToolUse: rm -rf /나 git push --force 같은 위험한 명령을 차단합니다
SessionStart: 현재 날짜, 활성 git 브랜치, 환경 변수를 맥락에 주입합니다(SessionStart 훅의 표준 출력은 Claude의 맥락으로 들어갑니다)
Stop: Claude가 작업을 끝냈을 때 테스트 스위트를 자동으로 실행합니다

훅은 Claude Code를 대화형 도구에서 통제 가능한 개발 환경으로 바꿔 놓습니다. 잘 고른 훅이 한두 개만 있어도 실수의 한 부류가 통째로 사라집니다.

문제가 생겼을 때

Claude Code를 쓰기 시작한 첫 주에는 네 가지 상황이 반복해서 찾아옵니다. 미리 알아 두면 디버깅 시간을 아낄 수 있습니다.

Claude가 CLAUDE.md 지시를 무시합니다. 가장 흔한 원인은, 내가 파일을 고치기 전에 Claude가 이미 그 파일을 읽고 이해한 내용을 캐시해 둔 경우입니다. /clear를 실행해 맥락을 초기화하거나 새 세션을 시작하세요. Claude는 CLAUDE.md를 세션 시작 시점에 읽지, 프롬프트마다 다시 읽지 않습니다. 새 세션에서도 여전히 지시를 무시한다면, 더 높은 우선순위의 CLAUDE.md(사용자 수준의 ~/.claude/CLAUDE.md)가 프로젝트 파일과 충돌하고 있지는 않은지 확인해 보세요.

승인하지 않은 변경을 Claude가 했습니다. 허용 목록 패턴을 너무 넓게 잡았다면(Bash(python -m pytest:*) 같은 좁은 접두사 대신 전부를 아우르는 Bash 규칙을 넣었다면), Claude가 묻지 않고 명령을 실행할 수 있습니다. 허용 목록 패턴을 좁히세요. 가장 안전한 방법은 읽기 작업과 이름을 명시한 특정 명령만 허용 목록에 넣는 겁니다. Claude가 이미 원치 않는 변경을 했다면 git diff가 무엇이 바뀌었는지 정확히 보여 주고, git checkout -- <file>로 되돌릴 수 있습니다.

긴 세션 도중에 컨텍스트 윈도가 가득 찹니다. 컨텍스트 윈도가 차오르면 Claude Code는 앞쪽 메시지를 압축합니다(2026년 중반 기준으로 기본 모델은 100만 토큰 윈도를 갖기 때문에 예전보다 훨씬 늦게 도달합니다). 다만 압축 과정에서 대화 초반의 중요한 세부 사항이 빠질 수 있습니다. 30분을 넘기는 세션이라면 작업 중인 변경 사항을 주기적으로 커밋하고 /clear로 새 세션을 시작하세요. 새 맥락은 CLAUDE.md를 다시 읽고 깨끗한 상태에서 출발합니다. 저는 하위 작업을 하나 끝낼 때마다 커밋하는데, 이렇게 하면 되돌릴 지점과 자연스러운 세션 경계를 동시에 얻게 됩니다.

Claude가 엉뚱한 파일을 편집하거나 불필요한 변경을 합니다. 건드려 달라고 하지 않은 코드까지 Claude가 “개선”하기 시작한다면, 대개는 프롬프트가 모호한 게 원인입니다. “auth 모듈 좀 정리해 줘” 대신 “app/auth/handlers.py에서 verify_user를 verify_user_credentials로 이름을 바꾸고 모든 호출부를 업데이트해 줘”라고 말하세요. 구체적일수록 원치 않는 부작용이 줄어듭니다. 원치 않는 편집이 이미 들어갔다면, git diff가 무엇이 바뀌었는지 정확히 보여 주고 git checkout -- <file>로 다른 작업을 잃지 않고 파일 단위로 되돌릴 수 있습니다.

다음 단계

여기까지가 핵심입니다. 설치, 첫 세션, 프로젝트 설정, 권한, 그리고 첫 훅까지 다뤘습니다. Claude Code를 다른 에이전트 도구와 비교한 내용은 Claude Code와 Codex 비교를 보세요. 다섯 가지 핵심 시스템(CLAUDE.md 계층, 전체 권한 모델, 훅 아키텍처, 커스텀 슬래시 명령, 멀티 에이전트 워크플로)을 모두 다루는 완전한 레퍼런스는 Claude Code 완전 가이드에 있습니다.

이 가이드는 컨텍스트 윈도 관리, 서브에이전트 위임, 스킬 자동 활성화, 그리고 Claude Code를 몇 달 동안 매일 쓰다 보면 드러나는 패턴을 다룹니다. 이 퀵스타트가 도움이 됐다면 완전 가이드가 자연스러운 다음 단계입니다. 모든 명령과 플래그, 단축키를 빠르게 찾아보고 싶다면 Claude Code 치트 시트를 참고하세요.

프로젝트가 iOS나 macOS 앱이라면 iOS 에이전트 개발 가이드가 Apple에 특화된 Claude Code 패턴을 다룹니다. 빌드와 시뮬레이터를 위한 XcodeBuildMCP 연동, 에이전트의 편집으로부터 .pbxproj를 지켜 주는 Apple 개발용 훅, 그리고 App Intents와 MCP 서버, Foundation Models, 프레임워크 수준에서의 에이전트 플랫폼 연결을 다루는 Apple 생태계 시리즈가 여기에 포함됩니다.

참고 자료

자주 묻는 질문

Claude Code를 설치하려면 무엇이 필요합니까?

Anthropic 계정(Pro, Max, Team, Enterprise 또는 Console이며, 무료 플랜에는 Claude Code가 포함되지 않습니다)과 아무 터미널 에뮬레이터가 있으면 됩니다. Claude Code는 macOS 13 이상, Linux, Windows(네이티브 또는 WSL)에서 동작합니다. 권장 설치 방식은 네이티브 설치 프로그램(curl -fsSL https://claude.ai/install.sh | bash)이고, Node.js도 Docker도 다른 런타임도 필요하지 않습니다. Node.js 22 이상은 npm 대안(npm install -g @anthropic-ai/claude-code)을 선택했을 때만 필요합니다.

CLAUDE.md는 무엇이고 왜 필요합니까?

CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일로, 기술 스택과 코딩 규칙, 자주 쓰는 명령을 Claude Code에 알려 줍니다. 이 파일이 없으면 Claude는 파일 내용을 보고 구성을 추론해 그럴듯한 추측을 하지만, 그 추측은 세션마다 흔들립니다. CLAUDE.md가 있으면 Claude는 매 세션 첫 프롬프트부터 내가 정한 규칙을 그대로 따릅니다. 세 단계 계층을 지원하며, 사용자 수준(~/.claude/CLAUDE.md), 프로젝트 수준(./CLAUDE.md), 디렉터리 수준(./src/CLAUDE.md)이 구체적인 순서대로 병합됩니다.

Claude Code는 비용이 얼마나 듭니까?

Claude Code는 두 가지 과금 모델을 지원합니다. API 종량제 모델은 Anthropic의 표준 API 요율로 토큰당 요금을 부과합니다⁶. 30~60분짜리 일반적인 세션이라면 코드베이스 규모와 생성량에 따라 0.50~3.00달러 정도입니다. 다른 하나는 Anthropic의 Max 플랜⁶(2026년 중반 기준 Max 5x는 월 100달러, Max 20x는 월 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의 Ask 모드는 파일 쓰기와 명령 실행마다 명시적인 승인을 요구합니다. 내가 확인하지 않으면 디스크에서 아무것도 바뀌지 않습니다. 이 권한 시스템에, 강제 푸시나 파괴적인 셸 명령 같은 위험한 작업을 차단하는 훅까지 더하면 Claude Code는 운영 업무에도 충분히 실용적입니다. 저도 실제 사용자에게 서비스하는 프로젝트에서 매일 Claude Code를 씁니다. 핵심은 Ask 모드로 시작하는 것, 승인하기 전에 각 도구 호출이 무엇을 하는지 이해하는 것, 그리고 신뢰가 가는 작업만 조금씩 허용 목록에 넣는 것입니다. 마지막 안전망은 버전 관리입니다. 중요한 Claude Code 세션을 시작하기 전에 커밋해 두면 언제든 되돌릴 수 있습니다.

새로 시작한 사람들이 가장 많이 하는 실수는 무엇입니까?

CLAUDE.md에 넣어야 할 내용을 프롬프트에 잔뜩 담아 Claude에게 던지는 것입니다. 처음 쓰는 분들은 코딩 표준 전체를 매 프롬프트에 붙여 넣는 경향이 있는데, 이러면 컨텍스트 윈도를 낭비하고 세션마다 결과도 들쭉날쭉해집니다. 반복되는 지시는 한 번만 CLAUDE.md로 옮기고, 프롬프트는 그 세션에만 해당하는 요청에 쓰세요. 두 번째로 흔한 실수는 특정 명령 대신 Bash(*)를 허용 목록에 넣는 것입니다. 와일드카드로 Bash를 허용하면 Claude가 묻지 않고 어떤 셸 명령이든 실행할 수 있게 되고, 권한 시스템의 의미가 사라집니다.

Anthropic, “ServiceNow chooses Claude to power customer apps and increase internal productivity.” anthropic.com/news/servicenow-anthropic-claude — “rolling out Claude and Claude Code across its global workforce of more than 29,000 employees.” ↩
Allianz, “Allianz and Anthropic forge global partnership,” 미디어 릴리스, 2026년 1월 9일. allianz.com/en/mediacenter/news/media-releases/260109 ↩
Anthropic, “Advanced setup” (설치 방법, 시스템 요구 사항, 인증). code.claude.com/docs/en/installation. 네이티브 설치 프로그램 권장, 바이너리 위치는 ~/.local/bin/claude, npm 패키지는 v2.1.198 기준 Node.js 22 이상이 필요하며 동일한 네이티브 바이너리를 설치합니다. 2026-08-08 확인. 출처: github.com/anthropics/claude-code ↩↩
Anthropic, “Claude Code Permissions.” code.claude.com/docs/en/permissions ↩↩
Anthropic, “Claude Code Hooks.” code.claude.com/docs/en/hooks ↩↩↩
Anthropic, “Pricing” (Max 5x와 Max 20x를 포함한 플랜). anthropic.com/pricing; API 토큰 요율은 platform.claude.com/docs/en/about-claude/pricing ↩↩↩
npm Documentation, “Resolving EACCES permissions errors when installing packages globally.” docs.npmjs.com/resolving-eacces-permissions-errors ↩
Anthropic, “Effective usage of Claude Code.” code.claude.com/docs/en/best-practices ↩
“AGENTS.md,” 에이전트 지시사항에 관한 개방형 명세. agents.md ↩