자주 묻는 질문 (FAQ)

Q1. Claude와 ChatGPT의 차이점은 무엇인가요?

A: Claude는 Anthropic이 개발한 AI 어시스턴트로, 다음과 같은 특징이 있습니다:

• 긴 컨텍스트 윈도우: 긴 문서/대화 처리를 위한 넓은 입력 범위
• 안전성 중심 설계: 안전을 고려한 정책과 가드레일
• 정확한 지시 따르기: 복잡한 구조화된 출력에 강점
• 코드 생성 능력: 코드 품질과 지시 준수에 강점
• 최신 지식: 모델/버전에 따라 범위가 다르므로 공식 문서 확인

Q2. 어떤 모델을 선택해야 하나요?

A: 사용 사례에 따라 선택하세요:

• 고성능 티어: 복잡한 분석, 고급 추론, 연구 작업
• 균형 티어: 대부분의 일반적인 사용 사례와 코딩
• 경량 티어: 빠른 응답, 간단한 작업, 대량 처리

대부분의 경우 균형 티어로 시작하고, 필요에 따라 조정하는 것을 권장합니다.

Q3. 비용이 얼마나 드나요?

A: 토큰 사용량에 따라 과금됩니다:

요금은 입력/출력 토큰, 선택한 티어, 캐싱 사용 여부에 따라 달라집니다. 최신 요금표는 공식 문서를 확인하세요.

Q4. API 키는 어떻게 발급받나요?

A: 다음 단계를 따르세요:

1. Anthropic Console 방문
2. 계정 생성 또는 로그인
3. Settings → API Keys 메뉴 선택
4. "Create Key" 버튼 클릭
5. 키 이름 입력 후 생성
6. 표시된 키를 안전한 곳에 저장 (재확인 불가)

주의: API 키는 한 번만 표시되므로 반드시 저장하세요. 노출되면 즉시 삭제하고 재발급받으세요.

Q5. 무료 체험이 가능한가요?

A: Anthropic은 신규 가입자에게 초기 크레딧을 제공합니다. Claude.ai 웹 인터페이스는 무료 플랜(Pro 플랜도 있음)이 있지만, API는 사용량에 따라 과금됩니다. 테스트 목적으로는 Haiku 모델을 사용하면 비용을 최소화할 수 있습니다.

Q6. 컨텍스트 윈도우가 200K 토큰인데, 실제로는 더 적게 사용되는 것 같아요.

A: 몇 가지 이유가 있습니다:

• 출력 토큰 제한: 최대 출력은 모델에 따라 4K-8K 토큰으로 제한됩니다.
• 시스템 프롬프트: 시스템 프롬프트도 컨텍스트에 포함됩니다.
• 토큰 계산 방식: 실제 텍스트 길이와 토큰 수는 다릅니다.

# 토큰 수 계산 예시 (Python SDK)
import anthropic

client = anthropic.Anthropic(api_key="your-api-key")
token_count = client.count_tokens("Hello, Claude!")
print(f"토큰 수: {token_count}")  # 3-4 토큰

Q7. 스트리밍 응답을 사용해야 하나요?

A: 사용자 경험을 개선하려면 스트리밍을 권장합니다:

• 장점: 실시간 피드백, 긴 응답에서 빠른 첫 토큰, 사용자 대기 시간 단축
• 단점: 구현 복잡도 증가, 에러 핸들링 어려움
• 권장 사용: 챗봇, 대화형 UI, 긴 텍스트 생성
• 불필요한 경우: 배치 처리, 자동화 스크립트, 구조화된 데이터 추출

# Python 스트리밍 예시
with client.messages.stream(
    model="claude-",
    max_tokens=1024,
    messages=[{"role": "user", "content": "긴 이야기를 써주세요"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Q8. JSON 형식으로 응답을 받고 싶어요. JSON 모드가 있나요?

A: Claude API에는 별도의 JSON 모드가 없지만, 프롬프트로 구조화된 출력을 얻을 수 있습니다:

system_prompt = """당신은 데이터를 JSON 형식으로 추출하는 어시스턴트입니다.
항상 유효한 JSON만 출력하세요. 추가 설명이나 마크다운은 포함하지 마세요.

출력 형식:
{
  "name": "문자열",
  "age": 숫자,
  "email": "문자열"
}"""

response = client.messages.create(
    model="claude-",
    max_tokens=1024,
    system=system_prompt,
    messages=[{
        "role": "user",
        "content": "이름: 홍길동, 나이: 30세, 연락처: hong@example.com"
    }]
)

import json
data = json.loads(response.content[0].text)

팁: 더 안정적인 파싱을 위해 XML 태그나 Pydantic 모델을 사용할 수도 있습니다.

Q9. Tool Use와 Function Calling의 차이점은?

A: 같은 개념입니다. Anthropic은 "Tool Use"라는 용어를 사용하고, OpenAI는 "Function Calling"이라고 부릅니다. Claude의 Tool Use는:

• 외부 API 호출 (검색, 데이터베이스 쿼리)
• 계산 수행 (수학, 데이터 처리)
• 파일 시스템 작업

등의 작업을 Claude가 요청할 수 있게 합니다. 실제 실행은 개발자가 처리합니다.

tools = [{
    "name": "get_weather",
    "description": "특정 도시의 현재 날씨를 가져옵니다",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "도시 이름"}
        },
        "required": ["city"]
    }
}]

response = client.messages.create(
    model="claude-",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "서울 날씨 알려줘"}]
)

if response.stop_reason == "tool_use":
    # tool_use 블록 처리
    tool_use_block = next(b for b in response.content if b.type == "tool_use")
    print(tool_use_block.name)  # "get_weather"
    print(tool_use_block.input)  # {"city": "서울"}

Q10. 이미지 분석은 어떻게 하나요?

A: Vision API를 사용하여 이미지를 전송합니다:

import base64

with open("image.jpg", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
    model="claude-",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/jpeg",
                    "data": image_data
                }
            },
            {"type": "text", "text": "이 이미지를 설명해주세요"}
        ]
    }]
)

print(response.content[0].text)

지원 형식: JPEG, PNG, GIF, WebP (최대 5MB)

Q11. 429 Rate Limit Error가 계속 발생해요.

A: Rate Limit을 초과했습니다. 다음 방법으로 해결하세요:

1. 지수 백오프 재시도 구현:

import time
import random

def call_with_retry(max_retries=5):
    for attempt in range(max_retries):
        try:
            response = client.messages.create(
                model="claude-",
                max_tokens=1024,
                messages=[{"role": "user", "content": "Hello"}]
            )
            return response
        except anthropic.RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait_time)

2. 티어 확인 및 업그레이드:

• Build Tier: 50 RPM, 40K TPM, 400K TPD
• Scale Tier: 1000 RPM, 80K TPM, 2.5M TPD (구매액 증가 시 자동 상승)

3. 요청 분산:

• 배치 처리 시 요청 간 딜레이 추가
• 동시 요청 수 제한
• 비동기 처리 활용

Q12. 응답이 너무 느려요.

A: 성능 최적화 체크리스트:

1. 적절한 모델 선택:

• Haiku: 가장 빠름 (~1-3초)
• Sonnet: 중간 (~3-8초)
• Opus: 가장 느림 (~10-20초)

2. max_tokens 조정:

# 너무 큰 max_tokens는 응답 시간을 늘립니다
response = client.messages.create(
    model="claude-",
    max_tokens=500,  # 필요한 만큼만 설정
    messages=[{"role": "user", "content": "간단히 답해줘"}]
)

3. Prompt Caching 활용:

system_prompt = [{
    "type": "text",
    "text": "[긴 시스템 프롬프트나 문서]",
    "cache_control": {"type": "ephemeral"}
}]

4. 컨텍스트 크기 줄이기:

• 불필요한 대화 히스토리 제거
• 긴 문서는 요약 후 전송
• 청킹 전략 사용

Q13. "Context length exceeded" 에러가 발생해요.

A: 입력 + 출력이 200K 토큰을 초과했습니다. 해결 방법:

1. 청킹 전략:

def chunk_text(text, chunk_size=100000):
    """텍스트를 청크로 분할"""
    words = text.split()
    chunks = []
    for i in range(0, len(words), chunk_size):
        chunk = " ".join(words[i:i+chunk_size])
        chunks.append(chunk)
    return chunks

def process_long_document(document):
    chunks = chunk_text(document)
    results = []

    for chunk in chunks:
        response = client.messages.create(
            model="claude-",
            max_tokens=2000,
            messages=[{
                "role": "user",
                "content": f"다음 텍스트를 요약하세요:\n\n{chunk}"
            }]
        )
        results.append(response.content[0].text)

    return results

2. 대화 히스토리 관리:

def truncate_history(messages, max_messages=10):
    """최근 N개 메시지만 유지"""
    return messages[-max_messages:]

def summarize_history(messages):
    """오래된 대화를 요약"""
    if len(messages) > 20:
        old_messages = messages[:-10]
        summary = client.messages.create(
            model="claude-",
            max_tokens=500,
            messages=[{
                "role": "user",
                "content": f"대화 요약:\n{old_messages}"
            }]
        )
        return [{"role": "assistant", "content": summary.content[0].text}] + messages[-10:]
    return messages

Q14. 같은 프롬프트인데 응답이 매번 달라요.

A: Claude는 생성형 AI이므로 결정론적이지 않습니다. 일관성을 높이려면:

1. temperature 조정:

response = client.messages.create(
    model="claude-",
    max_tokens=1024,
    temperature=0,  # 0에 가까울수록 일관성 증가 (기본값: 1)
    messages=[{"role": "user", "content": "2+2는?"}]
)

2. 구체적인 형식 지정:

system_prompt = """다음 형식으로만 답변하세요:

정답: [숫자]
설명: [한 문장]

다른 형식이나 추가 내용은 포함하지 마세요."""

3. Few-shot 예제 제공:

messages = [
    {"role": "user", "content": "긍정/부정: '이 제품 정말 좋아요!'"},
    {"role": "assistant", "content": "긍정"},
    {"role": "user", "content": "긍정/부정: '실망스러워요'"},
    {"role": "assistant", "content": "부정"},
    {"role": "user", "content": "긍정/부정: '배송이 빨라요'"}
]

Q15. API 키가 노출되었어요. 어떻게 해야 하나요?

A: 즉시 다음 조치를 취하세요:

1. 키 삭제: Anthropic Console에서 해당 키 즉시 삭제
2. 새 키 발급: 새 API 키 생성
3. 사용 내역 확인: 비정상적인 사용량 체크
4. 노출된 코드 수정: Git history에서 키 제거

   # Git history에서 민감한 정보 제거
   git filter-branch --force --index-filter \
     "git rm --cached --ignore-unmatch config.py" \
     --prune-empty --tag-name-filter cat -- --all

5. 향후 예방:
   • 환경 변수 사용 (ANTHROPIC_API_KEY)
   • .env 파일을 .gitignore에 추가
   • Secret manager 사용 (AWS Secrets Manager, GitHub Secrets)
   • 코드 리뷰 시 키 노출 여부 확인

Q16. Claude Code란 무엇인가요?

A: Claude Code는 Anthropic의 공식 CLI(Command Line Interface) 도구로, 터미널에서 Claude를 사용할 수 있게 해줍니다:

• 코드 생성 및 수정: 자연어로 코드 작성/리팩토링 요청
• 파일 읽기/쓰기: 프로젝트 파일 자동 분석 및 수정
• 명령어 실행: git, npm, pip 등 자동 실행
• 멀티파일 편집: 여러 파일을 동시에 수정
• 컨텍스트 인식: 전체 프로젝트 구조 이해

설치: npm install -g @anthropic-ai/claude-code

Q17. Claude Code와 Claude API의 차이는?

A:

• Claude API: HTTP 기반 프로그래밍 인터페이스, 애플리케이션에 통합
• Claude Code: 터미널 기반 대화형 도구, 개발자가 직접 사용

Q18. Claude Code가 내 파일을 마음대로 수정하지는 않나요?

A: 안전합니다. Claude Code는 다음과 같이 작동합니다:

• 명시적 권한: 파일 읽기/쓰기 전 사용자 승인 요청
• Diff 확인: 변경사항을 먼저 보여주고 승인 후 적용
• Git 통합: 변경사항은 Git으로 추적 가능
• 실행 확인: 명령어 실행 전 확인 프롬프트
• 읽기 전용 모드: --read-only 플래그로 쓰기 방지

권장 사항: 항상 Git을 사용하고, 중요한 변경 전에는 브랜치를 생성하세요.

Q19. Claude Code로 무엇을 할 수 있나요?

A: 다양한 개발 작업을 자동화할 수 있습니다:

코드 작성 및 수정:

$ claude "Python으로 FastAPI 서버 만들어줘"
$ claude "이 함수를 TypeScript로 변환해줘"
$ claude "main.py의 버그 찾아서 고쳐줘"

리팩토링:

$ claude "utils.py를 여러 모듈로 분리해줘"
$ claude "이 코드에 타입 힌트 추가해줘"

테스트 작성:

$ claude "auth.py에 대한 pytest 테스트 작성해줘"
$ claude "커버리지 90% 이상 달성하도록 테스트 추가해줘"

문서화:

$ claude "모든 함수에 docstring 추가해줘"
$ claude "README.md 작성해줘"

Git 작업:

$ claude "변경사항 커밋하고 의미있는 커밋 메시지 작성해줘"
$ claude "main 브랜치와 충돌 해결해줘"

Q20. Claude Code의 한계는 무엇인가요?

A: 다음과 같은 제약이 있습니다:

• 컨텍스트 제한: 매우 큰 프로젝트(수천 개 파일)는 처리가 어려울 수 있음
• 복잡한 리팩토링: 전체 아키텍처 변경은 사람의 감독이 필요
• 도메인 지식: 특정 비즈니스 로직은 명확한 설명이 필요
• 실시간 협업: 여러 개발자가 동시에 같은 파일 수정 시 충돌 가능
• 디버깅: 런타임 버그는 실행 환경 정보가 필요

권장: Claude Code는 보조 도구로 사용하고, 중요한 결정은 직접 검토하세요.

Q21. Vibe Coding이란 무엇인가요?

A: Vibe Coding은 자연어 대화로 코드를 작성하는 새로운 개발 패러다임입니다:

• 정의: 세부 구문이나 API를 암기하지 않고 "의도"만 전달하면 AI가 완전한 코드를 생성
• 배경: Anthropic이 Claude Opus (고성능) 출시와 함께 공식적으로 강조한 개념
• 핵심 특징: 낮은 진입장벽, 빠른 프로토타이핑, 맥락 이해, 반복 개선
• 지원 언어: Python, TypeScript, JavaScript, Rust, Go 등 모든 주요 프로그래밍 언어

예시:

# 전통적 코딩
1. Stack Overflow 검색 → API 문서 읽기 → 구문 학습 → 코드 작성 → 디버깅

# Vibe Coding
You: "FastAPI로 JWT 인증 시스템 만들어줘"
Claude: [완전한 코드 생성 + 설명]
You: "이제 리프레시 토큰 기능 추가해줘"
Claude: [기존 코드 개선]

자세한 내용은 Vibe Coding 가이드를 참조하세요.

Q22. Vibe Coding과 일반 프롬프팅의 차이는?

A: Vibe Coding은 프롬프팅을 넘어 전체 개발 워크플로우를 포함합니다:

핵심 차이: 일반 프롬프팅은 "코드 조각 요청"이고, Vibe Coding은 "AI와 협업하는 개발 방식"입니다.

Q23. Vibe Coding 사용 시 주의사항은?

A: 효과적인 Vibe Coding을 위한 권장 사항:

✅ DO (권장 사항):

• 구체적인 의도 전달: "사용자 인증" 대신 "JWT 기반 사용자 인증, 로그인/로그아웃 엔드포인트 포함"
• 맥락 제공: 프로젝트 구조, 기존 코딩 스타일, 사용 중인 프레임워크 언급
• 점진적 개선: 작은 기능부터 시작해서 대화로 확장
• 코드 리뷰: 생성된 코드를 항상 검토하고 이해하기
• Git 사용: 변경사항 추적 및 롤백 가능하도록 버전 관리

❌ DON'T (피해야 할 것):

• 맹목적 신뢰: 생성된 코드를 검증 없이 프로덕션에 배포
• 모호한 요청: "좋은 코드 만들어줘" 같은 불명확한 지시
• 보안 무시: API 키, 비밀번호 등 민감 정보를 프롬프트에 포함
• 복잡한 전체 시스템: 한 번에 대규모 아키텍처 변경 요청 (단계별로 진행)
• 디버깅 위임: 에러 메시지만 전달하고 컨텍스트 생략

예시 (좋은 Vibe Coding 요청):

"현재 Express.js 프로젝트에 Redis 캐싱 레이어를 추가하고 싶어.
- 모든 GET 요청은 5분간 캐싱
- POST/PUT/DELETE는 관련 캐시 무효화
- 환경 변수로 Redis 연결 설정
- 기존 코드 스타일(TypeScript, async/await) 유지"

Q24. Codex는 어떤 도구인가요?

A: Codex는 코딩 작업을 실행하고 변경 사항을 제안하는 코딩 에이전트입니다.

• 작업 범위 지정: 수정할 파일/폴더와 목표를 명확히 지정할수록 품질이 높습니다.
• 검증 흐름: 테스트 실행과 결과 확인을 함께 요청하는 것이 안전합니다.
• 보안: 민감한 작업은 승인 흐름과 권한 제한을 적용하세요.

자세한 내용은 Codex 가이드를 참조하세요.

Q25. 더 나은 응답을 받으려면 어떻게 프롬프트를 작성해야 하나요?

A: 효과적인 프롬프트 작성 팁:

1. 구체적으로 작성:

# 나쁜 예
"코드 작성해줘"

# 좋은 예
"Python FastAPI로 사용자 인증 API를 작성해줘.
JWT 토큰 사용, 로그인/로그아웃 엔드포인트 포함,
SQLAlchemy로 PostgreSQL 연결"

2. 형식 지정:

"다음 형식으로 답변해줘:
1. 요약 (3줄 이내)
2. 상세 설명
3. 코드 예제
4. 주의사항"

3. 컨텍스트 제공:

"Django REST Framework 프로젝트에서 사용자 모델을 확장하려고 합니다.
현재 AbstractUser를 상속받고 있고, 프로필 이미지와 생일 필드를 추가하고 싶습니다."

4. 단계별 요청:

"다음 순서로 작업해줘:
1. 먼저 requirements.txt 확인
2. 필요한 패키지 설치 명령어 제시
3. 코드 작성
4. 테스트 코드 작성"

5. 제약사항 명시:

"Python 3.8 호환, 외부 라이브러리 사용 금지,
타입 힌트 필수, 최대 100줄 이내"

Q26. 비용을 절감하려면 어떻게 해야 하나요?

A: 종합 비용 최적화 전략:

1. 적절한 모델 선택:

# 간단한 작업 → Haiku
response = client.messages.create(
    model="claude-",
    messages=[{"role": "user", "content": "감정 분석: 좋아요"}]
)

# 복잡한 작업 → Sonnet/Opus
response = client.messages.create(
    model="claude-",
    messages=[{"role": "user", "content": "복잡한 비즈니스 로직 분석"}]
)

2. max_tokens 최적화:

# 필요한 만큼만 요청
response = client.messages.create(
    model="claude-",
    max_tokens=100,  # 짧은 답변만 필요한 경우
    messages=[{"role": "user", "content": "YES 또는 NO로만 답해줘"}]
)

3. Prompt Caching 활용:

# 동일한 시스템 프롬프트/문서를 반복 사용 시
system = [{
    "type": "text",
    "text": large_document,
    "cache_control": {"type": "ephemeral"}
}]

# 첫 요청: 캐시 쓰기 비용
# 이후 요청: 90% 비용 절감

4. 컨텍스트 압축:

def compress_context(messages):
    # 오래된 메시지 요약
    if len(messages) > 10:
        old = messages[:-5]
        summary = summarize(old)  # Haiku 사용
        return [summary] + messages[-5:]
    return messages

5. 배치 처리:

# 여러 질문을 한 번에
questions = ["질문1", "질문2", "질문3"]
combined = "\n\n".join(f"{i+1}. {q}" for i, q in enumerate(questions))

response = client.messages.create(
    model="claude-",
    max_tokens=1000,
    messages=[{"role": "user", "content": combined}]
)

Q27. 프로덕션 환경에서 주의할 점은?

A: 프로덕션 배포 체크리스트:

1. 에러 핸들링:

import anthropic
import logging

logger = logging.getLogger(__name__)

try:
    response = client.messages.create(...)
except anthropic.RateLimitError as e:
    logger.error(f"Rate limit: {e}")
    # 재시도 로직
except anthropic.APIError as e:
    logger.error(f"API error: {e}")
    # 사용자에게 친절한 메시지
except Exception as e:
    logger.critical(f"Unexpected error: {e}")
    # 알림 전송

2. 타임아웃 설정:

client = anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    timeout=30.0,  # 30초 타임아웃
    max_retries=3
)

3. 모니터링:

• 응답 시간 추적
• 토큰 사용량 모니터링
• 에러율 측정
• 비용 추적

4. 보안:

• API 키를 환경 변수나 Secret Manager에 저장
• 사용자 입력 검증 (프롬프트 인젝션 방지)
• 출력 필터링 (민감 정보 노출 방지)
• Rate limiting 구현

5. 캐싱 및 최적화:

from functools import lru_cache

# 동일 질문에 대한 캐싱
@lru_cache(maxsize=100)
def get_cached_response(prompt: str):
    response = client.messages.create(
        model="claude-",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}]
    )
    return response.content[0].text