---
name: engineering-writing
description: >
  PR 본문, 커밋 메시지, 이슈 코멘트, 릴리스 노트, 설계 문서와 README의 문장을 작성하거나
  개선할 때 쓴다. 기술적 원인과 결과를 독자가 이해할 수 있게 쓰고 저장소의 형식과 용어를
  따른다. 일반 업무 문서는 korean-writing, 기존 한국어 글의 윤문은 korean-humanize를 쓴다.
---

# 개발 산출물 글쓰기

문제, 변경 후 동작과 검증 근거를 독자가 한 번에 이해하도록 쓴다. 형식은 요청과 저장소
관례를 따르고 내용의 길이는 변경의 복잡도에 맞춘다.

ISO 24495-1처럼 **쉽게 찾고 이해하고 사용할 수 있게**, ASD-STE100처럼
**짧고 명확하며 모호하지 않게** 작성한다. 독자에게 필요한 문제·결과·근거를 남기고,
제목과 링크로 찾게 한다. 같은 개념에는 같은 용어를 쓰고 행동의 주체·조건·확인 방법을 밝힌다.
영어 전용 어휘·단어 수 규칙을 한국어에 적용하지 않는다.

## 자료와 형식 확인

1. 문서의 독자, 목적과 작성 범위를 확인한다. 제공된 diff, 파일, 실행 결과와 기존 문서를 읽는다.
2. 커밋은 최근 메시지, PR은 템플릿과 기존 본문, README와 릴리스 노트는 기존 구조를 따른다.
   도구로 확인할 수 없으면 제공 자료를 사용한다. 예시가 없다는 이유만으로 작성을 멈추지 않는다.
3. PR 구조가 필요하면 연결된 `pr-description`을 사용한다. 이 스킬은 문장과 근거를 다룬다.

## 내용 구성

- 해결할 문제와 변경 후 동작을 먼저 쓴다. 원인, 구현 방식과 검증은 판단에 필요한 만큼 이어 쓴다.
- 확인한 사실, 예상 영향과 미확인을 구분한다. 실행하지 않은 검사를 통과했다고 쓰지 않는다.
- 변경 이유는 diff만으로 추측하지 않는다. 근거가 없으면 확인된 동작을 설명하고 이유는 미확인으로 둔다.
- 파일·함수 목록은 변경을 찾거나 위험을 판단하는 데 필요한 경우에만 넣는다.
- 관련 이슈와 문서는 확인된 링크를 붙인다. 번호나 URL을 만들지 않는다.

## 문장 원칙

- 한 문장에는 핵심 판단 하나, 한 문단에는 하나의 주제를 담는다. 필요한 조건과 근거는 다음 문장으로 잇는다.
- 전문용어는 독자의 수준에 맞춰 쓴다. 낯선 내부 용어는 처음에 역할을 설명하고 식별자는 백틱으로 표시한다.
- 원인과 결과를 구체적으로 연결한다. 예: “종료 상태가 갱신되지 않아 같은 요청이 다시 큐에 들어간다.”
- “최적화”, “안정화”, “강력한” 같은 평가 대신 무엇이 어떻게 바뀌는지 쓴다. 성능 주장은 측정값을 붙인다.
- 불필요한 대조문, 과장된 은유와 교훈형 마무리를 덜어낸다. 새로운 결론을 마지막에 덧붙이지 않는다.
- 괄호와 부연은 판단에 필요한 조건이면 유지한다. 중복 설명과 의미 없는 완충 표현만 줄인다.
- 한국어 종결어미와 용어는 문서 관례에 맞춰 일관되게 쓴다. 번역투와 반복되는 전환어를 다듬는다.
- 목록은 비교나 순서가 있을 때 쓴다. 항목 수와 줄 수를 맞추려고 근거를 삭제하거나 내용을 늘리지 않는다.

## 관례가 없을 때

커밋은 `type(scope): subject` 형태로 짧게 쓴다. 본문이 필요하면 무엇을 왜 바꿨는지 적는다.
PR은 문제와 결과를 한두 문단으로 설명하고 검증을 덧붙인다. 복잡한 변경에는 위험과 관련 자료를 추가한다.
작성 언어는 사용자 요청과 독자에 맞추고 코드·API·제품 이름은 원문을 유지한다.

## 마무리

초안을 원본 자료와 대조해 사실, 수치, 조건과 링크를 확인한다. 필요한 근거를 유지하면서 중복 문장을 줄인다.
Markdown의 코드, 링크, 표와 목록이 의도대로 읽히는지 확인한다.
독자가 본문만으로 변경 영향과 필요한 다음 행동을 찾고, 검증 결과와 미확인 사항을 구별할 수 있는지 확인한다.

상세한 한국어 윤문 예시가 필요하고 `korean-humanize`가 연결돼 있으면
`Skill(skill_name="korean-humanize", file_path="ai-tell-catalog.md")`로 참고 자료를 읽는다.
연결되지 않았으면 위 원칙만으로 작성한다. 문장 작성 요청을 커밋·게시 권한으로 확대하지 않는다.