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 태그도 포착됩니다:
| 시나리오 | 위험도 | 영향 |
|---|
| 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)
...