Humanize KR — 한글 AI 티 제거기 v2.3.2
English: README.en.md
AI(ChatGPT · Claude · Gemini 등)가 쓴 한글 글을 사실 · 주장 · 수치는 바꾸지 않고 문체 · 리듬 · 표현만 자연스러운 한국어로 되돌리는 CLI 스킬입니다.
번역투, 과도한 영어 인용, 기계적 병렬 ("첫째 · 둘째 · 셋째"), "결론적으로 / 시사하는 바가 크다" 같은 AI 특유 관용구, 피동태 남용, 문두 접속사 남발, 이모지·불릿 남용 등 10대 카테고리 × 85 서브 패턴(+검증 대기 hold 1건 포함)을 심각도(S1/S2/S3)로 분류해 스팬 단위로 탐지한 뒤, 윤문합니다.
설치 (Install)
Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, Gemini CLI를 지원합니다. 전체 가이드: INSTALL.md
GitHub Copilot CLI — 플러그인 마켓플레이스 (클론 불필요, 권장)
copilot plugin marketplace add epoko77-ai/im-not-ai
copilot plugin install humanize-korean@im-not-ai
copilot plugin list
Copilot에서 humanize-korean 스킬로 이 글의 AI 티를 없애줘:처럼 요청하거나 /skills list로 로드 여부를 확인하세요. 업데이트는 copilot plugin update humanize-korean@im-not-ai, 제거는 copilot plugin uninstall humanize-korean@im-not-ai입니다. Copilot은 단일 호출 경로만 제공하며 Claude Code 전용 진단·finalize 다중 호출 경로는 실행하지 않습니다.
호환성 참고: 1.0.79-5에서는 copilot plugin install epoko77-ai/im-not-ai도 동작하지만, CLI가 저장소 직접 설치의 사용 중단 예정 경고를 표시합니다. 신규 설치 경로로는 권장하지 않습니다.
Claude Code — 플러그인 마켓플레이스 (클론 불필요, 권장)
/plugin marketplace add epoko77-ai/im-not-ai
/plugin install humanize-korean@im-not-ai
새 세션에서 /humanize-korean (또는 자연어로 "이 글 AI 티 없애줘").
Claude Code · Codex CLI — 클론 + 스크립트
git clone https://github.com/epoko77-ai/im-not-ai.git
cd im-not-ai
./install.sh # 설치된 claude/codex 자동 감지 → 전역 심링크
- Claude:
/humanize-korean · Codex: $humanize-korean
- 한쪽만:
./install.sh --claude-only / --codex-only / --gemini-only · 제거: ./uninstall.sh
- 업데이트:
./update.sh — 새 버전 자동 감지 후 git pull + 재설치(--check는 감지만). 마켓플레이스 설치는 /plugin update.
- Codex도 light·standard·heavy 전체 경로를 제공합니다. 협업 에이전트가 있으면 진단·윤문·finalize를 독립 실행하고, 없으면 같은 역할을 순차 실행합니다.
Gemini CLI — 원격 설치 (클론 불필요, Gemini CLI 0.14.0 이상)
gemini extensions install https://github.com/epoko77-ai/im-not-ai.git
새 세션에서 /humanize-korean(또는 /humanize). 업데이트는 gemini extensions update im-not-ai, 제거는 gemini extensions uninstall im-not-ai입니다. 클론해 둔 경우 ./install.sh --gemini-only로도 연결됩니다.
Gemini 확장은 별도 룰북을 씁니다. GEMINI.md에 패턴 47종을 내장한 독립 배포물(확장 버전 1.5.0)이라, 본체 분류 체계(85 서브 패턴)와 route_hint 3경로·결정적 게이트는 적용되지 않습니다. 자세한 내용: RELEASING.md · INSTALL.md
왜 한글 특화인가
영어권 humanizer(QuillBot · Hix · Undetectable AI)는 한국어에 약합니다. 한글 AI 글의 티는 대부분 영어 번역투에서 나옵니다.
- "AI 기술을 통해 효율을 높일 수 있다" → "AI로 효율을 높일 수 있다"
- "이에 있어서 중요한 점은" → "여기서 중요한 건"
- "~에 의해 생성된" → "~가 만든"
- "결론적으로, 이는 시사하는 바가 크다" → (삭제)
이 도구는 그 한글 고유 패턴을 SSOT로 정리하고, 글의 상태에 맞는 세 경로(light 1콜 / standard 2콜 / heavy 3+콜) 중 하나로 윤문합니다. 잘 쓴 글일수록 콜 수가 줄어 빠르고 싸게 끝납니다.
4대 철칙
- 의미 불변 — 사실 · 주장 · 수치 · 고유명사 · 직접 인용은 100% 원문 보존.
- 근거 기반 — 탐지된 span에만 수술적 수정. 탐지 없는 구간은 건드리지 않음.
- 장르 유지 — 칼럼을 문학으로, 리포트를 에세이로 옮기지 않음.
- 과윤문 금지 — 변경률 30% 초과 시 경고, 50% 초과 시 강제 중단.
아키텍처 (v2.3) — route_hint 3경로 + 구조 수렴 게이트
입력을 shim(prepare_monolith_input.py)이 먼저 정량 채점하고, 그 점수로 route_hint(light | standard | heavy) 를 결정적으로 산출합니다. 글의 상태가 경로를 정하고, 경로가 콜 수를 정합니다. 절감은 모델 교체가 아니라 콜 수 축소에서 옵니다(모델 선택은 사용자 몫).
| 경로 | LLM 콜 수 | 언제 | 파이프라인 |
|---|
| light | 1 | 잘 쓴 글 — 어휘 티가 거의 0 | 진단·finalize 생략, 보수 강도 단일 윤문. 손댈 게 거의 없으면 "이미 좋습니다"로 조기 종료 |
| standard | 2 | 보통의 AI 초안 — 어휘·구조 티 섞임 | 진단 1콜 + 겨냥 윤문 1콜. 1만자급도 청킹 없이 단일 윤문 콜 |
| heavy | 3+ | 중증 AI 슬롭 밀집 or 초장문(15,000자 초과) or 검증 증적 필요 | 진단 → 윤문(shim이 청크를 2개 이상 만든 경우에만 청크 병렬) → finalize |
입력 텍스트
↓
[prepare_monolith_input.py] ── 정량 사전 점수 (KatFish·post-editese 지표) + route_hint 산출
↓ 실패 시 점수 없이 standard로 자동 진행 (graceful degrade)
├─ light ────→ [humanize-monolith ×1] ────────────────────────────→ final.md
├─ standard ─→ [humanize-diagnostician] → [monolith 겨냥 윤문] ───→ final.md
└─ heavy ────→ [diagnostician] → [monolith(필요시 청크 병렬)] → [humanize-finalizer]
↓
[verify_gates.py] ── 문자율·목표달성·대구 전멸·golden/수치 검증 — 모든 경로 공통
- 사용자 명시가 route_hint를 오버라이드합니다:
--strict·"정밀 모드" → heavy 고정, "가볍게" → light 고정.
- 단일 콜 우선: 청킹은 heavy 전용이며 15,000자 이하는 비권장. 실측으로 1만자 글을 청킹 7콜로 돌리면 610K 토큰, 단일 콜이면 134K(4.5배 절감, 품질 동등)였습니다 — 청크마다 룰북·진단을 재로드하는 비용이 절감분을 다 먹기 때문입니다.
- 이번 개선의 핵심 가치: 잘 쓴 글은 1콜로 싸게 끝납니다. 어휘 티 없는 글에 최중량 파이프라인을 돌리던 낭비를 route_hint가 차단합니다.
verify_change_rate.py는 기존 연동을 위한 하위 호환 도구로 보존하며, 최종 판정의 SSOT는 verify_gates.py입니다.
에이전트 구성
윤문 런타임 역할 3개와 별도 유지보수 역할 1개가 있습니다.
| 에이전트 | 경로 | 역할 |
|---|
humanize-monolith | 전 경로 공용 | 단일 호출 윤문 (탐지·윤문·자체검증 일괄, 도구 호출 3회 캡) |
humanize-diagnostician | standard·heavy | 글 전체의 지배 패턴 3~6개 진단, taxonomy ID + 처방 |
humanize-finalizer | heavy | 원문 직접 대조로 의미 보존 15항 + 자연성 판정, 국소 보정 |
korean-ai-tell-taxonomist | 별도 명령 | 분류 체계(SSOT) 관리, 신규 패턴 심사 승격 |
이 외에 agents/에는 릴리스 회차 전용 개발 도구 5개(translationese-research-distiller · korean-translation-scholar · taxonomy-gap-analyzer · post-editese-metric-engineer · quick-rules-integrator — v2.0 학술 흡수 작업용, 윤문 실행과 무관)가 함께 들어 있습니다.
Claude Code는 루트 agents/ 정의를 호출합니다. Codex는 같은 런타임 역할을 references/roles/{diagnostician,monolith,finalizer}.md 계약으로 실행합니다. 협업 에이전트를 사용할 수 있으면 역할별 독립 컨텍스트로 실행하고, 사용할 수 없으면 주 에이전트가 같은 계약을 순차 실행합니다.
옛 strict 5인 파이프라인의 ai-tell-detector · korean-style-rewriter · content-fidelity-auditor · naturalness-reviewer와 웹 확장 설계용 humanize-web-architect는 v2.1에서 은퇴했습니다(아래 v2.1 릴리스 노트 참조).
This is the beginning of the README. Read the rest at the original. Read the full README ↗
