Claude Code 완벽 가이드

설치 & 인증

Claude Code는 npm 패키지로 배포됩니다. Node.js 18 이상이 설치된 환경이라면 단일 명령어로 전역 설치가 가능합니다. 설치 후 claude auth login 으로 인증을 완료하면 바로 사용할 수 있습니다.

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

# Claude 구독 인증
claude auth login

# API 키 인증 (콘솔에서 직접 입력)
claude auth login --console

claude auth status

인증 명령어 요약

CLI 명령어

Claude Code의 CLI는 대화형 세션부터 파이프 처리, 원격 제어까지 폭넓은 사용 패턴을 지원합니다. 아래 표에서 자주 쓰는 명령어와 그 역할을 확인할 수 있습니다. 비대화형 환경(스크립트, CI 등)에서는 -p 플래그와 조합하는 패턴이 특히 유용합니다.

$ claude -p "이 파일의 함수 목록을 알려줘" < main.py
1. parse_args()
2. load_config()
3. run()

$ cat error.log | claude -p "에러 원인을 요약해줘"
세 번째 줄에서 NullPointerException이 발생했습니다...

CLI 플래그

플래그는 명령어 실행 시 동작을 세밀하게 조정하는 데 사용됩니다. 세션 관리, 모델 선택, 출력 형식, 권한 제어 등 역할에 따라 아래 소절로 나누어 정리했습니다. 자주 쓰는 플래그는 ~/.claude/settings.json 에 기본값으로 저장해 두면 반복 입력을 줄일 수 있습니다.

세션 설정

모델 & 성능

시스템 프롬프트

입출력

claude -p "현재 디렉터리의 파일 목록" --output-format json

권한 & 도구

MCP & 플러그인

기타

슬래시 명령어

Claude Code 인터랙티브 세션에서 /로 시작하는 명령어를 입력하면 설정 변경, 세션 관리, 특수 기능을 빠르게 호출할 수 있습니다. /help를 입력하면 현재 설치된 커스텀 명령어를 포함한 전체 목록을 확인할 수 있습니다.

키보드 단축키

Claude Code 인터랙티브 세션에서 사용할 수 있는 단축키 목록입니다. 터미널 종류와 운영체제 환경에 따라 일부 단축키의 동작이 다를 수 있습니다. 플랫폼별 차이가 있는 항목은 별도로 구분해 표시합니다.

일반 제어

모드 전환

Option+P: 모델 전환
Option+T: 확장 사고 토글
Option+O: Fast 모드 토글
Cmd+V 또는 Option+V: 클립보드 이미지 붙여넣기
Space (길게 누르기): 음성 입력 (Push-to-talk)

텍스트 편집

멀티라인 입력

멀티라인 입력 단축키는 터미널 종류에 따라 지원 여부가 다릅니다. 아래는 터미널별 권장 방식입니다.

\ + Enter: 백슬래시 뒤에 Enter를 입력하면 모든 터미널에서 줄바꿈이 가능합니다.

입력 모드

Claude Code는 일반 텍스트 입력 외에 세 가지 특수 입력 모드를 제공합니다. 각 모드는 접두사 문자로 진입하며, 파일 참조, 쉘 명령어 실행, 히스토리에 남기지 않는 사이드 질문을 각각 담당합니다.

@ 파일 참조

@ 접두사 뒤에 파일 경로를 입력하면 해당 파일의 내용을 대화에 포함시킵니다. 글로브 패턴을 사용해 여러 파일을 한 번에 참조할 수 있습니다.

! Bash 모드

! 접두사를 붙이면 쉘 명령어를 Claude Code 안에서 직접 실행할 수 있습니다. 실행 결과는 대화 컨텍스트에 자동으로 추가됩니다.

/btw 사이드 질문

/btw는 대화 히스토리에 남지 않는 빠른 질문을 위한 모드입니다. Claude가 작업을 진행하는 중에도 사용할 수 있습니다.

Vim 모드

/vim 명령어로 현재 세션에서 즉시 Vim 모드를 활성화할 수 있습니다. 영구적으로 사용하려면 /config 에서 설정을 변경합니다. 기본 Vim 키바인딩을 그대로 사용하므로 기존 Vim 사용자라면 별도 학습 없이 적용할 수 있습니다.

모드 전환

이동 (NORMAL 모드)

편집 (NORMAL 모드)

텍스트 오브젝트

텍스트 오브젝트는 d(삭제), c(변경), y(복사) 등의 연산자와 함께 사용합니다. i는 내부(inner), a는 주변 공백이나 구분 문자를 포함한 범위(around)를 의미합니다.

설정 파일

Claude Code의 설정은 계층 구조로 관리됩니다. 구체적인 설정이 일반적인 설정보다 우선하며, 프로젝트 수준 설정이 사용자 전역 설정을 덮어씁니다. 팀 공유 설정과 개인 설정을 분리하여 관리할 수 있습니다.

설정 계층

우선순위: settings.local.json > settings.json (프로젝트) > settings.json (사용자 전역)

주요 설정 항목

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Read", "Write(src/**)", "Bash(git *)", "Bash(npm *)"],
    "deny": ["Read(.env*)", "Write(production.config.*)", "Bash(rm *)"]
  }
}

권한 설정

deny 패턴은 allow 패턴보다 항상 우선합니다. 같은 도구가 양쪽에 모두 일치하는 경우 차단됩니다.

CLAUDE.md

CLAUDE.md는 프로젝트별 지시사항을 담는 파일입니다. Claude Code가 세션 시작 시 자동으로 읽어 컨텍스트에 포함하며, 하위 디렉토리에도 별도로 배치할 수 있습니다.

Skills (커스텀 명령어)

Skills는 마크다운 파일로 만드는 커스텀 슬래시 명령어입니다. 기존 .claude/commands/도 계속 동작하지만, Skills는 프론트매터 기반 자동 실행과 파일 관리 기능이 추가되었습니다. 프로젝트 단위로 버전 관리하며 팀 전체가 동일한 명령어를 공유할 수 있습니다.

파일 구조

---
description: Brief description
argument-hint: [arg1] [arg2]
allowed-tools: Read, Bash(git:*)
model: sonnet
effort: high
---

Command prompt content here.
Arguments: $1, $2, or $ARGUMENTS
File references: @path/to/file
Bash execution: !`command here`

프론트매터 옵션

동적 인자

---
description: Fix issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following our coding standards.

Hooks

Hooks는 특정 이벤트에 자동으로 쉘 명령어를 실행하는 기능입니다. settings.json에서 설정하며, 도구 실행 전후, 세션 시작, 파일 변경 등 다양한 시점에 동작을 자동화할 수 있습니다.

이벤트 종류

설정 예시

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write(*.py)",
      "hooks": [{
        "type": "command",
        "command": "python -m black \"$file\""
      }]
    }],
    "PreToolUse": [{
      "matcher": "Bash(rm *)",
      "hooks": [{
        "type": "command",
        "command": "echo 'BLOCK: rm 명령어는 허용되지 않습니다'"
      }]
    }]
  }
}

MCP 서버

MCP(Model Context Protocol)는 Claude Code에 외부 도구를 연결하는 표준 규격입니다. 데이터베이스, 검색 엔진, 클라우드 서비스 등 다양한 외부 시스템을 Claude가 직접 사용할 수 있게 해줍니다. 프로젝트 단위 또는 사용자 전역 범위로 등록하며, stdio·HTTP 두 가지 전송 방식을 지원합니다.

등록 & 관리

$ claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1
$ claude mcp add web-search --transport stdio -- npx open-websearch@latest
$ claude mcp add remote-server --transport http -- https://example.com/mcp
$ claude mcp list
$ claude mcp remove my-server

외부 설정 파일

--mcp-config 플래그로 JSON 파일에서 MCP 서버를 일괄 로드할 수 있습니다. 팀 단위로 서버 목록을 공유하거나, CI/CD 환경에서 동일한 설정을 재사용할 때 유용합니다.

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "open-websearch": {
      "type": "stdio",
      "command": "npx",
      "args": ["open-websearch@latest"],
      "env": { "MODE": "stdio" }
    }
  }
}

서브에이전트

서브에이전트는 특정 작업에 특화된 별도의 Claude 인스턴스입니다. 메인 에이전트가 복잡한 작업을 분담시킬 때 사용하며, 각 에이전트는 독립된 컨텍스트와 도구 권한을 가집니다. 에이전트 정의 파일을 .claude/agents/ 디렉토리에 배치하면 메인 에이전트가 필요 시 자동으로 호출합니다.

설정

---
name: reviewer
description: 코드 리뷰 전문 에이전트
model: sonnet
effort: high
allowed-tools: Read, Grep, Glob
---

당신은 코드 리뷰 전문가입니다.
보안, 성능, 코드 품질에 집중해서 리뷰합니다.

프론트매터 옵션

CLI에서 동적 생성

$ claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer","model":"sonnet"}}'

워크트리

워크트리는 git worktree를 사용해서 저장소의 격리된 복사본에서 작업하는 기능입니다. 메인 브랜치를 건드리지 않고 병렬로 여러 작업을 동시에 진행할 수 있습니다. 각 워크트리는 독립된 작업 공간을 가지므로 실험적인 변경이나 긴급 수정을 안전하게 처리할 수 있습니다.

$ claude -w feature-auth
$ claude --worktree my-feature

대규모 monorepo에서는 worktree.sparsePaths 설정으로 필요한 디렉토리만 체크아웃할 수 있습니다.

{
  "worktree": {
    "sparsePaths": ["src/api", "src/shared", "package.json"]
  }
}

2026년 3월 주요 업데이트

2026년 3월은 Claude Code에 큰 변화가 많았던 달입니다. Opus 4.6의 1M 컨텍스트 지원부터 새로운 훅, 성능 개선까지 주요 업데이트를 정리했습니다. 버전별 변경 사항을 확인해서 현재 사용 중인 버전에서 어떤 기능을 사용할 수 있는지 파악하십시오.

FAQ

Claude Code 사용 시 자주 묻는 질문을 정리했습니다. 요금, 모델 선택, 타 도구와의 비교, 세션 관리 등 핵심 사항을 간결하게 답변합니다.