---
name: engineering-writing
description: >
  PR 본문·커밋 메시지·이슈 코멘트·릴리스 노트·설계 노트·README처럼 사람이 읽을
  개발 산출물의 문장을 쓸 때 로드한다. 이 스킬은 문장만 정한다 — 문서 형식은
  호출한 쪽(pr-description, 커밋 관례, 이슈 템플릿)이 갖는다. AI 티가 나는
  대조 부정문·격언형 마무리·홍보 형용사를 걷고, 전문용어로 압축한 인과를 단계로
  푼다. 이미 써 둔 한국어 글을 윤문하는 일은 korean-humanize가, 사내 메일·메신저·
  결재 문서는 korean-writing이 맡는다.
---

# 개발 산출물 글쓰기

피곤한 리뷰어가 한 번에 이해하는 문장을 쓴다. 압축해서 영리한 문장보다 평범하고
구체적인 문장이 낫다. 사실을 기록하는 글이지 변경을 파는 글이 아니다.

## 형식은 이 스킬이 정하지 않는다

| 무엇을 쓰는가 | 형식을 정하는 쪽 |
|---|---|
| 커밋 메시지 | 저장소의 커밋 관례 (최근 커밋 목록으로 확인) |
| PR 본문 | `pr-description`, 없으면 저장소의 PR 템플릿 |
| 이슈·코멘트 | 이슈 트래커의 관례 |
| 릴리스 노트·README | 그 문서의 기존 구조 |

이 스킬의 규칙과 저장소의 관례가 부딪히면 **저장소가 이긴다.** 한국어 해요체로
쓰던 PR을 이 스킬 때문에 `## Summary / ## Changes`로 바꾸지 않는다.

## 두 방향의 실패

- **AI 슬롭** — 극적인 대구, 홍보 형용사, 반사적인 3개 나열, 마지막에 붙인 멋진 한 줄.
- **용어 압축** — 인과의 사슬을 내부 용어 하나에 우겨넣어 독자가 해독 비용을 낸다.

한쪽을 피하려다 반대쪽으로 가지 않는다. 짧게 쓰라는 말은 암호처럼 쓰라는 말이 아니다.

## 구조 금지

- **대조 부정문** — "단순히 A가 아니라 B", "A에 그치지 않고", "not just A, but B".
- **은유 공식** — "A는 B의 C다", "A is the B of C".
- **격언형 마무리** — 끝에 교훈처럼 붙이는 한 줄.
- **연속 단문 드라마** — 짧은 문장을 연달아 놓아 리듬을 만드는 것.
- **3개 나열 습관** — 항목이 둘이면 둘만 쓴다. 세 번째를 지어내지 않는다.
- **드라마용 em dash(—)** — 문장 중간을 끊어 긴장을 만드는 용법. 쉼표나 마침표로 바꾼다.
  영어 산문에서는 아예 쓰지 않는다. 라벨과 설명을 가르는 구조적 용법(`항목 — 설명`)은
  이 저장소의 문서 관례라 그대로 둔다.

## 어휘 금지

- **자기과시 형용사** — clean, elegant, powerful, robust, seamless, comprehensive,
  강력한, 우아한, 견고한.
- **냄새나는 단어** — delve, tapestry, realm, landscape, leverage, intricate,
  pivotal, crucial, underscore, foster, harness, unlock, showcase, myriad.
- **군더더기 전환어** — Moreover, Furthermore, Notably, "It's worth noting",
  "결론적으로", "이를 통해", 문두의 "또한·따라서".
- **불필요한 완충** — "~할 수 있습니다", "~로 보입니다"로 확인한 사실을 흐리지 않는다.
  확인한 것은 단언하고, 확인 못 한 것은 "확인 못 함"이라고 적는다.
- **마케팅 톤** — 변경을 홍보하지 않는다. 무엇을 하는지 적는다.

## 쉽고 구체적으로

- 내부 용어를 일상어와 구체 명사로 푼다. "ledger" → "요청 상태를 담아 둔 Redis",
  "admission control" → "큐에 넣기 전 제출 조건 검사".
- 인과를 한 단어로 압축하지 말고 단계로 편다.
  "버퍼가 매 주기 재충전" → "버퍼 조건이 항상 참 → 작업이 무한 제출 → 큐 상한이 무시됨".
- 코드 식별자는 백틱으로 두되 옆에 일상어 설명을 붙인다.
- 깊은 기술 설명을 요청받으면 정밀함을 지킨다. 요약·개요에서만 평이함이 우선이다.

## 한국어 문장

- **종결어미** — 배경·개요처럼 독자가 먼저 읽는 산문은 하나로 통일한다. 절차·체크리스트는
  건조하게 "~한다"로 두어도 된다. 한 문서 안에서 섞지 않는다.
- **괄호 부연을 뺀다.** `prefix(KV) 캐시` → `prefix 캐시`,
  `라우터 변경 없이(라운드로빈 유지)` → `라우터 변경 없이`.
- **불릿 하나에 메시지 하나.** 효과 설명 꼬리와 둘째 문장을 잘라 한 줄로 만든다.
  "이 문서를 정리한다" 같은 메타 항목은 지운다.
- **번역투를 우리말로.** "~을 만들다"류 직역 동사를 자연스럽게 바꾼다.
  `캐시 적중을 만들` → `캐시 적중률을 높일`.
- **강조 따옴표로 힘주지 않는다.** 비유적인 단어("함정", "폭탄")는 중립어로 바꾼다.
- **짧은 두 문장은 잇는다.** `논의했어요. 하지만 ~` → `논의했지만 ~`.
- **참조는 텍스트가 아니라 링크로.** 이슈 번호와 문서 이름을 적을 때 실제 링크를 건다.
- **연결어미 뒤 쉼표를 뺀다.** "-고,", "-지만,", "-어서,"는 쉼표 없이 잇는다.

전체 패턴 목록과 전후 예시는 이 저장소의
`plugins/workspace/skills/korean-humanize/ai-tell-catalog.md` 가 source 다. 인라인 규칙과
카탈로그가 어긋나면 카탈로그가 이긴다.

## 근거

- diff와 실제로 바뀐 파일에서 확인한 것만 쓴다. "아마 ~때문일 것"은 쓰지 않는다.
- 길이 상한을 지킨다. 불릿은 한 줄, 설명은 세 문장 이내.
- "다듬어서", "매력적으로" 같은 목표어를 따르지 않는다. 목표는 정확함과 간결함이다.
- 저장소의 기존 톤을 먼저 본다. github MCP가 있으면 최근 커밋과 PR 서너 개를 읽고,
  없으면 사용자에게 예시를 받는다. 관례를 확인 못 했으면 그 사실을 밝힌다.

## 형식 기본값 (관례가 없을 때만)

저장소 관례도 없고 호출한 쪽도 형식을 정하지 않았을 때만 쓴다. 실제로는 드물다.

커밋 메시지:

- `type(scope): subject` 형태, 제목은 명령형에 50자 이내, 끝에 마침표 없음.
- 본문은 무엇과 왜만 적고 72자에서 줄바꿈한다.
- 헤더·볼드·이모지 같은 마크다운 서식을 넣지 않는다.

PR 본문:

- `## 요약` / `## 변경` / `## 검증` 세 절.
- 각 불릿은 동사로 시작하고 한 줄을 유지한다.

## 내보내기 전 자가 점검

아래에 걸리면 완화하지 말고 그 문장을 **다시 쓴다.**

- 문장 중간을 끊는 em dash `—`, dash로 쓴 `--`
- `not (just|only|merely)\b.*\bbut\b`, `단순히 .*아니라`, `에 그치지 않`
- `\bis the\b .* \bof\b`, `.*는 .*의 .*다` 형태의 은유
- 위 어휘 금지 목록 (대소문자 무시)
- 문단 끝의 요약 한 줄, 본문에 없던 결론

## 멈춰야 할 신호

이런 생각이 들면 그 문장을 쓰지 않는다.

- "밋밋하니 마지막에 한 줄 멋지게 붙이자."
- "여기엔 em dash가 어울린다."
- "이 단어 하나면 다 설명된다." — 독자가 해독해야 한다는 뜻이다.
- "전환어 하나 넣으면 매끄러워질 텐데."