Skip to content

epoko77-ai/im-not-ai / skills/humanize-korean

humanize-korean

Verified

AI(ChatGPT·Claude·Gemini 등)가 쓴 한글 텍스트를 "사람이 쓴 글처럼" 윤문해주는 오케스트레이터 스킬. 번역투·영어 인용 과다·기계적 병렬·관용구·피동태 남용·접속사 남발·리듬 균일성·이모지/불릿 과다 등 10대 카테고리 85개 AI 티 패턴을 탐지·분류해 내용은 한 글자도 건드리지 않고 문체·리듬·표현만 자연스러운 한국어로 재작성한다. shim의 route_hint(light|standard|heavy)로 경로를 정해 잘 쓴 글은 1콜, 표준은 2콜, 중증·장문만 3+콜(진단→겨냥 윤문→finalize)로 처리한다. 트리거 — "AI 티 없애줘", "AI 같은 글 자연스럽게", "GPT/ChatGPT 문체", "AI 번역투 고쳐", "사람이 쓴 것처럼 윤문", "AI 윤문", "ChatGPT 티 제거", "한글 AI 탐지·윤문", "AI 글 사람처럼", "번역투 제거", "영어 인용 많은 글 윤문", "AI 글 티 안 나게", "휴머나이저", "humanize Korean", "AI detector bypass 한글". 후속 작업 — "특정 카테고리만 다시", "윤문 강도 조정", "장르 바꿔서", "이 문단만", "2차 윤문" 도 모두 이 스킬. 단순 맞춤법·오탈자 교정은 직접 처리, 번역은 번역 스킬, 내용 추가·삭제를 동반한 재작성은 별도 집필 스킬.

references/design-notes.md

View on GitHub
# Humanize Korean — 설계 근거·버전 히스토리 (design-notes)

> SKILL.md에서 이관된 설계 근거 — **실행 규칙은 SKILL.md 참조.** 이 파일은
> 스킬 발동 시 로드되지 않는다. 규칙을 되돌리려는 기여자가 "왜 이렇게
> 됐는가"를 확인하는 용도다.

## 버전 히스토리 (상세)

- **v1.5 (2026-04-26)** — v1.1 5인 파이프라인 위에 단일 호출 `humanize-monolith` fast path 신설. voice profile·candidate pool·권한 위계 §1~§6은 핫패스 비용 문제로 삭제.
- **v1.6 (2026-05-07)** — KatFish·LREAD 기반 정량 점수 레이어 도입. `scripts/prepare_monolith_input.py`(입력 shim)가 monolith 호출 *전* 외부 사전 처리로 점수를 산출해 결합 입력 파일에 prepend.
- **v1.6.1 (2026-05-07)** — fast 산출물을 `final.md` 1개로 통합(본문 끝 `<!-- HUMANIZE-SUMMARY -->` HTML 주석 블록). monolith 도구 호출 캡 4회 → **3회**.
- **v2.0 (2026-05-07)** — 한국 번역학계 8유형 + post-editese metric 트랙(`metrics_v2.py`) 흡수. 분류 체계 본진 v2.0(활성 패턴 70건 + A-17 hold 1건).
- **v2.0.1** — 패치 릴리스: shim 실행 절차 명문화, 실사용 백포트(격식 상향 금지·구조/각주 보존·과윤문 게이트 코드화), quick-rules 빌드 생성.
- **v2.1.0** — 정밀 모드를 5인 파이프라인 → **3콜 구조**(진단→겨냥 윤문→finalize)로 재편. 옛 4종+web-architect 은퇴. 8,000자 strict 자동 승급 폐지.
- **v2.2.0** — **경량 경로 재설계.** shim이 산출하는 `route_hint`(light|standard|heavy)로 디폴트 경로를 3단 분기. **단일 콜 우선 원칙** 명문화 — 1만자급도 청킹 없이 단일 콜(실측: 청킹 7콜 610K 토큰 → 단일 콜 134K, 품질 동등). 청킹은 shim이 실제로 청크를 2개 이상 만들 때만. finalize는 heavy·의심·사용자 요청 시로 한정.
- **v2.3.0** — **효율화 릴리스.** ① Tier 1 구조 수렴 게이트(`verify_gates.py` 4축: 문자율 + 진단 목표달성 z 수렴 + C-8 대구 전멸 + golden/수치) — 문자 change_rate가 못 보는 구조 편집(쉼표·대구 해체)을 결정적으로 검증, LLM 콜 0. ② 진단 입력을 taxonomy 전량(74.8KB) → `diagnosis-rules.md` 슬림 인덱스(~13KB, 빌드 생성)로 교체, 진단 콜 토큰 35~50%↓. 실측 회귀에서 하중 패턴(C-8·C-11·E-5·D-7) 지목 동등.

- **v2.4.0** — **어휘 레이어.** 문장 구조와 별개로, 한국어 독자가 읽다가 걸리는 낱말("~의 렌즈로 보면"·"세 개의 축으로"·"논의에 결을 더한다"·"잠재력을 잠금 해제한다")을 다룬다. 후보 148개를 블라인드 평가(0/1/2)해 1·2점 111개를 `references/lexicon.json`에 싣고, ① shim이 원문에서 발견된 항목만 `[어휘 점검]` 블록으로 결합 입력에 넣어 실행자가 문맥으로 판단하게 하고(전 경로), ② Phase 2.4가 윤문이 새로 만든 2점 낱말의 문장만 되돌린다. 실측: 실사용 문단 24개 × 2회 A/B에서 표시 표현 생존율 94% → 34%(2점 96% → 22%), 변경 정도 0.06 → 0.05.

- **v2.4.1** — 어휘 점검이 짝 맞는 인용부 안의 낱말을 힌트에서 뺀다. AI 티를 설명하는 글(예문 인용)을 윤문할 때 인용까지 고칠 대상으로 짚던 문제 — Do-NOT list(직접 인용 보존)와의 정합.
- **v2.4.2** — 어휘 복원도 힌트용 넓은 정규식으로 매칭한다. 좁은 정규식은 활용형을 놓쳐 "세 가지 렌즈로 살펴본다" 같은 주입을 되돌리지 못했다. 안전장치는 '원문 문서 전체에 없던 낱말' 조건이다(r4 120건 재적용: 되돌림 6→8, 평균 변화량 0.0014→0.0018). 또 `tests/test_pipeline_scripts.py`를 신설했다 — 라이브 층은 "파일은 만들지 마" 호출이라 스크립트 단계를 못 돌기 때문에, 얼린 윤문본으로 shim→Phase 2.4→게이트 사슬을 결정적으로 돌린다.
- **v2.4.3** — 사전 1.1: 넓은 정규식이 사람 글의 실물 용법을 짚던 10항목을 정밀화했다(L-05 "한 축" 1회·L-25 실제 배의 항해·L-40 실제 숨결·L-54 "~로 작용하다"·L-08 손으로 쥐다·인명 "쥘"·L-09 체포·천체·L-32 "세계에서 가장"·AST-10 동물 무늬·X-01 지리 지형·X-02 "태풍경보"). 사람 85.7만 자 오탐 171→113건(10만 자당 20.0→13.2), AI 탐지 3,746→3,548건(-5%). 계기: 웹 이식 A/B의 사람 칼럼 대조군 5편 중 3편에서 정당 용법이 고쳐지고 1편은 구절이 빠졌다(처음 2편으로 셌으나 1편은 문장 분할을 삭제로 오독한 것 — v2.4.4 정정).
- **v2.4.4** — 어휘 복원에 문장 분할 가드를 넣었다. 원문 한 문장이 윤문에서 둘로 쪼개지면 짝 문장만 되돌릴 때 나머지 조각과 명제가 중복된다(합성 재현). 서법 복원의 `split_gap`과 같은 판정이다. r4·r5 실제 윤문 236쌍에서는 결과가 같다(되돌림 8·보류 17, 분할 보류 0). 웹 이식판이 먼저 넣은 가드로, 두 구현이 다시 같아진다.
- **v2.4.5** — 사전 1.2(113개). 외부 지적("층위·기둥을 지나치게 쓴다")을 메인테이너가 확인해 반영했다. 「기둥」(X-14, 바꿈 우선): 사람 0.47 vs Claude계 7.95/10만 자. 「버팀목·디딤돌」(X-15, 조건부): 사람 0 vs Claude·Solar 0.2~0.8. 「층위」(L-34) 논문 생략 해제: 사람 글 85.7만 자에 이어 사람 경제학 논문 4편(24만 자)에서도 0건인데 Claude계 5.5·Solar 4.1. 장르 판정에 메인테이너 판정(`genre_user`)이 모델 판정보다 우선하도록 빌드를 바꿨다. 토대·근간·기틀은 사람도 쓰거나(토대 1.4) 차이가 작아 넣지 않았다.
- **v2.4.6** — 사전 1.3(115개). 외부 지적("~하는 편이 좋습니다", "본질적으로", "짚고 간다")을 메인테이너가 재판정했다. 「짚다」(INJ-03) 1→2점·일반 글 생략 해제: 사람 0.23 vs Claude계 1.9·GPT 3.4·Solar 3.4/10만 자 — 웹앱(장르 '일반')에서는 그동안 한 번도 잡지 않았다. 「본질적으로」(X-12) 0→1점, 논문은 둔다(사람 경제학 논문 2건). 「~하는 편이 좋다·낫다」(X-16) 조건부 신설 — 칼럼·위키·번역 코퍼스에는 거의 없어 판별력은 재지 못했다(챗봇·조언 글 말투). "형편이 좋다", "남편이 좋다"는 정규식에서 뺐다.
- **v2.4.7** — `checks.check_register`: 원문이 순수 '하였'체('했' 0회)면 분절로 새로 생긴 문장 수까지 '하였' 증가를 허용한다(#184, 38,621자 학술 원고에서 C-11 분절이 매번 hayeot_injection FAIL을 냈다). 시제 변경("공개한다"→"공개하였다")은 문장 수가 늘지 않으므로 계속 잡는다. '했'체·혼용·과거 표지 없는 원문은 기존대로 엄격하다. 테스트 측: live 러너가 줄여 쓴 닫는 센티넬을 받고(#183), 강제 중단 게이트(≥50% 롤백 1회)를 흉내 내며 변경률을 게이트 SSOT(metrics_v2)로 잰다(#187). Codex용 AGENTS.md(#161).

## 설계 노트 — 어휘 레이어 (v2.4)

- **왜 사전이 아니라 힌트인가**: 같은 낱말도 장르·문맥·정당 용법에 따라 두어야 한다("시스템을 구축하다"·"카메라 렌즈"·"결이 다르다"). 고정 대체어는 그 자체가 새 상투어가 된다. 그래서 항목마다 바꿀 때/둘 때/방식만 주고 판단은 실행자에게 맡긴다. 발견된 항목만 실으므로 프롬프트 비용은 발견 수에 비례한다(상한 15개).
- **정규식 두 벌**: 힌트용 `regex_detect`는 재현율 우선(활용형·슬라이드 제목형 "세 개의 렌즈로 본 X"까지), `regex`는 정밀도 우선(사전 단위 테스트의 기준). v2.4.2부터 복원도 `regex_detect`로 매칭한다 — 복원은 '원문 전체에 없던 낱말'에만 작동하므로 그 조건이 정밀도를 지킨다. 사람 글(2021년 이전 칼럼·위키·사람 번역 85.7만 자) 오탐은 전 항목 10만 자당 3회 이하로 묶었다.
- **왜 프롬프트 금지 조항이 아니라 복원기인가**: 같은 설정에서 금지 조항을 두 번 실행하자 주입 문서가 6편 ↔ 17편으로 요동쳤다(효과 < 실행 간 분산). 서법 복원(restore_modality)과 같은 결정적 문장 복원은 분산이 없다. 단, 원문 문장의 2점 낱말을 고치던 중이면(예: 렌즈→층위) 되돌리지 않고 보류한다 — 되돌리면 그 낱말이 부활한다.
- **주의(평가 하네스)**: `tests/humanize_runner.py`의 라이브 프롬프트는 "파일은 만들지 마"라서 shim·복원 스크립트가 돌지 않는다. 스크립트 단계의 효과는 light 경로를 단계별로 직접 실행해 쟀다.

## 설계 노트 — 단일 콜 우선 (v2.2 실측 근거)

**1만자 글 실측**: 정밀 청킹 경로(7콜) = **610K 토큰**. 같은 입력 단일 콜 = **134K 토큰**(4.5배 절감), 품질 동등. 폭발 원인은 청크 콜마다 룰북·진단·시스템 프롬프트를 재로드한 것 — 절감은 모델 교체가 아니라 **콜 수 축소**에서 온다. 요즘 모델은 1만자를 단일 콜로 무리 없이 처리하므로, 청킹은 "shim이 실제로 쪼갤 수밖에 없는 초장문"의 예외 경로다.

또 하나의 실증: 어휘 티 0·구조 티만 있는 잘 쓴 글에도 최중량 파이프라인을 돌리고 있었다. v2.2의 route_hint 분기가 이를 차단한다.

(v2.1까지의 "왜 5인에서 3콜로" 배경: 옛 5인 파이프라인은 detector span 열거가 0↔18개로 요동쳐 불안정했고, 587줄 taxonomy를 이중 로드해 탐지에만 wall-clock 54%를 썼다. 웹앱 실증에서 "지배 패턴 진단 1콜 + 결정적 지표 수렴"이 동급 품질을 냈고, 3콜 구조는 그 이식이다. v2.2는 같은 원리를 한 단계 더 밀어 진단·finalize조차 필요할 때만 쓰게 했다.)

## 설계 노트 — 진단 슬림 인덱스 (v2.3)

진단(humanize-diagnostician)의 핸드오프 계약은 "정확한 본진 ID + 지배도 판단"이다. taxonomy 전량(74.8KB)의 대부분은 예문·처방·학술 인용·버전주석 — 진단에 불필요. `scripts/build_diagnosis_rules.py`가 SSOT에서 전 패턴 전수(ID·정의·탐지 시그니처)를 ~13KB로 결정적 생성한다(83% 절감). quick-rules로 대체할 수 없는 이유: 진단은 문서 레벨 패턴(C-8 대구·E-1 리듬·D-6 결말공식 등 quick:false 다수)을 반드시 봐야 한다. drift는 CI `--check`가 차단.

## 테스트 시나리오

### Light — 잘 쓴 글
- 입력: 사람이 쓴 칼럼 또는 어휘 티 없는 글 (route_hint=light)
- 기대: monolith 1콜(보수), 변경률 5% 미만, "이미 좋습니다 + 손댄 곳 요약" 보고. 진단·finalize 콜 0

### Standard — 보통의 AI 초안
- 입력: ChatGPT가 생성한 AI 칼럼 초안 (2,000~10,000자, route_hint=standard)
- 기대: 진단 1콜 + 윤문 1콜 = 2콜, **1만자도 청킹 없음**, 변경률 15~25%, 등급 A/B, finalize 생략

### Heavy — 중증·증적 필요
- `--strict` 명시 또는 route_hint=heavy
- 기대: 진단→윤문→finalize 3콜. 변경률 11~22%, `09_finalize.json` verdict=accept/corrected

### 초장문 — 청킹은 shim의 결정
- heavy + shim 청킹 임계 초과 입력 → `--chunk` 실행, manifest body 청크 2+개일 때만 병렬. 청크가 1개로 나오면 단일 콜. 손실 없는 분할 + 헤딩 승격 + 각주 passthrough

### 엣지 케이스 — route_hint 부재
- 구버전 shim·metrics 실패(`00_metrics.error`) → standard 경로로 진행. 게이트는 항상 실행

## 에이전트 계보 (은퇴·개발용)

**개발용 1회성 5종 (릴리스 회차 전용 — 런타임 미로드)**
- `translationese-research-distiller` · `korean-translation-scholar` · `taxonomy-gap-analyzer` · `post-editese-metric-engineer` · `quick-rules-integrator` — v2.0 학술 흡수 회차에서 사용된 개발 도구. 윤문 실행과 무관

> v2.1에서 옛 정밀(strict) 파이프라인 4종(`ai-tell-detector`·`korean-style-rewriter`·`content-fidelity-auditor`·`naturalness-reviewer`)과 미사용 `humanize-web-architect`를 은퇴시켰다. 진단·윤문·finalize 3콜이 이들을 대체한다.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall