클로드 코드(Claude Code) 사용법 총정리 2026 — 설치·CLAUDE.md·Hooks·MCP·비용 관리까지

이 글의 요점

Claude Code는 Anthropic이 만든 CLI 기반 AI 코딩 에이전트로, 파일 조작·셸 실행·웹 검색을 모델이 자율적으로 완결한다
CLAUDE.md를 통한 지시의 영속화, Hook 시스템을 통한 자동화, MCP 서버 연계가 실무에서의 주요 차별화 포인트
요금은 Max 구독 또는 API 종량 과금으로 이용 가능. 비용 상한의 사전 설정이 필수

요금 관련 보충: 원문은 Max 구독과 API 종량 과금만 언급하지만, Claude Code는 Pro 플랜(월 $20)으로도 이용할 수 있습니다(글 뒷부분의 인증 섹션에서도 "Pro 또는 Max 플랜"이라고 언급되어 있어, 요점 정리 쪽이 이전 시점의 정보로 보입니다). 가볍게 시작한다면 Pro, 본격 사용이라면 Max(월 $100/$200)라는 선택지가 일반적입니다.

Claude Code란 무엇인가

Claude Code는 Anthropic이 개발하는 AI 코딩 에이전트입니다. 터미널에서 자연어로 지시하면 모델이 자율적으로 파일을 읽고 쓰고, Bash 커맨드를 실행해 태스크를 완결합니다. 2025년 2월 베타 공개를 거쳐 같은 해 5월에 정식 릴리스(GA)됐고, 2026년 현재는 Claude Sonnet 4.6과 Opus 4.8을 이용할 수 있습니다.

2026년 7월 기준으로는 이 밖에 경량 모델 Claude Haiku 4.5, 그리고 Claude 5 패밀리의 최상위 모델 Claude Fable 5도 제공되고 있습니다.

VS Code·JetBrains의 IDE 확장으로도 쓸 수 있지만, 본래의 강점은 CLI에서의 자율적인 태스크 실행에 있습니다. "이 버그 고쳐 줘"라고 지시하면 관련 파일 조사·수정·테스트 실행까지 한 번에 진행하는 동작은 자동 완성형 툴과는 결이 다릅니다.

기존 AI 코딩 툴과의 차이

자주 비교되는 Cursor·GitHub Copilot과의 차이를 표로 정리합니다.

툴	주요 형태	파일 조작	셸 실행	백그라운드 실행
GitHub Copilot	IDE 자동 완성 / Chat	제한적	불가	불가
Cursor	IDE 에디터	있음	제한적	불가
Claude Code	CLI / IDE 확장	있음	있음	있음

가장 큰 차이는 "백그라운드 실행"입니다. Claude Code는 서브에이전트를 별도 프로세스로 돌리면서 내 손으로는 다른 태스크를 진행하는 병렬 작업이 가능합니다.

설치와 초기 설정

npm으로 설치

Node.js 18 이상이 전제입니다.

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

설치 후에는 claude 커맨드로 실행합니다.

claude

인증 방법은 3종류

Anthropic 계정으로 로그인(Pro 또는 Max 플랜): 실행 후 브라우저 인증이 진행된다
API 키를 환경 변수에 설정: export ANTHROPIC_API_KEY="sk-ant-..." 를 .zshrc 등에 추가
Claude for Work(Enterprise): 조직의 IT 관리자가 AWS나 GCP 경유로 설정

저는 API 키 방식으로 쓰고 있습니다. 여러 프로젝트를 넘나들며 돌려 쓸 수 있어 관리가 편해요. 다만 공유 머신에 키를 그대로 쓰는 건 위험하니, direnv 등으로 환경별로 전환하는 것을 추천합니다.

주요 슬래시 명령어 목록

대화 모드 중 / 로 시작하는 커맨드로 Claude Code 자체를 제어합니다.

커맨드	설명
`/help`	커맨드 목록 표시
`/clear`	대화 이력 리셋
`/compact`	긴 대화를 요약해 컨텍스트 절약
`/model`	사용 모델 전환
`/cost`	세션 중 토큰 소비량 확인
`/init`	프로젝트에 CLAUDE.md 자동 생성
`/review`	브랜치의 변경 사항(diff)을 코드 리뷰시킨다

장시간 작업 세션에서는 /compact 를 정기적으로 실행하는 습관을 들이면 컨텍스트 윈도가 눌리는 것을 막을 수 있습니다.

CLAUDE.md로 프로젝트의 동작을 제어한다

Claude Code를 실무에서 쓸 때 가장 중요한 기능이 CLAUDE.md입니다. 프로젝트 루트에 두는 Markdown 파일로, Claude Code가 기동할 때마다 읽어 들이는 "지시서"로 작동합니다.

# CLAUDE.md 예시

## 프로젝트 개요
Next.js 15 + TypeScript 이커머스 사이트.

## 개발 규칙
- 주석은 한국어
- 테스트는 vitest. `npm run test` 로 실행
- `npm run build` 가 통과하지 않는 변경은 커밋하지 않는다

## 금지 사항
- API 키와 시크릿을 코드에 쓰지 않는다
- `console.log` 를 프로덕션 코드에 남기지 않는다

/init 을 실행하면 기존 코드베이스를 분석해 CLAUDE.md 초안을 자동 생성해 줍니다. 맨땅에서 쓰는 것보다 훨씬 빠르니, 새 프로젝트에서 쓰기 시작할 때 꼭 시험해 볼 가치가 있습니다.

전역 설정은 ~/.claude/CLAUDE.md 에 씁니다. "이모지는 쓰지 마", "응답은 한국어로" 같은 개인 취향은 여기에 한 번 써 두면 전체 프로젝트에 적용됩니다.

Hook 시스템으로 반복 작업을 자동화한다

Claude가 툴을 부르기 전후에 임의의 셸 커맨드를 끼워 넣을 수 있는 Hook 시스템은 .claude/settings.json 에서 설정합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix"
          }
        ]
      }
    ]
  }
}

위 설정에서는 Claude Code가 파일을 편집할 때마다 lint가 자동으로 돌아갑니다. "고쳐 쓰면 반드시 포맷해 줘"라는 요구를 매번 지시하지 않아도 됩니다.

대응하는 이벤트는 PreToolUse(툴 실행 전)·PostToolUse(툴 실행 후)·Stop(Claude 정지 시) 등입니다.

MCP 서버 연계로 할 수 있는 일을 확장한다

MCP(Model Context Protocol)는 Claude가 외부 툴과 통신하기 위한 프로토콜입니다. MCP 서버를 추가하면 표준 기능에 없는 조작도 Claude Code가 해내게 됩니다.

원문의 설정 예시(.claude/settings.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

위 예시에는 두 가지 문제가 있습니다. 첫째, MCP 서버 설정 위치가 잘못되었습니다. Claude Code의 MCP 서버는 .claude/settings.json 이 아니라 프로젝트 루트의 .mcp.json(팀 공유용) 또는 사용자 스코프의 ~/.claude.json 에 저장되며, .claude/settings.json 에 쓴 mcpServers 설정은 무시됩니다(공식 문서 및 공식 리포지토리 이슈에서 확인). 가장 확실한 방법은 claude mcp add 커맨드로 추가하는 것입니다(--scope project 를 붙이면 .mcp.json 이 생성됩니다). 둘째, 예시의 패키지명 @anthropic-ai/mcp-server-github 는 통용되는 표기가 아니며, 커뮤니티 패키지는 @modelcontextprotocol/server-github, 현재는 GitHub 공식 원격 MCP 서버 이용이 일반적입니다.

대표적인 MCP 서버 예시:

GitHub MCP: Issue 생성·PR 리뷰·브랜치 조작
PostgreSQL MCP: SQL 쿼리 직접 실행
Playwright MCP: 브라우저 조작 자동화
Slack MCP: 채널로 알림 전송

MCP 생태계는 2026년 현재도 확대가 이어지고 있고, 주요 SaaS 다수에 MCP 서버가 존재합니다. "Claude Code를 자사의 사내 툴과 연계시키고 싶다"는 용도에도 통합니다.

비용 관리의 사고방식

요금 체계

Claude Code는 다음 중 하나로 이용합니다. 정확한 최신 요금은 Anthropic 공식 요금 페이지를 확인하세요.

Claude Max 플랜: 구독형. 월 단위 이용 상한이 설정되어 있어 비용을 예측하기 쉽다
API 키 경유 종량 과금: 토큰 수에 따른 과금. 사용량이 많으면 Max 플랜보다 비싸지는 경우가 있다

[역주 — 최신 정보] 앞서 언급했듯 **Pro 플랜(월 $20, 원화 약 3만 원 + 부가세)**으로도 Claude Code를 이용할 수 있으며, 개인의 가벼운 사용이라면 Pro로 시작하는 것이 일반적입니다. 이용량 상한은 Pro < Max 5배($100) < Max 20배($200) 순입니다.

비용 상한은 반드시 설정한다

API 키로 쓸 경우 Anthropic 대시보드에서 월간 상한액(spending limit)을 걸어 둘 수 있습니다. 루프 처리가 의도치 않게 계속 도는 등의 실수로 비용이 불어날 위험이 있으니, 가장 먼저 반드시 상한을 설정하는 것을 강력히 추천합니다.

세션 중에는 /cost 로 소비량을 수시로 확인하면 됩니다.

흔히 걸려 넘어지는 포인트

허가 다이얼로그가 자꾸 뜬다

기본값에서는 조작마다 확인을 요구합니다. 신뢰할 수 있는 조작은 .claude/settings.json 의 permissions.allow 로 화이트리스트에 올려 둡니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff*)"
    ]
  }
}

CLAUDE.md가 읽히지 않는 것 같다

서브디렉터리 안에서 claude 를 실행하면 상위 디렉터리의 CLAUDE.md가 읽히지 않을 때가 있습니다. 원문은 여기서 --cwd 옵션으로 루트를 명시하라고 안내합니다.

claude --cwd /path/to/project

이 --cwd 플래그는 메인 claude 커맨드에 존재하지 않습니다. 공식 CLI 레퍼런스의 플래그 목록에 없고, --cwd 추가는 공식 리포지토리에 기능 요청 이슈로 열려 있는 상태입니다(존재하는 것은 claude agents 서브커맨드의 --cwd 뿐). 올바른 대응은 프로젝트 루트로 이동해서(cd /path/to/project && claude) 실행하는 것이고, 추가 디렉터리 접근이 필요하면 --add-dir 옵션을 씁니다.

컨텍스트가 길어져 응답이 느려진다

장시간 세션에서는 /compact 로 컨텍스트를 압축하거나, 태스크 전환 시 /clear 로 리셋합니다. 새 태스크로 옮길 때마다 리셋하는 쪽이 모델의 정확도도 안정되기 쉬운 경향이 있습니다.

자주 묻는 질문

Q. Claude Code와 Cursor는 어느 쪽을 쓰면 좋나요?

A. 용도에 따라 다릅니다. CLI에서 자율적으로 태스크를 완결시키고 싶다, 셸 조작과 CI/CD를 조합하고 싶다면 Claude Code가 알맞습니다. 에디터 안에서의 자동 완성과 UI에서 변경 사항(diff)을 확인하는 걸 중시한다면 Cursor가 다루기 쉽습니다. 실제로는 둘을 나눠 쓰는 엔지니어가 많아, 배타적으로 고를 필요는 없습니다.

A. Anthropic의 이용 규약에는 사용자가 생성한 아웃풋의 권리를 제한하지 않는다는 취지가 명기되어 있습니다. 다만 법적 판단은 상황에 따라 다르므로, 기업에서 본격 이용할 때는 법무 부서 확인을 권합니다.

Q. CLAUDE.md는 팀에서 공유할 수 있나요?

A. .claude/settings.json 과 프로젝트의 CLAUDE.md 는 Git 리포지토리에 포함해 팀 전원이 공유하면 됩니다. API 키는 개인별로 발급하는 것이 기본입니다. 조직 차원의 관리에는 Claude for Work(Enterprise) 이용을 검토하세요.