# Ko Natural

> 사람이 읽을 한국어 텍스트를 자연스럽게 생성·교정한다. 한국어로 된 요약, 앱 UI 카피, 푸시·알림 문구, 이메일, 보고서, 제품에 들어갈 텍스트 데이터를 생성할 때, 또는 기존 한국어 텍스트가 "어색하다", "번역투다", "AI 티가 난다", "자연스럽게 고쳐줘"라는 요청이 있을 때 반드시 사용한다. LLM 파이프라인용 한국어 프롬프트를 만들 때도 사용한다(export 스크립트). 사용자가 자연스러움을 명시하지 않아도, 두세 문장 이상의 사용자 대상 한국어 텍스트를 만들 때는 이 스킬을 적용한다. 단, 본문의 '발동 수위'에 따라 가벼운 텍스트는 원칙만 적용하고 파일 읽기·린트를 생략한다.

- Skill: `douinc/ko-natural` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add douinc/ko-natural`
- Raw SKILL.md: https://api.skillmd.com/api/skills/douinc/ko-natural/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: douinc (https://skillmd.com/u/douinc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/douinc/ko-natural

---


# ko-natural — 자연스러운 한국어 생성·교정

## 왜 필요한가

LLM 한국어는 두 방향으로 어긋난다. 첫째 **번역투** — 다국어 모델은 영어 중심 표상에서 한국어를 생성하므로 "~에 대해", "~를 통해", 이중피동, 소유격 대명사 남용, 명사화("검토를 진행하다") 같은 직역 흔적이 남는다. 둘째 **GPT체** — 정렬 과정에서 보상받은 장황함, 헤징("~할 수 있습니다" 연발), 상투구("중요한 역할을 합니다"), 과잉 격식이 기본값이 된다. 이 스킬은 두 가지를 규칙 사전 + 자동 린트로 잡는다.

## 발동 수위 — 먼저 결정하라

이 스킬의 오버헤드(참조 읽기 + 린트 왕복)는 과제 크기와 무관한 고정비다. 벤치마크상 전체 워크플로는 시간 약 5배·토큰 약 2.4배를 쓰므로, 텍스트의 노출도에 맞는 수위를 먼저 고른다:

- **0단계 — 원칙만 (파일 읽기·린트 없음).** 대화 응답, 2~3문장 내부 메모, 일회성 초안. 아래 핵심 원칙 8을 기억으로 적용하고 끝. 이 문서(SKILL.md)만으로 충분하며 references를 열지 않는다.
- **1단계 — 표준 (린트 최대 2회).** 사용자에게 전달되는 결과물: 요약, 푸시, 이메일, 문서 단락. examples.md의 **해당 타입 섹션만** 읽고, 초안 → 린트 → 수정 → 재린트로 종료.
- **2단계 — 전체.** 대량 생성(같은 유형 N건), 고노출 카피(온보딩·결제·릴리스 노트), 사용자가 품질을 명시 요구할 때. 축 플래그 전부 + 필요시 예시 추가 참조.
- **배치 규칙.** 여러 건을 만들 땐 한 파일에 모아 린트 1회로 검사한다 — 고정비를 N으로 나누는 유일한 방법.

읽기 금지 목록: `patterns.md`와 `lint.py` 소스는 읽지 않는다(린트 실행이 그 내용을 대신 적용한다). `patterns.json`도 직접 읽지 않는다 — 사전에 패턴을 추가할 때만 연다.

## 작업 순서 (1단계 이상)

1. **텍스트 타입 판별** — 아래 표에서 스펙 확인. 애매하면 독자와 매체(앱 화면? 메일함? 문서?)로 판단.
2. **초안 작성** — 핵심 원칙(아래) 적용. 1단계 이상이면 해당 타입의 Before/After 예시를 `references/examples.md`에서 먼저 읽는다.
3. **린트 실행** — 초안을 파일로 저장 후:
   ```bash
   python scripts/lint.py 초안.txt --register casual                  # 앱 카피·요약·알림
   python scripts/lint.py 초안.txt --register formal                  # 문서·이메일
   python scripts/lint.py 초안.txt --register formal --tone 합니다체 --lexicon easy   # 축 지정 시
   ```
4. **수정** — error는 전부 해소, warn은 맥락 판단(의도된 표현이면 유지 가능). 수정 후 재실행해 error 0 확인.
5. **의미 보존 확인** — 교정 과정에서 정보가 빠지지 않았는지 원문과 대조.

린트를 건너뛰지 않는다. 산문 규칙은 긴 컨텍스트에서 잊히지만 린트는 결정적으로 잡아낸다 — 이 스킬의 신뢰성은 3~4단계 루프에서 나온다.

길이·어투 검증을 손으로 반복하지 마라. 줄 길이는 `--max-line 45`, 문장 길이는 `--max-sentence`, 어투는 `--tone`이 검사한다. 초안 → 린트 → 수정 → 린트, 이 두 번의 실행으로 끝내는 것이 정상 경로다.

## 핵심 원칙 8

1. **동사로 말하라.** 한국어는 동사 중심 언어다. "검토를 진행하다" → "검토하다", "제공합니다" → "드려요/줘요".
2. **대명사·소유격은 기본 생략.** "당신의 저장함에서 그것을" → "저장함에서". 반복되는 "그것/이것"은 번역 흔적.
3. **능동이 기본.** "~에 의해 개발되었다" → "~이 개발했다". 이중피동(보여지다, 되어지다)은 무조건 오류.
4. **짧은 고유어가 이긴다** (앱·일상 레지스터). 수령→받다, 금일→오늘, 용이하다→쉽다. 단, 문서·격식 레지스터에서는 한자어 허용.
5. **종결어미 하나로 통일.** 합니다체·해요체·다체·명사형 중 타입 스펙이 지정한 하나만.
6. **헤징과 상투구를 지워라.** "~할 수 있습니다" 연발, "중요한 역할", "다양한", "물론입니다" — 구체적 사실·숫자로 대체.
7. **문장당 정보 하나.** 관형절 3겹, 80자 넘는 문장은 분리.
8. **메타 담화 금지.** "이 영상은 ~를 소개하고 있습니다"처럼 내용을 소개한다고 말하지 말고 내용을 말하라. "요약하자면/결론적으로"도 짧은 글에선 삭제.

## 텍스트 타입 (프리셋) + 오버라이드 축

타입이 기본값을 정하고, 요청에 따라 축 3개를 오버라이드한다. 무효 조합(카드 필드에 해요체 등)을 만들지 않으려면 타입 기본값에서 출발할 것.

| 타입 | 기본 어투 | 길이 | 규칙 |
|---|---|---|---|
| 요약(카드·3줄) | '~다'체 또는 명사형, 혼용 금지 | 줄당 ≤45자 | 메타 문장 금지, 숫자·고유명사 전면 배치. **주제 식별자(도구·기술·장소명 등)를 첫 줄에 반드시 포함** — 글자수에 밀려 빼면 나중에 검색으로 못 찾는다 |
| UI 라벨·카드 필드 | 명사형("저장됨") | ≤20자 | 마침표 없음, '해당·정보·목록' 군더더기 금지 |
| 푸시·알림 | 해요체 | 1문장 ≤45자 | 구체 숫자 포함, "~하시기 바랍니다" 금지 |
| 업무 이메일 | 합니다체 | — | 용건 먼저, 이유는 구체적으로, 상투 서두·결구 금지 |
| 문서·보고서 | '~다'체 | 문장 ≤80자 | 개조식/서술식 혼용 금지, 판단·수치 명시 |

**오버라이드 축** — 사용자 요청에서 신호를 읽어 적용하고, 린트 플래그로 검증한다:

- **어투(tone)**: 해요체 | 합니다체 | 다체 | 명사형 → `lint.py --tone 해요체` (위반 = error)
- **어휘(lexicon)**: easy(비전문가 — 한자어·전문용어 풀어쓰기, 문장 ≤60자) | normal | expert(실무자 — 전문용어 원어 유지, 풀어쓰기 금지) → `lint.py --lexicon easy`
- **길이(length)**: 요약 계열에서 1line | 3line | paragraph

"비개발자도 이해하게", "쉽게 설명" → lexicon easy. "개발자용", "전문용어 그대로" → lexicon expert. 자주 쓰는 조합은 `references/profiles.json`에 명명 프로필로 저장돼 있다(retriever-push, ax-workshop-material 등). 새 프로젝트가 생기면 프로필을 추가하라.

## 리소스

- `references/patterns.json` — 금칙·대체 사전(성장형, 린트가 읽음). 카테고리: 번역투(T)·GPT체(G)·형태(M)·어휘(L)·쉬운 어휘(E)
- `references/profiles.json` — 명명 프로필(타입+축 조합). 프로젝트별로 추가
- `references/patterns.md` — 사전 해설: 각 카테고리가 왜 부자연스러운지, 대표 사례
- `references/examples.md` — 타입별 Before/After 골든 예시. **생성 전에 해당 타입 섹션을 읽을 것**
- `scripts/lint.py` — 자동 검사(stdlib만 사용). `--json`으로 채점·자동화 연동
- `scripts/export.py` — 외부 LLM 파이프라인용 시스템 프롬프트 블록 추출: `python scripts/export.py --profile retriever-push`

## 사전 성장 루프 (유지보수)

사용자가 어색하다고 지적한 표현은 그 자리에서 `references/patterns.json`에 패턴으로 추가한다(id는 카테고리 접두사 + 다음 번호, 정규식·severity·fix 포함). 사전은 합성 시드(v0.1)로 시작했으므로, 실제 실패 사례가 쌓일수록 이 스킬의 가치가 커진다. 오탐(자연스러운 표현이 걸림)을 발견하면 severity를 낮추거나 regex를 좁힌다.

## 외부 파이프라인 적용

이 스킬은 Claude 작업에 직접 적용되고, 외부 API 파이프라인(예: 제품의 요약 생성)에는 export로 간접 적용된다:

```bash
python scripts/export.py --profile retriever-push > prompt_block.txt
python scripts/export.py --type summary --lexicon expert --length 3line   # 축 직접 지정
```

출력물(핵심 원칙 + 금칙 목록 + 타입 스펙 + 축 스펙 + few-shot 예시)을 파이프라인의 시스템 프롬프트에 삽입하고, 서버에서는 patterns.json 기반 린트를 후처리 검증으로 이식하면 자산 하나로 두 소비처를 커버한다.