Claude Code
Claude Code(클로드 코드)는 Anthropic이 만든 AI 코딩 에이전트다. 코드를 대신 써 주는 자동완성 도구가 아니라, 코드베이스를 읽고 파일을 고치고 명령을 실행하는 것까지 스스로 반복하는 방식으로 동작한다.
터미널에서 시작했지만 지금은 VS Code·JetBrains 확장, 데스크톱 앱, 웹, 모바일까지 같은 엔진을 공유한다.
개요
AI 코딩 도구는 크게 세 갈래로 나뉜다.
- 자동완성형 — 타이핑하는 자리에서 다음 코드를 제안한다 (GitHub Copilot의 출발점)
- 편집기 내장형 — 파일을 보면서 AI에게 수정을 시킨다 (Cursor)
- 에이전트형 — 작업을 통째로 맡기면 알아서 탐색·수정·검증을 반복한다
Claude Code는 세 번째다. "인증 모듈에 테스트를 짜고, 돌려 보고, 실패하면 고쳐 줘" 같은 지시를 받으면 파일을 찾고, 테스트를 작성하고, 실행하고, 결과를 보고 다시 고치는 과정을 사람 개입 없이 이어 간다.
모델을 직접 만드는 회사가 만든 도구라는 점이 다른 코딩 도구와의 구조적 차이다. Cursor나 GitHub Copilot은 여러 회사의 모델을 가져다 쓰지만, Claude Code는 Claude 모델만 쓴다. 대신 새 모델이 나오면 가장 먼저 반영된다.
이름이 헷갈리기 쉽다. Claude 는 모델이고, Claude Code 는 그 모델을 쓰는 코딩 도구다. 웹 채팅 서비스인 claude.ai 와도 다르다. 구독은 셋이 공유한다.
어디서 쓸 수 있나
같은 엔진을 여러 환경에서 공유한다. CLAUDE.md, 설정, MCP 서버가
환경을 옮겨도 그대로 따라온다.[1]
| 환경 | 특징 | 비고 |
|---|---|---|
| 터미널 (CLI) | 가장 기능이 완전하다. 파이프·스크립트·CI 연동 가능 | 기본 |
| VS Code 확장 | 인라인 diff, @멘션, 계획 검토 | Cursor에도 설치 가능 |
| JetBrains 플러그인 | IntelliJ·PyCharm·WebStorm 등 | CLI 별도 설치 필요 |
| 데스크톱 앱 | diff를 눈으로 검토, 여러 세션 동시 실행 | 유료 구독 필요 |
| 웹 | 설치 없이 브라우저에서. 긴 작업을 걸어 두고 나중에 확인 | claude.ai/code |
| 모바일 | iOS·Android 앱에서 작업 시작·확인 | |
| GitHub Actions / GitLab CI | PR 리뷰·이슈 분류 자동화 | |
| Slack | @Claude 로 버그를 던지면 PR로 돌아온다 |
주요 기능
CLAUDE.md — 프로젝트 규칙 파일
프로젝트 루트에 CLAUDE.md 를 두면 세션이 시작될 때마다 읽는다.
코딩 컨벤션, 쓰지 말아야 할 라이브러리, 아키텍처 결정 같은 것을 적어 둔다.
작업하면서 알게 된 빌드 명령이나 디버깅 요령을 스스로 기록하는 auto memory 도 있다.[1]
공식 문서는 CLAUDE.md 를 200줄 이하로 유지하라고 권한다.
이 파일은 매 세션 시작 시 통째로 컨텍스트에 올라가므로, 특정 작업에만 필요한
긴 지침은 스킬로 빼는 편이 낫다. 스킬은 호출될 때만 로드된다.
서브에이전트와 에이전트 팀
작업을 쪼개서 여러 인스턴스에 병렬로 맡긴다. 리드 에이전트가 조율하고 결과를 합친다. 여러 세션을 한 화면에서 지켜보는 Agent View 도 있다.
MCP — 외부 도구 연결
MCP로 Google Drive 문서를 읽거나 Jira 티켓을 고치는 등 외부 서비스에 연결한다. 열린 표준이라 직접 만든 도구도 붙일 수 있다.
훅과 스킬
훅은 특정 동작 전후에 셸 명령을 끼워 넣는다. 파일을 고칠 때마다 자동 포맷, 커밋 전 린트 실행 같은 것이다.
스킬은 반복 작업을 패키지로 묶는다. /review-pr, /deploy-staging
같은 명령을 팀이 공유할 수 있다.
플랜 모드와 되돌리기
Shift+Tab 으로 플랜 모드에 들어가면 바로 고치지 않고
접근 방식을 먼저 제안한다. 방향이 틀렸을 때 낭비를 줄인다.
이미 진행했다면 Esc 로 중단하고 /rewind 로
대화와 코드를 이전 지점으로 되돌린다.
스케줄 실행
Routines 는 클라우드에서 돌아가므로 컴퓨터를 꺼도 실행된다. 아침 PR 리뷰, 야간 CI 실패 분석 같은 반복 작업에 쓴다.
권한과 승인
작업을 통째로 맡기는 도구인 만큼 무엇까지 허용할지를 정하는 장치가 있다. 경쟁 도구에는 이만큼 세분화된 것이 없다.[2]
계층형 승인
| 도구 종류 | 예 | 승인 필요 | "다시 묻지 않기" 범위 |
|---|---|---|---|
| 읽기 전용 | 파일 읽기, Grep | 불필요 (작업 디렉터리 안) | 해당 없음 |
| Bash 명령 | 셸 실행 | 필요 (읽기 전용 명령 제외) | 저장소·명령 단위로 영구 |
| 파일 수정 | 편집·쓰기 | 필요 | 세션 종료까지 |
파일을 읽는 것은 묻지 않고, 바꾸거나 실행하는 것은 묻는다. "다시 묻지 않기"를 눌렀을 때의 유효 범위가 종류마다 다르다는 점이 실무에서 중요하다. 파일 수정 허용은 세션이 끝나면 초기화되지만, Bash 명령 허용은 남는다.
권한 모드
설정 파일의 defaultMode 로 기본 동작을 정한다.
plan— 파일을 읽되 고치지 않는다. 계획만 세우게 할 때acceptEdits— 파일 편집과mkdir·mv같은 흔한 명령을 자동 승인bypassPermissions— 승인 절차를 건너뛴다
bypassPermissions 는 공식 문서도 경고를 붙여 둔 모드다.
명시적 ask 규칙, 승인이 필요하도록 표시된 MCP 도구,
그리고 rm -rf / 같은 홈·루트 삭제는 이 모드에서도 여전히 묻는다.
안전장치가 남아 있다는 뜻이지, 안전하다는 뜻이 아니다.
편하다는 이유로 이 모드를 기본값으로 두면 확인 없이 파일이 바뀌고 명령이 돈다. 격리된 컨테이너처럼 망가져도 되는 환경이 아니라면 쓰지 않는 편이 낫다.
규칙 — Allow · Ask · Deny
도구별로 규칙을 걸 수 있고, /permissions 로 현재 규칙과
그것이 어느 설정 파일에서 왔는지 확인한다.
평가 순서는 deny → ask → allow 이고, 먼저 맞는 규칙이 결정한다.
규칙의 구체성은 순서를 바꾸지 않는다.
Bash(aws *) 같은 넓은 deny 규칙을 걸면, Bash(aws s3 ls) 처럼
더 좁은 allow 규칙이 있어도 전부 막힌다. deny 규칙에 예외를 파는 방식은
동작하지 않는다.
ask 와 allow 사이도 마찬가지다. 맞는 ask 규칙이 있으면 더 구체적인 allow 가 있어도 묻는다.
설정 파일을 저장소에 커밋하면 팀 전체가 같은 권한 규칙을 공유한다. 개발자마다 자기 설정을 덧붙일 수도 있다. 회사에서 도입할 때 "AI가 무엇까지 할 수 있는지"를 코드로 관리할 수 있다는 뜻이다.
명령이 뭘 하는지 모를 때
Bash 승인 화면에서 Ctrl+E 를 누르면 그 명령이 무엇을 하는지,
왜 실행하려는지, 무엇이 잘못될 수 있는지를 설명해 준다.
위험도가 낮음·중간·높음으로 표시된다.
낯선 명령이 올라왔을 때 그냥 승인하지 않고 확인할 수 있는 장치다.
가격
| 플랜 | 월 요금 | 연간 결제 시 | 내용 |
|---|---|---|---|
| Free | $0 | — | Claude Code 포함. 한도가 작다 |
| Pro | $20 | $17/월 | 개인 개발자 기준선 |
| Max 5x | $100 | — | Pro의 5배 사용량 |
| Max 20x | $200 | — | Pro의 20배 사용량 |
| Team | $25 / 좌석 | $20 / 좌석 | 2~150명 |
| Team 프리미엄 | $125 / 좌석 | $100 / 좌석 | 좌석당 한도가 크다 |
| Enterprise | 별도 | — | 좌석 요금 + API 종량, SCIM·감사 로그·HIPAA |
구독 대신 API 종량제로도 쓸 수 있다. 이 경우 토큰 사용량만큼 과금된다.
실제로 얼마나 나가나
공식 문서가 기업 도입 사례 기준 수치를 공개하고 있다.[3]
| 기준 | 금액 |
|---|---|
| 개발자 1인 / 활동일 평균 | 약 $13 |
| 개발자 1인 / 월 | $150~250 |
| 사용자 90%의 활동일 상한 | $30 미만 |
이건 API 종량제 기준이다. 구독을 쓰면 이 금액을 내는 게 아니라 구독 한도 안에서 쓰는 것이다. 다만 자신의 사용량이 구독료를 넘는지 가늠하는 기준으로는 쓸 만하다. 월 $150어치를 쓰는 사람이라면 Pro($20)로는 한도에 계속 걸린다는 뜻이다.
사용 한도
이 도구를 쓸 때 가장 자주 겪는 문제다. 별도로 정리한다.
구독 플랜에는 두 가지 창이 있다.[3]
- 세션 한도 — 5시간 단위로 갱신
- 주간 한도 — 일주일 단위로 갱신
모델을 바꿔도 한도가 복구되지 않는다.
이 창들은 모든 모델이 공유한다. /model 로 Opus에서 Sonnet으로 바꾸는 것은
"Opus 한도에 걸렸습니다" 메시지 이후 작업을 이어 가게 해 줄 뿐,
세션·주간 한도 자체를 되돌리지는 못한다.
한도에 걸리면 갱신 시각을 기다리거나, 사용 크레딧을 켜서 초과분을 따로 결제하는 수밖에 없다.
/usage 로 현재 사용량과 갱신 시각을 확인한다.
어떤 스킬·서브에이전트·MCP 서버가 사용량을 많이 먹는지도 항목별로 보여 준다.
긴 세션이 한도를 조용히 먹는다
공식 문서가 명시하는 사실이다. Claude Code는 요청할 때마다 대화 전체를 다시 보낸다. 캐시 요금이 적용되긴 하지만, 하루 종일 열어 둔 세션에서 한 줄짜리 질문을 하면 그 한 줄이 아니라 그날 대화 전체 분량이 사용량으로 계산된다.
대응은 단순하다. 관련 없는 작업으로 넘어갈 때 /clear 로 세션을 비운다.
문서는 이것을 비용 절감 1순위로 든다.
데이터와 프라이버시
회사에서 도입을 검토할 때 가장 먼저 막히는 부분이라 따로 정리한다.[4]
| 플랜 | 모델 학습에 사용 | 데이터 보관 |
|---|---|---|
| Free · Pro · Max | 설정으로 켜고 끌 수 있다 | 학습 허용 시 5년 / 미허용 시 30일 |
| Team · Enterprise · API | 사용하지 않는다 | 30일 |
소비자 플랜(Free·Pro·Max)은 개인정보 설정에서 언제든 바꿀 수 있다. Team·Enterprise·API 같은 상업 약관에서는 기본적으로 학습에 쓰지 않는다.
Enterprise 플랜에 한해 Zero Data Retention(서버에 아무것도 남기지 않음)을 적용할 수 있으나, 기본 포함이 아니라 자격 확인 후 조직 단위로 켜 준다.
대화 기록이 내 컴퓨터에 평문으로 남는다.
세션 재개 기능 때문에 ~/.claude/projects/ 아래에 대화 기록이
암호화되지 않은 상태로 기본 30일 저장된다. 여기에는 읽은 파일 내용도 포함된다.
공용 PC나 백업이 외부로 나가는 환경이라면 이 점을 확인해야 한다.
보관 기간은 cleanupPeriodDays 설정으로 조절한다.
텔레메트리는 DISABLE_TELEMETRY=1, 오류 보고는 DISABLE_ERROR_REPORTING=1,
비필수 통신 전체는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 로 끈다.
수집 항목에 코드·프롬프트·파일 경로는 포함되지 않는다고 명시되어 있다.
장점
작업을 통째로 맡길 수 있다
파일 단위로 지시하는 게 아니라 "이 버그 고쳐 줘" 수준의 지시가 통한다. 탐색·수정·테스트·재수정을 스스로 반복하므로, 맡겨 놓고 다른 일을 할 수 있다.
터미널 도구라 조합이 자유롭다
유닉스 철학을 따른다. 로그를 파이프로 넣거나, CI에서 실행하거나, 다른 도구와 엮을 수 있다.
tail -200 app.log | claude -p "이상 징후가 있으면 알려 줘" git diff main --name-only | claude -p "바뀐 파일들 보안 관점에서 검토해 줘"
GUI 편집기에 갇힌 도구로는 하기 어려운 방식이다.
환경을 옮겨도 설정이 따라온다
터미널에서 시작한 작업을 데스크톱 앱으로 넘기거나, 웹에 걸어 두고
휴대폰으로 확인할 수 있다. CLAUDE.md 와 MCP 설정이 공유된다.
프로젝트 규칙을 파일로 관리한다
CLAUDE.md 를 저장소에 커밋해 두면 팀 전체가 같은 규칙을 공유한다.
사람마다 프롬프트가 다른 문제가 줄어든다.
권한을 코드로 관리할 수 있다
경쟁 도구에 없는 부분이다. 어떤 명령을 허용하고 어떤 것을 막을지 규칙으로 정하고, 그 설정을 저장소에 커밋해 팀 전체에 적용한다.
회사에서 도입할 때 "AI가 무엇까지 할 수 있느냐"에 답할 수 있다는 뜻이다. 승인 버튼을 누르는 사람의 판단에만 맡기지 않아도 된다.
단점
한도 구조가 예측을 어렵게 한다
5시간 창과 주간 창이 동시에 걸리고, 모델을 바꿔도 복구되지 않는다. 작업이 몰리는 날에 주간 한도가 먼저 소진되면 며칠을 기다려야 한다. 정액제를 기대하고 결제하면 어긋나는 지점이다.
긴 세션이 대화 전체를 반복 전송한다는 점도 체감 소모를 키운다.
/clear 습관이 없으면 사용량이 예상보다 빨리 찬다.
터미널이 익숙하지 않으면 진입 장벽이 있다
VS Code 확장과 데스크톱 앱이 나왔지만 가장 기능이 완전한 것은 여전히 CLI다. 파이프·환경변수·설정 파일 편집이 낯설면 기능의 절반을 못 쓴다.
무엇을 고쳤는지 검토하는 부담이 크다
작업 단위가 크다는 것은 한 번에 바뀌는 코드도 많다는 뜻이다. Cursor처럼 파일 하나씩 diff를 보며 승인하는 방식보다, 결과를 신뢰하고 나중에 검토하는 쪽에 가깝다. 코드 리뷰 습관이 없으면 이해하지 못한 코드가 쌓인다.
대화 기록이 로컬에 평문으로 남는다
~/.claude/projects/ 에 기본 30일. 읽은 파일 내용도 들어간다.
보안 정책이 엄격한 환경에서는 이것부터 확인해야 한다.
모델을 고를 수 없다
Claude 계열만 쓴다. Claude 모델 자체는 코딩 평가에서 좋은 평을 받지만, 특정 회사에 묶인다는 점은 구조적 제약이다. 여러 회사 모델을 비교하며 쓰고 싶다면 Cursor 쪽이 맞다.
에이전트 팀은 토큰을 훨씬 많이 쓴다
공식 문서 기준 일반 세션의 약 7배다. 팀원마다 별도 컨텍스트를 유지하기 때문이다. 그래서 기본적으로 꺼져 있고, 환경변수로 따로 켜야 한다.
윈도우는 준비물이 하나 더 있다
네이티브 윈도우에서는 Bash 도구를 쓰려면 Git for Windows 설치가 권장된다. 없으면 PowerShell로 대체되는데, 셸 문법이 달라 명령이 어긋나는 경우가 생긴다.
경쟁 도구와 비교
| 항목 | Claude Code | Cursor | GitHub Copilot |
|---|---|---|---|
| 형태 | 터미널 CLI + 확장·앱·웹 | GUI 편집기 | 편집기 확장 |
| 기반 | 독립 실행 | VS Code 포크 | 기존 편집기에 얹음 |
| 모델 | Claude 전용 | 자체 + 여러 회사 선택 | 여러 회사 선택 |
| 작업 단위 | 크다 (통째로 위임) | 중간 (파일·블록) | 작다 (줄·함수) |
| 검토 방식 | 결과 확인 | diff 승인 | 인라인 수락 |
| 권한 제어 | 규칙·모드로 세분화 | 승인 UI | 승인 UI |
| 편집기 밖 실행 | CI·스케줄·Slack·웹 | Bugbot·클라우드 에이전트 | 클라우드 에이전트(GitHub 전용) |
| 과금 | 구독 한도 또는 API 종량 | 사용량 풀 2개 | 크레딧 |
| 개인 진입가 | $20 | $20 | $10 |
결정적 차이는 작업 방식이다. Cursor는 코드를 보면서 고치는 도구고, Claude Code는 작업을 맡기는 도구다. 대체재라기보다 쓰는 상황이 다르며, 둘을 같이 쓰는 사람도 많다 — Claude Code VS Code 확장은 Cursor에도 설치된다.
이런 사람에게 맞다
- 터미널 작업이 익숙한 사람
- 큰 코드베이스에서 여러 파일에 걸친 작업이 많은 사람
- 테스트 작성, 린트 수정, 의존성 업데이트처럼 미뤄 둔 잡일이 쌓인 사람
- CI·스케줄·Slack에 AI를 엮고 싶은 사람
- 팀이 같은 코딩 규칙을 공유해야 하는 경우 (
CLAUDE.md커밋)
이런 사람에게는 안 맞다
- 매달 비용이 일정해야 하는 사람 — 한도 구조상 변동이 크다
- 터미널이 부담스러운 사람 — GUI만 쓸 거면 Cursor 쪽이 낫다
- 바뀐 코드를 한 줄씩 확인하고 싶은 사람 — 작업 단위가 커서 맞지 않는다
- 코드 외부 전송이 금지된 환경 — 보안 정책부터 확인해야 한다
- 여러 회사 모델을 비교하며 쓰고 싶은 사람 — Claude 계열만 지원한다
- 자동완성 위주로 쓰려는 사람 — 그 용도라면 GitHub Copilot이 더 싸다
시작하기
1. 설치
# macOS · Linux · WSL curl -fsSL https://claude.ai/install.sh | bash # Windows PowerShell irm https://claude.ai/install.ps1 | iex # Homebrew brew install --cask claude-code # WinGet winget install Anthropic.ClaudeCode
2. 프로젝트에서 실행
cd 프로젝트폴더 claude
처음 실행하면 로그인하라고 나온다.
3. 첫 작업은 작게
claude "이 프로젝트 구조를 설명해 줘"
4. CLAUDE.md 만들기
프로젝트 루트에 만들고 코딩 규칙을 적는다. 200줄을 넘기지 않는다.
처음 쓸 때 익혀 둘 것 네 가지
/clear— 다른 작업으로 넘어갈 때. 비용 절감 1순위/usage— 남은 한도와 갱신 시각 확인Shift+Tab— 플랜 모드. 큰 작업 전에 방향부터 맞춘다Esc//rewind— 잘못 가고 있을 때 중단·되돌리기
자주 겪는 문제
"세션 한도에 걸렸습니다"가 떴다
/model 로 모델을 바꿔도 소용없다. 창을 모든 모델이 공유하기 때문이다.
/usage 로 갱신 시각을 확인하고 기다리거나,
/usage-credits 로 초과분을 결제한다.
사용량이 예상보다 빨리 줄어든다
세션을 오래 열어 뒀을 가능성이 크다. 요청마다 대화 전체가 다시 전송되므로
하루 종일 켜 둔 세션에서는 짧은 질문도 비싸다.
관련 없는 작업으로 넘어갈 때 /clear 로 비운다.
/usage 가 어떤 스킬·서브에이전트·MCP 서버가 많이 먹는지도 보여 준다.
CLAUDE.md 를 적었는데 반영이 약하다
파일이 너무 길 수 있다. 공식 문서는 200줄 이하를 권한다. 매 세션 시작 시 통째로 올라가므로, 특정 작업에만 필요한 긴 지침은 스킬로 빼는 편이 낫다. 스킬은 호출될 때만 로드된다.
권한 규칙을 걸었는데 원하는 명령까지 막힌다
deny 규칙이 너무 넓게 잡혔을 수 있다. Bash(aws *) 같은 규칙은
좁은 allow 규칙으로 예외를 팔 수 없다. /permissions 로
어느 설정 파일의 어떤 규칙이 걸리는지 확인한다.
윈도우에서 Bash 명령이 이상하게 동작한다
Git for Windows 가 없으면 PowerShell 로 대체된다. 셸 문법이 달라 명령이 어긋난다. Git for Windows 설치를 권한다.
자주 묻는 것
무료로 쓸 수 있나?
Free 플랜에도 포함되지만 한도가 작다. 데스크톱 앱은 유료 구독이 필요하다. 실제로 일에 쓰려면 Pro 이상이 현실적이다.
한국에서 결제되나?
된다. 해외 결제가 가능한 카드가 필요하다.
claude.ai 구독과 별도인가?
같다. Pro·Max 구독 하나로 웹 채팅과 Claude Code를 함께 쓴다. 한도도 함께 쓴다 — 채팅을 많이 하면 코딩에 쓸 몫이 줄어든다.
한도에 걸리면?
갱신 시각까지 기다리거나 /usage-credits 로 초과 사용분을 결제한다.
모델을 바꾸는 것으로는 해결되지 않는다.
내 코드가 학습에 쓰이나?
Free·Pro·Max는 설정에 따라 다르며 직접 끌 수 있다. Team·Enterprise·API는 기본적으로 쓰지 않는다.
Cursor와 같이 써도 되나?
된다. Claude Code VS Code 확장은 Cursor에도 설치할 수 있다.
여담
Claude Code는 자기 자신을 만드는 데도 쓰인다. Anthropic이 공개한 동적 워크플로우 관련 글에는 개발팀이 수십 개의 서브에이전트를 병렬로 돌려 작업을 조율하는 방식이 나온다.
기능 이름에 유닉스 문화의 흔적이 남아 있는 것도 특징이다. 파이프로 로그를
넘기고, -p 플래그로 한 줄 실행을 하고, CI에 그대로 꽂아 쓰는 방식은
GUI 우선으로 설계된 도구에서는 잘 나오지 않는 발상이다.
