Skip to main content

트러블슈팅

Claude Code를 사용하다 보면 예상치 못한 동작, 반복되는 실수, 막힌 상황을 마주칩니다. 이 챕터에서는 가장 자주 발생하는 문제와 검증된 해결 방법을 다룹니다.

문제 1: Claude가 계속 같은 실수를 반복한다​

증상: 수정을 요청해도 같은 방식으로 잘못된 코드를 생성함.

원인: 잘못된 패턴이 대화 컨텍스트에 쌓여 있거나, 요청이 모호함.

해결책:

# 방법 1: 컨텍스트 초기화
> /clear

# 방법 2: 명시적으로 잘못된 점 지적
> 이전에 생성한 코드에서 [구체적인 문제]가 있어.
  [올바른 방식]으로 다시 작성해줘.
  특히 [특정 부분]은 절대 [잘못된 방식]으로 하지 마.

# 방법 3: 예시 제공
> 이 패턴을 따라줘:
  [올바른 코드 예시]
  같은 방식으로 [새 기능]을 구현해줘.

예방: CLAUDE.md에 금지 패턴을 명시합니다:

## 금지 패턴
- 콜백 사용 금지 → async/await 사용
- var 사용 금지 → const/let 사용
- any 타입 사용 금지 → 정확한 타입 추론

문제 2: Claude가 원하지 않는 파일을 수정한다​

증상: 요청하지 않은 파일까지 변경함.

원인: 요청 범위가 불명확하거나, Claude가 "도움이 될 것 같은" 추가 변경을 함.

해결책:

# 범위를 명확히 제한
> src/services/user.service.ts 파일만 수정해줘.
  다른 파일은 건드리지 마.

# 변경 전 계획 확인
> 실제로 수정하기 전에, 어떤 파일들을 변경할 계획인지 먼저 알려줘.

예방: CLAUDE.md에 금지 파일 명시:

## 수정 금지 파일
- src/config/ (설정 파일)
- *.lock 파일
- src/generated/ (자동 생성 코드)

문제 3: 빌드/테스트 오류가 발생했는데 Claude가 고치지 못한다​

증상: 에러를 보여줘도 계속 잘못된 수정을 반복함.

해결책:

# 1단계: 에러 전체를 정확히 전달
> 이 에러가 발생해:
  [에러 메시지 전문]

  관련 파일:
  [파일 내용]

# 2단계: 근본 원인부터 파악 요청
> 수정하기 전에, 이 에러의 근본 원인이 뭔지 먼저 설명해줘.

# 3단계: 단계별로 접근
> 가장 단순한 수정 방법으로 먼저 에러만 없애줘.
  그 다음에 코드 품질을 개선할게.

막힌 경우 접근 방향 변경:

# 현재 코드 버리고 새로 시작
> /clear
> [해당 기능]을 완전히 새로 구현해줘.
  기존 코드 참고하지 말고, 처음부터 올바르게 만들어줘.

문제 4: 컨텍스트가 너무 길어져 응답 품질이 떨어진다​

증상: 대화가 길어질수록 이전 요청을 무시하거나 일관성이 없어짐.

원인: 컨텍스트 창이 가득 차서 초기 지시사항이 희석됨.

해결책:

# 현재 컨텍스트 초기화
> /clear

# 핵심 정보만 다시 요약해서 시작
> 지금까지 작업 내용 요약:
  - 완료: [완료된 작업]
  - 진행 중: [현재 작업]
  - 남은 것: [남은 작업]
  이어서 [다음 작업]을 진행해줘.

예방: 긴 작업은 체크포인트마다 /clear 실행:

[기능 A 완료] → git commit → /clear → [기능 B 시작]

문제 5: Claude가 너무 많은 것을 한 번에 바꾼다​

증상: 요청한 것 외에 여러 파일을 추가로 "개선"함.

해결책:

# 명시적으로 제한
> 딱 요청한 부분만 수정해줘. 다른 "개선"은 하지 마.

# 최소 변경 요청
> 이 버그만 고쳐줘. 가장 작은 변경으로.

# 수정 내용 먼저 확인
> 실제 수정 전에 변경할 내용의 diff를 보여줘.

문제 6: API 키 오류 / 인증 문제​

증상: Authentication error 또는 Invalid API key 오류.

해결책:

# API 키 확인
echo $ANTHROPIC_API_KEY

# API 키 재설정
export ANTHROPIC_API_KEY="sk-ant-..."

# 또는 ~/.claude/.env 파일에 저장
echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.claude/.env

문제 7: 속도가 너무 느리다​

증상: 응답이 오래 걸리거나, 도구 호출 승인 대기 시간이 길다.

해결책:

# 1. 더 빠른 모델 사용
claude --model claude-haiku-4-5-20251001 "빠른 작업"

# 2. 권한 모드 변경 (파일 수정 자동 승인)
# VSCode: 설정 → Claude Code → Permission Mode → acceptEdits

# 3. 헤드리스 모드로 실행
claude --print "빠른 질의" < input.txt

문제 8: 생성된 코드가 동작하지 않는다​

증상: Claude가 작성한 코드에 오류가 있음.

체계적인 디버깅 접근:

# 1단계: 에러 메시지 전달
> 이 코드를 실행했더니 다음 에러가 발생해:
  [에러 내용]
  [스택 트레이스]

# 2단계: 환경 정보 제공
> 내 환경은 Node.js 20, TypeScript 5.3이야.
  이 패키지 버전을 사용하고 있어: [package.json 내용]

# 3단계: 최소 재현 케이스
> 이 최소 코드로 에러를 재현할 수 있어:
  [최소 재현 코드]

문제 9: Hook이 작동하지 않는다​

증상: settings.json에 Hook을 설정했는데 실행되지 않음.

디버깅 방법:

# settings.json 문법 확인
cat ~/.claude/settings.json | python -m json.tool

# Hook 명령어 직접 실행 테스트
echo "test" > /tmp/test.ts
npm run lint /tmp/test.ts

# Claude Code 재시작
# (VSCode 확장: 명령 팔레트 → "Claude Code: Restart")

흔한 실수:

// 잘못된 예
{
  "hooks": {
    "PostToolUse": {
      "matcher": "Write",  // ❌ 객체로 감싸면 안 됨
      "hooks": [...]
    }
  }
}

// 올바른 예
{
  "hooks": {
    "PostToolUse": [       // ✅ 배열이어야 함
      {
        "matcher": "Write",
        "hooks": [...]
      }
    ]
  }
}

문제 10: MCP 서버 연결 실패​

증상: MCP 서버가 연결되지 않거나 도구를 사용할 수 없음.

디버깅:

# 서버 목록 확인
claude mcp list

# 서버 상태 확인
claude mcp get <서버명>

# 서버 직접 실행 테스트
node /path/to/mcp-server.js

흔한 원인:

  • 환경변수 미설정 (API 키, 연결 문자열)
  • 서버 실행 파일 경로 오류
  • Node.js 버전 불일치

효과적인 도움 요청 템플릿​

문제가 생겼을 때 Claude에게 정확히 전달하는 방법:

> 문제 상황:
  [무엇을 하려고 했는지]

  발생한 에러:
  [에러 메시지 전문]

  관련 코드:
  [파일명]: [관련 코드]

  이미 시도한 것:
  [시도한 해결 방법]

  예상하는 동작:
  [올바른 동작 설명]

막혔을 때 탈출 전략​

어떤 방법도 통하지 않을 때:

  1. /clear 후 재시작 — 컨텍스트 오염 제거
  2. 더 작은 단위로 분해 — "이 함수 하나만" 집중
  3. 다른 접근법 요청 — "완전히 다른 방식으로 구현해줘"
  4. 직접 해결 후 검토 요청 — 일부 직접 작성 후 "이 방향 맞아?"
  5. 공식 문서 참조 — Claude에게 공식 문서 URL 제공
가장 중요한 원칙

막혔을 때 같은 방법을 반복하지 마세요. 접근법을 바꾸는 것이 훨씬 효율적입니다.

다음 챕터: 프롬프트 전략 →

Last updated on