UTF-8 Guard for Claude

설치

Claude Code 터미널 프롬프트에서:

/plugin install utf8-guard --marketplace M1nu0x0/claude-utf8-guard

Add marketplace?에 y를 누르고 scope는 user를 고릅니다. PATH에 Node.js 18 이상이 있어야 합니다.

셸에서는:

claude plugin install utf8-guard --marketplace M1nu0x0/claude-utf8-guard

Claude Desktop에서는 프롬프트 옆 + → Plugins → Add marketplace에 M1nu0x0/claude-utf8-guard를 넣고 utf8-guard를 추가합니다. 다음 세션부터 적용됩니다.

전과 후

tool_use TodoWrite {"content": "\uc810\uae54\ub3c4 \uc644\ub9b7\ub41c"}
card  ☐ 점깔도 완릷된

tool_use TodoWrite {"content": "점검도 완료된"}
card  ☐ 점검도 완료된

만든 이유

AskUserQuestion, TodoWrite, Notion이나 Jira MCP 도구 같은 도구 호출에서 Claude가 한글을 글자 대신 \uXXXX 이스케이프로 쓰는 경우가 있습니다. hex 한 자리를 틀려도 이스케이프는 실제 음절로 풀리기 때문에, 누군가 읽기 전까지는 깨진 줄 모릅니다.

anthropics/claude-code#83033은 두 방식을 비교했습니다. 이스케이프로 쓴 실행은 45번 모두 한글 일부(음절의 약 3~5%)가 깨졌고, UTF-8로 쓰라고 한 실행은 거의 깨지지 않았습니다. Claude Code는 이스케이프를 받은 그대로 풀 뿐이라 틀린 코드포인트를 고칠 수 없고, 이 이슈는 모델 팀으로 넘어갔습니다.

일본어도 마찬가지입니다. #54051은 Notion MCP 호출에서 揃え가 諿え로, 処分이 処勭으로, 側이 간체자 侧로 바뀌었다고 보고했고, #59649는 AskUserQuestion에서 叩き가 鯰し로, 再起動이 在控으로 바뀌었다고 보고했습니다. 이스케이프가 원인인지는 확인되지 않았기 때문에, 이 플러그인은 원인 대신 결과를 검사합니다.

이 이슈가 고쳐진 것으로 닫히면 이 플러그인은 필요 없어집니다. 그때는 세션을 시작할 때 알려 주고, CI도 매일 이슈 상태를 확인합니다.

동작

세션이 시작될 때 SessionStart 훅이 Claude에게 지시 한 줄을 넣습니다. 도구 호출의 비ASCII 문자는 \uXXXX 이스케이프가 아니라 UTF-8 글자 그대로 쓰고, 그대로 옮겨 적는 코드 속 이스케이프만 예외로 두라는 내용입니다. #83033에서 효과가 확인된 우회법입니다.

도구를 호출하기 전마다 PreToolUse 훅이 입력의 텍스트를 봅니다. 깨져 보이는 글자가 있으면 호출을 한 번 멈추고 어떤 글자가 어디 있는지 Claude에게 알려 줍니다. 같은 호출을 그대로 다시 보내면 통과하므로, 의도한 드문 단어라면 한 번 더 주고받을 뿐 작업이 막히지 않습니다.

하루에 한 번 세션 시작 훅이 백그라운드에서 GitHub에 #83033이 고쳐진 것으로 닫혔는지 묻습니다. 닫혔으면 세션을 시작할 때 플러그인을 꺼도 된다는 한 줄이 보입니다. 이 알림과 한글, 한자 검사는 /config에서 끌 수 있습니다.

검사하는 것

Claude Code는 훅에 넘기기 전에 모델의 JSON을 먼저 풀기 때문에, 훅은 이스케이프 자체가 아니라 그것이 바뀐 결과만 봅니다.

드문 한글 음절

한국어 문장 대부분을 덮는 KS X 1001(EUC-KR)의 2,350자 밖의 음절. hex 한 자리를 틀리면 약 70%가 이 밖으로 떨어집니다. #83033의 릷, 딅, 잩을 잡습니다.

드문 한자

가나가 섞인 문장에서 JIS X 0208(Shift_JIS)의 한자 6,355자 밖의 한자. #54051의 諿, 勭, 간체자 侧, 亿을 잡습니다. hex 한 자리를 틀리면 약 66%가 이 밖으로 떨어집니다. 가나가 없는 문장은 중국어일 수 있어 검사하지 않습니다.

짝 없는 서로게이트

\uD83A 같은 반쪽 문자. API가 400으로 거부해 세션이 끝날 수 있습니다.

U+FFFD

디코딩에 실패한 자리에 남는 대체 문자.

\uXXXX

질문, 할 일, MCP 호출처럼 코드가 아닌 곳에 글자 대신 텍스트로 적힌 한글, 가나, 한자의 이스케이프.

틀린 글자가 그 자체로 흔한 글자이면 잡지 못합니다. hex가 다른 흔한 음절에 떨어진 경우(잡히지가 잡힐지로)나 鳴이 鳥로, 再起動이 在控으로 바뀐 경우입니다. 훅이 돌기 전에 Claude Code가 거부한 호출과 중국어 문장의 틀린 한자도 잡지 못합니다.

관련 이슈

배지는 각 이슈의 현재 상태입니다.

원인

#83033

Claude가 도구 호출 파라미터의 한글을 \uXXXX로 쓰고 hex를 틀림. 이 플러그인을 만든 이유.

같은 증상

#80009

AskUserQuestion 입력의 한글 음절이 깨짐. 세션 로그에서 확인됨.

#78996

긴 한국어 세션에서 한글이 잘못된 형태로 무너짐.

#57981

AskUserQuestion에서 틀렸지만 실제로 있는 음절이 가끔 나옴.

#53665

Opus 4.7에서 tool_use JSON 파라미터의 한글이 깨짐.

#82588

Opus 5가 틀린 한글 음절을 씀.

#79339

이스케이프 중간에 글리치가 나서 도구 입력 전체를 파싱할 수 없음.

#61670

짝 없는 \uD83A와 깨진 한글로 세션이 끝남.

#69522

이스케이프로 쓴 긴 도구 인자가 파싱에 실패함.

#54051

Notion MCP 도구로 쓴 일본어에 틀린 한자가 섞임. 일부는 간체자.

#59649

Opus 4.7의 AskUserQuestion에 비슷하게 생긴 틀린 한자가 나옴.

#56003

AskUserQuestion에 일본어가 \uXXXX 그대로 보임.

#78568

번체 중국어 출력에 틀린 글자가 섞임.

도구가 만드는 같은 이스케이프

#99361

이스케이프 형태로 일치한 뒤 Edit이 new_string의 비ASCII 문자를 모두 이스케이프로 씀.

#72957

Write와 Edit이 파일 내용의 \uXXXX를 풀어 버림.

훅이 볼 수 없는 것

#93311

입력 검증에서 거부된 호출은 PreToolUse에 오지 않음.

#96285

훅 stdin은 UTF-8인데 Windows의 Python 훅은 ANSI로 읽음. 이 플러그인은 UTF-8로 읽음.

자주 묻는 질문