Natural Korean Writing

---
name: natural-korean-writing
description: Use when asked to review, rewrite or proofread Korean technical prose — 한국어 문서 다듬기, 말투 검토, 번역체 고치기, 용어 통일, 커밋 메시지·PR 설명·README 교정, 판교어 제거. Opens the full rule table (about 600 rules); the always-on output style carries only the most frequent rules.
---
<!-- kimchi-ignore-file 나쁜 예를 그대로 인용한다 -->

# 한국어 글 다듬기

출력 스타일이 **매 문장에** 적용하는 규칙은 분량 상한 때문에 50개 남짓입니다.
전체 규칙은 600개 가까이 됩니다. 글을 검토하거나 고쳐 달라는 요청을 받으면 그 표를 열어 보십시오.

**규칙표는 이 파일 기준 `../../rules/` 에 있습니다.** 플러그인 디렉터리 안이고, 사용자의
작업 디렉터리가 아닙니다. 경로를 사용자 프로젝트 기준으로 찾으면 없습니다.

## 언제 이 스킬을 쓰나

- "이 문서 말투 좀 다듬어줘"
- "번역체 같은데 고쳐줘"
- "커밋 메시지 한국어로 자연스럽게 써줘"
- 한국어 README·API 문서·릴리스 노트를 쓰거나 고칠 때
- 용어를 통일해야 할 때

평소 대화에서는 이 스킬이 필요 없습니다. 출력 스타일이 이미 적용하고 있습니다.

## 먼저 이 다섯 순서로 판단합니다

1. **한국 개발자가 실제로 타이핑하는 대로.** 슬랙, PR, 코드 리뷰에 쓰는 말이 기준입니다.
   확신이 서지 않으면 원어(로마자)를 그대로 씁니다.
2. **한국어로 정착한 말은 한국어로.** 음차: 배포, 커밋, 브랜치, 머지, 캐시, 빌드, 테스트,
   로그, 업데이트, 리팩터링, 인터페이스, 스레드. 기본 명사: 함수, 배열, 값, 호출, 반환, 설정.
   한자어 기술 용어: 결합도, 응집도, 의존성, 멱등, 동시성, 병목, 직렬화, 캡슐화, 추상화,
   인증, 인가.
3. **개발자가 로마자로 쓰는 말은 로마자로.** state, props, payload, target, directory,
   endpoint 같은 명사입니다. race condition·deadlock·latency·throughput·side effect·
   regression도 여기 포함됩니다 — 슬랙·PR에서 개발자가 실제로 영어 원어를 그대로 타이핑하고,
   규칙표(hanja.md, terms.md)도 이제 원어를 `쓸 것`의 첫 자리로 가르칩니다. 경쟁 조건·교착
   상태·지연 시간·처리량·부수 효과·회귀는 설명이 필요할 때 괄호로 덧붙이는 대안입니다. 여러
   낱말로 된 용어는 통째로 씁니다("build target directory"). 로마자는 명사 자리에만 씁니다 —
   동사는 한국어를 쓰고, 로마자 동사에 하다를 붙이지 않습니다("state를 업데이트하고"는 맞고
   "push합니다"는 틀립니다). 정착한 음차 동사는 한글로 씁니다 — 푸시합니다, 머지합니다,
   업데이트합니다. 사내 은어(컨펌, 어사인, 팔로업)는 기술 용어가 아니라 그대로 한국어로
   씁니다(확인, 배정, 후속 처리). function·array·value는 함수·배열·값이라는 정착 한국어
   명사가 있으니 그대로 한국어로 씁니다 — 로마자로 남기지 않습니다. 질문에 타겟·디렉토리처럼
   한글 음차로 적혀 있어도 target·directory로 쓰고, 릴리즈처럼 정착어 표기가 다르면 릴리스로
   고쳐 씁니다. 아무도 안 쓰는 한글 음차(아이덤포턴트, 블라스트 레디우스)는 로마자로
   바꿔도 여전히 틀립니다 — 2번이나 4번을 다시 찾으십시오.
4. **순우리말 풀어쓰기는 최후 수단입니다.** 서술문으로 늘이면 대개 더 어색해집니다.
   답이 길어지고 있으면 틀렸다고 의심하고 1~3번을 다시 찾아보십시오.
5. **은유는 번역 대상이 아닙니다.** 활용형에도 똑같이 적용됩니다. "얇은 계약"만 피하는 것이
   아니라 "계약이 얇으면", "계약을 얇게", "계약이 두꺼워지는"도 모두 쓰지 않습니다.

4번이 가장 자주 어긋납니다. "자연스러운 한국어"는 순우리말을 뜻하지 않습니다.

## 규칙표

| 파일 | 다루는 것 |
|---|---|
| `../../rules/hanja.md` | 영어 개념에 대응하는 한국어 기술용어. 대개 한자어 |
| `../../rules/metaphors.md` | 영어 은유의 정착 여부 판정. 얇다·두껍다·깊다는 정착하지 않았다 |
| `../../rules/terms.md` | 직역 신조어와 불필요한 음차. 반대로 정착 외래어를 되돌리는 실수도 |
| `../../rules/patterns.md` | 번역체 문장 구조. 인칭 주어 직역, 기능동사 남용, 이중 피동 |
| `../../rules/pangyo.md` | 판교어와 한영 혼용 |
| `../../rules/register.md` | 어투 일관성, 사물 존대, 외래어 표기, 띄어쓰기 |
| `../../rules/observed.md` | 실제 출력에서 관찰한 실패. 짜낸 예시보다 값어치가 크다 |

표의 `검사` 칸이 그 규칙을 누가 막는지 알려 줍니다.

| 값 | 뜻 |
|---|---|
| `치환` | 린터가 자동으로 고칩니다 |
| `정규식` | 린터가 잡아서 알려 줍니다 |
| `프롬프트` | 문자열로 잡을 수 없습니다. 읽고 판단해야 합니다 |

`프롬프트` 규칙이 이 스킬의 값어치입니다. 문자열 검사로는 잡히지 않고 출력 스타일에도
분량 때문에 대부분 들어가지 못합니다. 글을 검토할 때 이 항목들을 직접 읽어 보십시오.

## 기계로 채점하기

규칙표를 눈으로 훑기 전에 린터를 돌리면 잡히는 것은 먼저 걸러집니다.

채점 도구도 플러그인 디렉터리 안에 있습니다. 이 파일 기준 `../../scripts/score-response.mjs` 입니다.

```bash
node <플러그인>/scripts/score-response.mjs 문서.md          # 걸리는 표현을 나열한다
node <플러그인>/scripts/score-response.mjs --fix 문서.md    # 치환 규칙을 적용한 결과
node <플러그인>/scripts/score-response.mjs --json 문서.md   # 기계가 읽을 형태
```

도구를 돌릴 수 없는 환경(샌드박스가 플러그인 디렉터리를 막는 경우)이면 규칙표를 읽어
직접 판단하십시오. 위의 다섯 순위만으로도 대부분 갈립니다.

린터가 0건이라고 해서 자연스러운 글은 아닙니다. 문장 구조와 어투는 읽어야 압니다.

## 검사에서 빼기

문체 가이드처럼 나쁜 예를 일부러 인용하는 문서는 표시로 뺍니다.

```markdown
<!-- kimchi-ignore-file -->          문서 전체
<!-- kimchi-ignore-start --> … <!-- kimchi-ignore-end -->   구간
얇은 계약이라고 쓴 줄 <!-- kimchi-ignore -->   그 줄
```

## 자주 틀리는 것

- 순우리말로 풀어써서 더 어색하게 만들기 — "여파가 미치는 범위"보다 "영향 범위"
- 정착한 외래어를 되돌리기 — "캐시"를 "임시 저장소"로 바꾸는 것은 개선이 아니라 훼손
- 은유의 관형형만 고치고 활용형을 놓치기 — "얇은 계약"은 고치고 "계약이 얇으면"은 남기기
- 한자어 밀도를 올리다가 공문서체로 튀기 — "본 변경 사항은 상기 모듈에 대하여 적용됨"
- 사물 존대 — "빌드가 완료되셨습니다"
- 원어를 문장마다 병기하기 — 병기는 문서에서 첫 등장 한 번만