AGENTS.md

1# Humanize KR — AI 한글 티 제거 하네스 (v2.2.0)
2 
3## 프로젝트 개요
4 
5AI(ChatGPT·Claude·Gemini 등)가 쓴 한글 텍스트를 "사람이 쓴 글처럼" 윤문해주는 3경로 하네스. 번역투·영어 인용 과다·기계적 병렬·관용구·피동태 남용·접속사 남발·리듬 균일성·이모지/불릿 과다 등 10대 카테고리 70개 AI 티 패턴(+A-17 hold 1건)을 탐지·분류해 **내용은 한 글자도 건드리지 않고** 문체·리듬·표현만 재작성한다.
6 
7v2.2부터 shim이 정량 점수로 산출하는 **`route_hint`(light | standard | heavy)** 가 디폴트 경로를 정한다(사용자 명시가 오버라이드). 글의 상태가 콜 수를 정하는 구조로, 구 "fast 1콜 / 정밀 3콜" 이분법을 대체한다.
8 
9- **light (1콜)** — 잘 쓴 글(어휘 티 거의 0). 진단·finalize 생략, 보수 강도 단일 윤문. 손댈 게 거의 없으면 "이미 좋습니다" 조기 종료.
10- **standard (2콜)** — 보통의 AI 초안. 진단 1콜 + 겨냥 윤문 1콜. finalize 생략이 기본(결정적 변경률 게이트로 대체). 1만자급도 청킹 없이 단일 윤문 콜.
11- **heavy (3+콜)** — 중증 AI 슬롭 밀집 or 초장문(15,000자 초과) or 검증 증적 필요. 진단 → 윤문(shim이 청크를 2개 이상 만든 경우에만 청크 병렬) → finalize. `--strict`·"정밀 모드"는 이 경로를 강제.
12 
13**콜 수 절감 원리** — 절감은 모델 티어가 아니라 콜 수에서 온다. 실측: 1만자 글 청킹 7콜 = 610K 토큰 vs 단일 콜 = 134K(품질 동등). 청크마다 룰북·진단이 재로드되는 비용이 폭발 원인. 따라서 **단일 콜 우선, 청킹은 heavy 전용·15,000자 이하 비권장.**
14 
15## 철칙
16 
171. **의미 불변 (Fidelity First)** — 사실·주장·수치·고유명사·인용은 100% 원문 보존.
182. **근거 기반 (Span-Grounded)** — 모든 변경은 탐지 finding에 연결. 탐지 없는 구간은 건드리지 않음.
193. **장르 유지 (Tone Match)** — 칼럼을 문학으로, 리포트를 에세이로 옮기지 않음.
204. **과윤문 금지 (No Over-Polish)** — 변경률 30% 초과 시 경고, 50% 초과 시 강제 중단.
215. **register 보존 — 양방향** — 격식체 입력은 격식체 출력, 구어 입력은 구어 출력. 원문보다 딱딱하게 만들지 않는다: **'-했-' → '-하였-' 치환 금지**, '~인데요/~거든요/~한 겁니다' 구어 종결 보존. (하향 금지만 있던 기존 단방향 규칙으로는 합쇼체가 유지되는 '했→하였' 상향을 못 잡았다.) AI 티는 문법·수사이지 격식 자체가 아니다.
226. **AI 티는 빼기만 하고 넣지 않는다 (No New Tells)** — 원문에 없던 상투구("기록적인 성과를 거두었다"·"괄목할 만한"·"~로 평가된다") 신규 삽입 금지. 살아있는 구어는 사람 글의 증거이므로 보존한다. 철칙 #2가 "탐지 없는 구간은 손대지 않는다"라면, #6은 "손대는 구간에도 새 AI 티를 심지 않는다" — 모순이 아니라 보완이다.
23 
24## 디렉토리 구조
25 
26```
27im-not-ai/
28├── CLAUDE.md                      # 본 파일 — 프로젝트 가이드
29├── README.md / INSTALL.md         # 사용·설치 안내
30├── RELEASING.md                   # 릴리스 체크리스트 (버전 문자열 전수 + 글로벌 심링크 동기화)
31├── CONTRIBUTORS.md
32├── .claude-plugin/                # Claude 플러그인 + 마켓플레이스 매니페스트
33│   ├── plugin.json                # skills: ./.claude/skills/ · 에이전트는 루트 agents/ 자동탐색
34│   └── marketplace.json           # /plugin marketplace add epoko77-ai/im-not-ai
35├── gemini-extension.json          # Gemini CLI Extension 매니페스트
36├── GEMINI.md                      # Gemini 에이전트 컨텍스트 (monolith 룰 인라인)
37├── commands/                      # Gemini CLI 커스텀 명령 (/humanize-korean, /humanize, /humanize-redo)
38├── install.sh / uninstall.sh / update.sh   # Claude·Codex·Gemini 전역 설치/제거 (심링크 기본)
39├── scripts/
40│   ├── prepare_monolith_input.py  # input shim — 정량 점수 + route_hint 산출 + 결합 입력 (`--diagnosis`·`--chunk` 지원)
41│   ├── reassemble_chunks.py       # 장문 청킹 재조립 (passthrough 원문 삽입 + 문자수 대사)
42│   ├── verify_change_rate.py      # 변경률 게이트 — 철칙 #4의 결정적 판정 (exit code)
43│   ├── build_quick_rules.py       # taxonomy quick 메타 → quick-rules.md 빌드 (ID 드리프트 차단)
44│   ├── build_social_preview_v2.py
45│   └── make_thumbnail.py
46├── tests/                         # pytest — metrics 단위 + 청킹 + 빌드 sync + golden 픽스처
47│   ├── test_metrics.py · test_metrics_v2.py · test_chunking.py · test_quick_rules_build.py
48│   └── golden/                    # 윤문 품질 회귀 픽스처 + 결정적 채점기(checks.py)
49├── agents/                        # 서브에이전트 9종 (플러그인 컨벤션 — 루트 agents/에 둬야 로드됨)
50│   ├── humanize-monolith.md       # 전 경로 공용 윤문 콜
51│   ├── humanize-diagnostician.md  # standard·heavy P1 진단 (지배 패턴 3~6개)
52│   ├── humanize-finalizer.md      # heavy P3 마무리 (의미 15항 + 자연성)
53│   ├── korean-ai-tell-taxonomist.md  # 유지보수 (SSOT 갱신)
54│   └── … 개발용 지원 5종 (scholar·distiller·gap-analyzer·metric-engineer·integrator)
55├── .claude/skills/                # 스킬 3종 (humanize-korean 오케스트레이터 + humanize·humanize-redo 진입)
56│   └── humanize-korean/
57│       ├── SKILL.md               # 오케스트레이터 (route_hint 3경로 분기·shim 배선, quick_rules_path: ${CLAUDE_SKILL_DIR}/...)
58│       └── references/
59│           ├── quick-rules.md          # monolith 슬림 룰북 (build_quick_rules.py가 taxonomy에서 생성)
60│           ├── quick-rules.header.md · quick-rules.footer.md  # 빌드 고정 템플릿
61│           ├── ai-tell-taxonomy.md     # SSOT — 10대분류 × 활성 70 패턴 (+ _quick 빌드 메타)
62│           ├── rewriting-playbook.md   # 카테고리별 치환 레시피
63│           ├── metrics.py · metrics_v2.py     # v1.6 8종 + v2.0 post-editese 14종
64│           ├── baseline.json · baseline_v2.json   # v1.6 baseline · v2.0(placeholder — calibration 대기)
65│           ├── scholarship.md          # v2.0 학술 인용 외부 SSOT
66│           └── web-service-spec.md     # 웹 확장 스펙 (옵션)
67├── codex/skills/humanize-korean/  # Codex Fast Path 스킬 (references → SSOT 공유 심링크)
68└── _workspace/                    # 런타임 산출물 (run_id별, gitignored)
69    └── {YYYY-MM-DD-NNN}/
70        ├── 01_input.txt · 00_metrics.json · 01_input_with_metrics.txt  # 원문·점수·결합
71        ├── final.md                    # 윤문본 (끝에 <!-- HUMANIZE-SUMMARY --> 블록)
72        ├── 01_chunk_{NN}… · 02_chunk_{NN}_rewritten.txt · 03_reassembled.md  # (장문 청킹)
73        ├── 02_diagnosis.md             # (standard·heavy P1) 지배 패턴 진단
74        ├── final_pre_finalize.md · 09_finalize.json   # (heavy P3) 백업 · 판정
75```
76 
77## 파이프라인 (route_hint 3경로)
78 
79```
8001_input.txt
81    ↓ [scripts/prepare_monolith_input.py --run-dir _workspace/{run_id} --genre {genre}]
8200_metrics.json (route_hint 포함) + 01_input_with_metrics.txt
83    ↓ route_hint가 디폴트 경로 결정 (사용자 명시 --strict/"가볍게"가 오버라이드)
84    │
85    ├─ light ────→ [humanize-monolith ×1, 보수 강도] ──→ final.md
86    │
87    ├─ standard ─→ [humanize-diagnostician] → 02_diagnosis.md
88    │                ↓ [shim --diagnosis] 진단+점수+원문 결합
89    │              [humanize-monolith 겨냥 윤문] ──────→ final.md
90    │
91    └─ heavy ────→ [humanize-diagnostician] → 02_diagnosis.md
92                     ↓ [shim --diagnosis] (청킹 필요 시에만 --chunk)
93                   [humanize-monolith — shim이 청크 2+개 만든 경우에만 청크 병렬]
94                     ↓ [verify_change_rate.py] (P2.5)
95                   [humanize-finalizer — 의미 15항 + 자연성, 국소 보정]
96                   final.md(보정) + 09_finalize.json
97    ↓ [scripts/verify_change_rate.py — 변경률 게이트 (exit code)] — 모든 경로 공통
98```
99 
100- shim은 graceful degrade 내장 — metrics 실패 시 점수 블록 없는 결합 파일을 쓰고 `00_metrics.error`를 남긴다. 이 경우 route_hint 부재 → **standard로 간주**.
101- **청킹 남발 금지** — `--chunk`는 heavy 전용, 15,000자 이하 비권장. 그때도 shim이 실제로 청크를 2개 이상 만들었을 때만 병렬(청크 1개면 단일 콜). 재조립은 `reassemble_chunks.py`.
102- light·standard 결과가 등급 C/D면 heavy 재실행을 사용자에게 권고한다(자동 전환 아님 — opt-in).
103- finalize의 `verdict=hold_and_report`면 사람 검토 권고. 수렴 판정은 LLM 재탐지가 아니라 `verify_change_rate.py`(결정적, exit code)가 내린다.
104 
105## 에이전트 구성 (9개 — 역할 구분 필수)
106 
107**런타임 3종** (스킬 실행 중 호출):
108 
1091. **humanize-monolith** — 전 경로 공용 윤문 콜. 한 콜에서 탐지·윤문·자체검증. 도구 호출 3회 캡 (v1.6.1).
1102. **humanize-diagnostician** — standard·heavy P1 진단. 글 전체의 지배 패턴 3~6개를 본진 ID로 진단 → `02_diagnosis.md`.
1113. **humanize-finalizer** — heavy P3 마무리. 원문 직접 대조로 의미 15항 + 자연성(잔존·과윤문 양방향) 판정, 문제 구간만 국소 보정 → `09_finalize.json`. 도구 호출 4회 캡.
112 
113**유지보수 1종** (별도 명령으로만):
114 
1154. **korean-ai-tell-taxonomist** — 분류 체계 SSOT 관리. 신규 패턴 심사·승격.
116 
117**개발용 1회성 5종** (v2.0 학술 흡수 회차 전용 — 윤문 런타임에 로드되지 않음):
118 
1195. **translationese-research-distiller** — 번역투 학술 보고서 구조화 증류.
1206. **korean-translation-scholar** — 학술 인용 계보를 taxonomy + scholarship.md 양면 안착.
1217. **taxonomy-gap-analyzer** — 외부 후보 풀 vs 본진 3축 갭 매핑.
1228. **post-editese-metric-engineer** — post-editese 3축을 metrics_v2.py로 코드화.
1239. **quick-rules-integrator** — v2.0 변경 묶음의 quick-rules 안착 + 캡 회귀 검증 + PR 준비.
124 
125**은퇴 (v2.1)**: 옛 strict 5인 파이프라인의 `ai-tell-detector`·`korean-style-rewriter`·`content-fidelity-auditor`·`naturalness-reviewer`와 웹 확장 설계용 `humanize-web-architect`는 v2.1에서 은퇴(정의 파일 삭제). 탐지·감사·리뷰 역할은 diagnostician·finalizer와 `verify_change_rate.py` 게이트가 대체했다.
126 
127## 심각도 기준
128 
129- **S1 결정적**: 한 번만 나와도 AI라고 확신하게 되는 패턴. 무조건 제거.
130- **S2 강함**: 1~2회 허용, 3회+ 반복 시 제거.
131- **S3 약함**: 다른 패턴과 중첩될 때만 문제.
132 
133## 품질 등급
134 
135- **A**: S1 0건, S2 2건 이하, score 개선 70%+
136- **B**: S1 0건, S2 4건 이하, score 개선 50%+
137- **C**: S1 1~2건 또는 과윤문 시그널 2개 — 2차 윤문
138- **D**: S1 3건 이상 또는 심각한 과윤문 — 사람 검토
139 
140## 사용 방법
141 
1421. 새 세션에서 오케스트레이터 스킬 트리거:
143```
144   이 AI 글 자연스럽게 윤문해줘:
145```
146   (텍스트 첨부) — 또는 `/humanize` 슬래시 커맨드.
1472. 디폴트는 shim의 `route_hint`가 정한다 — light 1콜 / standard 2콜 / heavy 3+콜. `--strict`·"정밀 모드"·부분 재실행은 heavy 강제, "가볍게"는 light 강제.
1483. 결과: light는 `final.md` 1개(끝에 summary 주석 블록), standard는 + `02_diagnosis.md`, heavy는 + `09_finalize.json`·`final_pre_finalize.md`.
149 
150## 파일 시스템 접근 규칙
151 
152에이전트가 파일·디렉토리에 접근할 때는 전용 도구를 우선 사용한다.
153`Bash` 툴의 `ls`·`cat`·`echo`는 실행 환경(OS·경로 형식)에 따라 동작이 달라져 예측 불가한 오류를 일으킬 수 있다. 예외: `prepare_monolith_input.py`(shim)·`verify_change_rate.py`(변경률 게이트)·`reassemble_chunks.py`(청킹 재조립) 실행은 Bash `python3` 호출이 정규 경로다.
154 
155| 작업 | 올바른 방법 | 피할 방법 |
156|---|---|---|
157| 파일 존재 확인 | `Glob` 도구 | `Bash` 툴 `ls` |
158| 디렉토리 목록 열거 | `Glob` 도구로 안의 표지 파일 매칭 (예: `*/01_input.txt`) | `Bash` 툴 `ls` |
159| 파일 읽기 | `Read` 도구 | `Bash` 툴 `cat` / `head` |
160| 파일 쓰기·편집 | `Write` / `Edit` 도구 | `Bash` 툴 리다이렉션 |
161 
162## 주요 금기
163 
164- 수치·단위·날짜 변경 금지.
165- 고유명사·제품명·모델명 변경 금지.
166- 큰따옴표 인용문 내부 변경 금지.
167- 법률 조문·학술 개념어 임의 치환 금지.
168- 새로운 주장·사실·예시 추가 금지.
169- 원문에 있던 정보 누락 금지.
170 
171## 릴리스
172 
173버전 문자열이 흩어져 있어 릴리스마다 누락 사고가 반복됐다 (v1.6.1·v2.0에서 SKILL.md 두 번 연속 누락). **릴리스 전 반드시 `RELEASING.md` 체크리스트를 따를 것.** 태그는 발행 노트·문서 갱신 커밋이 main에 머지된 뒤에 찍는다.
174 
175## 확장 포인트
176 
177- **웹 서비스화**: 별도 코드베이스로 라이브 (imnotai.kr). 본 리포의 `web-service-spec.md`는 설계 산출물로만 보존 (설계 에이전트 `humanize-web-architect`는 v2.1에서 은퇴).
178- **다국어 확장**: 일본어·중국어로 확장 시 언어별 taxonomy 분리 파일 추가.
179- **장르 확장**: 현재 4장르(칼럼·리포트·블로그·공적). 학술 논문·법률 문서·제품 카피 추가 가능.
180 
181## 참고
182 
183- 오케스트레이터: `.claude/skills/humanize-korean/SKILL.md`
184- 분류 체계: `.claude/skills/humanize-korean/references/ai-tell-taxonomy.md`
185- 윤문 처방: `.claude/skills/humanize-korean/references/rewriting-playbook.md`
186- 슬림 룰북(monolith): `.claude/skills/humanize-korean/references/quick-rules.md`
187- 학술 인용 SSOT: `.claude/skills/humanize-korean/references/scholarship.md`
188- 웹 스펙: `.claude/skills/humanize-korean/references/web-service-spec.md`
189