humanize-korean

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: 입력 저장

1. cwd 기준 _workspace/{run_id}/ 생성
2. 입력 텍스트를 01_input.txt에 저장
3. 첫 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는 단일 호출 안에서 다음을 모두 수행 (자세히는 에이전트 정의 참조):

1. quick-rules 룰북 로드 → 메모리에서 패턴 탐지 + 윤문 + 자체검증 6항 점검
2. 변경률 50% 초과 시 자동 롤백
3. 자체검증 위반 시 1회 부분 재실행
4. final.md + summary.md 작성

Phase 3: 결과 전달

사용자에게 다음 4개를 반환:

1. 한 줄 상태: 완료. 변경률 X% / 등급 Y / 자체검증 N/6 통과
2. 윤문본 본문 (마크다운 블록)
3. summary.md의 핵심 표 (메트릭 + 카테고리 탐지 + 자체검증)
4. 등급 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: 최종 출력

1. final.md에 최종 윤문본 복사
2. summary.md 생성 (fast 모드와 동일 포맷)
3. 사용자에게 결과 + 등급 + 안내

부분 재실행 / 후속 명령

사용자 신호	처리
"특정 카테고리만 다시"	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 탐색 경로:

1. 플러그인 설치 시 — humanize-korean 플러그인이 agents/를 번들로 제공(전역).
2. 스크립트 설치 시 — 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콜로 변경률 1525%, 등급 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 — 웹 확장 시 로드