설치 트러블슈팅

1장에서 막혔을 때 보는 자세한 판. 1.9절은 요약본이고, 여기가 전체입니다.

---

A.1 먼저 — 지금 어디까지 됐는지 확인

막혔을 때 어디서 막혔는지부터 확인하세요. 위에서부터 하나씩 짚습니다.

• VS Code가 실행된다
• 터미널에서 python --version(Mac은 python3 --version)이 답한다
• 터미널에서 git --version이 답한다
• VS Code 왼쪽에 Claude 아이콘이 보인다
• Claude 패널 아래쪽에 내 계정이 보인다
• 폴더를 열고 “이 폴더 뭐 있어?” 를 보냈더니 답이 왔다

처음으로 체크가 안 되는 줄이 막힌 지점입니다. 그 줄에 해당하는 절로 가세요.

A.2 VS Code

설치 파일이 실행되지 않는다 (Windows)

• 백신이 막았을 수 있습니다. 다운로드를 다시 받아보세요
• 회사 PC면 설치 권한이 없을 수 있습니다 → A.9

“확인되지 않은 개발자” 경고 (Mac)

정상입니다. 인터넷에서 받은 앱은 처음에 이 경고가 뜹니다.

1. 시스템 설정 → 개인정보 보호 및 보안
2. 아래로 내리면 “Visual Studio Code이(가) 차단되었습니다” 가 있습니다
3. 확인 후 열기 클릭

한글이 깨져 보인다

메뉴가 아니라 파일 내용의 한글이 깨진다면, 파일 인코딩 문제입니다. VS Code 오른쪽 아래에 인코딩 표시(UTF-8 등)를 눌러 Reopen with Encoding → UTF-8 을 고르세요.

---

A.3 Python

“python을 찾을 수 없습니다” (Windows)

가장 흔한 문제입니다. 원인은 거의 항상 하나 — 설치할 때 Add python.exe to PATH 체크박스를 놓친 것입니다.

고치는 법 (권장)

1. 설정 → 앱 → 설치된 앱에서 Python 3.11.9 제거
2. 다시 설치. 이번엔 첫 화면 아래의 체크박스를 반드시 켜기
3. 명령 프롬프트를 새로 열어서 python --version 확인

⚠️ 터미널을 새로 열어야 합니다

설치 중에 열어둔 터미널 창은 예전 설정을 그대로 들고 있습니다. 창을 닫고 새로 여세요. 이것 때문에 “다시 깔았는데도 안 돼요” 가 자주 나옵니다.

그래도 안 되면 — VS Code도 껐다 켜세요. 같은 이유입니다.

python 은 되는데 pip 이 안 된다

python -m pip --version

이렇게 하면 대개 됩니다. 앞으로도 pip 무엇 대신 python -m pip 무엇 을 쓰세요.

Microsoft Store가 열린다 (Windows)

python 을 쳤는데 스토어가 열리는 경우입니다. Windows에 들어 있는 가짜 python 바로가기가 먼저 잡힌 것입니다.

• 설정 → 앱 → 앱 실행 별칭
• python.exe, python3.exe 를 끔으로
• 터미널을 새로 열어 다시 확인

버전이 3.11.9가 아니다

여러 버전이 깔려 있으면 섞입니다. 3.11.9 하나만 남기는 게 가장 속 편합니다. 다른 이유로 다른 버전이 필요한 게 아니라면 나머지는 지우세요.

Mac에서 python 은 없고 python3 만 된다

정상입니다. Mac은 python3 를 씁니다. 그대로 쓰세요.

---

A.4 Git

Git Bash Here가 안 보인다 (Windows)

git --version 이 답하면 메뉴가 안 보여도 문제없습니다. Claude Code는 메뉴가 아니라 Git 자체를 씁니다.

git 명령을 찾을 수 없다

Python과 같은 이유입니다. 터미널을 새로 여세요. 그래도 안 되면 재설치.

Mac에서 설치 팝업이 안 뜬다

xcode-select --install

터미널에 이렇게 치면 설치 안내가 뜹니다. 또는 git-scm.com/download/mac 에서 직접 받으세요.

---

A.5 Claude Code 확장

확장 검색에 안 나온다

1. VS Code 업데이트 — Help → Check for Updates
2. 인터넷·방화벽 — 회사 네트워크가 마켓플레이스를 막는 경우가 있습니다
3. 검색어를 정확히 Claude Code 로

비슷한 이름이 여러 개 나온다

⚠️ 만든 곳이 Anthropic 인지 반드시 확인하세요

이름이 비슷한 다른 확장들이 함께 나옵니다. 제작사 이름을 보고 고르세요.

설치했는데 아이콘이 안 보인다

• VS Code 재시작
• 왼쪽 세로 막대를 오른쪽 클릭 → 숨겨진 아이콘이 있는지 확인
• 그래도 없으면 확장을 지우고 다시 설치

---

A.6 로그인

Sign in을 눌러도 브라우저가 안 열린다

1. 10초 기다려 보세요. 느릴 수 있습니다
2. 기본 브라우저를 Chrome이나 Edge로 바꿔 보세요
3. 브라우저에서 이미 다른 계정으로 로그인되어 있으면 꼬입니다 → 시크릿 창을 기본으로 쓰거나, 기존 세션을 로그아웃하고 다시

로그인은 됐는데 계정이 안 보인다

VS Code를 껐다 켜세요. 표시가 늦게 갱신되는 경우가 있습니다.

로그인이 자꾸 풀린다

• 회사 보안 프로그램이 저장소를 지우는 경우가 있습니다
• 브라우저의 쿠키 차단 설정 확인

---

A.7 대화가 안 될 때

메시지를 보내도 답이 없다

순서대로 확인하세요.

“그 파일이 없다” 고 한다

2.1절입니다. 그 파일이 작업 폴더 밖에 있습니다. 파일을 폴더 안으로 옮기거나, 그 파일이 있는 폴더를 새로 여세요.

답이 영어로 온다

7장의 CLAUDE.md 로 해결합니다. 급하면 그때그때 “한국어로 답해줘” 라고 하세요.

권한 창이 안 뜨고 아무것도 안 한다

거부를 눌렀거나, 권한 설정이 막고 있을 수 있습니다. 다시 시켜보세요.

---

A.8 폴더·경로 문제

⚠️ 한글·공백·동기화 폴더를 피하세요

설치는 다 됐는데 이상하게 안 되는 경우, 상당수가 폴더 위치 문제입니다.

피할 것	증상
한글이 든 경로	파일을 못 찾거나 깨진 이름으로 만듦
공백이 든 경로	명령이 중간에서 끊김
OneDrive·iCloud·구글드라이브	파일이 잠기거나 충돌

권장: Windows C:\claude-lecture\ / Mac ~/claude-lecture/

이미 한글 폴더에서 작업 중이라면 — 폴더를 통째로 영어 경로로 옮기고, VS Code에서 새 위치를 다시 여세요.

---

A.9 회사 PC라 설치가 막힐 때

실제로 있는 경우입니다. 순서대로 시도하세요.

1. IT팀에 문의 — VS Code·Python·Git 설치 가능 여부를 먼저 확인
2. 사용자 설치 버전 — VS Code는 관리자 권한 없이 설치되는 버전이 있습니다 (User Installer). Python도 “Install for me only” 옵션이 있습니다
3. 안 되면 개인 PC 를 쓰세요

⚠️ claude.ai 웹으로 대체할 수는 없습니다

웹 Claude는 내 컴퓨터의 파일을 열지 못합니다(4장). 이 책이 하려는 일의 전부가 그것이라, 대체가 안 됩니다.

보안 정책이 걱정될 때

읽힌 파일 내용은 Anthropic 서버로 전송됩니다(4.7절). 회사 자료를 다루기 전에 정책을 먼저 확인하세요. 이 책의 실습은 전부 가짜 데이터로 해도 됩니다.

---

A.10 마지막 수단

어디가 문제인지 모르겠으면, Claude에게 물어보세요. 이게 진짜로 빠릅니다.

설치 상태를 점검해줘.
python, git, vscode 버전을 확인하고 뭐가 빠졌는지 알려줘.

작업 폴더가 열려 있고 Claude가 응답만 한다면, 나머지는 대개 Claude가 짚어줍니다.

오류 메시지가 나왔다면 통째로 복사해서 던지세요.

이런 오류가 났어. 무슨 뜻이고 어떻게 고치면 돼?

(오류 메시지 붙여넣기)

---