Claude Code를 처음 쓰거나 제대로 못 쓰고 있다면 이 글부터 읽자. 2026년 최신 설정과 실전 워크플로로 여름 사이드 프로젝트 개발 속도를 확 끌어올리는 방법을 정리했다.
여름 사이드 프로젝트 시작했는데 코딩 속도가 안 나온다면, 세팅 문제일 가능성이 크다.
이 글은 Claude Code를 제대로 쓰기 위한 설정과 실전 워크플로를 정리한 가이드다.
2026년 7월 기준, 최신 Claude Code 기능을 기준으로 작성했다.
Claude Code가 뭔지 모르는 사람을 위한 30초 정리
Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트다.
에이전트란, 단순히 코드를 제안하는 게 아니라 파일을 읽고, 수정하고, 명령을 실행하는 걸 스스로 해내는 도구를 말한다.
VS Code 플러그인 방식이 아니다. 터미널에서 claude 명령어 하나로 실행한다.
프로젝트 폴더를 통째로 맥락으로 이해하고, 코드를 짜고, 디버깅까지 한 사이클로 처리한다.
Claude Code는 "코드 자동완성 도구"가 아니다. 프로젝트 구조를 읽고 판단하는 에이전트다. 처음부터 그 관점으로 써야 제대로 활용된다.
다른 AI 코딩 도구와 뭐가 다른가
| 항목 | Claude Code | GitHub Copilot | Cursor |
|---|---|---|---|
| 실행 방식 | 터미널 에이전트 | IDE 플러그인 | IDE 내장 |
| 파일 수정 | 직접 수정 가능 | 제안만 함 | 직접 수정 가능 |
| 터미널 명령 실행 | 가능 | 불가 | 제한적 |
| 맥락 이해 범위 | 프로젝트 전체 | 현재 파일 중심 | 프로젝트 전체 |
| 기반 모델 | Claude 3.7 Sonnet | GPT-4o 계열 | 선택 가능 |
| 월 요금 (2026.07 기준) | $20 (Pro) | $10~$19 | $20 |
Copilot이 "옆에서 코드 완성해주는 동료"라면, Claude Code는 "프로젝트 맥락 파악하고 혼자 작업하는 주니어 개발자"에 가깝다.
설치와 초기 설정 — 여기서 5분 아끼면 나중에 한 시간 번다
설치는 딱 이 순서로
npm install -g @anthropic-ai/claude-code
claude
처음 실행하면 API 키 인증이 뜬다.
Claude Pro 구독자라면 추가 비용 없이 쓸 수 있다. 단, Pro 플랜 내 사용량 한도가 있다.
API 키 직접 발급 방식도 있다. 이 경우 입력 토큰당 $3/백만 토큰, 출력 토큰당 $15/백만 토큰이 과금된다 (2026.07 기준 Claude 3.7 Sonnet 기준).
API 키 직접 방식은 대형 리팩토링 한 번에 $2~5가 나올 수 있다. 장기 프로젝트라면 Pro 구독($20/월)이 훨씬 낫다. 단발성 실험이면 API 키 방식도 괜찮다.
CLAUDE.md 파일 — 모르면 반쪽짜리로 쓰는 거다
프로젝트 루트에 CLAUDE.md 파일을 만들어두면, Claude Code가 세션 시작할 때마다 자동으로 읽는다.
여기에 프로젝트 규칙을 써두면 매번 설명 안 해도 된다.
실제로 써본 CLAUDE.md 예시:
# 프로젝트 규칙
## 기술 스택
- Next.js 15, TypeScript, Tailwind CSS
- ORM: Prisma / DB: PostgreSQL
- 테스트: Vitest
## 코드 규칙
- 함수명은 camelCase, 컴포넌트명은 PascalCase
- any 타입 금지. unknown으로 대체
- console.log는 커밋 전 전부 제거
## 브랜치 전략
- main: 배포 브랜치
- feature/[이름]: 기능 개발
- PR 전 `npm run lint` 반드시 통과
이거 하나로 같은 말 10번 반복하는 걸 없앤다.
실전 워크플로 — 이렇게 쓰면 속도가 다르다
여름 사이드 프로젝트에서 실제로 쓴 방식
7월 초에 포트폴리오 사이트 리뉴얼을 진행했다. 기존 코드베이스가 있는 상태에서 Claude Code를 붙였다.
작업 흐름은 이랬다:
claude실행 → 프로젝트 폴더에서 바로 시작- "현재 프로젝트 구조 파악하고 문제점 3가지 알려줘" 로 시작
- Claude가 파일 트리 읽고 의존성 확인 후 진단 리포트 출력
- 우선순위 높은 작업부터 순서대로 지시
- 파일 수정 완료되면 직접
git diff확인 후 커밋
하루 3~4시간 작업 기준, 혼자 했으면 3일 걸릴 리팩토링을 반나절에 끝냈다.
대화 방식이 결과를 결정한다
Claude Code에 "코드 짜줘" 식으로 막연하게 지시하면 결과가 엉망이다.
아래 두 방식의 차이를 보면 바로 이해된다.
| 나쁜 지시 | 좋은 지시 |
|---|---|
| "로그인 기능 만들어줘" | "NextAuth.js 사용해서 Google OAuth 로그인 추가해줘. 세션 방식은 JWT. /api/auth 경로 사용" |
| "버그 고쳐줘" | "src/lib/api.ts 45번째 줄에서 TypeError 나. fetch 응답이 null일 때 처리가 빠져 있어" |
| "테스트 추가해줘" | "UserCard 컴포넌트에 Vitest로 유닛 테스트 추가해줘. props 없을 때 폴백 렌더링 케이스 포함" |
맥락 + 기술 스펙 + 제약 조건. 이 세 가지를 같이 넣으면 된다.
CLAUDE.md에 프로젝트 규칙 → 구체적 지시 → git diff로 검토. 이 세 단계가 Claude Code 활용의 기본 사이클이다.
속도를 3배 올리는 설정 5가지
1. 슬래시 명령어 외워두기
Claude Code는 터미널에서 / 로 시작하는 명령어를 지원한다.
/clear— 현재 대화 컨텍스트를 초기화한다. 세션이 길어지면 응답 품질이 떨어진다. 이 명령어로 리셋하면 된다./compact— 컨텍스트를 요약해서 토큰 사용량을 줄인다. 긴 작업 세션에서 유용하다./review— 현재까지 Claude가 수정한 파일 목록을 보여준다./cost— 현재 세션에서 소모된 토큰 비용을 표시한다. API 키 방식 쓰는 사람에게 필수다.
2. --continue 플래그로 세션 이어가기
claude --continue 를 쓰면 이전 세션을 이어서 작업한다.
작업 중간에 터미널을 닫아도 맥락이 날아가지 않는다.
3. 멀티 파일 작업은 명시적으로 지정하라
Claude Code가 자동으로 파일을 탐색하지만, 범위가 넓어지면 엉뚱한 파일을 건드리기도 한다.
"src/components 폴더 내 파일만 수정해줘" 처럼 범위를 명시하면 사고가 줄어든다.
4. Git과 같이 쓰는 게 기본이다
Claude Code는 실제로 파일을 수정한다.
git status, git diff 습관이 없으면 뭐가 바뀌었는지 파악이 안 된다.
작업 전 브랜치 하나 새로 파고, 작업 후 diff 확인 → 커밋. 이 루틴을 지켜야 한다.
5. 모델 선택 옵션 알아두기
claude --model claude-3-5-haiku-20241022 처럼 모델을 지정할 수 있다.
빠른 작업(리팩토링, 단순 버그 수정)엔 Haiku를 써서 비용을 아낀다.
복잡한 설계나 알고리즘 작업엔 Sonnet을 쓴다.
2026년 7월 기준 Haiku는 Sonnet 대비 약 80% 저렴하다.
✅ CLAUDE.md 파일 프로젝트 루트에 생성했는가
✅ 작업 전 git 브랜치 새로 팠는가
✅ 지시문에 기술 스펙과 제약 조건 포함했는가
✅ 세션이 길어지면 /compact or /clear 실행했는가
✅ 파일 수정 후 git diff로 검토했는가
한계도 알고 써야 한다 — 과신하면 시간을 더 쓴다
Claude Code가 잘 못하는 게 있다. 솔직히 적어둔다.
실시간 환경 의존 작업에 약하다.
"지금 로컬 서버에서 이 에러가 나고 있어" 같은 상황은 Claude Code가 직접 확인할 수 없다.
에러 로그를 복사해서 붙여줘야 한다.
보안 민감한 코드 자동 실행은 위험하다.
Claude Code는 터미널 명령을 실행할 수 있다. --dangerously-skip-permissions 옵션은 모든 권한 확인을 건너뛴다.
이름부터 위험하다. 신뢰할 수 없는 코드베이스에서 절대 쓰지 말 것.
맥락이 너무 길면 응답 품질이 떨어진다.
Claude 3.7 Sonnet의 컨텍스트 윈도우는 200K 토큰이다.
대형 프로젝트에서 모든 파일을 한꺼번에 넣으면 초반부 내용을 잊어버리는 현상이 생긴다.
작업 범위를 나눠서 세션을 관리하는 게 낫다.
Claude Code가 수정한 코드라도 그냥 믿고 커밋하면 안 된다. 테스트 통과 여부, 로직 의도, 사이드 이펙트는 개발자가 직접 확인해야 한다. 도구는 도구다.
Claude Code vs 경쟁 도구 — 언제 뭘 쓸까
2026년 7월 기준, AI 코딩 에이전트 시장은 선택지가 많아졌다.
팔란티어 CEO가 OpenAI·Anthropic의 토큰 비용 구조를 공개 비판할 만큼, 비용 효율 논의가 활발하다.
그 맥락에서 Claude Code가 어디 위치하는지 짚어본다.
| 상황 | 추천 도구 | 이유 |
|---|---|---|
| 터미널 친숙한 개발자, 대형 리팩토링 | Claude Code | 파일 직접 수정, 프로젝트 전체 맥락 |
| IDE 떠나기 싫은 개발자 | Cursor | IDE 내 통합 경험 |
| 가볍게 코드 완성만 필요 | Copilot | 비용 저렴, 빠른 응답 |
| 오픈소스 코드베이스, 로컬 실행 | Continue.dev + 로컬 모델 | 보안·비용 이슈 없음 |
| 복잡한 멀티파일 리팩토링 | Claude Code | 에이전트 루프 처리 강점 |
하나만 골라야 한다면, 여름 사이드 프로젝트처럼 "새 기능을 빠르게 쌓아가는" 작업엔 Claude Code가 낫다.
반면 레거시 코드 유지보수처럼 "조심스럽게 건드려야 하는" 작업엔 Cursor나 Copilot이 심리적 부담이 덜하다.
Claude Code는 "빠르게 쌓는" 프로젝트에 강하다. 모든 상황에서 Claude Code가 정답은 아니다. 작업 성격에 따라 도구를 바꾸는 게 맞다.
FAQ
Q. Claude Code는 무료로 쓸 수 있나?
Claude Pro 구독($20/월)이 있으면 별도 비용 없이 쓸 수 있다. 단, Pro 플랜 내 사용량 한도 내에서만 무료다. 한도를 넘으면 API 키 방식으로 전환해야 하고, 토큰당 과금이 시작된다.
Q. Windows에서도 되나?
된다. WSL2(Windows Subsystem for Linux) 환경에서 쓰는 걸 추천한다. PowerShell 기반 native 환경에서도 작동하지만, Node.js와 npm이 설치돼 있어야 한다.
Q. 회사 코드베이스에 써도 괜찮나?
Anthropic은 API를 통한 데이터를 학습에 사용하지 않는다고 밝히고 있다. 하지만 코드가 서버를 거쳐 처리되는 건 맞다. 사내 보안 정책이 있는 회사라면 법무/보안팀 확인 먼저가 맞다. 민감한 프로젝트라면 로컬 모델 쪽을 보는 게 낫다.
Q. Claude Code가 파일을 잘못 수정하면 어떻게 되나?
기본적으로 파일 수정 전에 권한 확인 프롬프트가 뜬다. 여기서 거절하면 수정이 일어나지 않는다. --dangerously-skip-permissions 옵션을 쓰면 이 확인 과정이 없어진다. 이 옵션은 Docker 같은 격리 환경에서만 쓰는 걸 권장한다.
Q. 한국어 지시도 잘 알아듣나?
잘 알아듣는다. 다만 코드 관련 기술 용어는 영어로 섞어 쓰는 게 오해가 줄어든다. "TypeScript any 타입 없애줘" 처럼 기술 스펙은 영어, 지시 문장은 한국어로 섞어 쓰면 된다.
Q. 긴 프로젝트에서 맥락을 어떻게 유지하나?
CLAUDE.md에 핵심 규칙을 써두는 게 기본이다. 그리고 세션이 1시간 이상 길어지면 /compact 명령어로 컨텍스트를 요약한다. 작업 단위를 잘게 나눠서 세션을 자주 시작하는 것도 방법이다.
마무리
Claude Code는 설정 5분, CLAUDE.md 작성 10분으로 세팅이 끝난다.
여름 사이드 프로젝트 하나를 빠르게 치고 나가기에 지금이 딱 좋은 시점이다.
지금 터미널 열고 npm install -g @anthropic-ai/claude-code 부터 실행해보자. CLAUDE.md 없이 쓰면 절반짜리다.
