humanize-korean

Humanize Korean — AI 한글 티 제거 오케스트레이터

AI가 쓴 한글 글의 시그니처 패턴을 탐지·분류해 내용 불변을 전제로 자연스러운 한국어로 윤문하는 5인 에이전트 파이프라인.

실행 모드: 하이브리드 — 주 흐름은 파이프라인(순차), 검증 단계만 팀(병렬 리뷰).

Phase 0: 컨텍스트 확인

실행 모드: 단일 (오케스트레이터)

작업 시작 시 가장 먼저 실행 모드를 판정한다:

1. 사용자 프로젝트의 작업 디렉토리(현재 cwd) 하위 _workspace/ 확인. plugin 모드면 사용자 프로젝트, 로컬 모드면 이 리포 루트.
2. 분기:
   • _workspace/ 없음 또는 사용자가 새 입력 제공 → 새 실행. run_id를 YYYY-MM-DD-NNN 형식으로 생성.
   • 사용자가 "특정 카테고리만 다시" / "2차 윤문" / "윤문 강도 조정" / "이 문단만" → 부분 재실행. 기존 run_id의 해당 에이전트만 재호출.
   • 사용자가 "웹 서비스로 만들어줘" / "API 배포" → 웹 확장 모드. Phase 5로 직행.
3. 분류 체계 상태 확인: references/ai-tell-taxonomy.md 로드 검증.

Phase 1: 입력 수신 및 정규화

실행 모드: 단일 (오케스트레이터)

1. 입력 텍스트를 _workspace/{run_id}/01_input.txt에 저장.
2. 장르 힌트를 사용자에게 확인하거나 첫 300자 분석으로 추정 (칼럼·리포트·블로그·공적 연설).
3. 옵션 기본값: min_severity: S2, include_document_level: true.

Phase 2: AI 티 탐지

실행 모드: 서브 에이전트 (단일 호출)

ai-tell-detector 에이전트를 Agent 도구로 호출 (model: "opus").

입력 프롬프트:

run_id: {run_id}
input_path: _workspace/{run_id}/01_input.txt
taxonomy_path: references/ai-tell-taxonomy.md   # 본 스킬 디렉토리 기준. plugin/.claude 양쪽 호환. LLM이 못 찾으면 Glob "**/ai-tell-taxonomy.md" 로 탐색.
genre_hint: {칼럼|리포트|블로그|공적|null}
options: { min_severity, include_document_level }

출력: _workspace/{run_id}/02_detection.json 생성.

게이트: detected_count == 0 이면 "AI 티가 거의 없습니다. 윤문 불필요" 메시지로 종료.

Phase 3: 윤문

실행 모드: 서브 에이전트 (단일 호출, 최대 3회 루프)

korean-style-rewriter 에이전트를 Agent 도구로 호출 (model: "opus").

입력:

run_id: {run_id}
input_path: _workspace/{run_id}/01_input.txt
detection_path: _workspace/{run_id}/02_detection.json
playbook_path: references/rewriting-playbook.md   # 본 스킬 디렉토리 기준. 못 찾으면 Glob "**/rewriting-playbook.md".

출력: _workspace/{run_id}/03_rewrite.md + 03_rewrite_diff.json.

게이트: over_polish_warning: true 이면 즉시 Phase 4로 (감사관이 롤백 판정).

Phase 4: 병렬 검증 (에이전트 팀)

실행 모드: 에이전트 팀 (2인 병렬)

TeamCreate로 humanize-review-team 구성:

• 멤버: content-fidelity-auditor, naturalness-reviewer
• TaskCreate로 각자 독립 평가 할당 (의존성 없음).

두 에이전트 모두 _workspace/{run_id}/01_input.txt + 03_rewrite.md + 03_rewrite_diff.json을 읽고:

• fidelity-auditor: 04_fidelity_audit.json 생성 — 의미 동등성 판정.
• naturalness-reviewer: 05_naturalness_review.json 생성 — 잔존·과윤문 판정.

완료 후 TeamDelete로 팀 정리.

Phase 4 종합 판정 (오케스트레이터)

fidelity	naturalness	종합	후속
full_pass	accept / accept_with_note	최종 승인	Phase 6
full_pass	rewrite_round_2	2차 윤문	Phase 3 재호출 (target finding만)
full_pass	rollback_and_rewrite	롤백 후 재윤문	윤문가에 edit 롤백 지시
conditional_pass	-	롤백 지시된 edit만 재시도	Phase 3 재호출 (특정 edit만)
fail	-	전면 재작업	Phase 3 전면 재호출

2차/3차 윤문 진입 시 _workspace/{run_id}/03_rewrite_v2.md·v3.md로 버전 분리.

최대 루프 3회. 3회 후에도 미해결이면 hold_and_report로 사람 개입 요청.

Phase 5: 웹 확장 (옵션)

실행 모드: 서브 에이전트 (요청 시만)

사용자가 "웹 서비스로 만들어줘" / "API 배포" 요청 시 humanize-web-architect를 호출 (model: "opus").

산출물: _workspace/web/01_architecture.md·02_api_spec.md·03_ux_flow.md.

실제 코드 구현은 이 아키텍트의 설계 승인 후 별도 프런트엔드 엔지니어(필요 시 신규 에이전트)를 통해 진행.

Phase 6: 최종 출력

실행 모드: 단일 (오케스트레이터)

1. 최종 윤문본을 _workspace/{run_id}/final.md로 복사.
2. 요약 리포트 _workspace/{run_id}/summary.md 생성:
   • 원본 길이·윤문본 길이·변경률
   • 카테고리별 탐지 건수 (before/after)
   • 점수 변화 (severity_weighted_score)
   • 잔존 findings (있을 경우)
   • 품질 등급 (A/B/C/D)
3. 사용자에게:
   • 윤문본 본문 (마크다운 블록)
   • 요약 표
   • 주요 변경 하이라이트 3~5건 (before/after 대비)
   • "2차 윤문을 원하시면 말씀해주세요" 안내 (등급 B 이하일 때)

Phase 7: 피드백 수집 (진화 루프)

결과 전달 후 사용자에게:

"윤문 결과에서 개선할 부분이 있나요? 예) '이 카테고리가 과하게 고쳐졌다', '이 표현은 그대로 두는 게 낫다', '리듬이 부자연스럽다'"

피드백 유형별:

• 개별 edit 이의: 해당 edit 롤백 후 재윤문.
• 카테고리 전역 이의: 해당 카테고리 finding 재감사, 필요 시 taxonomy 항목의 심각도 조정 요청을 분류학자에게.
• 장르 추정 오류: genre_hint 수정 후 Phase 2부터 재실행.
• 새 패턴 제보: 분류학자에 "taxonomy 확장 후보" 에스컬레이션.

데이터 흐름 요약

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 3으로 복귀
    └→ (승인) final.md + summary.md

에이전트 호출 규칙

모든 Agent 호출은 model: "opus" 명시. 파일 기반 데이터 전달, _workspace/{run_id}/ 하위에 번호 접두사 파일 저장.

에이전트 정의 위치 (둘 다 동일 — plugin/local 양쪽 호환):

• 정본: 리포 루트의 agents/*.md
• 미러: .claude/agents/*.md (루트로 향하는 심볼릭 링크)
• 정의된 에이전트 6명: korean-ai-tell-taxonomist, ai-tell-detector, korean-style-rewriter, content-fidelity-auditor, naturalness-reviewer, humanize-web-architect

타입: 모두 general-purpose로 스폰 후 정의 파일을 Agent 프롬프트에 포함 (또는 이미 정의된 agent 타입으로 호출).

테스트 시나리오

정상 흐름

• 입력: ChatGPT가 생성한 AI 칼럼 초안 (2000자).
  • 번역투 빈번 ("~를 통해" 6회, "~에 대해" 4회)
  • 관용구 ("결론적으로", "시사하는 바가 크다")
  • 기계적 "첫째·둘째·셋째"
  • 이모지 몇 개
• 기대 출력:
  • 02_detection.json: 30~50 finding, score ≥ 60
  • 03_rewrite.md: 변경률 15~25%
  • 04_fidelity_audit: full_pass
  • 05_naturalness_review: accept, score < 20, 등급 A/B
  • 최종 윤문본 + 요약

에러 흐름 1 — 과윤문

• 1차 윤문에서 변경률 40% → 감사관 flag
• 리뷰어가 장르 이탈·문학화 감지 → rollback_and_rewrite
• 2차 윤문에서 변경률 22%, 안정화

에러 흐름 2 — S1 잔존

• 1차 윤문 후 S1 2건 잔존 (D-1 "결론적으로" 미제거)
• 리뷰어 rewrite_round_2 판정
• 2차 윤문에서 해당 finding만 재처리, 잔존 0

엣지 케이스 — 이미 사람이 쓴 글

• detected_count == 0 또는 score < 10
• Phase 2 게이트에서 "윤문 불필요" 메시지로 종료

주의 사항

• 의미 불변이 최상위 불문율. 모든 에이전트가 이를 위반 감지 즉시 롤백.
• 수치·고유명사·직접 인용은 탐지/윤문 대상 아님. Do-NOT list 엄수.
• 장르 이탈 금지. 에세이를 문학으로, 리포트를 블로그로 옮기지 않는다.
• 이모지·불릿·헤딩 제거는 장르 규칙 따름. SNS·제품 카피는 유지 가능.
• 변경률 30% 초과 → 경고, 50% 초과 → 강제 중단.

참고 자료

• 분류 체계: references/ai-tell-taxonomy.md (10대분류 × 40+ 서브 패턴, 심각도 정의, 탐지 JSON 스키마)
• 윤문 처방: references/rewriting-playbook.md (카테고리별 치환 레시피, 장르별 허용 표, 변경률 모니터링)
• 웹 서비스 스펙: references/web-service-spec.md (Phase 5에서만 로드, 아키텍처·API·UX)