Appearance
부록 D: 트러블슈팅 15선
선생님들이 Claude Code를 쓰면서 가장 자주 마주치는 문제와 해결법을 모았어요. 당황하지 마세요. 대부분 1~2분이면 해결돼요.
설치 관련
1. npm install -g가 permission error로 실패할 때
증상: "EACCES: permission denied"라는 빨간 글씨가 뜨면서 설치가 안 돼요.
해결법:
- Mac: 명령어 앞에
sudo를 붙여요.bash비밀번호를 입력하면 설치가 진행돼요.sudo npm install -g @anthropic-ai/claude-code - Windows: VS Code를 닫고, 마우스 오른쪽 버튼으로 "관리자 권한으로 실행"을 선택한 뒤 다시 시도해요.
2. claude 명령어를 입력해도 "command not found"가 뜰 때
증상: 설치는 됐다고 나왔는데, claude를 입력하면 아무 반응이 없어요.
해결법:
- VS Code를 완전히 닫았다가 다시 열어보세요. PATH(경로 설정)가 새로고침돼요.
- 그래도 안 되면 이 명령어로 직접 실행해보세요.bash
npx @anthropic-ai/claude-code
3. 로그인 화면이 뜨지 않을 때
증상: Claude Code를 시작했는데 로그인 창이 안 나와요.
해결법: 터미널에서 직접 로그인 명령을 입력해요.
bash
claude --login4. Node.js 버전 오류가 날 때
증상: "Node.js 18 or higher required" 같은 메시지가 뜨면서 실행이 안 돼요.
해결법: nodejs.org에 접속해서 최신 LTS 버전을 내려받아 다시 설치해요. 설치 후 VS Code를 재시작하면 돼요.
대화 관련
5. 응답이 갑자기 느려질 때
증상: 처음에는 빨랐는데, 한참 대화하다 보면 응답이 10초, 20초씩 걸려요.
해결법: /compact를 입력하세요. 대화 내용이 압축되면서 속도가 빨라져요. 30분 이상 작업했다면 한 번씩 써주는 게 좋아요.
6. 앞에서 말한 내용을 기억 못 할 때
증상: "아까 얘기한 3반 퀴즈 수정해줘"라고 했는데, "어떤 퀴즈인지 모르겠습니다"라고 대답해요.
해결법:
- CLAUDE.md에 자주 쓰는 정보(학년, 과목, 학급 정보)를 미리 적어두세요.
/compact후 "아까 만든 3반 국어 퀴즈를 수정해줘. 5번 문제의 정답을 ③으로 바꿔줘"처럼 구체적으로 다시 요청하세요.
7. "I cannot help with that" 응답이 나올 때
증상: 평범한 요청을 했는데 AI가 거부해요.
해결법:
- 요청 방식을 바꿔보세요. "학교 현장 교사로서 수업에 활용할 자료를 만들고 있어요"라는 맥락을 앞에 붙이면 잘 돼요.
- 요청에 학생의 개인정보나 민감한 내용이 포함되지 않았는지 확인하세요.
8. 파일이 저장됐다는데 찾을 수 없을 때
증상: Claude Code가 "저장했습니다"라고 했는데, 파일이 보이지 않아요.
해결법:
- 현재 작업 폴더를 확인하세요. Claude Code에게 "지금 어느 폴더에서 작업하고 있어?"라고 물어보면 알려줘요.
- VS Code 좌측 탐색기에서 폴더를 열어 파일 위치를 직접 확인하세요.
파일 작업 관련
9. @파일명으로 파일을 불러오지 못할 때
증상: @수업자료.hwp처럼 입력했는데 파일을 찾지 못해요.
해결법:
- 파일이 현재 작업 폴더 안에 있는지 확인하세요.
- 한글 파일명에 특수문자가 포함되면 따옴표로 감싸보세요:
@"수업 자료.txt"
10. 한글 파일명에서 오류가 날 때
증상: 한글 파일명으로 저장하면 깨지거나 오류가 나요.
해결법: 파일명을 영문으로 바꿔서 시도해보세요. 예를 들어 국어퀴즈3단원.md 대신 quiz-korean-unit3.md로 저장하세요.
11. 파일 내용이 깨져서 저장될 때
증상: 한글이 물음표(???)나 네모(□□□)로 나와요.
해결법: VS Code 하단 상태바에서 파일 인코딩을 확인하세요. UTF-8이 아니면 "UTF-8로 다시 열기"를 선택하면 돼요.
비용 관련
12. 예상보다 비용이 많이 나올 때
증상: 한 달 사용량이 생각보다 빨리 차요.
해결법:
/cost로 현재 세션 비용을 확인하세요.- 긴 파일을
@로 첨부하면 토큰을 많이 소모해요. 필요한 부분만 복사해서 붙여넣으세요. - 간단한 수정 작업은
/model haiku로 전환하면 비용이 줄어요.
13. Max 플랜에서도 응답이 느릴 때
증상: 유료 플랜인데도 응답이 한참 걸려요.
해결법:
- 서버 피크 시간대(한국 기준 오후 9시~11시)를 피해서 작업하세요.
/compact로 컨텍스트를 줄이면 응답 속도가 개선돼요.
기타
14. CLAUDE.md를 수정해도 반영이 안 될 때
증상: CLAUDE.md 내용을 바꿨는데 Claude Code가 여전히 옛날 정보로 대답해요.
해결법: /clear로 대화를 초기화한 뒤 새로 시작하세요. CLAUDE.md는 대화가 시작될 때 읽어들이기 때문에, 수정 후에는 새 대화를 시작해야 반영돼요.
15. Claude Code를 업데이트하는 방법
증상: 새 기능이 나왔다는데, 내 Claude Code에는 없어요.
해결법: 터미널에서 이 명령어를 입력하세요.
bash
npm update -g @anthropic-ai/claude-code업데이트 후 VS Code를 재시작하면 최신 버전으로 바뀌어요.