Claude Code 한글이 깨지는 문제 | 던스커버리

Claude Code로 작업하다 보면 한글이 깨지는 문제가 발생한다. 혼자만 그런 건가 싶어 찾아봤더니 이미 정리된 이슈가 있었다.

어떤 증상인가

글자가 깨지는 게 아니다. 멀쩡한 다른 한글로 바뀐다.

의도한 문장   SSO 로그인 점검도 완료된 상황
실제 출력     SSO 로그인 점깔도 완릷된 상황

점검이 점깔이 되고 완료가 완릷이 된다. ???나 占쏙옙 같은 깨짐이었다면 바로 알아챘을 텐데, 이건 형태가 멀쩡해서 훑어볼 때 잘 걸리지 않는다. 이게 문제다.

도구 호출 파라미터에 한글을 넣을 때, 리터럴 UTF-8 대신 \uXXXX 유니코드 이스케이프로 쓰는 경우가 있다고 한다.

리터럴      "점검"
이스케이프   "\uc810\uac80"

이스케이프로 쓰면 코드포인트를 한 자씩 적어 넣게 되는데, 그 과정에서 값이 어긋난다. 사람으로 치면 받아쓰기 중에 숫자를 잘못 옮겨 적는 셈이다.

이해하고 나서 납득이 된 부분이다.

한글 음절은 유니코드에서 U+AC00부터 11,172자가 빈틈없이 이어져 있다. 그래서 값이 조금 어긋나도 여전히 한글 영역 안에 떨어진다. 유효한 글자가 나오니 어디에서도 오류가 나지 않고, 그대로 파일에 저장된다.

영어였다면 값이 어긋나는 순간 엉뚱한 기호나 제어문자가 튀어나와 금방 눈에 띄었을 것이다. 한글은 촘촘해서 오히려 조용히 지나간다.

이슈 #83033 본문에 두 계정으로 나눠 돌린 A/B 실험 결과가 정리되어 있다.

조건	결과
이스케이프로 작성	45회 중 45회 손상 (23/23 + 22/22)
리터럴 UTF-8로 작성	60회 중 1회 손상

손상률이 전부 아니면 전무로 갈리는 걸 보면 원인 지목이 맞아 보인다. 작성 시점 기준으로 이슈는 아직 열려 있다.

이슈에 적힌 해결책은 지시문 한 줄이다. CLAUDE.md나 메모리에 넣으면 된다.

한글 등 비ASCII 문자열은 도구 호출 파라미터에 리터럴 UTF-8로 쓴다.
\uXXXX 유니코드 이스케이프로 표기하지 않는다.

결과를 고치는 방식이 아니라 인풋을 수정하여 원인을 제거하는 방식이라는 점이 마음에 들었다. 받아쓰기를 하지 않으면 잘못 받아쓸 일도 없기 때문이다.

이 블로그 저장소의 CLAUDE.md에 아래와 같이 추가했다.

## 도구 호출

한글 등 비ASCII 문자열을 도구 호출 파라미터에 넣을 때는 리터럴 UTF-8로 그대로 쓴다.
`\uXXXX` 유니코드 이스케이프로 바꿔 쓰지 않는다.

프로젝트 폴더에 두면 해당 폴더에서 여는 모든 세션에 적용된다. 특정 프로젝트가 아니라 전체에 걸고 싶다면 사용자 메모리에 넣으면 된다.

왜 애초에 이스케이프로 쓰는 경우가 생기는지는 알 수 없다. 학습 과정에서 그런 표기를 많이 본 탓일 수도 있고, 다른 이유가 있을 수도 있다.
일본어나 중국어에서도 같은 문제가 생기는지는 확인하지 못했다. 한자·가나도 코드포인트가 촘촘하니 비슷하지 않을까 짐작만 하고 있다.
겪은 증상이 전부 이 원인에서 온 것인지는 확인하지 못했다. 터미널 인코딩 문제로 깨져 보이는 경우도 섞여 있었을 것이다. 다만 비용이 한 줄이라 일단 넣어뒀다.

한글로 AI 도구를 쓰는 입장에서, 이런 건 알고 있는 것과 모르는 것의 차이가 크다. 커밋 메시지나 문서에 조용히 섞여 들어갔다면 한참 뒤에나 발견했을 테니 말이다.