Claude Code에서 한글이 깨질 때는 대부분 Claude 자체 문제가 아니라 윈도우 터미널의 코드 페이지, PowerShell 출력 인코딩, Git 파일명 표시 설정이 서로 어긋난 경우입니다. 빠른 결론은 Windows Terminal에서 PowerShell 7을 쓰고, UTF-8 출력 설정을 고정한 뒤, Git의 한글 경로 표시 옵션까지 맞추는 것입니다.
지금 쓰는 터미널에서 chcp와 PowerShell 인코딩을 먼저 확인한 뒤, Claude Code를 새 세션에서 다시 실행해보세요.
저는 Claude Code로 한국어 README, 커밋 메시지, 한글 파일명이 섞인 작은 자동화 스크립트를 만들다가 터미널에 ���, ??가 보이는 문제를 겪었습니다. 아래 순서대로 잡으면 VS Code 통합 터미널, Windows Terminal, Git 출력까지 한 번에 정리하기 쉽습니다.
아래 명령어 3개를 적용한 뒤 Claude Code를 새 터미널에서 다시 실행하면 원인 범위가 크게 줄어듭니다.
가장 먼저 확인할 3가지
1. 현재 터미널 코드 페이지 확인
Windows에서 오래된 CMD나 일부 PowerShell 환경은 기본 코드 페이지가 UTF-8이 아닐 수 있습니다. Claude Code가 한국어 응답을 정상으로 만들어도 터미널이 다르게 해석하면 깨져 보입니다.
chcp65001이 아니면 현재 세션에서 다음 명령을 실행합니다.
chcp 65001다만 이 명령은 임시 처방에 가깝습니다. 터미널을 새로 열면 다시 바뀔 수 있어 PowerShell 프로필에 고정하는 편이 낫습니다.
2. PowerShell 출력 인코딩을 UTF-8로 고정
PowerShell에서는 $OutputEncoding과 콘솔 입출력 인코딩을 함께 맞추는 것이 안전합니다. PowerShell 7 기준으로 아래를 실행해 현재 세션에서 먼저 테스트해보세요.
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new()
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
$OutputEncoding = [System.Text.UTF8Encoding]::new()문제가 해결되면 프로필에 넣습니다.
notepad $PROFILE열린 파일에 위 3줄을 붙여넣고 저장한 뒤, Windows Terminal을 완전히 닫았다가 다시 실행합니다. 프로필 파일이 없다고 나오면 새로 만들면 됩니다.
3. Git 한글 파일명 표시 설정
Claude Code는 프로젝트 파일을 읽고 수정할 때 Git 상태를 자주 확인합니다. 이때 한글 파일명이 \354\225...처럼 보이면 Git 설정도 손봐야 합니다.
git config --global core.quotepath false이 설정은 Git이 비ASCII 파일명을 과도하게 이스케이프하지 않도록 합니다. 한글 폴더명, 문서 파일명, 테스트 데이터 이름을 그대로 확인해야 하는 프로젝트에서 특히 체감이 큽니다.
어느 조합이 가장 안정적일까
윈도우에서 Claude Code를 쓸 때는 터미널 선택도 중요합니다. 같은 명령을 실행해도 CMD, Windows PowerShell 5.1, PowerShell 7, Git Bash의 표시 방식이 조금씩 다릅니다.
| 환경 | 추천도 | 한글 처리 포인트 | 메모 |
|---|---|---|---|
| Windows Terminal + PowerShell 7 | 높음 | UTF-8 프로필 고정 | Claude Code, pnpm, Git 작업에 가장 무난 |
| VS Code 통합 터미널 | 높음 | 기본 셸을 PowerShell 7로 지정 | 코드 수정 결과를 바로 확인하기 좋음 |
| CMD | 낮음 | chcp 65001 필요 |
임시 테스트용으로만 권장 |
| Git Bash | 보통 | UTF-8은 강하지만 경로 호환성 확인 | 리눅스식 명령에 익숙하면 편함 |
제가 실제로 막혔던 지점
예를 들어 Claude Code에 “한글 README를 읽고 설치 순서를 요약해줘”라고 요청했는데, 터미널 출력만 깨지고 파일 자체는 정상인 경우가 있습니다. 이때 에디터에서 파일을 열면 멀쩡하므로 모델이 잘못 쓴 것처럼 오해하기 쉽습니다.
제가 확인한 순서는 단순했습니다. 먼저 type README.md 또는 Get-Content README.md로 터미널 표시를 봤고, 그다음 VS Code에서 같은 파일을 열었습니다. VS Code에서는 정상인데 터미널만 깨지면 Claude Code 문제가 아니라 콘솔 표시 문제로 보는 게 빠릅니다.
반대로 파일 자체가 깨져 있다면 다른 원인입니다. 기존 파일이 CP949로 저장되어 있거나, 외부에서 받은 CSV가 EUC-KR인 경우가 있습니다. 이때는 VS Code 오른쪽 아래 인코딩 표시를 눌러 “인코딩하여 다시 열기” 또는 “UTF-8로 저장”을 확인하세요.
상황별 추천 설정
개발 프로젝트를 계속 Claude Code로 만질 사람
Windows Terminal + PowerShell 7 + VS Code 조합을 추천합니다. PowerShell 프로필에 UTF-8 설정을 넣고, VS Code의 기본 터미널도 PowerShell 7로 맞추면 프로젝트마다 같은 문제를 반복하지 않습니다.
한글 파일명과 문서가 많은 자동화 작업
Notion에서 내려받은 Markdown, Google Drive 문서명, 한글 CSV를 자주 다룬다면 Git 설정까지 반드시 같이 적용하세요. Claude Code가 파일명을 참조해 수정 계획을 세울 때 경로가 깨져 보이면 엉뚱한 파일을 대상으로 설명할 수 있습니다.
회사 PC라 설정 변경이 제한된 경우
관리자 권한이 막혀 있다면 세션 단위로 chcp 65001을 실행하고, 프로젝트 폴더를 영문 경로에 두는 것이 현실적인 우회책입니다. 예를 들어 C:\work\ai-agent-test처럼 짧은 경로를 쓰면 한글 사용자명 경로에서 생기는 문제를 줄일 수 있습니다.
자주 하는 실수
가장 흔한 실수는 깨진 화면을 보고 바로 프롬프트를 바꾸는 것입니다. “한국어로 다시 출력해줘”, “UTF-8로 작성해줘”라고 반복해도 터미널이 잘못 해석하면 결과는 같습니다.
또 하나는 Windows Terminal 설정만 바꾸고 기존 창에서 계속 테스트하는 것입니다. 인코딩 관련 설정은 새 세션에서 확인해야 합니다. 설정 후에는 Claude Code를 종료하고 터미널을 새로 열어 다시 실행하세요.
FAQ
Claude Code 응답만 깨지고 npm 로그는 정상입니다. 왜 그럴까요?
Claude Code가 출력하는 문자 범위와 npm 로그의 문자 범위가 다를 수 있습니다. 한글, 특수문자, 이모지가 섞이면 문제를 더 빨리 드러냅니다. PowerShell 출력 인코딩과 터미널 폰트를 함께 확인하세요.
폰트도 영향을 주나요?
네. 인코딩이 맞아도 폰트가 한글 글리프를 제대로 지원하지 않으면 네모 박스처럼 보일 수 있습니다. Windows Terminal에서는 Cascadia Mono, D2Coding, Noto Sans Mono CJK 계열을 테스트해볼 만합니다.
WSL을 쓰면 해결되나요?
WSL Ubuntu 환경은 UTF-8 기본값이 잘 잡혀 있어 유리합니다. 다만 Windows 파일시스템과 오가며 작업하면 경로, 권한, 줄바꿈 문제가 생길 수 있으니 팀 환경에 맞춰 선택하는 편이 좋습니다.
마지막으로 한 번만 정리하면, 새 Windows Terminal을 열고 PowerShell 7에서 UTF-8 설정을 적용한 뒤 git config --global core.quotepath false를 실행하세요. 그다음 Claude Code를 다시 켜서 한글 README, 한글 파일명, 커밋 메시지를 각각 확인하면 어디서 깨지는지 바로 분리할 수 있습니다.
관련 링크
- ai 코딩 구독 요금 비교: Claude Code·Cursor·Copilot, 빌드용으로 돈값 하는 조합
- claude code artifacts, 웹 미리보기 대신 파일로 남기는 실전 작업법
- claude code 모델 추천: 실제 빌드 작업에서 Sonnet과 Opus를 나눠 쓰는 기준
- 관련 태그 더 보기
- 카테고리 더 보기
- 검색 결과 더 보기
- 참고 링크
