Claude Code 윈도우 사용법, 한글 깨짐·bat·환경변수 함정

회사 노트북은 윈도우 11이다. 여기서 Claude Code를 15개월 썼는데, 코드 문제로 막힌 기억은 별로 없고 막힌 건 거의 전부 인코딩과 경로였다. 한글 윈도우라서 생기는 함정이다. 메모리에 "2회 재발" 표시가 붙은 것부터 적는다.

첫째, PowerShell로 파일을 읽고 쓰면 한글이 깨진다

Get-Content로 읽어 Set-Content로 되쓰는 왕복에서 한글이 깨졌고, 인코딩을 utf8로 지정한 Add-Content도 같은 증상이었다. 7월에 파이썬 docstring의 한글이 깨져서 잘라내고 다시 쓴 적이 있다.

더 심한 건 리다이렉션이다. echo와 >>로 설정 파일에 한 줄을 붙였더니 파일이 UTF-16으로 바뀌면서 NUL 문자가 섞여 들어갔고, 앱이 기동하면서 설정을 못 읽고 죽었다.

규칙은 하나다. 파일 수정은 Claude Code의 편집 도구로만 하고, PowerShell의 텍스트 명령으로는 손대지 않는다.

둘째, 깨져 보이는 것과 깨진 것을 구분해야 한다

Claude가 자기 PowerShell 출력에서 한글이 깨진 걸 보고 제품 버그로 오인해 콘솔 인코딩을 고치려 든 적이 있다. 실제 파일은 멀쩡했고 캡처만 깨진 것이었다. 지금은 화면에 깨져 보이면 파일 바이트를 먼저 확인한다.

셋째, 배치 파일은 반대다

.bat와 .cmd는 CP949로 저장해야 한다. UTF-8로 저장하면 실행 자체가 깨진다. 배치 안에서 chcp 65001로 코드페이지를 바꾸는 것도 안 된다. 배치 파서가 깨진다. 그래서 규칙이 "배치는 ASCII만, 한글 출력은 파이썬이 담당"이 됐다.

그런데 파이썬도 함정이 있다. 콘솔이 CP949라서 em dash나 경고 기호 같은 문자를 print하면 인코딩 오류로 프로그램이 죽는다. 에이전트 크론 스크립트의 출력을 UTF-8로 고정하는 것으로 해결했는데, 누군가 CP949로 되돌려서 한글 알림이 전멸한 일이 8월에 두 번 있었다. 방향이 반대인 규칙 둘을 같이 외워야 한다.

넷째, python3라고 치면 마이크로소프트 스토어가 뜬다

윈도우의 앱 실행 별칭이 python3.exe와 python.exe를 스토어 리다이렉터로 연결해 두기 때문이다. 파이썬이 아니라 스토어를 여는 프로그램이다. python이 정상으로 보이는 건 PATH 순서상 가상환경이 먼저 잡혀서일 뿐이라, PATH 맥락이 다른 프로세스에서는 같은 명령이 스토어를 띄운다. 간헐적으로 뜨는 이유가 이거였다.

별칭을 끄거나, 스크립트에서는 가상환경의 python 전체 경로를 쓴다. 나는 어떤 프로세스가 부르는지 잡으려고 호출 기록을 남기는 덫까지 깔았다.

다섯째, 테스트와 가상환경

이 환경의 pytest는 기본 임시 폴더에 권한 거부가 나서 basetemp 옵션을 항상 준다. 프로젝트의 .venv가 WSL용 리눅스 가상환경이라 윈도우 파이썬으로 착각하고 실행하면 안 되는 것도 있었다. 어느 쪽 파이썬인지 먼저 본다.

여섯째, 운영 PC 배포

git pull이 HEAD는 옮겼는데 정적 JS 파일 쓰기만 실패한 적이 있다. 서버가 파일을 잡고 있었거나 백신이 개입한 것으로 보인다. 버전 확인 API는 최신 커밋을 답하는데 화면 일부만 먹통이었다. 저장소는 완벽히 정상이라 어떤 테스트로도 못 잡는다.

지금은 "화면 일부만 안 된다"는 신고가 오면 정적 파일 URL을 직접 찍어 404인지부터 본다. 복구는 git checkout으로 그 폴더만 되돌리면 되고, 기동 시 템플릿이 참조하는 정적 파일이 디스크에 있는지 확인해 로그로 남기는 가드를 넣었다.

터미널과 환경변수

터미널은 git-bash를 쓴다. Claude Code가 부르는 스크립트도 bash로 쓴다. PowerShell은 윈도우 고유 작업에만 쓰고 텍스트는 안 만진다. 환경변수는 Claude Code의 settings.json에 env 항목으로 두면 프로세스 맥락과 무관하게 같은 값이 들어간다.

인코딩 셋과 경로 하나

정리하면 윈도우에서 Claude Code를 쓰는 규칙은 인코딩 셋과 경로 하나다. 파일은 편집 도구로, 배치는 ASCII로, 파이썬 출력은 UTF-8로, 파이썬은 전체 경로로. 이 넷이 메모리에 자리 잡기까지 재발이 여섯 번이었다.

※ 회사 노트북의 Claude Code 자동 메모리와 2026년 7~8월 사고 기록을 근거로 썼다. 시스템 이름과 주소는 뺐다.

함께 보면 좋은 글

• Claude Code 메모리 다른 PC로 옮기는 법 (46개 프로젝트)
• Claude Code 업무 자동화, 무너지는 건 코드가 아니라 코드 밖