insightflo/edu-deck-skills / edu-deck/shared/skills/humanize-korean
humanize-korean
VerifiedAI(ChatGPT·Claude·Gemini 등)가 쓴 한글 텍스트를 "사람이 쓴 글처럼" 윤문해주는 오케스트레이터 스킬. 번역투·영어 인용 과다·기계적 병렬·관용구·피동태 남용·접속사 남발·리듬 균일성·이모지/불릿 과다 등 10대 카테고리 70개 AI 티 패턴을 탐지·분류해 내용은 한 글자도 건드리지 않고 문체·리듬·표현만 자연스러운 한국어로 재작성한다. shim의 route_hint(light|standard|heavy)로 경로를 정해 잘 쓴 글은 1콜, 표준은 2콜, 중증·장문만 3+콜(진단→겨냥 윤문→finalize)로 처리한다. 트리거 — "AI 티 없애줘", "AI 같은 글 자연스럽게", "GPT/ChatGPT 문체", "AI 번역투 고쳐", "사람이 쓴 것처럼 윤문", "AI 윤문", "ChatGPT 티 제거", "한글 AI 탐지·윤문", "AI 글 사람처럼", "번역투 제거", "영어 인용 많은 글 윤문", "AI 글 티 안 나게", "휴머나이저", "humanize Korean", "AI detector bypass 한글". 후속 작업 — "특정 카테고리만 다시", "윤문 강도 조정", "장르 바꿔서", "이 문단만", "2차 윤문" 도 모두 이 스킬. 단순 맞춤법·오탈자 교정은 직접 처리, 번역은 번역 스킬, 내용 추가·삭제를 동반한 재작성은 별도 집필 스킬.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 28.5 KB |
| references/ai-tell-taxonomy.md | markdown | 120.7 KB |
| references/baseline.json | config | 8.5 KB |
| references/baseline_v2.json | config | 13.2 KB |
| references/design-notes.md | markdown | 5.8 KB |
| references/diagnosis-rules.md | markdown | 16.1 KB |
| references/empirical-validation.md | markdown | 14.7 KB |
| references/metrics.py | script | 14.7 KB |
| references/metrics_v2.py | script | 30.6 KB |
| references/quick-rules.footer.md | markdown | 2.9 KB |
| references/quick-rules.header.md | markdown | 2.2 KB |
| references/quick-rules.md | markdown | 16.2 KB |
| references/rewriting-playbook.md | markdown | 15.5 KB |
| references/scholarship.md | markdown | 34.7 KB |
| references/web-service-spec.md | markdown | 7.8 KB |
references/web-service-spec.md
View on GitHub# Humanize KR 웹 서비스 스펙 (Phase 5에서만 로드)
Humanize Korean 파이프라인을 일반 사용자용 웹앱으로 확장할 때 아키텍트가 따르는 참조. 기본 윤문 파이프라인이 안정화된 뒤에만 읽는다.
## 목차
1. 서비스 콘셉트
2. 기술 스택
3. 아키텍처 토폴로지
4. API 스펙
5. UX 플로우
6. 데이터 모델
7. 요금·쿼터·인증
8. 배포·운영
9. 확장 로드맵
## 1. 서비스 콘셉트
**한 줄 설명**: AI가 쓴 한글을 붙여 넣으면 "사람이 쓴 것처럼" 윤문해주는 서비스.
**핵심 가치**:
- **근거 제시**: 어디가 왜 AI 티인지 카테고리별 하이라이트.
- **내용 불변 보증**: 사실·수치·인용이 바뀌지 않았음을 diff로 시각화.
- **한국어 특화**: 번역투·영어 용어 과다 등 한글 고유 패턴에 특화.
**경쟁 차별점**:
- 기존 영어 중심 humanizer(QuillBot·Hix·Undetectable AI)가 한국어에 약함.
- 단순 재작성이 아닌 "탐지 → 근거 → 수술적 윤문" 3단계.
## 2. 기술 스택
- **프레임워크**: Next.js 15 App Router + React Server Components.
- **런타임**: Vercel Fluid Compute (기본 Node.js 24 LTS).
- **AI**: Vercel AI Gateway — Claude(탐지·윤문) + GPT(교차 검증 옵션).
- **스타일**: Tailwind CSS v4 + shadcn/ui + Pretendard 자동 로딩.
- **상태**: useActionState + SSE 스트리밍.
- **캐시**: Runtime Cache API (입력 해시 기반 결과 재활용).
- **DB (옵션)**: Neon Postgres (히스토리 저장 시만).
- **인증 (옵션)**: Clerk Marketplace.
- **이메일 (옵션)**: Resend (가입 확인·요금제 알림).
## 3. 아키텍처 토폴로지
```
[Browser]
↓ POST /api/humanize (stream: true)
[Routing Middleware]
├─ BotID 검증
├─ 쿼터 확인 (Runtime Cache)
└─ 언어 감지 (한글 아니면 400)
↓
[Next.js App Router · Fluid Compute]
↓
[Vercel Workflow — durable orchestration]
├─ step: detect() ← AI Gateway → Claude Haiku
├─ step: rewrite() ← AI Gateway → Claude Opus
├─ step: fidelity_audit() ← AI Gateway → Claude Sonnet
└─ step: review() ← AI Gateway → GPT-5 (옵션)
↓ stream SSE
[Browser EventSource]
```
Workflow는 각 step 실패 시 재시도·부분 응답을 허용한다. detect 단계 완료 즉시 하이라이트가 먼저 스트리밍되어 체감 지연을 줄인다.
## 4. API 스펙
### `POST /api/humanize`
**입력:**
```json
{
"text": "…",
"genre": "auto | column | report | blog | formal",
"min_severity": "S1 | S2 | S3",
"options": {
"preserve_formatting": false,
"cross_validate_with_gpt": false,
"stream": true
}
}
```
**응답 (SSE):**
```
event: detection_meta
data: {"detected_count":37,"score":71.5,"estimated_genre":"column"}
event: detection_finding
data: {"id":"f001","category":"A-2","severity":"S1","start":142,"end":153,"text_span":"데이터 분석을 통해","reason":"..."}
...
event: rewrite_chunk
data: {"delta":"데이터를 분석해 인사이트를 얻는다."}
...
event: audit_verdict
data: {"verdict":"full_pass"}
event: review_verdict
data: {"verdict":"accept","quality_level":"A","score_after":18.2}
event: final
data: {"rewrite_text":"…","summary":{...}}
```
**에러 코드:**
- 400: 입력 검증 실패 (비한국어·길이 초과·빈 문자열).
- 401: 인증 필요 (유료 플랜 API).
- 429: 쿼터 초과.
- 502: AI Gateway upstream 실패.
- 504: Workflow 타임아웃.
### 개별 라우트
- `POST /api/detect` — 탐지만 (리포트 JSON 반환).
- `POST /api/rewrite` — 탐지 결과를 같이 주면 윤문만.
- `POST /api/review` — 윤문본을 주면 재평가만.
- `GET /api/runs/:id` — 저장된 히스토리 (인증 사용자).
- `DELETE /api/runs/:id` — 히스토리 삭제.
## 5. UX 플로우
### 화면 1 — 랜딩·입력
- 좌측: 붙여넣기 textarea (최대 10,000자, 현재 글자 수 표시).
- 우측: 사이드 패널
- 장르 라디오 (자동·칼럼·리포트·블로그·공적).
- 엄격도 슬라이더 (S1만 / S2+ / 전체).
- 옵션 토글: "영어 인용 유지", "이모지 유지" (기본 꺼짐).
- 하단: "윤문하기" 1 버튼. 익명 사용자는 남은 횟수 표시.
### 화면 2 — 처리 진행 (스트리밍)
- 탐지 하이라이트가 실시간으로 문서에 그려짐.
- 우측 사이드: 카테고리별 카운트 막대 그래프.
- 윤문 시작되면 하단 영역에 토큰 스트림.
### 화면 3 — 좌우 diff 뷰
- 좌: 원문 + 카테고리 하이라이트.
- 우: 윤문본 + 변경 영역 강조.
- 상단 배지: `변경률 18% · S1 0 잔존 · 점수 71.5 → 18.2 · 등급 A`.
- 우측 패널: 주요 변경 3~5건 (before/after 카드).
### 화면 4 — 완료·액션
- "윤문본 복사" / ".md 다운로드" / "2차 윤문" / "피드백 보내기" 버튼.
- 하단 보증 문구: "내용은 수정되지 않았습니다. 사실·수치·인용은 원문과 동일합니다."
### 화면 5 — 히스토리 (인증 사용자)
- 최근 50건의 run 목록.
- 각 run 카드에 입력 시각·길이·점수 개선·등급.
- 개별 클릭 시 화면 3(diff 뷰) 재현.
## 6. 데이터 모델 (Neon Postgres 옵션)
### 테이블
**users** (Clerk 연동)
- `id` (Clerk user_id 매핑)
- `plan` (anonymous / free / pro)
- `quota_daily` (integer)
- `created_at`
**humanize_runs**
- `id` (uuid)
- `user_id` (nullable, 익명 허용)
- `input_hash` (sha256, 중복 탐지용)
- `input_length`
- `estimated_genre`
- `score_before`, `score_after`
- `change_rate`
- `quality_level` (A/B/C/D)
- `created_at`
- `retain_content` (bool — 사용자가 본문 저장 동의했는지)
**run_contents** (retain_content = true 일 때만)
- `run_id`
- `input_text`, `rewrite_text`
- `detection_json`, `diff_json`
- `expires_at` (30일 후 자동 삭제)
**feedback**
- `run_id`, `user_id`, `type` (over_polish / under_polish / wrong_category / other), `comment`, `created_at`
## 7. 요금·쿼터·인증
| 플랜 | 가격 | 일 쿼터 | 글자 한도 | API |
|------|------|---------|----------|-----|
| Anonymous | 무료 | 5회 | 3,000자 | ✕ |
| Free (로그인) | 무료 | 30회 | 5,000자 | ✕ |
| Pro | $9/월 | 300회 | 10,000자 | ✓ (API 키 발급) |
| Team | $29/월 | 1,500회 | 20,000자 | ✓ + 웹훅 |
**BotID 검증**을 통해 익명 쿼터 남용을 차단. 쿼터는 Runtime Cache(IP + user hash)로 관리.
## 8. 배포·운영
- **환경**: `vercel.ts`로 설정 (vercel.json 사용 안 함).
- **환경변수**:
- `AI_GATEWAY_API_KEY`
- `DATABASE_URL` (Neon)
- `CLERK_SECRET_KEY` (옵션)
- `RESEND_API_KEY` (옵션)
- **Cron** (옵션): 일 1회 오래된 히스토리 정리 (`/api/cron/cleanup`).
- **모니터링**: Vercel Analytics + AI Gateway observability 대시보드.
- **Rolling Releases**로 신규 프롬프트 버전 점진 롤아웃.
## 9. 확장 로드맵
| 단계 | 내용 |
|------|------|
| **v0 MVP** | 익명·단일 호출·결과 저장 안 함. Phase 3까지만 (탐지+윤문+단일 검증) |
| **v1** | Clerk 로그인·히스토리·장르 프리셋·교차 검증 옵션 |
| **v2** | Pro/Team 플랜·API 키·웹훅·팀 계정 |
| **v3** | Chrome Extension — 선택 영역 즉석 윤문·Google Docs 플러그인 |
| **v4** | 한국어 외 일본어·중국어로 확장 (언어별 taxonomy 분리) |
## 10. 리스크 & 완화
- **악용(AI Detector 우회)**: 학계·저널리즘 맥락에서 논란. 서비스 설명에 "진실성 보증 도구 아님" 명시, 학술 제출용 사용을 약관에서 제한.
- **저작권**: 입력 본문 저장 기본 OFF. 저장 시 TTL 30일.
- **오탐·과윤문**: 등급 C/D일 때 "사람 검토 권고" 안내, 결과를 자동 게시하지 않음.
- **프롬프트 주입**: 입력을 역할·시스템 프롬프트로 해석하지 않도록 격리. Claude·GPT 모두 user 메시지 슬롯에서만 처리.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |