이 장에서 배우는 것
•
오류의 3가지 원인 구분 (내 지시 문제 / 맥락 손실 / 기술적 한계)
•
흔한 오류 메시지와 해결법
•
원하는 결과가 아닐 때 구체적으로 수정 요청하는 방법
•
중요한 작업 전 백업하는 습관
•
포기해야 할 때를 아는 것
Claude Code를 쓰다 보면 오류 메시지를 만나거나 예상과 다른 결과가 나올 때가 있습니다. 이 장에서는 흔한 문제 상황과 대응법을 다룹니다.
문제의 원인 파악하기
오류가 나면 "Claude가 고장났다"고 생각하기 쉽습니다. 실제로는 세 가지 원인 중 하나입니다.
원인 | 확인 방법 | 해결법 |
내 지시가 불분명했다 | 지시를 다시 읽어봄 | 더 구체적으로 지시 |
Claude가 맥락을 놓쳤다 | "지금까지 내가 지시한 조건을 정리해봐" | /compact 또는 새 대화 |
기술적 제약이다 | "이거 할 수 있어? 솔직하게 말해줘" | 다른 방법 찾기 |
이 세 가지를 구분하지 않으면 헛수고를 반복합니다 지시 문제인데 Claude에게 "다시 해봐"만 반복하거나, 기술적 한계인데 지시를 바꿔가며 시간과 사용량을 낭비하게 됩니다.
흔한 오류 상황과 대응
"권한이 없습니다" (Permission denied)
파일이나 폴더를 수정할 권한이 없을 때 나타납니다.
방금 권한 오류가 났는데, 이 폴더에 파일을 저장할 수 있도록 권한을 확인해줘
Plain Text
복사
sudo(관리자 권한)를 시키지 마세요 이 오류가 반복될 때 흔한 실수는 Claude에게 sudo(관리자 권한)로 실행하라고 시키는 겁니다. sudo는 시스템 전체를 건드릴 수 있어서, 잘못하면 컴퓨터 설정을 망가뜨릴 수 있습니다. 권한 오류의 올바른 해결법은 대부분 저장 위치를 바꾸는 것입니다. 홈 폴더(~) 아래의 문서, 다운로드, 바탕화면 폴더는 대부분 권한 문제 없이 쓸 수 있습니다.
"파일을 찾을 수 없습니다" (No such file or directory)
경로가 틀렸거나 파일 이름이 다를 때 나타납니다.
~/문서/보고서.xlsx 파일을 찾을 수 없다고 나와. 비슷한 이름의 파일이 있는지 찾아봐줘
Plain Text
복사
한글 폴더명이 가장 흔한 원인입니다 Mac의 파인더에서 "문서"로 보이는 폴더가 실제로는 Documents인 경우가 많습니다. ~/문서/로 지시하면 파일을 찾지 못하고, ~/Documents/로 지시해야 찾습니다. `` 이 폴더의 실제 경로를 확인해줘 ``
"설치가 필요합니다"
특정 도구나 라이브러리가 없을 때 나타납니다.
pandas가 없다는 오류가 나왔어. 설치하고 다시 실행해줘
Plain Text
복사
Claude가 필요한 패키지를 설치한 뒤 작업을 이어갑니다.
설치 후 "command not found"가 나오면 Claude Code를 종료했다가(Ctrl+C 또는 /exit) 터미널을 새로 열고 다시 시작하면 대부분 해결됩니다. 터미널을 새로 열어야 설치한 프로그램이 인식되는 경우가 많습니다.
작업이 멈추거나 너무 오래 걸릴 때
먼저 기다려보세요. 큰 파일을 읽거나 복잡한 계산을 하면 1~2분간 아무 반응이 없을 수 있습니다. 화면 하단에 진행 표시가 있는지 먼저 확인하세요.
5분 이상 반응이 없으면 Esc로 중단합니다.
방금 중단했어. 파일 100개를 한꺼번에 하지 말고, 10개씩 나눠서 처리해줘
Plain Text
복사
"API 오류" / "네트워크 오류"
Claude Code는 인터넷을 통해 Anthropic 서버와 통신합니다.
"overloaded", "rate limit", "529" 같은 메시지가 나오면 Anthropic 서버가 바쁜 상태입니다. 이건 내 문제가 아니라 서버 문제이므로 1~2분 기다렸다가 다시 시도하면 됩니다.
계속 반복되면 status.anthropic.com에서 현재 서비스 상태를 확인할 수 있습니다.
Claude가 잘못했을 때 바로잡기
엉뚱한 파일을 수정했을 때
방금 수정한 거 되돌려줘. 보고서.xlsx가 아니라 보고서_초안.xlsx를 수정해야 해
Plain Text
복사
Claude는 파일을 수정하기 전에 확인을 요청합니다. 이때 파일 경로를 꼼꼼히 확인하면 예방할 수 있습니다.
"방금 한 거 취소해줘"가 항상 통하는 건 아닙니다 Claude가 직전 작업을 기억하고 있을 때만 됩니다. /compact를 했거나 새 대화로 넘어간 경우에는 이전 작업을 모를 수 있습니다. 이럴 때는 구체적으로 말해야 합니다: `` 보고서.xlsx 파일의 B열 데이터가 원래 매출액이었는데, 지금 이상한 값으로 바뀌어 있어. 원래대로 복원해줘 ``
원하는 결과가 아닐 때
결과물의 방향 자체가 다를 때는, 무엇이 잘못되었는지 구체적으로 짚어주는 것이 효과적입니다.
이 요약은 너무 길어. 핵심 3가지만 각각 한 줄로 줄여줘
Plain Text
복사
표 형식이 아니라 글로 풀어서 써줘. 팀원들에게 메일로 보낼 거야
Plain Text
복사
수정 요청이 안 먹힐 때
같은 수정을 두세 번 요청했는데 계속 같은 결과가 나오는 경우가 있습니다.
해결법:
1.
/clear로 대화를 초기화합니다
2.
원하는 결과를 처음부터 구체적으로 지시합니다
3.
이전 대화에서 잘 된 부분이 있으면, 그 결과 파일을 참조하라고 합니다
보고서-초안.md를 참고해서 수정 버전을 만들어줘.
변경 사항:
- 2장의 표를 삭제하고 글로 풀어쓰기
- 결론을 3줄로 줄이기
- 전체 톤을 딱딱한 보고서체에서 부드러운 설명체로 변경
Plain Text
복사
예방 습관
중요한 작업 전 백업 요청
원본 파일을 직접 수정하는 작업이라면, 먼저 백업을 만들어두는 것이 안전합니다.
거래처_목록.xlsx를 수정하기 전에 백업 파일을 먼저 만들어줘
Plain Text
복사
Claude가 거래처_목록_백업.xlsx 같은 사본을 만든 뒤 원본을 수정합니다.
결과를 눈으로 확인하는 습관
Claude가 "완료했습니다"라고 해도 바로 믿지 마세요.
Claude는 자신감과 정확도가 비례하지 않습니다 특히 다음 상황에서는 반드시 결과를 직접 확인합니다: - 엑셀 파일 수정: 파일을 직접 열어서 데이터가 맞는지 확인 - 여러 파일 일괄 처리: 몇 개만 샘플로 열어서 확인 - 숫자 계산: 합계나 평균을 수작업으로 한두 건 검산
"계획 먼저" 패턴
8장에서 다룬 "계획 먼저" 패턴이 여기서도 핵심입니다. 문제를 예방하는 가장 효과적인 방법은 큰 작업을 시키기 전에 계획을 먼저 확인하고, 단계별로 중간 결과를 검토하면서 진행하는 것입니다.
포기해야 할 때를 아는 것
모든 문제를 Claude로 해결할 수 있는 건 아닙니다.
신호 | 대응 |
같은 오류가 3회 이상 반복 | /clear 후 한 번 더. 그래도 안 되면 다른 방법 탐색 |
Claude가 매번 다른 방법을 시도하지만 전부 실패 | "이거 할 수 있어? 솔직하게 말해줘" - Claude는 한계를 인정합니다 |
해결에 10분 이상 걸리는 오류 | 수작업으로 하거나 접근 자체를 바꾸기 |
전용 소프트웨어가 필요한 작업 | 복잡한 엑셀 매크로, 특수 파일 형식 변환 등 |
Claude Code는 범용 도구이지 만능 도구가 아닙니다 "이 도구로 안 되는 게 있다"를 아는 것이 오히려 더 잘 쓰는 방법입니다.
오류 메시지로 다시 물어보기
오류가 나면 당황하지 말고, Claude에게 이어서 물어보세요.
지금 나온 오류가 무슨 뜻이야? 어떻게 해결하면 돼?
Plain Text
복사
Claude Code 화면에 표시된 오류 내용은 Claude도 같이 보고 있습니다. 대부분의 오류는 Claude가 원인을 파악하고 해결 방법을 제안합니다.
실전 예시
데이터 처리 중 오류:
매출_2024.xlsx를 읽어서 분기별 합계를 내줘
Plain Text
복사
"시트를 찾을 수 없습니다" 같은 오류가 나오면:
오류 원인을 파악해줘. 파일 구조를 먼저 확인해볼래?
Plain Text
복사
"다른 방법으로 열어봐"보다 "원인이 뭐야?"가 먼저 시트 이름이 다른 게 문제인데 파일 읽기 방식을 바꿔봤자 해결되지 않습니다. 오류가 나면 무작정 재시도하기 전에 "원인이 뭐야?"부터 물어보는 습관이 중요합니다.
스캔 PDF 변환 실패:
"계약서.pdf를 텍스트 파일로 변환해줘"라고 했는데 안 될 때:
텍스트 추출이 안 되면 다른 방법이 있어?
Plain Text
복사
Claude가 "이 PDF는 스캔 이미지라 직접 추출이 어렵습니다. OCR 도구를 사용하거나, 원본 워드 파일이 있다면 그쪽에서 추출하는 것이 정확합니다" 같은 대안을 제시합니다.
직접 해보기
일부러 존재하지 않는 파일을 지시해서 오류를 경험해보기 (예: "없는파일.csv를 읽어줘")
오류가 나면 "이 오류를 해결해줘" 요청해보기
중요한 파일 작업 전에 "먼저 백업을 만들어줘" 습관 들이기
오류가 반복될 때 "이거 할 수 있어? 솔직하게 말해줘" 물어보기
정리
•
오류가 나면 먼저 원인을 파악합니다: 내 지시 문제인지 / Claude가 맥락을 놓친 건지 / 기술적 한계인지 구분하면 해결이 빨라집니다.
•
오류 메시지가 나오면 당황하지 말고 Claude에게 "이게 무슨 뜻이야?"라고 물어보면 대부분 해결됩니다.
•
중요한 작업 전에는 백업을 만들고, "먼저 계획만 보여줘"로 방향을 확인하면 실수를 줄일 수 있습니다.
•
같은 오류가 반복되면 새 대화에서 처음부터 다시 시도하는 것이 가장 빠른 해결법일 때가 많습니다.
•
3회 이상 실패하면 다른 접근법을 찾습니다. Claude Code는 범용 도구이지 만능 도구가 아닙니다.
파트 3을 마치며: 여기까지 오면 구체적으로 지시하고, CLAUDE.md로 규칙을 저장하고, 대화를 효율적으로 관리하고, 문제가 생겨도 스스로 해결할 수 있습니다. Claude Code를 "쓰는 사람"에서 "잘 다루는 사람"이 된 것입니다.
여기까지 오면 할 수 있는 것•
구체적인 조건, 예시, 이미지를 활용해서 정확한 결과를 얻을 수 있다
•
CLAUDE.md로 반복 지시를 자동화할 수 있다
•
모델 전환과 대화 관리로 사용량을 절약할 수 있다
•
오류가 나도 당황하지 않고 해결할 수 있다