text-encoding-guard: AI 코딩 어시스턴트의 중국어 깨짐 현상 자동 탐지 및 복구

AI 코딩 어시스턴트가 중국어를 깨진 글자(乱码)로 만드나요? 자동 탐지, 원클릭 복구.

AI 코딩 어시스턴트(Claude, Cursor, Copilot, Codex)가 중국어가 포함된 파일을 편집할 때, 인코딩 손상이 조용히 발생할 수 있습니다. UTF-8 바이트가 GBK로 잘못 읽히는 현상 — 사용자가 깨진 글자를 보게 되었을 때는 이미 늦은 상태입니다.

복구 전 (깨진 글자) 복구 후 (정상)
───────────────────── ─────────────────────
// 鐢ㄦ埛鐧诲綍鎴愬姛 // 用户登录成功
...

HTML 태그 손상도 포착할 수 있습니다:

<!-- AI 편집 후 → 태그 손상 -->
<p>鐢ㄦ埛涓�績</p>
?/div> <!-- ← </div>의 < 가 사라짐 -->
...

시나리오	발생 확률	결과
Claude Code가 중국어가 포함된 Vue/React 컴포넌트 편집	매우 높음	UI 문구가 모두 깨져서 사용자가 직접 보게 됨
Cursor가 중국어 주석을 일괄 리팩토링	높음	코드 가독성이 제로가 되어 신규 개발자가 이해 불가
Copilot이 중국어 문서 생성	중간	README / CHANGELOG가 외계어로 변함
CI/CD 자동화 스크립트가 중국어 파일 처리	중간	조용히 손상되어 배포 후에야 발견됨

git clone https://github.com/haodehaode378/text-encoding-guard.git
cd text-encoding-guard
pip install -e .

# 프로젝트 스캔
check-mojibake --root ./src
# 자동 복구 (.bak 백업 생성)
...

설치 없이 바로 사용하기

python scripts/check_mojibake.py --root ./src
# 또는
python -m check_mojibake --root ./src

깨진 글자 유형	발생 원인	탐지 신호	가중치
口字码 (구자코드)	UTF-8을 GBK로 읽음	Unicode 대체 문자 �	+12
파손된 태그	AI 편집 중 꺽쇠 괄호 삼킴	손상된 HTML 닫기 태그	+10
고문 코드 (古文码)	GBK를 UTF-8로 읽음	18개의 알려진 깨진 코드 포인트	+2
锟拷码 (쿤카오코드)	UTF-8→GBK→UTF-8 이중 변환	锟斤拷 패턴 매칭	+8
烫屯码 (탕툰코드)	VC 디버깅 시 초기화되지 않은 메모리	烫烫烫 / 屯屯屯 반복	+6
물음표 코드	이중 변환	중국어 뒤에 연속된 ??	+8
기호 코드	ISO8859-1로 UTF-8을 읽음	라틴 확장 문자가 밀집되어 나타남	+2

파일 총점이 0보다 크면 의심스러운 파일로 표시됩니다. 점수가 높을수록 깨진 글자의 심각도가 높습니다.

--fix-gbk

무분별한 교체가 아니라, 3중 안전 장치를 따릅니다:

① GB18030 인코딩 시도 → UTF-8 디코딩 (역방향 복구)
또한 반대 방향도 시도: UTF-8 인코딩 → GB18030 디코딩
↓
...

name: Encoding Guard
on: [push, pull_request]
jobs:...

PR(Pull Request)에서 깨진 글자를 자동으로 차단합니다.

선택적 파라미터

- uses: haodehaode378/text-encoding-guard@v1
with:
  root: './src' # 스캔 디렉토리 (기본값 .)
...

첫 번째 단계 — PostToolUse hook 추가:

{
"hooks": {
"PostToolUse": [
...

두 번째 단계 (선택 사항) — skill 설치:

cp -r .claude/skills/text-encoding-guard/ /path/to/your/project/.claude/skills/

파라미터	설명	예시
--root PATH	스캔할 루트 디렉토리 (필수)	--root ./src
--json	JSON 형식으로 출력	--json
--fail-on-find	의심스러운 파일 발견 시 종료 코드 2 반환	--fail-on-find
--fix-gbk	GBK에서 UTF-8로 자동 복구 시도	--fix-gbk
--ext	추가 확장명 추가 (여러 번 사용 가능)	--ext .sql --ext .cfg
--verbose	상세 진단 정보 표시	-v
--quiet	정적 모드 (Silent mode)	-q

기본 20개 확장명:
.py

.md

.txt

.json

.yaml

.yml

.toml

.ini

.js

.ts

.tsx

.jsx

.vue

.html

.css

.scss

.sh

.bat

.ps1

.xml

자동 스킵 대상:
.git

node_modules

dist

build

__pycache__

.venv

venv

target

.idea

.vscode

.claude

비교 항목	본 도구	수동 검사	file/uchardet
깨짐(Mojibake) 정밀 탐지	✅ 점수제 (Scoring system)	❌ 육안 확인	❌ 인코딩만 탐지
...

# 개발 의존성 설치
pip install -e ".[test]"
# 테스트 실행
...

AI 에이전트가 중국어 텍스트를 손상시키고 있나요? 탐지하고, 복구하고, 배포하세요.

AI 코딩 어시스턴트(Claude, Cursor, Copilot, Codex)가 중국어 텍스트가 포함된 파일을 편집할 때, 인코딩 손상이 소리 없이 침투합니다. UTF-8 바이트가 GBK로 잘못 읽히게 되며, 사용자가 깨진 글자를 보기 전까지는 알아차리기 어렵습니다.

이전 (손상됨) 이후 (복구됨)
───────────────────── ─────────────────────
// 鐢ㄦ埛鐧诲綍鎴愬姛 // 用户登录成功
...

손상된 HTML 태그도 포착됩니다:

<!-- AI 편집 후 — 깨진 태그 -->
<p>鐢ㄦ埛涓�績</p>
?/div> <!-- ← </div
의 < 가 유실됨 -->
...

시나리오	위험도	영향
Claude Code가 중국어가 포함된 Vue/React 편집	매우 높음	UI 텍스트가 깨져서 사용자에게 노출됨
Cursor가 중국어 주석을 일괄 리팩토링	높음	코드 가독성이 완전히 상실됨
Copilot이 중국어 문서 생성	중간	README / CHANGELOG를 읽을 수 없게 됨
CI/CD 스크립트가 중국어 파일 처리	중간	배포 후에야 발견되는 소리 없는 손상

git clone https://github.com/haodehaode378/text-encoding-guard.git
cd text-encoding-guard
pip install -e .

# 프로젝트 스캔
check-mojibake --root ./src
# 자동 복구 (.bak 백업 생성)
...

설치 없이 실행하기

python scripts/check_mojibake.py --root ./src
# 또는
python -m check_mojibake --root ./src

유형 (Type)	원인 (Cause)	신호 (Signal)	가중치 (Weight)
박스 문자 (Box chars)	UTF-8을 GBK로 읽음	유니코드 대체 문자 �	+12
깨진 태그 (Broken tags)	AI가 꺾쇠괄호(㰮⟩)를 삼킴	손상된 HTML 종료 태그	+10
고어 (Ancient text)	GBK를 UTF-8로 읽음	18개의 알려진 모지바케 (mojibake) 코드 포인트	+2
쿤카오 (Kun-Kao)	UTF-8→GBK→UTF-8 이중 변환	锟斤拷 패턴 매칭	+8
탕툰 (Tang-Tun)	VC의 미초기화 메모리 디버깅	烫烫烫 / 屯屯屯 반복	+6
물음표 코드 (Question code)	이중 변환	중국어 뒤에 연속된 ?? 발생	+8
기호 코드 (Symbol code)	ISO8859-1을 UTF-8로 읽음	밀집된 라틴 확장 문자 (Latin Extended characters)	+2

점수가 0보다 큰 모든 파일은 플래그(flag)가 지정됩니다. 점수가 높을수록 손상 정도가 심함을 의미합니다.

--fix-gbk 옵션은 무분별한 치환이 아닙니다. 이는 **3단계 안전 게이트 (triple safety gate)**를 따릅니다:

① GB18030 인코딩 시도 → UTF-8 디코딩 (역방향 복구)
반대 방향도 시도: UTF-8 인코딩 → GB18030 디코딩
↓
...

name: Encoding Guard
on: [push, pull_request]
jobs:
...

모지바케 (mojibake)가 포함된 PR (Pull Request)은 자동으로 차단됩니다.

선택적 파라미터 (Optional parameters)

- uses: haodehaode378/text-encoding-guard@v1
with:
root: './src' # 스캔 디렉토리 (기본값 .)
...

1단계 — PostToolUse 훅 (hook) 추가:

{
"hooks": {
"PostToolUse": [
...

2단계 (선택 사항) — 스킬 (skill) 설치:

cp -r .claude/skills/text-encoding-guard/ /path/to/your/project/.claude/skills/

플래그 (Flag)	설명 (Description)	예시 (Example)
--root PATH	스캔할 루트 디렉토리 (필수)	--root ./src
--json	JSON 출력	--json
--fail-on-find	의심스러운 파일 발견 시 종료 코드 2 반환	--fail-on-find
--fix-gbk	GBK→UTF-8 자동 복구 시도	--fix-gbk
--ext	추가 확장자 추가 (반복 가능)	--ext .sql --ext .cfg
--verbose	상세 진단 정보 표시	-v
--quiet	출력 억제	-q

기본 20개 확장자:
.py

.md

.txt

.json

.yaml

.yml

.toml

.ini

.js

.ts

.tsx

.jsx

.vue

.html

.css

.scss

.sh

.bat

.ps1

.xml

자동 제외 (Auto-skipped):
.git

node_modules

dist

build

pycache

.venv

venv

target

.idea

.vscode

.claude

기능 (Feature)	본 도구 (This Tool)	수동 확인 (Manual Check)	file/uchardet
정밀한 글자 깨짐 (mojibake) 탐지	✅ 점수 산정 (Scoring)	❌ 육안 확인 (Eyeball)	❌ 인코딩만 확인 (Encoding only)
...

# 개발 의존성 설치 (Install dev dependencies)
pip install -e ".[test]"
# 테스트 실행 (Run tests)
...