---
name: ko-writing
description: 한국어 산문을 쓰고 다듬는다. 보고, 요약, 설명, md 문서, README, 가이드, 설계 문서, 회의록, 릴리스 노트, 주석, 채팅 답변이 대상이다. 번역투와 AI 말투를 걷어내고, 두괄식으로 구조를 잡고, 근거와 추정을 갈라 쓰고, 용어를 고정한다. 사용자가 한국어로 문서·보고서·설명·요약을 써 달라거나 다듬어 달라고 할 때, 영어 메모나 작업 기록을 한국어 보고로 옮길 때, "번역투 같다", "AI가 쓴 것 같다", "읽기 어렵다", "말투가 섞였다", "다시 써줘"라고 할 때 반드시 이 스킬을 쓴다. 한국어 md 파일을 새로 만들거나 크게 고칠 때도 적용한다. 화면에 보이는 UI 문구는 이 스킬이 아니라 ko-ui-text를 쓴다.
---

# 한국어 문서·보고 작성

LLM이 쓴 한국어 산문은 다섯 가지가 반복해서 무너진다. 영어 문장 구조를 그대로 옮긴
번역투가 깔리고, 결론이 맨 뒤로 밀리고, 확인한 것과 추정한 것이 같은 말투로 섞이고,
같은 개념이 문단마다 다른 단어로 불리고, 비유와 자작 용어가 표준 용어 자리에 앉는다.
이 스킬은 그걸 진단하고 다시 쓴다. 규칙의 뿌리는 `references/rules.md` 0절의 열 가지
원칙이고, 원칙의 출처는 국립국어원 「논증적 글쓰기 능력 진단 기준안」이다. 원칙마다
대응하는 준거 번호가 붙어 있다.

## 언제 어떤 모드로

| 사용자 요청 | 모드 |
|---|---|
| "검수해줘", "어색한 데 찾아줘", "왜 읽기 어려운지 봐줘" | **audit**: 진단 + 수정 표 |
| "고쳐줘", "다시 써줘", "다듬어줘" | **rewrite**: 진단 요약 + 파일 직접 수정 |
| "보고서 써줘", "이 작업 정리해줘", "설명해줘" | **write**: 규칙에 맞춰 새로 작성 |
| "이 초안/메모/노트로 기술서 써줘", 표·불릿 뭉치를 외부 독자용 줄글로 | **write(변환)**: 아래 "재료를 줄글로 옮길 때" 절차를 따른다 |
| 모드가 불분명 | 짧은 글은 rewrite, 문서 여러 개면 audit로 시작 |

## 이 스킬을 쓰지 않는 경우

- 화면에 보이는 문구(버튼, 라벨, 에러, 빈 상태, 배너) → `ko-ui-text` 스킬
- 영어로 쓰기로 정해진 산출물 → 그대로 영어로 쓴다. 저장소에 `AGENTS.md`가 있으면
  Output Language 절이 우선이다. 대개 관리 문서·작업 로그·이슈/PR 본문·커밋 본문은
  영어, 사용자에게 가는 보고와 답변은 사용자 언어다. 어느 쪽인지 모르면 묻는다
- 코드 자체, 로그 원문, 명령어 출력 → 인용은 원문 그대로 둔다

## 워크플로우

### 1. 종류와 독자 확정

시작 전에 아래를 안다. 저장소에 `ko-writing.config.md`가 있으면 거기서 읽고, 없으면
대화에서 찾고, 그래도 없으면 **추정하지 말고 묻는다**. 독자만은 기본값이 있다. 정해지지
않았으면 **콜드 리더**, 곧 이 프로젝트를 모르지만 같은 분야의 일은 아는 사람이 처음
읽는다고 놓는다(`references/rules.md` 0절 1항).

- 글의 종류: 보고 / 요약 / 설명 / 문서 / 가이드 / 설계 / 회의록 / 릴리스 노트
- 읽는 사람: 나중의 나 / 팀 동료 / 다른 팀 / 경영진 / 외부 사용자
- 읽는 상황: 처음 읽는가, 이미 맥락을 아는가, 장애 중에 급히 찾는가
- 기본 말투: 문서체(`~한다`) / 보고체(`~합니다`) / 해요체
- 전문 용어 허용 수준

### 2. 뼈대 먼저

문장을 쓰기 전에 결론 한 줄과 헤딩 목록을 먼저 잡는다. 뼈대 없이 쓰면 결론이 맨 뒤로
밀리고 같은 말이 여러 문단에 흩어진다. 뼈대는 `references/rules.md`의 **3. 구조**를 따른다.

### 3. 진단 (audit·rewrite 모드)

`references/rules.md`의 **1. 진단 항목**으로 반복 패턴을 잡는다. 개별 문장을 나열하지
말고 유형별로 묶고, 유형마다 사례 2~3개를 인용한다. 패턴을 안 잡고 문장 단위로 고치면
같은 문제가 다음 문단에서 또 나온다.

### 4. 쓰기 또는 고치기

`references/rules.md`의 **2~8절**을 적용한다. 원문이 이미 읽히면 손대지 않고 "유지"로
남긴다. 이 규칙이 없으면 멀쩡한 문장까지 다 바뀐다.

### 5. 기계 검사

다 쓴 뒤 `scripts/check.py`를 돌린다. 사람 눈으로 잡기 전에 0/1로 셀 수 있는 것을
센다. 금지 패턴(엠대시, 가운뎃점, "~를 통해" 등), 종결어미 혼용, 문단 문장 수, 헤딩
길이, 문장형 헤딩, 볼드 개수, 수량 후치다. 남은 것은 손으로 고치고 다시 돌린다.

스크립트는 이 스킬 디렉터리(스킬이 로드될 때 "Base directory"로 표시되는 곳) 아래에
있다. 저장소에 설치됐으면 `.claude/skills/ko-writing/`, 개인 설치면
`~/.claude/skills/ko-writing/`이다.

```bash
python .claude/skills/ko-writing/scripts/check.py 문서.md
python .claude/skills/ko-writing/scripts/check.py 문서.md --heading 25 --from "## 표지" --to "## 그림 목록"
```

### 6. 출력

audit·rewrite 모드는 `assets/output-template.md` 형식을 따른다. write 모드는 결과물만
내고, 맥락 없이 정할 수 없었던 항목만 끝에 질문으로 남긴다.

## 영어 작업 메모를 한국어 보고로 옮길 때

**번역하지 않는다. 한국어로 처음부터 다시 쓴다.** 작업 중 메모는 영어로 남고 보고는
한국어로 나가는 경우가 많은데, 문장을 옮기면 어순과 수식 구조가 그대로 따라와 번역투가
된다. 순서는 이렇다.

1. 영어 메모에서 **사실만** 뽑는다: 무엇을 했나, 무엇이 확인됐나, 무엇이 남았나
2. 메모는 덮고, 뽑은 사실을 한국어 문장으로 새로 짠다
3. 원문 문장 구조가 남았는지 확인한다. "~를 통해", "~에 대한", "~을 제공한다"가 보이면
   그 문장은 아직 번역이다

기술 용어는 억지로 옮기지 않고 영어 원어를 그대로 쓴다(hook, worktree, pre-commit,
commit, branch, merge). 한 번 정한 표기는 문서 전체에서 고정한다.

## 재료를 줄글로 옮길 때

초안, 작업 노트, 표와 불릿의 뭉치를 외부 독자(평가자, 다른 팀, 경영진)가 읽을 줄글로
바꾸는 절차다. 불릿을 문장으로 잇는 것이 아니다. 재료는 덮고 문단을 새로 짠다.
일곱 단계를 순서대로 밟는다.

1. **독자를 정한다.** 정해지지 않았으면 콜드 리더다. 이 프로젝트를 처음 읽는가, 분야
   전문가인가, 어떤 매체로 읽는가. 여기서 내부 식별자(가설 번호, 그림 파일명, 파일 경로,
   "출처는 …" 줄)를 지울지 남길지가 정해진다. 콜드 리더와 외부 독자면 지우거나 풀어
   쓴다. 내부 독자면 남긴다.
2. **용어표를 먼저 만든다.** 문서에 나올 전문 용어를 뽑아 개념마다 한 문장 풀이와
   고정 표기를 정한다. 본문에서는 처음 나올 때 그 한 문장으로 풀고, 그 뒤로는 같은
   이름만 쓴다. 두 번째 설명은 없다.
3. **재료에서 주장을 뽑는다.** 표 한 행, 불릿 한 줄이 아니라 "독자가 알아야 할 결론"
   단위로 뽑는다. 주장 하나가 문단 하나가 된다. 주장이 안 되는 재료는 버린다.
4. **문단 틀을 고정한다.** 첫 문장이 주장, 그다음이 근거와 숫자, 마지막이 "그래서
   무엇을 정했고 어디에 쓰였나"다. 마지막 부분이 없으면 분석 문단이 "그래서요?"로
   끝난다. 분석·실험·데이터 절은 소절마다 이 틀을 반복한다.
5. **숫자는 짝과 함께 쓴다.** 값 하나만 두지 않는다. 기준선, 상한, 이전 값 중 하나가
   옆에 있어야 독자가 판단한다. 숫자를 쓰기 전에 계산식과 잰 데이터를
   한 번 밝히는 절을 앞에 둔다.
6. **실패와 한계를 독립 절로 쓴다.** 버린 것은 채택한 것과 같은 형식이다. 기대 →
   결과 → 왜 실패인지 해석. 문턱을 못 넘긴 것을 채택했으면 못 넘겼다고 먼저 적고
   그래도 고른 이유를 따로 쓴다. 한계 절은 "아직 재지 않은 것"과 "재봤지만 못
   가른 것"을 구분한다.
7. **기계 검사를 돌린다.** 워크플로우 5단계와 같다. 말투를 바꿔야 하면
   `references/style-conversion.md`의 규칙으로 바꾸고 예외를 손본 뒤 다시 검사한다.

그림이 들어갈 자리는 본문에 인용 블록으로 비워 두고, 블록 안에 파일명과 캡션을
적는다. 캡션은 제목이 아니라 그 그림의 결론 문장이다. 아직 없는 그림은 무엇을 그릴지
상자와 화살표 단위로 블록 안에 적는다.

이 절차의 근거는 `references/rules.md` 0절 원칙이고, 원칙은 국립국어원 논증적 글쓰기
기준안의 준거에 하나씩 대응한다(0-1절 대응표). 좋은 논증문의 조건을 공식 채점 기준에서
가져온 것이라 출처가 있고, 외부 평가자에게 내는 글은 그 표를 체크리스트로 삼는다.

## 길이

요청에 길이 지정이 없으면 아래를 기본으로 한다. 길이를 채우려고 문장을 늘리지 않는다.

| 종류 | 기본 길이 |
|---|---|
| 채팅 보고 | 결론 1~2문장 + 근거 불릿 3~5개 |
| 작업 요약 | 10줄 이내 |
| 설명 | 문단 2~4개 |
| 문서(md) | 필요한 만큼. 대신 헤딩으로 나눈다 |

## 여러 문서를 한 번에 다룰 때

문서가 5개를 넘거나 원고가 길면 배치로 나눈다. 한 번에 다 처리하면 뒤쪽에서 용어와
말투가 흐트러진다.

1. 3~5개씩 끊는다
2. 첫 배치에서 용어와 말투를 확정한다
3. 이후 배치는 확정된 기준에서 "벗어난 곳만" 지적한다
4. 마지막에 전체를 훑어 배치 간 불일치를 잡는다

## 프로젝트 설정 파일

저장소 루트 또는 `docs/` 아래에 둔다. 있으면 반드시 먼저 읽는다.

- `ko-writing.config.md`: 1단계 맥락과 말투. 템플릿은 `assets/config-template.md`
- `ui-text.glossary.md`: 확정 용어. `ko-ui-text` 스킬과 **같은 파일을 공유한다**.
  문서와 화면에서 같은 개념을 다르게 부르면 안 되기 때문이다

없으면 첫 작업 뒤에 생성을 제안한다.

## 하지 말 것

- 맥락을 추정해서 진행하기. 독자를 모르면 묻는다
- 영어 메모를 문장 단위로 번역하기
- 결론을 맨 뒤에 두기
- 확인한 것과 추정한 것을 같은 말투로 쓰기
- 규칙을 기계적으로 적용해서 이미 읽히는 문장까지 바꾸기
- 용어집을 무시하고 "더 자연스러운 표기"로 바꾸기. 통일이 우선이다
- 비유를 용어 대신 쓰기. 작업기록의 내부 표현을 외부 문서에 그대로 옮기기
- 수정 표 없이 파일만 조용히 바꾸기 (rewrite 모드에서도 무엇을 왜 바꿨는지 요약한다)

## 참고 파일

- `references/rules.md`: 열 가지 원칙과 국립국어원 기준안 대응표, 진단 항목, 구조,
  말투, 용어, 금지 목록, 판단 기준. 항상 읽는다
- `references/examples.md`: 유형별 원문→수정 예시. 판단이 애매할 때 읽는다
- `references/style-conversion.md`: 해라체와 하십시오체 사이 변환 규칙표, 예외,
  헤딩 처리. 말투를 통째로 바꿀 때 읽는다
- `scripts/check.py`: 기계 검사. 다 쓴 뒤 돌린다
- `assets/output-template.md`: audit·rewrite 출력 형식
- `assets/config-template.md`: 프로젝트 설정 파일 템플릿