Claude Code 실전 사용 가이드 - 터미널에서 만나는 AI 코딩 파트너

Claude Code가 뭔가요?

안녕하세요! 오늘은 요즘 개발자들 사이에서 화제인 Claude Code에 대해 이야기해보려고 해요. “AI가 코드를 짜준다”는 건 이제 익숙하시죠? 그런데 Claude Code는 좀 다릅니다.

Claude Code는 Anthropic에서 만든 터미널 기반 AI 코딩 도구예요. VS Code나 다른 IDE의 확장 프로그램이 아니라, 터미널에서 직접 작동하는 명령줄 도구입니다.

왜 굳이 터미널일까요? Anthropic 개발자들이 사용하는 에디터가 너무 다양해서 모두가 쓸 수 있는 방법을 찾다 보니 CLI가 되었다고 해요. 그리고 더 중요한 이유는 AI 모델이 너무 빠르게 발전해서, 곧 별도의 코드 에디터조차 필요 없어질 거라는 판단 때문이었대요.

놀랍죠? 😮

설치부터 시작해볼까요?

필요한 것

Node.js 18 이상
Claude Pro 또는 Max 플랜 구독 (또는 API 계정)

설치 방법

터미널을 열고 다음 명령어를 입력하세요:

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

설치가 끝나면 버전을 확인해보세요:

claude --version

첫 실행

프로젝트 폴더로 이동한 후:

cd your-project
claude

처음 실행하면 로그인하라는 메시지가 나타나요. Claude 계정으로 로그인하면 됩니다!

실전 사용법: 이렇게 쓰면 됩니다

1. 코드베이스 질문하기

새로운 프로젝트에 투입되었을 때 가장 먼저 해야 할 일은 코드 파악이죠. Claude Code에게 물어보세요!

claude
> 이 프로젝트의 인증 시스템은 어떻게 작동하나요?
> 결제 모듈은 어디에 있나요?
> 이 함수가 왜 15개의 인수를 받나요?

Anthropic에서는 신입 사원 온보딩이 2-3주에서 2-3일로 단축되었다고 해요!

2. 버그 수정

에러 메시지를 그대로 붙여넣으면 됩니다:

> TypeError: Cannot read property 'user' of undefined 이 에러 고쳐줘

Claude Code가 코드베이스를 분석하고, 문제를 식별하며, 수정 사항을 구현합니다.

3. 새 기능 구현

> OAuth2 인증 시스템을 구현해줘. Google과 GitHub 로그인을 지원해야 해.

Claude는 파일을 직접 편집하고, 명령을 실행하며, 커밋까지 생성할 수 있어요.

4. 자동 커밋

claude commit

변경 사항을 자동으로 분석해서 의미있는 커밋 메시지와 함께 커밋해줍니다!

작업 모드 이해하기

Claude Code에는 세 가지 작업 모드가 있어요. Shift+Tab으로 전환할 수 있습니다:

일반 모드 (Normal): 각 작업마다 승인 필요 (기본값)
계획 모드 (Plan): Claude가 먼저 계획을 설명하고 승인을 기다림
자동 수락 모드 (Auto Accept): 모든 작업을 자동으로 수락

초보자는 일반 모드로 시작하는 걸 추천해요!

고급 기능들

MCP (Model Context Protocol) 연동

MCP를 통해 Claude가 Google Drive의 설계 문서를 읽고, Jira 티켓을 업데이트하거나, PostgreSQL 데이터베이스에 접근할 수 있어요.

# PostgreSQL 서버 추가
claude mcp add postgres-server /path/to/postgres-mcp-server \
  --connection-string "postgresql://user:pass@localhost:5432/mydb"

# 데이터베이스 질문하기
> users 테이블의 스키마를 설명해줘
> 가장 최근 주문을 보여줘

이미지 기반 개발

놀랍게도 터미널 도구인데 이미지를 입력할 수 있어요! 디자인 목업을 드래그 앤 드롭하면:

> 이 디자인대로 UI를 만들어줘

Puppeteer 서버와 연동하면 웹 UI를 자동으로 구현하고, 반복을 통해 거의 완벽한 결과물을 만들어낼 수 있습니다.

커스텀 명령어

자주 쓰는 작업을 슬래시 명령어로 만들 수 있어요:

# .claude/commands 디렉토리 생성
mkdir -p .claude/commands

# 최적화 명령어 만들기
echo "이 코드의 성능을 분석하고 최적화를 제안해줘" \
  > .claude/commands/optimize.md

이제 /optimize만 입력하면 됩니다!

Claude Code의 장점

1. 어떤 환경에서든 작동

VS Code, Xcode, JetBrains, Vim, Emacs 등 어떤 IDE를 쓰든 상관없어요. 로컬 환경, 원격 SSH, 모든 터미널 환경에서 작동합니다.

2. 보안과 프라이버시

Claude Code는 코드 인덱싱을 하지 않으며, 원격 데이터베이스에 코드를 업로드하지 않고, 사용자 코드로 모델을 훈련하지 않습니다. 코드는 로컬에 안전하게 보관되며, 쿼리가 중간 서버 없이 Anthropic의 API로 직접 전송됩니다.

3. 전체 프로젝트 컨텍스트

별도의 인덱싱이나 대기 시간 없이 바로 전체 코드베이스를 이해합니다.

4. 실제 작업 수행

단순히 제안만 하는 게 아니라 파일을 직접 편집하고, 테스트를 실행하고, 커밋을 생성합니다.

Claude Code의 단점과 주의사항

1. 토큰 사용량

Pro 플랜으로는 약 10-40개의 프롬프트를 보낼 수 있어요. 코드베이스 크기와 자동 수락 모드 같은 설정에 따라 달라집니다. 큰 프로젝트에서는 사용량 제한에 빨리 도달할 수 있어요.

Flutter 앱처럼 컨텍스트가 긴 프로젝트는 1-2시간 만에 rate limit에 걸릴 수 있습니다.

2. 작은 프로젝트에 최적화

Pro 플랜은 소규모 저장소(일반적으로 1,000줄 미만의 코드)에서의 가벼운 작업에 최적입니다.

대규모 프로젝트는 Max 플랜이나 API 종량제를 고려하세요.

3. 실수 가능성

AI도 실수를 해요! 항상 변경 사항을 확인하고, 중요한 작업 전에는 Git 커밋을 만들어두세요.

더 안전한 방법은 Claude Code에게 변경사항을 만들 때마다 커밋하도록 요청하는 것입니다.

> 변경할 때마다 커밋해줘

4. 학습 곡선

처음엔 “뭘 어떻게 시켜야 하지?” 막막할 수 있어요. 작은 작업부터 시작하면서 익히세요.

어떤 스킬이 향상될까?

1. 코드 리딩 능력

복잡한 코드베이스를 Claude에게 물어보면서 빠르게 이해할 수 있어요. “이 함수는 왜 이렇게 작동하나요?”

2. 디버깅 스킬

에러를 해결하는 과정을 관찰하면서 디버깅 방법을 배울 수 있습니다.

3. 베스트 프랙티스

Claude가 제안하는 코드를 보면서 좋은 코딩 패턴을 익힐 수 있어요.

4. 생산성 향상

지루한 작업을 자동화할 수 있어요. 린트 문제 해결, 병합 충돌 해결, 릴리스 노트 작성 등.

실전 팁

1. CLAUDE.md 파일 만들기

프로젝트의 중요한 정보, 규칙, 자주 사용되는 명령을 저장하세요.

claude init

이 파일에 프로젝트 설명, 빌드 명령어, 코딩 컨벤션 등을 적어두면 Claude가 참고합니다!

2. 검증 도구 제공

Claude Code가 스스로 작업을 검증할 수 있는 방법을 제공하면 결과물의 품질이 비약적으로 향상됩니다. 유닛 테스트, 스크린샷 등을 통해 Claude가 결과물을 확인하고 반복적으로 개선할 수 있게 하세요.

3. 작은 작업 단위로

한 번에 너무 많은 걸 시키지 마세요. 작은 단위로 나눠서 하나씩 완성하는 게 좋아요.

4. Git Worktree 활용

여러 작업을 동시에 수행해야 할 때는 Git worktree를 사용하세요. 완전히 격리된 환경에서 각각의 Claude Code 세션을 실행할 수 있습니다.

요금제 선택하기

Claude Code는 Pro 플랜($20/월)과 Max 플랜에서 사용 가능해요. 하나의 구독으로 웹/앱의 Claude와 터미널의 Claude Code를 모두 사용할 수 있습니다.

Pro 플랜: 소규모 프로젝트, 가벼운 코딩
Max 플랜: 대규모 프로젝트, 집중적인 사용
API 종량제: 무제한 사용이 필요한 경우

마무리하며

Claude Code는 단순한 코드 완성 도구가 아니에요. 프로젝트를 이해하고, 버그를 수정하고, 테스트를 작성하고, Git 커밋까지 하는 진짜 AI 개발 파트너입니다.

처음엔 “AI한테 이걸 맡겨도 되나?” 고민될 수 있어요. 하지만 써보면 알아요. 정말 생산성이 몇 배로 올라갑니다.

시작 방법:

작은 프로젝트로 연습
간단한 질문부터 시작
점차 복잡한 작업 시도
항상 결과를 검토

AI와 함께 코딩하는 시대, Claude Code로 시작해보세요!

다음에는 더 유용한 IT 팁으로 찾아올게요. 읽어주셔서 감사합니다!