ahastudio/til/humanize-korean

Humanize Korean — AI 한글 티 제거 오케스트레이터 (v2.3)

v2.3.2 — 플러그인 스킬을 관례 위치(루트 skills/)로 이동. 마켓플레이스 설치에서 shim·진단이 조용히 누락되던 경로 문제 해소.

v2.3.1 — 경로 해석·런타임 경계·계약 정합 수정 회차(외부 제보 반영). 기능 변경 없음.

v2.3.0 — 구조 수렴 게이트(verify_gates.py 4축: 목표달성·대구 전멸·수치·golden) + 진단 슬림 인덱스(diagnosis-rules.md, taxonomy 83%↓). (v2.2: route_hint 3경로 + 단일 콜 우선)

버전 히스토리·실측 근거·테스트 시나리오: `${CLAUDE_SKILL_DIR}/references/design-notes.md`

목차

이 파일의 소제목과 같은 이름이다. 소제목을 검색하면 해당 절로 간다.

• Phase 0: 컨텍스트 확인 및 경로 결정: 경로(light, standard, heavy) 결정 규칙, run_id 결정
• 스크립트 경로 규칙: 스크립트는 절대경로로 부르고 references/*는 스킬 디렉터리 기준으로 쓴다
• Phase 1: 입력 저장과 정량 사전 점수: 입력 shim, 전 경로 공통
• Light 경로(1콜), Standard 경로(2콜), Heavy 경로(3+콜): 진단과 윤문과 finalize의 호출 구성
• Finalize 승급 규칙: finalize를 추가로 실행하는 조건
• Phase 2.4: 서법 국소 복원: 게이트 직전의 결정적 변형, LLM 콜 0회
• Phase 2.5: 구조 게이트: verify_gates.py 판정은 코드가 한다
• 결과 전달: 사용자에게 돌려줄 네 가지
• 부분 재실행과 후속 명령, 옵션: 사용자 신호별 처리, 장르와 강도 옵션
• 데이터 흐름 요약, 설계 노트, 에이전트 호출 규칙: 구조와 근거
• 주의 사항: 의미 불변이 최상위 불문율, 핵심 내용어 원형 보존
• 참고 자료: references/ 목록

Phase 0: 컨텍스트 확인 및 경로 결정

작업 시작 시 가장 먼저 다음 한 줄을 사용자에게 출력한다.

humanize-korean v2.3 — 경로: {light|standard|heavy} ({route_hint|사용자 지정}) / run_id: {YYYY-MM-DD-NNN-TAG}

(경로는 Phase 1의 shim 실행 후에 확정되므로, 이 상태 줄은 shim 직후 출력한다.)

전 경로 공통 의미 앵커

• 윤문 전에 문장별 핵심 내용 명사·개념어를 내부 목록으로 잡는다. 주어·목적어·보어에서 원문의 주장을 구성하는 어휘가 대상이다.
• 조사·어미는 바꿀 수 있지만, 내용 앵커의 원형 어휘는 결과에 최소 한 번 그대로 남긴다. 동의어 치환이나 문장 병합을 이유로 삭제하지 않는다.
• AI 관용구·추상어를 덜어낼 때는 수식어와 형식명사만 걷어낸다. 내용 앵커까지 함께 사라질 것 같으면 해당 문장을 롤백한다.
• 출력 직전 원문과 윤문본을 다시 대조한다. 내용 앵커 하나라도 빠졌으면 자연성보다 의미 보존을 우선해 복원한다.

경로 결정 규칙

1. 사용자 명시가 최우선. --strict·"정밀 모드"·"정밀하게"·"제대로" → heavy 고정. "가볍게"·"빠르게만" → light 고정. 명시가 있으면 route_hint는 무시한다.
2. 명시가 없으면 shim이 00_metrics.json에 쓴 `route_hint`(light|standard|heavy)를 디폴트 경로로 따른다.
3. route_hint 필드가 없거나 shim이 graceful degrade로 점수 산출에 실패한 경우 → standard로 간주.
4. light/standard 결과가 등급 C/D → 사용자에게 "heavy(정밀) 재실행 권고" 안내(자동 전환 아님 — 사용자 opt-in).
5. 입력 길이는 경로를 바꾸지 않는다. 1만자급도 단일 콜로 처리한다(§설계 노트의 실측 근거 참조). 길이·중증도 판단은 shim의 route_hint에 위임한다.

run_id 결정

• 모든 경로는 cwd 기준. 새 폴더 생성도 cwd 기준 _workspace/{YYYY-MM-DD-NNN-TAG}/에 만든다.
• `TAG` 는 세션 구분자다. Phase 1 맨 처음에 한 번 만들어 그 run 내내 재사용한다.

``bash TAG=$(python3 -c "import secrets;print(secrets.token_hex(2))") # 예: a3f9 ``

이후 모든 명령의 _workspace/{run_id} 에 같은 TAG 를 쓴다. 중간에 새로 만들지 않는다.

• 기존 시퀀스 확인은 `Glob` 도구로 표지 파일을 매칭해 간접 조회.

올바른 사용법: Glob(pattern="_workspace/YYYY-MM-DD-*/01_input.txt") → 결과에서 폴더명 추출 후 NNN 최댓값 + 1. (-TAG 가 뒤에 붙어도 접두어가 같아 이 패턴은 그대로 맞는다.) 주의: Glob은 디렉토리 자체는 매칭하지 못한다. 반드시 그 안의 표지 파일(01_input.txt)을 매칭할 것. Bash ls는 OS·셸 환경에 따라 경로 해석이 달라지므로 사용 금지.

• 당일 폴더가 없으면 NNN = 001. 있으면 마지막 NNN + 1.
• 부분 재실행 신호("이 카테고리만 다시"·"2차 윤문")일 경우 기존 run_id 재사용(TAG 포함) + heavy 경로로 자동 승급.

🔴 TAG 를 빼지 마라. 한 머신에서 세션이 여러 개 동시에 도는 환경에서는 NNN 만으로

겹친다. Glob 으로 자리를 확인하고 mkdir 하기까지 틈이 있어 다른 세션이 같은 번호를

잡기 때문이다. 두 세션이 한 디렉터리를 쓰면 서로의 01_input.txt 를 덮어쓰고, 게이트가

남의 원문과 내 윤문본을 비교해 있지도 않은 제목·인용이 사라졌다며 ABORT 를 낸다.

윤문본 자체는 멀쩡하므로 원인을 찾기가 특히 어렵다.

스크립트 경로 규칙 (${SKILL_ROOT})

스크립트는 절대경로로 부른다. cwd 기준 상대경로로 부르면 안 된다.

references/* 는 스킬 디렉터리 기준이라 ${CLAUDE_SKILL_DIR} 를 쓴다 — ${SKILL_ROOT} 와 기준이 다르니 섞지 않는다. 룰북·taxonomy 경로도 맨앞 접두어 없이 쓰면 cwd 로 풀려 No such file or directory 가 난다.

scripts/*.py는 설치 루트에 있고 cwd 는 사용자 작업 디렉터리다. 마켓플레이스 설치에서 둘은 절대 일치하지 않는다. 반면 _workspace/ 같은 데이터 경로는 cwd 기준이다(run_id 규칙 참조). 두 기준이 한 명령줄에 섞이므로 스크립트 쪽만 절대경로로 고정한다.

Phase 1 시작 전에 한 번 정한다.

SKILL_ROOT="$(d="$(cd -P "${CLAUDE_SKILL_DIR}" && pwd)"; \
  while [ "$d" != / ] && [ ! -d "$d/.claude-plugin" ] && [ ! -f "$d/scripts/prepare_monolith_input.py" ]; do d="$(dirname "$d")"; done; \
  [ "$d" = / ] && s="$(dirname "$(cd -P "${CLAUDE_SKILL_DIR}" && pwd)")/humanize-korean" && [ -f "$s/scripts/prepare_monolith_input.py" ] && d="$s"; echo "$d")"

.claude-plugin/ 디렉터리, 또는 scripts/prepare_monolith_input.py 를 품은 디렉터리를 만날 때까지 거슬러 올라간다. 뒤 조건은 install.sh --copy 설치용이다 — 복사 설치는 스킬 디렉터리만 떼어 오므로 조상에 마커가 없고, 대신 런타임 스크립트를 스킬 디렉터리 안 scripts/ 에 함께 복사한다(#144). 둘째 줄은 /humanize·/humanize-scan·/humanize-redo 로 들어온 복사 설치용 폴백이다 — 이 래퍼 스킬에는 scripts/ 가 없으므로, / 까지 올라가도 못 찾으면 형제 humanize-korean/ 을 본다. 고정된 횟수로 올라가지 않는 이유는 스킬 위치가 배포 방식마다 다를 수 있어서다 — 고정 깊이는 레이아웃이 바뀌면 조용히 엉뚱한 곳을 가리킨다.

`cd -P` 가 핵심이다. 심링크 설치(install.sh 기본)에서는 스킬 디렉터리가 저장소를 가리키는 심링크라, 그냥 cd 하면 셸이 논리 경로를 유지해 엉뚱한 곳(홈 디렉터리)으로 올라간다. -P 로 물리 경로를 먼저 푼 뒤 올라가야 심링크·플러그인 양쪽에서 같은 답이 나온다. 이후 모든 스크립트 호출에 ${SKILL_ROOT}/scripts/... 를 쓴다.

확인: ls "${SKILL_ROOT}/scripts/prepare_monolith_input.py" 가 실패하면 경로 유도가 틀린 것이다. 이 경우 스크립트를 찾을 때까지 임의로 추측하지 말고, 정량 shim·게이트 없이 진행한다고 사용자에게 알린 뒤 계속한다. 조용히 건너뛰면 route_hint 와 철칙 #4 게이트가 사라진 것을 아무도 모른다.

CLAUDE_PLUGIN_ROOT 는 Bash 도구 안에서 비어 있는 경우가 확인됐다(#84). 이 변수에 의존하지 않는다.

Phase 1: 입력 저장 + 정량 사전 점수 (input shim — 전 경로 공통)

1. cwd 기준 _workspace/{run_id}/ 생성
2. 입력 텍스트를 01_input.txt에 저장

• 챗봇 잔재 위생 (v2.6): 저장 전에 챗봇 프레임 문장이 섞여 있으면 벗겨낸다 — 머리("물론입니다!", "다음은 ~입니다:", "요청하신 내용을 정리하면"), 꼬리("도움이 되셨길 바랍니다", "추가 질문이 있으시면"), 지식 한계 면책("제 지식은 ~까지입니다"). 실사용자는 챗봇 출력을 그대로 붙여넣는 일이 많고, 이 문장들은 본문이 아니므로 제거해도 의미 손실이 0이다. 본문 안에 자연스럽게 녹아 있는 유사 표현은 건드리지 않는다.

1. 첫 300자로 장르 자동 추정 (사용자 명시 시 우선)
2. 사전 처리 shim을 Bash로 1회 실행:

`` python3 ${SKILL_ROOT}/scripts/prepare_monolith_input.py --run-dir _workspace/{run_id} --genre {genre} ``

• --genre 값은 영문 키: essay | column | report | blog | abstract (생략 시 essay). 장르 힌트 매핑: 칼럼→column, 리포트→report, 블로그→blog, 공적/기타→essay.
• --run-dir·--diagnosis의 상대 경로는 cwd 기준으로 해석된다(위 run_id 규칙과 동일 기준). 그 외 인자: --text(run-dir 없이 즉석 실행 시 새 run 디렉토리 자동 생성 — 이때는 --session-tag {TAG} 를 같이 준다), --baseline(baseline JSON 경로 override, 평소 불필요), --diagnosis(진단 텍스트 파일을 점수 블록 앞에 prepend — standard·heavy의 진단 결합용).
• 산출: 00_metrics.json(정량 점수 + `route_hint`) + 01_input_with_metrics.txt(점수 블록을 원문 앞에 붙인 결합 파일).
• graceful degrade 내장: metrics 계산이 실패하면 shim이 점수 블록 없이 원문만 감싼 결합 파일을 쓰고 00_metrics.error를 남긴다. 이 경우 route_hint 없음 → standard 경로.

1. 00_metrics.json의 route_hint를 읽어 Phase 0 규칙대로 경로를 확정하고 상태 줄을 출력한다.

단일 콜 우선 — 청킹은 여기서 하지 않는다. --chunk는 heavy 경로 전용이며, 그때도 청크 경로를 탈지는 shim이 실제로 청크를 2개 이상 만들었는지로 정한다(heavy 절 참조).

Light 경로 (1콜) — 잘 쓴 글

어휘 티가 거의 없고 구조 티만 미미한 글. 목표는 과윤문 방지이지 많이 고치는 게 아니다.

1. 진단 생략. humanize-monolith를 Agent 도구로 1회 호출 — 청킹 없음.

• 입력: input_path=01_input_with_metrics.txt, quick_rules_path=${CLAUDE_SKILL_DIR}/references/quick-rules.md, genre_hint, 그리고 강도 지시 보수(내용 앵커 원형 보존, 원문에 없던 표현 삽입 금지, 확신 없는 구간은 그대로 둔다).
• 출력: final.md (본문 + <!-- HUMANIZE-SUMMARY --> 블록).

1. Phase 2.5 변경률 게이트(Bash — LLM 콜 아님).
2. 조기 종료 보고: monolith 탐지가 거의 없고 게이트 변경률이 5% 미만이면, 결과 전달을 "이미 좋은 글입니다 — 손댄 곳은 {N}곳({요지}) 정도"로 요약한다. 억지로 더 고치지 않는다.
3. 게이트 exit 2(≥50%)일 때만 롤백 재실행 1회(이 경우 총 2콜). light에서 50%가 나오면 과윤문 사고이므로 재실행 지시에 보수 강도를 재강조한다.

콜 수: 1 (게이트 실패 시 최대 2).

Standard 경로 (2콜) — 보통의 AI 초안

1. 진단 1콜: humanize-diagnostician을 Agent 도구로 1회 호출.

• 입력: input_path=01_input_with_metrics.txt, taxonomy_path=${CLAUDE_SKILL_DIR}/references/diagnosis-rules.md (진단 전용 슬림 인덱스 — 전 패턴 전수, taxonomy에서 자동 생성)
• 출력: 02_diagnosis.md — 글 전체의 지배 패턴 3~6개(본진 ID + 근거 + 처방) + 장르·격식 + 보존 지침.
• 진단은 span을 세지 않는다. "무엇이 이 글을 지배하는가"를 판단한다(안정적).

1. shim으로 진단을 monolith 입력 앞에 결합 (Bash — LLM 콜 아님):

`` python3 ${SKILL_ROOT}/scripts/prepare_monolith_input.py --run-dir _workspace/{run_id} --genre {genre} --diagnosis _workspace/{run_id}/02_diagnosis.md ` → 01_input_with_metrics.txt`가 [진단 → 정량 블록 → 원문] 순으로 재생성된다.

1. 윤문 1콜: humanize-monolith 1회 호출 — 청킹 없음. 1만자급도 단일 콜이다. → final.md.
2. Phase 2.5 변경률 게이트(Bash).
3. finalize 생략이 기본. 과윤문은 verify_gates.py의 결정적 게이트가 잡는다. finalize 승급 조건(아래 표)에 걸릴 때만 humanize-finalizer 1콜 추가(이 경우 총 3콜).

콜 수: 2 (finalize 승급·게이트 롤백 시 3).

Heavy 경로 (3+콜) — 중증 AI 슬롭·검증 증적 필요

--strict·"정밀 모드"의 강제 대상. 진단→겨냥 윤문→finalize의 완전한 3콜 구조.

Phase P1: 진단

Standard의 1과 동일 — humanize-diagnostician 1콜 → 02_diagnosis.md. 장문이라도 진단은 통짜 1콜(전 청크 공유)이다.

Phase P2: 겨냥 윤문

1. shim으로 진단 결합 (Bash). heavy에서만 --chunk를 함께 줄 수 있다:

`` python3 ${SKILL_ROOT}/scripts/prepare_monolith_input.py --run-dir _workspace/{run_id} --genre {genre} --diagnosis _workspace/{run_id}/02_diagnosis.md --chunk ``

• 분할 여부·경계는 100% shim(Python)이 정한다(문단·문장 경계, 헤딩 승격, 말미 각주 passthrough — 청킹 임계는 shim 관리).
• 산출: 01_chunk_{NN}_input_with_metrics.txt N개 + chunk_manifest.json.

1. 청크 경로 판정: chunk_manifest.json의 body 청크(passthrough 제외)가 2개 이상일 때만 청크 경로. 1개면 단일 monolith 콜로 처리한다 — 청킹은 shim의 결정이지 오케스트레이터의 추측이 아니다. 단일 콜로 처리할 때의 입력 파일도 manifest가 있으면 그 청크의 input_file 값을, 없으면 01_input_with_metrics.txt를 쓴다.
2. 단일 콜(기본): humanize-monolith 1회 호출(input_path=01_input_with_metrics.txt). monolith는 진단문을 앞머리에서 읽고 지배 패턴을 겨냥해 윤문한다. → final.md.
3. 청크 병렬(shim이 실제로 쪼갠 경우만):

• 각 body 청크를 monolith로 병렬 호출(동시 최대 4). 입력·출력 파일명은 manifest의 `input_file`·`rewritten_file` 필드를 그대로 사용한다 — 파일명을 직접 조립하지 않는다(인덱싱 불일치 사고 방지).
• 각 청크 콜은 같은 quick_rules_path(파일 참조)와 같은 02_diagnosis.md를 공유한다. 룰북·진단 전문을 청크 프롬프트에 복붙하지 않는다 — 재로드 비용이 청킹 토큰 폭발의 주범이었다(§설계 노트).
• 재조립: python3 ${SKILL_ROOT}/scripts/reassemble_chunks.py --run-dir _workspace/{run_id} → 03_reassembled.md(passthrough 원문 삽입 + 문자수 대사). 이걸 final.md로 삼는다.
• 청크 경계 문체 이음매가 어색하면 경계 전후 2문단만 monolith로 국소 패치(전역 재작성 금지 — 의미 드리프트 유발).
• 재청킹 주의: --chunk 재실행 시 경계가 바뀌므로 기존 02_chunk_*_rewritten.txt는 shim이 자동 삭제한다(stale_removed). 청킹 후 입력을 수정하면 재청킹부터 다시 한다.

Phase P2.5: 구조 게이트

Phase 2.5(공통)와 동일 — verify_gates.py --genre {genre}. Bash 1회 — LLM 콜 아님.

Phase P3: finalize (heavy는 항상)

humanize-finalizer를 Agent 도구로 1회 호출.

• 입력: original_path=01_input.txt, rewritten_path=final.md, diagnosis_path=02_diagnosis.md
• 원문↔윤문본 직접 대조로 의미 보존 15항(각주·제목·없던 주장 주입 포함) + 자연성(잔존 + 과윤문 양방향)을 판정하고 문제 구간만 국소 보정(전체 재작성 금지).
• 출력: 보정된 final.md(원본은 final_pre_finalize.md 백업) + 09_finalize.json.
• verdict=hold_and_report면 사람 검토 안내. 그 외 finalize 후 verify_gates.py를 한 번 더 돌려 최종 변경률 확정.

콜 수: 3 (진단 1 + 윤문 1 + finalize 1). 청크 병렬 시 2 + N + 국소 패치.

Finalize 승급 규칙 (전 경로 공통)

finalize는 추가 LLM 콜이다. 다음 조건에서만 실행한다:

진단 파일이 없을 때(Light 승급). Light 경로는 02_diagnosis.md를 만들지 않는다. Light에서 승급 조건에 걸리면 `diagnosis_path` 없이 humanize-finalizer를 호출한다 — 진단을 만들려고 콜을 추가하지 않는다. finalize의 본체(의미 보존 15항 + 자연성)는 원문↔윤문본 직접 대조로 성립하므로 진단 없이도 온전히 동작하며, 이 경우 도구 호출은 3회로 줄어든다. (Light가 승급하는 상황은 애초에 "예상보다 많이 고쳤다"이므로, 겨냥 대상을 새로 진단하는 것보다 고친 결과를 검증하는 것이 맞다.)

Phase 2.4: 서법 국소 복원 (전 경로 공통, 게이트 직전)

P5는 서법 위반을 판정만 한다. 판정 전에 고칠 수 있는 것은 고쳐 둔다 — 유보·요구가 사라진 문장만 원문 문장으로 되돌리는 결정적 변형이다. LLM 콜 0회.

python3 ${SKILL_ROOT}/scripts/restore_modality.py \
    --before _workspace/{run_id}/01_input.txt \
    --after  _workspace/{run_id}/final.md \
    --out    _workspace/{run_id}/final.md
python3 ${SKILL_ROOT}/scripts/strip_injected_commas.py \
    --before _workspace/{run_id}/01_input.txt \
    --after  _workspace/{run_id}/final.md \
    --out    _workspace/{run_id}/final.md

두 번째 명령은 C-11 역주입 제거 — 윤문이 새로 쓴 문장에서만 연결어미 뒤 쉼표를 걷어낸다(원문에 있던 문장은 불가침 — 필자 쉼표 보호). light 실측에서 윤문 후 연결어미 쉼표가 원문보다 늘어난 문서가 16/28이었다. LLM 콜 0회.

`--all` 격상 (standard·heavy 한정): 02_diagnosis.md가 C-11(연결어미 뒤 쉼표)을 탐지 티로 지목한 경우에만 두 번째 명령에 --all을 붙인다 — 전 문장 (따옴표 안 제외)에서 제거해 원문에 실려 온 주입 쉼표(잔존분)까지 걷어낸다. 근거: 사람 532편 실측에서 연결어미 쉼표는 사람 중앙값이 문장의 15%라 밀도만으로는 사람/주입을 못 가른다 — 그래서 격상 조건은 밀도 임계가 아니라 경로+진단 판정이다. 진단이 없는 light 경로에서는 절대 쓰지 않는다.