Claude Code란?
Claude Code는 Anthropic에서 만든 CLI 기반 AI 코딩 도구다. 터미널에서 직접 실행되며, 프로젝트의 코드를 읽고, 수정하고, 명령어를 실행할 수 있는 에이전트형 도구다.
GitHub Copilot이 자동완성에 특화되어 있다면, Claude Code는 대화형으로 복잡한 작업을 통째로 맡길 수 있다는 점이 다르다.
주요 특징
| 특징 | 설명 |
|---|---|
| 터미널 네이티브 | IDE에 종속되지 않고 CLI에서 바로 동작 |
| 코드베이스 인식 | 프로젝트 전체 파일을 읽고 맥락을 파악 |
| 파일 수정 | 직접 코드를 생성/수정/삭제 가능 |
| 명령어 실행 | 빌드, 테스트, git 등 쉘 명령 실행 가능 |
| VSCode 연동 | 확장 프로그램으로 에디터 내에서도 사용 가능 |
설치 및 시작
1. 설치
1
npm install -g @anthropic-ai/claude-code
2. 실행
프로젝트 디렉토리에서 바로 실행하면 된다.
1
2
cd my-project
claude
처음 실행 시 Anthropic 계정 인증을 거치면 바로 사용 가능하다.
3. VSCode 확장
VSCode Marketplace에서 “Claude Code”를 검색해 설치하면 에디터 내에서도 동일한 기능을 쓸 수 있다. 터미널과 에디터 양쪽에서 자유롭게 사용할 수 있다는 점이 장점이다.
실전 활용 사례
사례 1: 버그 수정
단순히 에러 메시지를 붙여넣으면 알아서 원인을 파악하고 수정해준다.
1
2
> 현재 앱에서 다음 에러가 발생해:
PrismaClientKnownRequestError: Invalid `this.db.todo.findMany()` invocation
Claude Code는 관련 파일을 찾아 읽고, Prisma 스키마와 마이그레이션 상태를 확인한 뒤, 해결 방법을 제안하거나 직접 코드를 수정한다.
사례 2: 새로운 기능 구현
기능을 자연어로 설명하면 계획을 세우고 단계별로 구현한다.
1
2
> Todo 앱에 우선순위 기능을 추가해줘.
HIGH, MEDIUM, LOW 3단계로 나누고 필터링도 되게 해줘.
이렇게 요청하면:
- Prisma 스키마에
priority필드 추가 - API 엔드포인트 수정
- 프론트엔드 UI에 필터 컴포넌트 추가
- 마이그레이션 실행
까지 전 과정을 처리한다.
사례 3: 코드 리뷰 & 리팩토링
1
> 이 파일 코드 리뷰해줘. 개선할 점 알려줘.
함수 분리, 에러 처리 누락, 네이밍 개선, 성능 이슈 등을 짚어주고, 원하면 바로 수정까지 해준다.
사례 4: 인프라 & DevOps
1
> docker-compose.yml 만들어줘. PostgreSQL + Redis + 앱 서버 구성으로.
Docker 설정, 환경변수 구성, 볼륨 매핑 등 인프라 작업도 가능하다.
효과적으로 사용하는 팁
1. 맥락을 충분히 제공하라
1
2
3
4
5
6
7
# 나쁜 예
> 버그 고쳐줘
# 좋은 예
> 로그인 페이지에서 이메일 입력 후 제출하면 500 에러가 발생해.
콘솔에 "Cannot read property 'id' of undefined" 에러가 뜨고,
auth.service.ts의 login 메서드에서 문제가 있는 것 같아.
구체적인 에러 메시지, 파일 위치, 재현 조건을 알려줄수록 정확한 결과를 얻는다.
2. 단계별로 확인하며 진행하라
한번에 모든 것을 맡기기보다, 중간중간 결과를 확인하는 게 좋다.
1
> 먼저 계획만 세워줘. 코드는 아직 수정하지 마.
계획을 확인한 후에 실행을 지시하면 의도하지 않은 변경을 방지할 수 있다.
3. CLAUDE.md로 프로젝트 규칙 설정
프로젝트 루트에 CLAUDE.md 파일을 만들면 Claude Code가 매 세션마다 자동으로 읽는다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# CLAUDE.md
## 프로젝트 개요
Next.js 14 + Prisma + PostgreSQL 기반 Todo 앱
## 코딩 컨벤션
- 함수형 컴포넌트만 사용
- TypeScript strict 모드
- 에러 처리 필수
## 빌드 & 테스트
- `pnpm dev` : 개발 서버
- `pnpm test` : 테스트 실행
- `pnpm build` : 프로덕션 빌드
이렇게 해두면 매번 프로젝트 설명을 하지 않아도 된다.
4. 슬래시 명령어 활용
자주 쓰는 내장 명령어들이 있다.
| 명령어 | 설명 |
|---|---|
/help | 도움말 |
/clear | 대화 초기화 |
/compact | 컨텍스트 요약 압축 |
/cost | 현재 세션 비용 확인 |
GitHub Copilot과의 차이점
| 항목 | GitHub Copilot | Claude Code |
|---|---|---|
| 동작 방식 | 인라인 자동완성 | 대화형 에이전트 |
| 작업 범위 | 현재 파일 중심 | 프로젝트 전체 |
| 파일 수정 | 제안만 | 직접 수정 가능 |
| 명령어 실행 | 불가 | 가능 (빌드, 테스트, git 등) |
| 적합한 상황 | 코드 작성 보조 | 복잡한 작업 위임 |
둘은 경쟁 관계라기보다 보완 관계다. Copilot으로 빠르게 코드를 치고, 복잡한 리팩토링이나 디버깅은 Claude Code에 맡기는 조합이 효과적이다.
주의할 점
- 항상 코드를 검토하라 — AI가 생성한 코드를 무조건 신뢰하지 말고, git diff로 변경사항을 확인하자.
- 민감 정보 주의 — API 키나 비밀번호가 포함된 파일을 다룰 때 주의가 필요하다.
- 비용 관리 — API 호출 기반이므로
/cost로 사용량을 확인하는 습관을 들이자. - git 커밋 습관 — 큰 변경 전에 커밋해두면 문제가 생겨도 쉽게 되돌릴 수 있다.
마무리
Claude Code를 한 달 정도 써본 체감은, 반복적이고 지루한 작업에서 확실히 생산성이 올라간다는 것이다. 보일러플레이트 생성, 에러 디버깅, 설정 파일 작성 같은 작업은 확실히 빨라진다.
다만 AI 도구는 어디까지나 도구다. 코드의 품질과 방향은 결국 개발자가 판단해야 한다. AI가 만든 코드를 이해하고 검증할 수 있는 실력이 전제되어야 제대로 활용할 수 있다.
다음 포스팅에서는 Claude Code를 활용해 실제 프로젝트를 처음부터 만드는 과정을 다뤄볼 예정이다.