Claude Code 실전 활용법 (초급자용)

AI 코딩 도구를 제대로 활용하고 싶다면? 이 가이드 하나면 충분합니다.

🎯 이 가이드를 읽어야 하는 이유

Claude Code를 사용하다가 이런 경험 있으신가요?

• "처음엔 잘 되다가 갑자기 이상한 코드를 만들어요"
• "내가 원하는 게 아닌데 계속 엉뚱한 걸 만들어요"
• "코드가 너무 복잡해서 뭐가 뭔지 모르겠어요"

이런 문제들은 대부분 사용법의 문제입니다. Claude Code를 제대로 활용하는 방법을 알면 이런 문제를 90% 이상 해결할 수 있습니다.

---

1. 가장 중요한 3가지 원칙

원칙 1: 컨텍스트 관리가 전부다

컨텍스트란 Claude가 기억하고 있는 대화 내용을 말합니다. 컨텍스트가 너무 많아지면 Claude의 성능이 급격히 떨어집니다.

🔴 나쁜 예:

계속 대화를 이어가면서 코드를 수정하고, 또 수정하고...
→ 결국 Claude가 헷갈려서 이상한 코드를 만듭니다

🟢 좋은 예:

60,000 토큰 정도 사용했으면 /clear 명령어로 대화를 초기화
→ 항상 깨끗한 상태에서 시작

실전 팁:

• 대화 창에서 토큰 사용량을 자주 확인하세요
• 전체의 30%쯤 사용했다면 /clear로 초기화하세요
• 작업 중요한 내용은 파일로 저장한 후 초기화하세요

원칙 2: 계획 없이 코딩하지 말 것

🔴 나쁜 예:

"로그인 기능 만들어줘"
→ Claude가 막 만들기 시작 → 중간에 요구사항 변경 → 코드 엉망

🟢 좋은 예:

1단계: "로그인 기능 계획을 세워줘"
2단계: 계획 검토하고 수정
3단계: "이 계획대로 구현해줘"

원칙 3: 단순함이 최고다

복잡한 설정, 많은 플러그인보다는 단순하고 명확한 지시가 훨씬 효과적입니다.

---

2. 바로 시작하기: 필수 설정

2-1. CLAUDE.md 파일 만들기

프로젝트 최상위 폴더에 CLAUDE.md 파일을 만드세요. 이 파일은 Claude에게 주는 프로젝트 설명서입니다.

📝 기본 템플릿:

# 프로젝트 개요
이 프로젝트는 간단한 할일 관리 웹앱입니다.

## 기술 스택
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- Styling: Tailwind CSS

## 프로젝트 구조

src/ components/ # React 컴포넌트 pages/ # 페이지 파일 api/ # API 엔드포인트 utils/ # 유틸리티 함수

## 중요한 규칙
1. 모든 컴포넌트는 TypeScript로 작성
2. API 호출은 반드시 try-catch로 에러 처리
3. 스타일링은 Tailwind 유틸리티 클래스 사용

## 자주 쓰는 명령어
```bash
npm run dev      # 개발 서버 시작
npm run test     # 테스트 실행
npm run build    # 프로덕션 빌드

Claude가 자주 틀리는 것들

• ❌ 클래스 컴포넌트 사용하지 말 것 → ✅ 함수형 컴포넌트만 사용
• ❌ any 타입 사용 금지 → ✅ 정확한 타입 지정

**⚠️ 주의사항:**
- 100-200줄을 넘기지 마세요
- 너무 자세한 설명보다는 **핵심만** 적으세요
- Claude가 자주 틀리는 부분을 발견할 때마다 추가하세요

### 2-2. 기본 명령어 익히기

Claude Code에서 자주 쓰는 슬래시 명령어들:

| 명령어 | 설명 | 사용 예시 |
|--------|------|-----------|
| `/clear` | 대화 초기화 | 토큰 많이 썼을 때 |
| `/catchup` | 변경된 파일 읽기 | 다른 브랜치에서 작업 후 |
| `/dev-docs` | 개발 계획서 작성 | 새 기능 시작할 때 |

---

## 3. 올바른 작업 순서

### 3-1. 탐색 → 계획 → 코딩 → 커밋

이 순서를 **반드시** 지키세요. 이것만 지켜도 실패 확률이 90% 줄어듭니다.

#### **1단계: 탐색 (Explore)**

"src/components 폴더의 구조를 파악해줘. 아직 코드 수정하지 말고 살펴보기만 해줘."

**왜 중요한가?**
- Claude가 프로젝트를 이해하지 못한 채 코딩하면 엉망이 됩니다
- 먼저 충분히 탐색하게 하세요

#### **2단계: 계획 (Plan)**

"로그인 페이지를 만들 계획을 세워줘. 다음 내용을 포함해서:

1. 필요한 컴포넌트 목록
2. API 엔드포인트
3. 상태 관리 방법
4. 테스트 전략"

**좋은 계획의 예:**

```markdown
## 로그인 페이지 구현 계획

### 1. 컴포넌트 구조
- LoginPage.tsx (메인 페이지)
- LoginForm.tsx (폼 컴포넌트)
- useAuth.ts (인증 훅)

### 2. API 엔드포인트
- POST /api/login
  - 입력: { email, password }
  - 출력: { token, user }

### 3. 상태 관리
- React Context로 인증 상태 관리
- localStorage에 토큰 저장

### 4. 테스트
- 로그인 성공 케이스
- 잘못된 비밀번호 케이스
- 네트워크 에러 케이스

3단계: 검토 및 수정

계획을 받았다면 반드시 검토하세요:

"이 계획에서 보안 관련 부분이 빠진 것 같아. 
다음을 추가해줘:
- 비밀번호 암호화
- JWT 토큰 만료 처리
- CSRF 방어"

4단계: 구현

"이제 계획대로 구현해줘. 
한 번에 다 하지 말고 컴포넌트 하나씩 만들어줘.
각 컴포넌트를 만들 때마다 테스트도 함께 작성해줘."

5단계: 테스트 및 커밋

"지금까지 작성한 코드의 테스트를 실행하고,
통과하면 의미있는 커밋 메시지와 함께 커밋해줘."

---

4. 실전 예제로 배우기

예제 1: 간단한 TODO 앱 만들기

초보자가 하는 방식 (나쁜 예):

사용자: "TODO 앱 만들어줘"
Claude: [바로 코드를 막 만들기 시작]
사용자: "아 그게 아니라 삭제 기능도 필요해"
Claude: [이미 만든 코드를 뜯어고침]
→ 결과: 엉망진창인 코드

올바른 방식 (좋은 예):

1단계: 명확한 요구사항 정리

"다음 기능이 있는 TODO 앱을 만들 계획을 세워줘:

기능:
- TODO 항목 추가
- TODO 항목 완료 표시
- TODO 항목 삭제
- 완료된 항목 필터링

기술:
- React + TypeScript
- 상태관리는 useState 사용
- Tailwind CSS로 스타일링
- 로컬스토리지에 데이터 저장

먼저 계획만 세워줘. 코드는 아직 작성하지 마."

2단계: Claude의 계획 검토

Claude가 제시한 계획을 읽고 피드백:

"좋아. 그런데 다음 사항을 추가해줘:
1. 각 TODO에 우선순위(높음/중간/낮음) 추가
2. 생성 날짜 표시
3. 빈 문자열 입력 방지

계획을 수정해서 다시 보여줘."

3단계: 단계별 구현

"좋아. 이제 다음 순서로 구현해줘:

1단계: 기본 컴포넌트 구조와 타입 정의만 먼저
2단계: TODO 추가 기능
3단계: 완료 표시 기능
4단계: 삭제 기능
5단계: 필터링 기능
6단계: 로컬스토리지 연동

각 단계마다 테스트 코드도 함께 작성해줘.
1단계부터 시작해줘."

4단계: 각 단계마다 확인

"1단계 코드를 실행해봤어. 잘 작동해.
이제 2단계 진행해줘."

예제 2: API 연동하기

시나리오: 날씨 정보를 가져오는 API 연동

🔴 초보자의 실수:

"날씨 API 연동해줘"
→ Claude가 막 만듦
→ 에러 처리가 없음
→ 로딩 상태 처리가 없음
→ 타입 정의가 엉망

🟢 올바른 방법:

"OpenWeatherMap API를 연동하려고 해.
다음 요구사항으로 계획을 세워줘:

API:
- endpoint: api.openweathermap.org/data/2.5/weather
- 필요 파라미터: q (도시명), appid (API 키)

요구사항:
1. 타입스크립트로 응답 타입 정의
2. 로딩 상태 처리
3. 에러 처리 (네트워크 에러, 404, 500 등)
4. 환경변수로 API 키 관리
5. React Query 사용

먼저 타입 정의부터 보여줘."

구현 예시:

// types.ts - 먼저 타입 정의
interface WeatherData {
  main: {
    temp: number;
    humidity: number;
  };
  weather: Array<{
    main: string;
    description: string;
  }>;
  name: string;
}

// api.ts - API 호출 함수
async function fetchWeather(city: string): Promise {
  const API_KEY = process.env.REACT_APP_WEATHER_API_KEY;
  
  if (!API_KEY) {
    throw new Error('API 키가 설정되지 않았습니다');
  }

  try {
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${API_KEY}`
    );
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('날씨 정보 가져오기 실패:', error);
    throw error;
  }
}

---

5. 자주하는 실수와 해결법

실수 1: 컨텍스트를 초기화하지 않음

증상:

• Claude가 점점 이상한 코드를 만듦
• 이전에 지시한 내용을 잊어버림
• 같은 질문에 다른 답변

해결법:

# 토큰 사용량 확인
/context

# 60,000 토큰 이상이면
/clear

# 중요한 내용은 파일로 저장 후 초기화

실수 2: 너무 막연한 지시

🔴 나쁜 예:

"회원가입 기능 만들어줘"

🟢 좋은 예:

"회원가입 기능을 만들어줘. 구체적인 요구사항은:

1. 입력 필드:
   - 이메일 (이메일 형식 검증)
   - 비밀번호 (최소 8자, 영문+숫자+특수문자)
   - 비밀번호 확인
   - 이름

2. 검증:
   - 실시간 입력 검증
   - 이메일 중복 체크
   - 비밀번호 일치 확인

3. UI:
   - Material-UI 사용
   - 에러 메시지는 필드 하단에 빨간색으로
   - 제출 버튼은 모든 필드가 유효할 때만 활성화

4. API:
   - POST /api/register
   - 성공시 자동 로그인 및 메인 페이지 이동
   - 실패시 에러 메시지 표시
"

실수 3: 테스트 없이 진행

문제:

• 나중에 버그가 발견되면 원인 파악이 어려움
• 수정할 때마다 다른 부분이 망가짐

해결법:

"방금 만든 컴포넌트의 테스트 코드를 작성해줘.
다음 케이스를 테스트해줘:

1. 정상적인 입력 케이스
2. 잘못된 입력 케이스
3. API 에러 케이스
4. 로딩 상태 테스트

Jest와 React Testing Library를 사용해줘."

실수 4: 한 번에 너무 많이 시키기

🔴 나쁜 예:

"로그인, 회원가입, 비밀번호 찾기, 
프로필 수정, 설정 페이지 다 만들어줘"

🟢 좋은 예:

"먼저 로그인 기능만 완성하자.
1. 로그인 폼 컴포넌트
2. API 연동
3. 테스트
하나씩 진행해줘."

---

6. 4주 학습 로드맵

1주차: 기초 다지기

목표: Claude Code의 기본 사용법 익히기

할 일:

1. ✅ 프로젝트에 CLAUDE.md 파일 만들기
2. ✅ 기본 슬래시 명령어 익히기 (/clear, /catchup)
3. ✅ "탐색 → 계획 → 코딩" 순서 연습
4. ✅ 간단한 컴포넌트 하나 만들어보기

연습 프로젝트:

• 카운터 앱 (증가/감소 버튼)
• 간단한 계산기

2주차: 제대로 된 개발

목표: 테스트와 품질 관리

할 일:

1. ✅ 테스트 먼저 작성하는 습관 들이기
2. ✅ 타입스크립트 에러 0개 유지
3. ✅ 의미있는 커밋 메시지 작성
4. ✅ 코드 리뷰 요청하기

연습 프로젝트:

• TODO 앱 (테스트 포함)
• 간단한 블로그 포스트 목록

3주차: 고급 기능

목표: 복잡한 기능 구현

할 일:

1. ✅ API 연동 마스터하기
2. ✅ 상태 관리 라이브러리 활용
3. ✅ 에러 처리 완벽하게 하기
4. ✅ 개발 문서 작성하기

연습 프로젝트:

• 날씨 앱 (실제 API 사용)
• 간단한 쇼핑몰 (제품 목록, 장바구니)

4주차: 최적화

목표: 효율적인 워크플로우 구축

할 일:

1. ✅ 자주 쓰는 패턴을 Skills로 만들기
2. ✅ 커스텀 슬래시 명령어 만들기
3. ✅ 프로젝트별 CLAUDE.md 최적화
4. ✅ 개인 개발 템플릿 만들기

---

7. 실전 팁 모음

💡 팁 1: 스크린샷 활용하기

UI 작업할 때는 말보다 이미지가 백배 효과적:

[스크린샷 첨부]
"이 디자인과 똑같이 만들어줘.
- 레이아웃은 Flexbox 사용
- 색상은 이미지의 색상 그대로
- 폰트는 Pretendard 사용"

💡 팁 2: ESC 키 활용

Claude가 잘못된 방향으로 가고 있다면:

1. ESC 키 한 번: 작업 중단, 다른 방향 제시
2. ESC 키 두 번: 이전 메시지로 돌아가서 수정

💡 팁 3: 되돌리기 요청

"방금 만든 코드를 되돌려줘.
대신 다른 방법으로 접근해보자:
[새로운 접근 방법 설명]"

💡 팁 4: 깃 브랜치 활용

"feature/login-page 브랜치를 만들고
그곳에서 작업해줘"

여러 기능을 동시에 개발할 수 있습니다.

---

8. 체크리스트

코딩 시작 전에 확인하세요:

📋 프로젝트 시작 전

• [ ] CLAUDE.md 파일이 있나요?
• [ ] 기술 스택이 명확한가요?
• [ ] 프로젝트 구조를 Claude에게 설명했나요?

📋 기능 개발 전

• [ ] 요구사항이 명확한가요?
• [ ] 계획을 먼저 세웠나요?
• [ ] 계획을 검토했나요?

📋 코드 작성 후

• [ ] 테스트를 작성했나요?
• [ ] 타입 에러가 없나요?
• [ ] 에러 처리를 했나요?
• [ ] 코드를 리뷰했나요?
• [ ] 의미있는 커밋 메시지를 작성했나요?

---

9. 자주 묻는 질문 (FAQ)

Q1. Claude Code는 무료인가요?

A: Claude Code 자체는 Anthropic의 Claude API를 사용하므로 API 사용료가 발생합니다. 하지만 claude.ai 웹 인터페이스는 무료 플랜과 유료 플랜이 있습니다.

Q2. CLAUDE.md는 꼭 만들어야 하나요?

A: 필수는 아니지만 강력히 추천합니다. CLAUDE.md가 없으면 매번 프로젝트 설명을 반복해야 합니다.

Q3. 토큰이 뭔가요?

A: AI가 텍스트를 이해하는 단위입니다. 대략 한글 1자 = 2-3 토큰 정도로 생각하면 됩니다.

Q4. 언제 /clear를 해야 하나요?

A:

• 토큰 사용량이 60,000 이상일 때
• Claude가 이상한 답변을 하기 시작할 때
• 새로운 기능을 시작할 때

Q5. 에러가 계속 발생하면?

A:

1. 먼저 /clear로 초기화
2. 에러 메시지 전체를 복사해서 Claude에게 보여주기
3. 관련 코드 파일도 함께 제공
4. "단계별로 디버깅해줘"라고 요청

---

10. 마무리

Claude Code는 강력한 도구지만, 올바른 사용법을 알아야 제대로 활용할 수 있습니다.

핵심 3가지만 기억하세요:

1. 🎯 컨텍스트 관리 - 자주 초기화하고 깔끔하게 유지
2. 📝 계획 먼저 - 코딩 전에 항상 계획을 세우기
3. 🎨 단순하게 - 복잡한 설정보다 명확한 지시

이 가이드의 방법들을 하나씩 적용해보세요. 처음엔 번거로워 보이지만, 익숙해지면 개발 속도와 코드 품질이 크게 향상될 것입니다.

시작은 작게, 습관은 크게! 🚀

---

📚 더 배우고 싶다면

• Claude 공식 문서
• Claude Code 공식 가이드

---