Humanize Korean — AI 한글 티 제거 오케스트레이터 (v1.5)
v1.5 변경 고지 (2026-04-26) — v1.1 베이스라인 + Monolith Fast Path v1.2(voice profile)·v1.3(candidate pool)·v1.4(역할별 모델 분산)는 모두 핫패스 비용을 잡지 못해 5,000자 입력에 25분이 걸렸습니다. v1.5는 v1.1 단순 구조로 롤백한 뒤 단일 호출 monolith 에이전트만 추가한 설계입니다.
- Fast 모드(디폴트) —
humanize-monolith에이전트가 한 콜에서 탐지·윤문·자체검증 일괄 처리. 도구 호출 45회. 5,000자 이하 wall-clock 23분 목표.- Strict 모드(
--strict) — v1.1 5인 파이프라인 그대로(detector·rewriter·auditor·reviewer + taxonomist 분류 자산 유지). 정밀 검증·장문(8,000자+) 처리·etc.- 삭제됨: voice profile·candidate pool·promotion-checklist·sample-collection·권한 위계 §1~§6.
- 유지됨: 분류 체계 본진(C-9·C-10·D-7·H-3·I-3·I-4 등 v1.2~v1.3.1 신규 패턴)·rewriting-playbook·5인 에이전트 정의(strict 모드 백본).
Phase 0: 컨텍스트 확인 및 모드 결정
작업 시작 시 가장 먼저 다음 한 줄을 사용자에게 출력한다.
humanize-korean v1.5 — {fast|strict} 모드 / run_id: {YYYY-MM-DD-NNN}
모드 결정
- 사용자가
--strict·"정밀 모드"·"5인 파이프라인" 명시 → strict - 입력 8,000자 초과 → strict (자동 승급 + 사용자에 1줄 고지)
- 그 외 모두 → fast (디폴트)
run_id 결정
- 모든 경로는 cwd 기준. 새 폴더 생성도 cwd 기준
_workspace/{YYYY-MM-DD-NNN}/에 만든다. - 기존 시퀀스 확인은
Glob도구로 표지 파일을 매칭해 간접 조회. 올바른 사용법:Glob(pattern="_workspace/YYYY-MM-DD-*/01_input.txt")→ 결과에서 폴더명 추출 후 NNN 최댓값 + 1. 주의: Glob은 디렉토리 자체는 매칭하지 못한다. 반드시 그 안의 표지 파일(01_input.txt)을 매칭할 것.Bash ls는 OS·셸 환경에 따라 경로 해석이 달라지므로 사용 금지. - 당일 폴더가 없으면 NNN = 001. 있으면 마지막 NNN + 1.
- 부분 재실행 신호("이 카테고리만 다시"·"2차 윤문")일 경우 기존 run_id 재사용 + strict 모드로 자동 승급.
Fast 모드 (디폴트)
Phase 1: 입력 저장
- cwd 기준
_workspace/{run_id}/생성 - 입력 텍스트를
01_input.txt에 저장 - 첫 300자로 장르 자동 추정 (사용자 명시 시 우선)
Phase 2: Monolith 호출
humanize-monolith 에이전트를 Agent 도구로 1회 호출.
입력:
input_path: <abs path>/_workspace/{run_id}/01_input.txt quick_rules_path: ${CLAUDE_SKILL_DIR}/references/quick-rules.md genre_hint: 칼럼 | 리포트 | 블로그 | 공적 | null
출력 (에이전트가 직접 작성):
_workspace/{run_id}/final.md— 윤문본_workspace/{run_id}/summary.md— 메트릭·자체검증·하이라이트
monolith는 단일 호출 안에서 다음을 모두 수행 (자세히는 에이전트 정의 참조):
- quick-rules 룰북 로드 → 메모리에서 패턴 탐지 + 윤문 + 자체검증 6항 점검
- 변경률 50% 초과 시 자동 롤백
- 자체검증 위반 시 1회 부분 재실행
- final.md + summary.md 작성
Phase 3: 결과 전달
사용자에게 다음 4개를 반환:
- 한 줄 상태:
완료. 변경률 X% / 등급 Y / 자체검증 N/6 통과 - 윤문본 본문 (마크다운 블록)
- summary.md의 핵심 표 (메트릭 + 카테고리 탐지 + 자체검증)
- 등급 B 이하면 "정밀 검증이 필요하면
--strict로 5인 파이프라인" 안내
디폴트 wall-clock 목표: 5,000자 이하 23분, 8,000자 57분.
Strict 모드 (--strict 또는 자동 승급)
v1.1 5인 파이프라인 그대로. 검증 분리·재윤문 루프가 의미 있을 때만 사용.
Phase A: 탐지
ai-tell-detector 호출 → 02_detection.json
Phase B: 윤문 (최대 3회 루프)
korean-style-rewriter 호출 → 03_rewrite.md + 03_rewrite_diff.json
Phase C: 병렬 검증 (에이전트 팀)
TeamCreate로 humanize-review-team 구성:
content-fidelity-auditor→04_fidelity_audit.json(의미 동등성)naturalness-reviewer→05_naturalness_review.json(잔존·과윤문)
TeamDelete 후 종합 판정 매트릭스에 따라 분기:
| fidelity | naturalness | 종합 | 후속 |
|---|---|---|---|
| full_pass | accept / accept_with_note | 최종 승인 | Phase D |
| full_pass | rewrite_round_2 | 2차 윤문 | Phase B 재호출 (target finding) |
| full_pass | rollback_and_rewrite | 롤백 후 재윤문 | 윤문가에 edit 롤백 지시 |
| conditional_pass | - | 롤백된 edit만 재시도 | Phase B 재호출 |
| fail | - | 전면 재작업 | Phase B 전면 재호출 |
2차/3차 윤문 진입 시 03_rewrite_v2.md·v3.md로 버전 분리. **최대 3회 후 미해결이면 hold_and_report**로 사람 개입.
Phase D: 최종 출력
final.md에 최종 윤문본 복사summary.md생성 (fast 모드와 동일 포맷)- 사용자에게 결과 + 등급 + 안내
부분 재실행 / 후속 명령
| 사용자 신호 | 처리 |
|---|---|
| "특정 카테고리만 다시" | strict 모드로 자동 전환, 해당 카테고리 finding만 Phase B 재실행 |
| "이 문단만" | strict 모드, 해당 문단만 입력으로 새 run_id 생성 |
"2차 윤문"·"/humanize-redo" | 기존 run_id의 final.md를 새 입력으로 strict Phase B 재실행 |
| "윤문 강도 조정" | strict 모드, min_severity 옵션 변경 후 Phase A부터 재실행 |
| "장르 바꿔서" | genre_hint 변경 후 Phase A부터 재실행 |
옵션 (인자 끝에 자연어로)
장르: 칼럼|리포트|블로그|공적— 장르 명시 (생략 시 자동 추정)강도: 보수|기본|적극— 윤문 강도 (기본값: 기본)최소심각도: S1|S2|S3— 탐지 임계값 (기본값: S2)--strict— 5인 파이프라인 강제 사용
데이터 흐름 요약
Fast 모드 (디폴트)
01_input.txt ↓ [humanize-monolith — 단일 호출] ├ 메모리: quick-rules 로드 → 탐지 → 윤문 → 자체검증 └→ final.md + summary.md
Strict 모드
01_input.txt ↓ [ai-tell-detector] 02_detection.json ↓ [korean-style-rewriter] 03_rewrite.md + 03_rewrite_diff.json ↓ [병렬 팀] ├→ [content-fidelity-auditor] → 04_fidelity_audit.json └→ [naturalness-reviewer] → 05_naturalness_review.json ↓ [오케스트레이터 종합] ├→ (재작업) Phase B로 복귀 (최대 3회) └→ (승인) final.md + summary.md
에이전트 호출 규칙
모델: 모두 model: opus 통일 (v1.1 베이스라인). 모델 다운그레이드는 v1.4에서 시도했으나 도구 호출 chain이 진짜 병목이라 효과 미미했음.
에이전트 정의 위치: 저장소 루트 agents/에 12종 정의(플러그인 컨벤션). Claude Code 탐색 경로:
- 플러그인 설치 시 —
humanize-korean플러그인이agents/를 번들로 제공(전역). - 스크립트 설치 시 —
install.sh가agents/*.md를~/.claude/agents/에 심링크(전역).
필요 에이전트 6종:
humanize-monolith(v1.5 신규, fast 전용)ai-tell-detector·korean-style-rewriter·content-fidelity-auditor·naturalness-reviewer(strict 5인 중 4명)korean-ai-tell-taxonomist(분류 체계 유지·확장 — 본 스킬 실행 중에는 호출 안 됨, 별도 명령으로만 트리거)
테스트 시나리오
Fast 정상 흐름
- 입력: ChatGPT가 생성한 AI 칼럼 초안 (2,000~5,000자, 번역투·결말 공식·hype 어휘 풍부)
- 기대: monolith 1콜로 변경률 15
25%, 등급 A/B, wall-clock 23분, 자체검증 5~6/6
Strict 정밀 검증 흐름
- 사용자 명시
--strict또는 8,000자+ 입력 - 5인 파이프라인 끝까지 실행, 변경률 18~22%, 검증팀 full_pass
엣지 케이스 — 이미 사람이 쓴 글
- monolith 자체 탐지에서 매치 거의 없음 → 변경률 5% 미만 + summary.md에 "윤문 불필요 가능성" 메모
- 사용자가
--strict로 강제 검증 가능
주의 사항
- 의미 불변이 최상위 불문율. monolith·strict 모두에서 위반 즉시 롤백.
- 수치·고유명사·직접 인용은 탐지/윤문 대상 아님. Do-NOT list 엄수.
- 장르 이탈 금지. 칼럼이 에세이로, 에세이가 문학으로 옮겨가지 않는다.
- register 보존. 격식체 입력 → 격식체 출력. AI 티는 문법·수사이지 격식 자체가 아님.
- 변경률 30% 초과 → 경고, 50% 초과 → 강제 중단.
- 자동 로드 금지. 프로젝트 CLAUDE.md 등 다른 파일을 자동 파싱해 옵션을 추론하지 않는다.
참고 자료
- 슬림 룰북 (Fast 전용):
references/quick-rules.md— S1·S2 핵심 패턴 + 자체검증 체크리스트 - 분류 체계 본진 (Strict 전용):
references/ai-tell-taxonomy.md— 10대분류 × 40+ 패턴 전수 - 윤문 처방 (Strict 전용):
references/rewriting-playbook.md— 카테고리별 치환 레시피·장르별 허용 표 - 웹 서비스 스펙 (옵션):
references/web-service-spec.md— 웹 확장 시 로드
출처
이 스킬의 분류 체계는 내가 만든 것이 아니다. 외부 연구를 가져와 세운 것이다.
- 한국 번역학계 번역투 연구 — 8대 번역투 유형이 분류 체계의 뼈대다. 이영옥(2001) 「무생물 주어 타동사구문의 영한번역」 번역학연구 2(1): 53-76 을 비롯해 윤미선·김택민·임진주·홍승연(2018), 이상빈(2017·2018a·2018b), 마승혜(2018), 김혜림(2022), 김혜영(2019) 등.
- KatFish 정량 보고서 — 인간/AI 텍스트의 어절 수, POS 다양성, 한자어 명사화 밀도 같은 수치 임계값은 이 보고서에서 가져왔다. (예: 에세이 평균 어절 인간 4.35 vs AI 8.56)
- arXiv 계열 AI 텍스트 탐지 연구 — 일부 지표 정의를 참고했다.
학자 이름·연도·저널·페이지는 references/scholarship.md에
원문 그대로 보존돼 있다. 자체 추정이나 확장 없이 옮겼다.
내가 더한 부분은 이것뿐이다 — 한국어 실무에서 반복적으로 지적받은 표현
(~가 아니라 대조 구문, 여정, 굴러가다, 방어적 안심 문장 등)을 금지어로 추가하고,
윤문 강도를 Fast/Strict로 나눠 실제 원고에 돌 수 있게 절차화한 것.
