Yd Writer Kr

---
name: yd-writer-kr
description: doksam 스타일 한국어 글쓰기·교정 — 의미가 전달되는 논리적 단문, 번역투·군더더기 제거, 주장마다 근거. 이슈·MR/PR 본문, 문서(docs·README·wiki), 공지(디스코드·메일), 보고서·칼럼·기획서를 한국어로 쓰거나 고칠 때 사용한다. "글 다듬어", "읽기 쉽게", "번역투 빼고", "논리적으로", "유시민처럼" 같은 요청이나, 규칙을 말하지 않아도 사람이 읽을 한국어 산문을 쓸 때 적용한다. 채팅 대화체(MZ체)에는 문장 원칙만 쓰고 종결 규칙은 쓰지 않는다.
---

# yd-writer-kr — 의미가 전달되는 한국어

기준은 길이가 아니라 **의미 전달**이다(『유시민의 글쓰기 특강』).
짧게 자르는 것이 목표가 아니다. 읽는 사람이 무엇을 알고 무엇을 할지 분명해야 한다.

## 0. 어디에 쓰나 — 문체 두 갈래

| 대상 | 문체 | 이 스킬 적용 범위 |
|---|---|---|
| 이슈·MR 본문, 커밋 본문, docs·wiki, 보고서 | 표준 문어체(~한다/~이다) | 전부 |
| README·사용 안내·공지처럼 사용자에게 말하는 글 | ~합니다 체도 쓸 수 있다 | 전부 (~함·~임 종결 금지는 같다) |
| 채팅 응답(사용자와의 대화) | MZ체(~요, ~함, ㅇㅇ, ㅇㅋ) | 원칙 1·3·5만. 종결 규칙(~함 금지)은 적용하지 않는다 |
| 코드·명령어·식별자·표 안의 값·인용문·고유명사 | 원문 그대로 | 건드리지 않는다 |

한 문서 안에서는 문체를 섞지 않는다. 기존 문서를 고칠 때는 그 문서의 문체를 따른다. 새 README 는 저장소의 다른 README 문체를 따른다.

채팅에서 산출물로, 산출물에서 채팅으로 넘어갈 때 문체가 따라오지 않게 한다.
긴 세션에서 이슈 본문을 쓴 직후 채팅까지 격식체가 되는 것이 가장 흔한 실수다.

## 원칙 1. 먼저 독자와 요점을 정한다

- 쓰기 전에 두 가지를 한 문장씩 정한다. 독자가 알아야 할 것, 독자가 해야 할 것.
- 그 한두 가지가 첫 단락에 드러나게 쓴다. 결론을 뒤에 숨기지 않는다.
- 상태 질문의 답은 yes/no 와 짧은 근거로 시작한다.

## 원칙 2. 단문 — 한 문장에 생각 하나

- 한 문장에는 생각 하나만 담는다. 40자 안팎을 눈금으로 삼되, 의미를 자르면서까지 맞추지 않는다.
- 주어와 서술어는 한 번만 쓰고 서로 호응하게 한다.
- 접속사로 길게 잇지 않는다. 마침표를 찍고 새로 시작한다.

## 원칙 3. 필요 없는 것은 뺀다

- 독자에게 필요 없는 배경, 괄호 부연, 내부 사정은 뺀다. 필요한 근거는 남긴다.
- 독자별로 다르다. 이슈·MR 에서는 이슈 번호·파일 경로·커밋이 근거다. 사람에게 보내는 공지에서는 내부 사정이다.
- 없어도 뜻이 통하는 낱말은 지운다. 부사·형용사는 꼭 필요할 때만 쓴다.
- 금지 표현은 `references/banned-expressions.md` 와 대조한다(번역투·일본어투·이중 피동·중복 수식).

## 원칙 4. 주장에는 근거

- 취향과 주장을 구별한다. 취향은 쓰지 않는다.
- 근거는 사실(수치·날짜·로그·쿼리 결과)이나 논리만 인정한다. 근거 없는 주장은 지운다.
- 수치·날짜·라벨은 정확히 쓴다. 어림값을 쓸 때는 "약"을 붙이고 출처를 남긴다. placeholder 는 금지다.
- 확인하지 못한 것은 확인하지 못했다고 쓴다.

## 원칙 5. 구체적으로, 말하듯이

- 추상어 대신 구체어를 쓴다. 날짜, 경로, 명령, 해야 할 행동.
- 소리 내어 읽어 막히면 고친다. 한자어보다 우리말을 먼저 고른다.
- 영어 IT 용어는 첫 등장 때 한글 풀이를 붙인다. 예: sweep(일괄 점검), throttle(호출 속도 제한). server·API·CI·MR·merge 같은 친숙어와 코드 식별자는 그대로 둔다.

## doksam 표기 규칙

- 시각: `YYYY-MM-DD HH:MM:SS.mmm`(KST). ISO 8601 의 `T`·`+09:00` 은 쓰지 않는다. 날짜만이면 `YYYY-MM-DD`.
- 이모지를 아이콘이나 장식으로 쓰지 않는다.
- 코드·명령·경로·식별자는 백틱으로 감싼다. 시크릿 값은 어떤 글에도 쓰지 않는다.
- 숫자는 천 단위 쉼표를 찍는다(610,110건). 비율은 분자·분모를 같이 쓴다(7/30, 23%).

## 글 종류별 형식

### 이슈 (GitLab·GitHub)

```
## 배경        — 무엇이 문제인지, 근거(수치·로그·재현)
## 할 일       — 범위와 방법. 하지 않는 것도 적는다
## 판정        — 누가, 무엇을 보고 닫는가
```

### MR·PR 본문

```
## 변경        — 파일·동작 단위로 무엇이 바뀌었나
## 영향        — 파급된 사용처, 수용한 트레이드오프, 배포 필요 여부
Closes #N
```

### 공지(디스코드·메일)

- 첫 줄에 독자가 할 일이나 알아야 할 결론을 쓴다.
- 이슈 번호·구현 세부 같은 내부 사정은 뺀다. 날짜·장소·링크처럼 행동에 필요한 것은 남긴다.

### 보고서·칼럼·기획서

- 서론: 주장 한 문장, 근거 개요 한 문장.
- 본론: 근거 하나에 단락 하나. 단락의 첫 문장이 핵심이다.
- 결론: 주장을 다시 말한다. 새 내용은 넣지 않는다.
- 분량 지정이 없으면 800자 안팎. 소제목은 사용자가 원하는 대로 바꿀 수 있다.

### README·사용 안내

- 첫 화면에서 세 가지가 보여야 한다. 무엇인지 한 문장, 설치 명령, 가장 흔한 사용 예.
- 목록은 독자가 고르는 기준으로 묶는다. 표의 설명 칸은 "언제 쓰나" 한 줄로 맞춘다.
- 수치(개수·버전·테스트 건수)에는 측정한 날짜를 붙인다. 날짜 없는 수치는 언제 낡았는지 알 수 없다.
- 홍보 문장을 쓰지 않는다. 무엇을 하는지만 쓴다.

### 커밋 메시지

- 제목 형식은 저장소 규칙을 따른다(doksam 은 `yd-git-ship`).
- 본문은 **왜** 바꿨는지 쓴다. 무엇을 바꿨는지는 diff 가 말한다.
- 되돌릴 때 알아야 할 것(함께 바뀐 곳, 일부러 남긴 것)을 적는다.

### 코드 주석

- 코드가 말하지 못하는 것만 쓴다. 이유, 버린 대안, 실측으로 확인한 함정과 그 날짜.
- "무엇을 하는지" 를 되풀이하는 주석은 쓰지 않는다.
- 언어는 그 파일의 기존 주석을 따른다.

### 회의록

```
## 결정        — 정한 것 한 줄씩. 누가 정했는지
## 할 일       — 담당 · 기한 · 완료 기준 표
## 논의        — 결정에 이른 근거만 짧게. 발언 순서대로 받아 적지 않는다
## 미결        — 다음에 정할 것과 그때 필요한 자료
```

## 작업 순서

### 새로 쓸 때

1. 독자, 독자가 알 것, 독자가 할 것을 정한다. 불분명하면 묻는다.
2. 근거를 모은다. 수치·날짜는 실제 출처(DB·로그·이슈)에서 확인한다.
3. 글 종류별 형식으로 초안을 쓴다.
4. 검사기를 돌리고 오류를 고친다. 그다음 점검표로 검수한다.

### 고칠 때

1. 검사기로 기계 위반부터 찾는다.
2. 길거나 번역투가 많은 글은 Upstage 1차 교정을 돌린다(아래).
3. 문장마다 점검표를 적용한다. 뜻과 사실관계는 바꾸지 않는다.
4. 고친 글 전체를 낸다. 요청하면 원문과 나란히 보여준다.

## 검사 도구

### 검사기 — `scripts/check_writing.py`

```bash
python3 <스킬경로>/scripts/check_writing.py 글.md          # 문어체 산출물
python3 <스킬경로>/scripts/check_writing.py --chat 답장.txt # 채팅: 명사형 종결은 보지 않는다
```

- 오류: 금지 표현, 문어체의 ~함·~됨·~있음 종결, ISO 8601 시각, 이모지. 하나라도 있으면 exit 1 이다.
- 경고: 60자를 넘는 문장. 의미를 자르면서까지 맞추지 않는다. `--strict` 면 오류로 센다.
- 코드 블록·인라인 코드·표·인용·URL 은 보지 않는다. 한 줄만 면제하려면 `writer:allow` 를 적는다.
- 금지 표현은 `references/banned-expressions.md` 의 `검사` 열을 읽는다. 목록을 늘릴 때는 그 표만 고친다.
- 검사기는 근거 유무와 독자에게 필요한 내용인지는 판단하지 못한다. 그건 점검표로 본다.

### Upstage 1차 교정 — `scripts/upstage_proofread.py`

한국어 교정은 Upstage Solar(`solar-pro4`)가 빠르고 정확하다. 2026-10-04 실측에서 금지 표현 8건을 1.5초 만에 0건으로 줄였다.

```bash
python3 <스킬경로>/scripts/upstage_proofread.py 글.md -o 고친글.md
```

- 금지 표현 목록을 프롬프트에 넣어 고치고, 검사기에 오류가 남으면 그 목록을 붙여 한 번 더 고친다.
- 결과는 **교정 후보**다. 원문과 비교해 뜻·수치·이름이 바뀌지 않았는지 확인한 뒤에 쓴다. 바뀐 곳은 원문으로 되돌린다.
- 본문이 외부 API 로 나간다. 고객 데이터·비공개 문서는 보내지 않는다. 시크릿처럼 보이는 문자열이 있으면 스크립트가 멈춘다.
- 키는 환경변수 `UPSTAGE_API_KEY`, 없으면 `~/workspace/.env.toml` 에서 읽는다. 키가 없으면 이 단계를 건너뛰고 직접 고친다.

## 검수 점검표

- [ ] 첫 단락에 독자가 알 것·할 것이 드러난다.
- [ ] 한 문장에 생각이 하나다. 주어·서술어가 호응한다.
- [ ] 문어체 산출물에 ~함·~임·~됨 종결이 없다(채팅은 예외).
- [ ] 이중 피동, 번역투, 일본어투, 중복 수식이 없다.
- [ ] 근거 없는 주장, 주제와 무관한 문장, 독자에게 필요 없는 배경이 없다.
- [ ] 수치·날짜·시각 표기가 정확하고 규칙을 따른다.
- [ ] 영어 IT 용어 첫 등장에 한글 풀이가 있다.
- [ ] 이모지 아이콘이 없다. 시크릿 값이 없다.
- [ ] 소리 내어 읽어도 막히지 않는다.

## 예시

나쁜 이슈 문장:

> 백필 작업에 있어서 대상 추출 쿼리가 매우 오래 걸리는 현상이 발생되어지고 있는 것으로 보여짐.

고친 문장:

> 백필 대상 추출 쿼리가 1시간 넘게 끝나지 않는다. `biz_info` 61만 건을 랜덤 조회하기 때문이다.

나쁜 공지 문장:

> #418 이슈 관련하여 run_chunks.sh 래퍼를 통해 2026년 폐업자에 대한 백필을 진행하고 있는 중입니다.

고친 문장:

> 2026년 폐업 사업자의 상호명을 채우고 있습니다. 하루 약 4,000건씩, 100일 정도 걸립니다.

나쁜 채팅(격식체가 샌 경우):

> 머지가 완료되었습니다. 배포 파이프라인이 성공적으로 종료되었습니다.

고친 채팅:

> 머지 완료 ㅇㅇ 배포도 통과했어요.

## 예외

- 사용자가 다른 문체를 지시하면 그 지시를 따른다.
- 인용문, 고유명사, 코드, 명령어, 표 안의 값은 고치지 않는다.