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 · 제거: ./uninstall.sh
• 업데이트: ./update.sh — 새 버전 자동 감지 후 git pull + 재설치(--check는 감지만). 마켓플레이스 설치는 /plugin update.
• Codex도 light·standard·heavy 전체 경로를 제공합니다. 협업 에이전트가 있으면 진단·윤문·finalize를 독립 실행하고, 없으면 같은 역할을 순차 실행합니다.

왜 한글 특화인가

영어권 humanizer(QuillBot · Hix · Undetectable AI)는 한국어에 약합니다. 한글 AI 글의 티는 대부분 영어 번역투에서 나옵니다.

• "AI 기술을 통해 효율을 높일 수 있다" → "AI로 효율을 높일 수 있다"
• "이에 있어서 중요한 점은" → "여기서 중요한 건"
• "~에 의해 생성된" → "~가 만든"
• "결론적으로, 이는 시사하는 바가 크다" → (삭제)

이 도구는 그 한글 고유 패턴을 SSOT로 정리하고, 글의 상태에 맞는 세 경로(light 1콜 / standard 2콜 / heavy 3+콜) 중 하나로 윤문합니다. 잘 쓴 글일수록 콜 수가 줄어 빠르고 싸게 끝납니다.

4대 철칙

1. 의미 불변 — 사실 · 주장 · 수치 · 고유명사 · 직접 인용은 100% 원문 보존.
2. 근거 기반 — 탐지된 span에만 수술적 수정. 탐지 없는 구간은 건드리지 않음.
3. 장르 유지 — 칼럼을 문학으로, 리포트를 에세이로 옮기지 않음.
4. 과윤문 금지 — 변경률 30% 초과 시 경고, 50% 초과 시 강제 중단.

아키텍처 (v2.3) — route_hint 3경로 + 구조 수렴 게이트

입력을 shim(prepare_monolith_input.py)이 먼저 정량 채점하고, 그 점수로 route_hint(light | standard | heavy) 를 결정적으로 산출합니다. 글의 상태가 경로를 정하고, 경로가 콜 수를 정합니다. 절감은 모델 교체가 아니라 콜 수 축소에서 옵니다(모델 선택은 사용자 몫).

입력 텍스트
    ↓
[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개가 있습니다.

이 외에 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 릴리스 노트 참조).

AI 티 분류 체계 (요약)

전체 85 서브 패턴(hold 1건 포함)과 처방: ai-tell-taxonomy.md · rewriting-playbook.md · 학술 인용 외부 SSOT: scholarship.md (v2.0 신규)

심각도 & 품질 등급

심각도

• S1 결정적: 한 번만 나와도 AI 확신. 무조건 제거.
• S2 강함: 1~2회 허용, 3회+ 반복 시 제거.
• S3 약함: 다른 패턴과 중첩될 때만 문제.

품질 등급 (윤문 후)

• A: S1 0건, S2 ≤2건, 점수 개선 70%+
• B: S1 0건, S2 ≤4건, 개선 50%+
• C: S1 1~2건 or 과윤문 시그널 2개 → 2차 윤문
• D: S1 3건+ or 심각한 과윤문 → 사람 검토

사용법 — 5분이면 따라합니다

전역 설치(설치)를 마쳤다면 1~2단계(클론·폴더 진입)는 건너뛰고, 아무 폴더에서나 바로 3단계로 가세요. 아래는 설치 없이 리포에서 곧바로 체험하는 흐름입니다.

0. 전제

사용할 런타임을 하나 이상 설치합니다. Mac · Windows · Linux에서 사용할 수 있습니다.

# Claude Code
claude --version

# 또는 Codex CLI 0.121.0 이상
codex --version

웹 버전 Claude.ai나 일반 ChatGPT가 아니라, 파일·셸·에이전트 기능을 제공하는 Claude Code 또는 Codex CLI에서 실행합니다.

1. 리포 받기

git clone https://github.com/epoko77-ai/im-not-ai.git
cd im-not-ai

2. Claude Code 또는 Codex 실행

claude --plugin-dir .

# 또는
codex

전역 설치를 했다면 아무 폴더에서나 Claude Code의 /humanize-korean 또는 Codex의 $humanize-korean을 사용할 수 있습니다(설치 참고). 설치 없이 Claude Code로 체험만 하려면 방금 클론한 im-not-ai 폴더 안에서 실행하세요. Codex는 ./install.sh --codex-only로 스킬을 먼저 연결합니다.

3. AI가 쓴 한글 글 붙여넣고 부탁하기

Claude Code 사용자는 방법 A~C를, GitHub Copilot CLI 사용자는 방법 D를, Codex 사용자는 방법 E를 참고하세요.

방법 A — 자연어 한 문장 (가장 쉬움)

평소 말투 그대로 쓰면 됩니다:

이 AI 글 자연스럽게 윤문해줘:

[ChatGPT / Claude / Gemini 초안 여기에 붙여넣기]

아래 표현 중 아무거나 쓰면 스킬이 자동 발동합니다:

• "AI 티 없애줘"
• "GPT 문체 제거해줘"
• "사람이 쓴 것처럼 윤문해줘"
• "번역투 제거"
• "한글 AI 윤문"

방법 B — 슬래시 커맨드 (v1.2~)

/humanize [윤문할 텍스트 또는 파일 경로]

옵션을 인자 끝에 자연어로 적을 수 있습니다: 장르: 칼럼, 강도: 적극, 최소심각도: S1. 결과가 마음에 안 들면 /humanize-redo "번역투만 다시" 같은 식으로 재실행. 진입점은 스킬입니다: humanize · humanize-scan · humanize-redo

전수 윤문을 돌릴 값어치가 있는지 먼저 보고 싶으면 /humanize-scan입니다. 워크스페이스·진단·게이트 없이 이 대화 안에서 끝나고, 실측 판별력이 모델·과업을 바꿔도 살아남은 AI 티 6개(C-8 대구 12배 · E-1 장문 결핍 · C-11 연결어미 쉼표 · I-4 당위 · E-2 종결 편중 · F-5 추상 체인)를 실제로 고쳐 본 전후 수치와 바뀐 문장 표본을 돌려줍니다. 손볼 게 많다고 나오면 전문 대신 /humanize를 권합니다 — 6개만 본 결과를 완성본으로 쓰게 두지 않기 위해서입니다.

방법 C — Plugin / 마켓플레이스 (공식)

본체가 이제 Claude Code Plugin/Marketplace를 공식 지원합니다. 클론 없이 마켓플레이스로 설치하세요:

/plugin marketplace add epoko77-ai/im-not-ai
/plugin install humanize-korean@im-not-ai

스킬 3개 + 서브에이전트 9개가 함께 설치됩니다. 자세한 옵션·스크립트 설치는 설치 섹션과 INSTALL.md 참고. (초기 패키징을 탐색한 gaebalai/im-not-ai 포크도 있습니다.)

방법 D — GitHub Copilot CLI (공식, 단일 호출 경로)

GitHub Copilot CLI 1.0.79-5에서 마켓플레이스 설치와 스킬 탐색을 확인했습니다.

copilot plugin marketplace add epoko77-ai/im-not-ai
copilot plugin install humanize-korean@im-not-ai
copilot plugin list
copilot skill 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와 Codex가 제공하는 route_hint 3경로 오케스트레이션과 진단·finalize 역할 실행은 Copilot에서 수행하지 않습니다.

저장소 직접 설치 명령 copilot plugin install epoko77-ai/im-not-ai은 1.0.79-5에서 동작하지만 사용 중단 예정 경고가 표시되는 호환성 경로입니다.

방법 E — Codex CLI (공식, 전체 경로)

본체가 이제 Codex CLI Skills를 공식 지원합니다. 리포 클론 후 한 줄이면 ~/.codex/skills/에 연결됩니다:

git clone https://github.com/epoko77-ai/im-not-ai.git && cd im-not-ai
./install.sh --codex-only

Codex에서 $humanize-korean으로 발동합니다(또는 /skills 메뉴). route_hint가 light·standard·heavy를 선택하며 --strict로 heavy를 강제할 수 있습니다. Codex 협업 에이전트가 있으면 진단·윤문·finalize와 장문 청크를 역할별로 실행합니다.

$humanize-korean을 사용해 이 글의 AI 티를 없애줘.

[윤문할 한글 텍스트]

진단→윤문→finalize 전체 경로를 강제하려면:

$humanize-korean을 사용해 이 글을 --strict 정밀 모드로 윤문해줘.

[윤문할 한글 텍스트]

산출물은 Codex를 시작한 디렉터리의 _workspace/{실행날짜-번호}/에 저장됩니다. 별도 환경에서 시험하려면 임시 디렉터리에서 Codex를 시작하세요.

**방법 F — Web UI (비공식)