VS Code에서 Claude Code를 켰는데 한글 답변이 어색하거나, 터미널에서 글자가 깨지면 먼저 볼 곳은 세 군데입니다. 터미널 인코딩, 프로젝트 지시문(CLAUDE.md), 그리고 에이전트에게 주는 출력 규칙입니다.
CLAUDE.md 규칙부터 적용하고, 다음 실행에서 한글 응답과 Git diff 흐름을 같이 확인해보세요.
저도 블로그 자동화 파이프라인을 고치다가 같은 문제를 만났습니다. Claude Code 자체가 한글을 못하는 게 아니라, 작업 환경과 프롬프트 경계가 흐려서 영어로 돌아가거나 터미널 표시가 깨지는 경우가 많았습니다.
아래 3단계만 먼저 적용해보세요. 대부분은 재설치 없이 해결됩니다.
내가 실제로 막힌 지점
제 셋업은 macOS에서 VS Code 내장 터미널을 열고, 프로젝트 루트에서 claude를 실행하는 방식이었습니다. 평소에는 Warp 터미널을 더 많이 쓰지만, 코드 수정 흐름을 확인하려고 VS Code 터미널에서 Claude Code를 붙였습니다.
문제는 간단했습니다. 제가 한국어로 요청했는데 Claude가 파일명 설명은 영어로 쓰고, 일부 로그는 깨진 문자처럼 보였습니다. 처음에는 Claude Code 문제라고 생각했는데, 실제 원인은 프로젝트 지시문 부재 + 셸 인코딩 확인 부족에 가까웠습니다.
가장 먼저 적용한 해결 순서
1. 프로젝트 루트에 CLAUDE.md를 둔다
세션마다 “한국어로 답해줘”라고 치는 건 금방 무너집니다. 저는 프로젝트 루트에 CLAUDE.md를 만들고 아래처럼 짧게 고정했습니다.
# 응답 규칙
- 기본 응답은 한국어로 작성한다.
- 코드, 명령어, 파일명은 원문을 유지한다.
- 변경 전에는 수정 계획을 3줄 이내로 요약한다.
- 불확실한 내용은 추측하지 말고 확인 질문을 한다.
이렇게 해두면 Claude Code가 프로젝트 컨텍스트를 읽을 때 말투와 작업 방식이 훨씬 안정됩니다. 특히 README, package.json, Git diff를 같이 보며 수정할 때 “설명은 한글, 코드는 원문”이라는 기준이 잡힙니다.
2. VS Code 터미널이 UTF-8인지 확인한다
macOS나 Linux는 대체로 큰 문제가 없지만, Windows PowerShell에서는 한글 출력이 깨지는 경우가 있습니다. 이때는 먼저 아래 명령으로 코드 페이지를 확인했습니다.
chcp
chcp 65001
그리고 VS Code 설정에서 터미널 폰트가 한글을 제대로 지원하는지도 봐야 합니다. 저는 D2Coding이나 MesloLGS NF처럼 터미널에서 검증된 폰트를 쓰는 쪽을 선호합니다. 폰트 문제면 Claude가 정상 출력해도 화면에서만 깨져 보입니다.
3. 첫 요청에 출력 형식을 못 박는다
CLAUDE.md를 넣어도 첫 요청이 애매하면 영어 섞임이 생길 수 있습니다. 저는 작업 시작 때 이렇게 보냅니다.
이 저장소를 먼저 읽고, 앞으로 설명은 한국어로 해줘.
코드와 커밋 메시지 후보는 원문을 유지해도 돼.
먼저 수정 계획만 짧게 보여줘.
이 문장은 단순하지만 효과가 있었습니다. “한국어만 써”보다 실무에서 덜 답답합니다. 함수명, npm 스크립트, 에러 메시지까지 번역하면 오히려 디버깅이 느려지기 때문입니다.
어디에 한글 지시를 둘까?
매번 프롬프트로 넣을지, 파일로 고정할지 헷갈린다면 아래처럼 나누면 됩니다.
| 방식 | 좋은 점 | 주의할 점 | 추천 상황 |
|---|---|---|---|
| 매 세션 프롬프트 | 빠르고 테스트하기 좋음 | 새 세션에서 잊기 쉬움 | 1회성 수정, 짧은 실험 |
| CLAUDE.md | 프로젝트마다 규칙 고정 | 너무 길면 핵심이 흐려짐 | 블로그 자동화, SaaS 코드베이스 |
| 터미널/셸 설정 | 깨짐 문제의 근본 해결 | OS별 명령이 다름 | Windows, 원격 서버, 컨테이너 작업 |
구체적인 예: 블로그 자동화 스크립트 고칠 때
가령 scripts/generate-post.ts가 있고, Claude Code에게 “워드프레스 JSON 출력이 깨지는 원인을 찾아줘”라고 맡긴다고 해보겠습니다. 이때 저는 바로 수정시키지 않고 아래 순서로 돌립니다.
claude
> 이 프로젝트를 읽고 한국어로 설명해줘.
> scripts/generate-post.ts에서 JSON 문자열 깨짐 가능성이 있는 부분만 찾아줘.
> 수정 전에는 파일명, 원인, 수정안을 표로 정리해줘.
이렇게 하면 Claude가 무작정 여러 파일을 바꾸기보다, 인코딩·이스케이프·출력 포맷을 먼저 좁혀줍니다. 실제 작업에서는 Git diff를 보면서 한 번에 작은 변경만 승인하는 편이 안전했습니다.
이 셋업이 특히 맞는 사람
VS Code는 쓰지만 IDE 안에서 길게 채팅하고 싶지 않은 사람
Cursor처럼 에디터 안에서 대화하는 흐름도 좋지만, 저는 요즘 터미널 중심 루프가 더 편합니다. git status, 테스트 명령, Claude Code 실행을 한 화면에서 반복하면 생각의 끊김이 적습니다.
한국어 설명은 필요하지만 코드 품질은 놓치기 싫은 사람
입문자에게는 한글 설명이 속도를 올려줍니다. 다만 에러 텍스트와 API 이름까지 번역하면 검색성이 떨어집니다. 그래서 “설명은 한국어, 코드와 로그는 원문” 규칙을 권합니다.
자주 묻는 질문
Q. Claude Code가 계속 영어로 답하면 어떻게 하나요?
세션 첫 메시지에 언어 규칙을 다시 넣고, 프로젝트 루트의 CLAUDE.md가 실제로 있는지 확인하세요. 하위 폴더에서 실행하면 의도한 파일을 못 읽는 것처럼 느껴질 때가 있습니다.
Q. 한글 입력은 되는데 출력만 깨집니다.
대부분 터미널 표시 문제입니다. Windows라면 chcp 65001을 확인하고, VS Code 터미널 폰트를 한글 지원 폰트로 바꿔보세요. 원격 SSH 환경이면 서버 로케일도 같이 봐야 합니다.
Q. 모든 답변을 한국어로 강제하는 게 좋나요?
저는 권하지 않습니다. 코드, 명령어, 에러 메시지, 라이브러리 이름은 원문이 낫습니다. 대신 의사결정 과정과 수정 이유를 한국어로 받는 쪽이 실전에서 더 빠릅니다.
흔한 실수 하나
가장 많이 돌아가는 길은 확장 프로그램부터 의심하는 겁니다. 하지만 vscode 클로드코드 한글 문제는 재설치보다 작업 규칙과 터미널 표시를 먼저 봐야 합니다. 설정이 흐린 상태에서 모델만 바꾸면 같은 문제가 반복됩니다.
지금 바로 할 일
- 프로젝트 루트에 짧은
CLAUDE.md를 만든다. - VS Code 터미널에서 UTF-8과 폰트를 확인한다.
- 첫 요청에 “설명은 한국어, 코드·로그는 원문”을 명시한다.
- 수정 전 계획 → 작은 변경 → Git diff 확인 루프로 작업한다.
여기까지 적용하면 vscode 클로드코드 한글 환경은 꽤 안정됩니다. 다음 단계는 내 프로젝트에 맞는 CLAUDE.md를 더 짧고 강하게 다듬는 것입니다.
오늘도, 코딩할 용기.
관련 링크
- .env 시크릿을 깃에 안 올리고 관리하기 gitignore 실수 복구까지, AI 코딩 프로젝트에서 바로 쓰는 셋업
- AutoWP 개발기 — OpenAI로 WordPress 콘텐츠 파이프라인을 만들고 사람이 검수하는 반자동 시스템
- PyInstaller onefile exe가 윈도우 디펜더에 오탐 차단될 때 뚫은 방법: 우회 말고 신뢰도부터 올렸다
- 관련 태그 더 보기
- 카테고리 더 보기
- 검색 결과 더 보기
- 참고 링크
