claude-utf8-guard

한국어 | English | 日本語

Claude가 도구 호출의 한글, 일본어, 중국어를 \uXXXX 이스케이프로 쓰다가 엉뚱한 글자로 바꾸는 문제를 막는 Claude Code 플러그인입니다.

AskUserQuestion, TodoWrite, Notion이나 Jira MCP 도구 같은 도구 호출에서 Claude는 한글을 글자 대신 \uXXXX 이스케이프로 쓰기도 합니다. 이때 hex를 틀리게 적으면 이스케이프가 다른 실제 음절로 풀려서, 누군가 읽기 전까지는 깨진 줄 모릅니다. 일본어에서도 揃え가 諿え로, 側이 간체자 侧로 바뀌는 등 같은 증상이 보고됐습니다. 이 플러그인은 세션이 시작될 때 UTF-8 글자 그대로 쓰라고 Claude에게 알려 주고, 도구를 호출하기 전마다 깨져 보이는 글자가 있으면 그 호출을 한 번 멈춥니다. 원인 이슈가 고쳐지면 세션을 시작할 때 플러그인을 꺼도 된다고 알려 줍니다.

Website · Releases · Changelog

Claude가 쓴 도구 입력	화면에 보이는 글자
{"content": "\uc810\uae54\ub3c4 \uc644\ub9b7\ub41c"} (이스케이프, hex가 틀림)	점깔도 완릷된
{"content": "점검도 완료된"} (이 플러그인이 안내하는 UTF-8)	점검도 완료된

만든 이유

anthropics/claude-code#83033 (Sonnet 5 writes Korean tool-call parameters as \uXXXX escapes and mis-spells the hex) 때문입니다.

이 이슈의 작성자는 한국어 도구 호출을 이스케이프로 쓰게 한 실행과 UTF-8로 쓰게 한 실행을 비교했습니다. 이스케이프로 쓴 실행은 45번 모두 한글 일부가 깨졌고(음절의 약 3~5%), UTF-8로 쓰게 한 실행은 30번 중 1번, 30번 중 0번이었습니다. 깨진 글자는 점검 → 점깔, 코딩 → 코딅처럼 모두 실제로 있는 한글이라 U+FFFD처럼 눈에 띄지 않습니다. 댓글에서는 Opus 5와 Notion, Jira MCP 쓰기 도구에서도 같은 증상이 보고됐습니다.

일본어도 마찬가지입니다. #54051은 Notion MCP 호출에서 揃え → 諿え, 処分 → 処勭, 側 → 侧(간체자), 億 → 亿(간체자)으로 바뀌었다고 보고했고, #59649는 AskUserQuestion에서 叩き → 鯰し, 再起動 → 在控, 鳴る → 鳥る로 바뀌었다고 보고했습니다. 두 이슈 모두 이스케이프가 원인인지는 확인되지 않았습니다. 그래서 이 플러그인은 원인이 아니라 결과를 검사합니다.

Claude Code 쪽 답변은 CLI가 이스케이프를 받은 그대로 풀 뿐이라 틀린 코드포인트를 고칠 수 없고, 이 이슈를 모델 팀에 넘겼다는 것입니다. 같은 증상의 다른 보고들은 대부분 고쳐지지 않은 채 닫혔습니다(아래 관련 이슈). #83033이 고쳐진 것으로 닫히면 이 플러그인은 필요 없어지므로, 그때 레포를 보관(archive)할 예정입니다. 플러그인은 세션을 시작할 때, CI는 매일 #83033의 상태를 확인합니다.

설치

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

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

Add marketplace?에 y를 누르고 scope는 user를 고릅니다. 셸에서는 이렇게 설치합니다.

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

Claude Desktop에서는 프롬프트 옆 + → Plugins → Add marketplace에 M1nu0x0/claude-utf8-guard를 넣고 utf8-guard를 추가합니다.

훅은 Node.js로 실행되므로 PATH에 Node.js 18 이상이 있어야 합니다. 설치한 뒤 새 세션부터 적용됩니다.

동작

1. 세션 시작(SessionStart): Claude에게 지시 한 줄을 넣습니다(additionalContext). 도구 호출의 비ASCII 문자는 \uXXXX 이스케이프가 아니라 UTF-8 글자 그대로 쓰고, 그대로 옮겨 적는 코드 속 이스케이프(소스 파일의 "\u200b" 등)만 예외로 두라는 내용입니다. #83033에서 효과가 확인된 우회법입니다. startup, resume, clear, compact마다 다시 넣습니다.

2. 도구 호출 전(PreToolUse): 입력의 모든 문자열을 검사합니다(아래 표). 걸리면 호출을 거부(deny)하고 어떤 글자가 어디 있는지 Claude에게 알려 주며, 사용자에게도 한 줄 보여 줍니다(systemMessage). 같은 세션에서 같은 호출을 그대로 다시 보내면 통과합니다. 의도한 드문 단어라면 한 번 더 주고받을 뿐 작업이 막히지 않습니다.

3. 원인 이슈 확인: 세션 시작 훅은 플러그인 데이터 폴더(CLAUDE_PLUGIN_DATA)의 캐시만 읽어서 네트워크를 기다리지 않습니다. 캐시가 하루 지났으면 백그라운드 프로세스가 GitHub API에 #83033의 상태를 한 번 묻고 다음 세션을 위해 저장합니다. #83033이 completed로 닫혔으면 새 세션을 시작할 때(startup) 아래처럼 알려 줍니다. not planned나 stale로 닫힌 것은 고쳐졌다는 뜻이 아니라서 알리지 않습니다.

   utf8-guard: anthropics/claude-code#83033 was closed as fixed on 2026-12-01 (...). If Claude no longer writes
   broken \uXXXX escapes, turn this plugin off with "claude plugin disable utf8-guard". To stop this notice, turn off
   "Notify when fixed upstream" in /config.
   

Claude Code는 훅에 넘기기 전에 모델이 쓴 JSON을 먼저 풉니다. 그래서 훅은 이스케이프 자체를 볼 수 없고, 그것이 바뀐 결과만 봅니다. 검사가 "이스케이프를 썼는가"가 아니라 "깨진 결과처럼 보이는가"인 이유입니다.

막는 것과 못 막는 것

증상	예	검사	이 플러그인
hex를 틀려 드문 음절이 됨	완료 → 완릷, 코딩 → 코딅, 멀쩡 → 멀잩	KS X 1001(EUC-KR) 2,350자 밖의 한글 음절	막음. hex 한 자리를 틀린 경우의 약 70%
틀린 한자가 드문 한자가 됨	揃え → 諿え, 処分 → 処勭, 側 → 侧(간체자)	가나가 섞인 문장에서 JIS X 0208(Shift_JIS) 6,355자 밖의 한자	막음. hex 한 자리를 틀린 경우의 약 66%. 가나가 없는 문장(중국어일 수 있음)은 검사 안 함
짝 없는 서로게이트	\uD83A 하나만 있음, API가 400으로 거부하고 세션이 멈춤	짝 없는 U+D800~DFFF	막음
디코딩 실패	한�글	U+FFFD	막음
이스케이프가 텍스트로 남음	AskUserQuestion에 \uc810\uac80이 그대로 보임	코드가 아닌 도구에서 한글, 가나, 한자를 가리키는 \uXXXX 텍스트	막음
hex를 틀려 흔한 음절이 됨	잡히지 → 잡힐지, 점검 → 점깔	구별할 방법 없음	못 막음. 세션 시작 지시로 예방만
틀린 한자가 흔한 한자가 됨	鳴る → 鳥る, 再起動 → 在控, 중국어 문장의 틀린 한자	다른 실제 글자라 구별 불가	못 막음. 지시로 예방만
이스케이프 중간 글리치로 JSON이 깨짐	#79339	훅이 돌기 전에 Claude Code가 거부(#93311)	못 막음. 지시로 예방만
이스케이프 없이 틀린 음절	새벽 → 새벅 (#83033, 0.3~0.4%)	KS X 1001 밖이면 잡힘	일부만

드문 음절 검사는 똠, 햏, 뷁, 쌰 같은 실제 단어에도, 한자 검사는 JIS X 0208에 없는 인명용 한자에도 걸립니다. 2010년 상용한자 추가분 剝, 頰, 塡과 이름에 흔한 髙은 미리 허용해 두었습니다. 이때는 Claude가 이유를 보고 같은 호출을 다시 보내 통과하거나, 아래 설정에서 이 검사만 끌 수 있습니다. Read, Glob, Grep처럼 읽기만 하는 도구는 검사하지 않습니다. Write, Edit, Bash처럼 코드를 다루는 도구에서는 텍스트로 적힌 \uXXXX를 의도한 것으로 보고 검사하지 않습니다.

설정과 끄기

/config(또는 /plugin)의 utf8-guard 항목에서 바꿉니다. 값은 settings.json의 pluginConfigs에 저장됩니다.

설정	기본값	끄면
Notify when fixed upstream (upstream_check)	켜짐	GitHub에 묻지 않고, 고쳐졌다는 알림도 보이지 않음
Check Korean syllables (hangul_check)	켜짐	드문 한글 음절 검사만 빠짐. 서로게이트, U+FFFD, 텍스트 이스케이프 검사와 세션 시작 지시는 그대로
Check Japanese kanji (kanji_check)	켜짐	일본어 문장의 드문 한자 검사만 빠짐

플러그인 전체를 끄려면 claude plugin disable utf8-guard, 제거하려면 claude plugin uninstall utf8-guard를 실행합니다.

관련 이슈

배지는 각 이슈의 현재 상태(open/closed)를 보여줍니다.

원인 이슈

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗