yd-writer-kr git:20261004.ffb8314A

Immutable. This exact content never changes and is served at /api/v1/blob/493ccab7646399ed.

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

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

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

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

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

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

## 원칙 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자 안팎. 소제목은 사용자가 원하는 대로 바꿀 수 있다.

## 작업 순서

### 새로 쓸 때

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

### 고칠 때

1. 원문을 문장 단위로 나눈다.
2. 문장마다 점검표를 적용한다. 뜻과 사실관계는 바꾸지 않는다.
3. 고친 글 전체를 낸다. 요청하면 원문과 나란히 보여준다.

## 검수 점검표

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

## 예시

나쁜 이슈 문장:

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

고친 문장:

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

나쁜 공지 문장:

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

고친 문장:

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

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

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

고친 채팅:

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

## 예외

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