Skip to content

JellyBrick/korean-prose-skill / skills/korean-prose

korean-prose

Verified

자연스럽고 일관된 한국어 산문을 작성하거나 교정합니다. 커밋과 PR 본문, README와 기술 문서, i18n 다국어 문구와 UI 문구, 에러 메시지, 여러 줄 코드 주석이 대상입니다. "한국어로 써 줘", "말투를 고쳐 줘", "PR 본문을 작성해 줘", "번역투를 없애 줘", "i18n 문구를 다듬어 줘" 같은 요청과 한국어 산문을 새로 쓰거나 다듬는 모든 상황에서 사용합니다. 짧은 한 줄 주석과 변수명에는 사용하지 않습니다.

FileKindSize
SKILL.mdskill md8.4 KB
agents/openai.yamlconfig262 B
references/style.mdmarkdown17.9 KB
scripts/prose.tsscript31.6 KB

references/style.md

View on GitHub
# 한국어 문체

## 목차

- [독자에 따른 문체 구분](#독자에-따른-문체-구분)
- [줄표 미사용 원칙](#줄표-미사용-원칙)
- [가운뎃점 사용 지침](#가운뎃점-사용-지침)
- [다섯 가지 작성 원칙](#다섯-가지-작성-원칙)
- [AI 글쓰기 패턴 배제](#ai-글쓰기-패턴-배제)
- [주석 작성 규약](#주석-작성-규약)

## 독자에 따른 문체 구분

| 대상 | 문체 | 예 |
|---|---|---|
| 사용자에게 보이는 UI 문구 | 부드러운 해요체 | "저장됐어요", "다시 시도해 주세요" |
| README, `docs/`, 코드 주석 | 습니다체 | "로컬 SQLite가 단일 진실 공급원입니다" |
| 커밋, PR, 이슈 제목 | 명사구 | "레거시 필드 제거" |

**평어체(`~한다`/`~이다`)는 어디에도 사용하지 않습니다.**

UI는 사용자에게 말을 건네는 자리이므로 해요체가 적절합니다. README와 기술 문서는 한국어
오픈소스 생태계에서 통용되는 습니다체를 사용합니다. 한 문서 안에서 두 문체를 섞지 않습니다.
기술 문서에서 UI 문구를 인용할 때만 해당 인용구에 해요체를 유지합니다.

커밋, PR, 이슈 제목은 문장이 아닌 명사구로 작업 내용을 분명하게 표현하고 마무리합니다.

```text
레거시 필드 제거
강제 업데이트 최소 버전 상향
```

`~를 걷어낸다`, `~로 올린다`와 같은 서술형 표현은 사용하지 않습니다. 본문의 불릿 항목도
명사구로 끝맺습니다. 제목에는 작업 대상과 변경 사항을 함께 담습니다. PR 본문에서 불릿만으로
담기 어려운 맥락이나 근거를 풀어 쓸 때는 해요체 산문을 사용합니다.

## 줄표 미사용 원칙

**em-dash(U+2014)와 en-dash(U+2013)는 사용하지 않습니다.** 산문, 코드 주석, 커밋 메시지,
PR 본문, UI 문구 등 모든 영역에 적용됩니다.

- 문장을 구분할 때는 양옆에 공백을 둔 하이픈(` - `)이나 쉼표, 콜론으로 대체합니다.
- 범위는 한국어와 UI 문구에서 `~`로, 영어 기술 문서에서 하이픈으로 표시합니다.
  예: `10-13px`, `2~15초`

이는 단순한 입력 편의 때문이 아닙니다. MS Word나 일부 IDE, 마크다운 렌더러가 일반 하이픈을
자동으로 줄표로 바꾸기도 합니다. 이 경우 한 줄만 고쳐도 문단 전체가 변경 사항으로 잡히며,
직접 입력한 값과 도구가 바꾼 값이 섞입니다.

**예외는 산문이 아닌 경우에만 허용하며, 코드 옆에 그 이유를 명시해야 합니다.**

- 모델에게 줄표를 쓰지 말라고 지시하는 프롬프트 문장: 문자 자체가 전달 내용입니다.
- 값이 없는 자리를 나타내는 조판 글리프: 하이픈으로 바꾸면 수치 칸에서 음수 부호로 읽힐 수
  있습니다.

## 가운뎃점 사용 지침

단어나 구를 가운뎃점(`·`)으로 기계적으로 연결하지 않습니다. 문맥에 맞추어 쉼표, 접속 표현, 조사나 연결 어미로 자연스럽게 풀어 씁니다. 항목이 길고 복잡하면 문장을 나누거나 불릿 목록으로 정리합니다.

- **쉼표 사용:** 대등한 항목을 세 개 이상 나열할 때는 쉼표를 사용합니다.
  - "이름·이메일·전화번호를 입력해 주세요" → "이름, 이메일, 전화번호를 입력해 주세요"
- **'및' 사용:** 두 항목을 대등하게 묶을 때는 '및'을 사용합니다.
  - "계정 설정·보안 관리 권한" → "계정 설정 및 보안 관리 권한"
- **조사나 연결 어미 사용:** 풀어서 서술할 수 있는 문장은 조사나 연결 어미를 붙여 자연스럽게 씁니다.
  - "오류 확인·수정 작업을 진행합니다" → "오류를 확인하고 수정한 뒤 작업을 진행합니다"
- **문장 분리나 목록 사용:** 각 항목의 수식어가 길거나 내용이 복잡하면 문장을 따로 나누거나 불릿 목록으로 작성합니다.

**예외:** 법률 조항의 명칭, 등록된 공식 고유 명칭, 원문 인용과 같이 원형 표기를 그대로 보존해야 하는 자리에만 가운뎃점을 허용합니다.

## 다섯 가지 작성 원칙

### 1. 어미의 일관성과 공손함

행동을 요청할 때 "버튼 눌러요", "입력해요"와 같이 직역한 명령투를 사용하지 않습니다.
배려를 담아 `~해 주세요` 형식을 사용하거나, UI 요소라면 명사형으로 간결하게 작성합니다.

| 자리 | 형태 | 예 |
|---|---|---|
| 사용자에게 무언가를 요청 | `~해 주세요` | "다시 시도해 주세요", "날짜를 골라 주세요" |
| 기능이 무엇을 하는지 | `~해요` / `~할 수 있어요` | "게스트로 추가할 수 있어요" |
| 상태와 결과 | `~했어요` / `~됐어요` | "저장됐어요" |
| 시스템이 수행하는 동작 | `~할게요` | "편집 화면으로 이동할게요" |
| 버튼, 짧은 명령 라벨 | 명사형 | "복사", "확인", "신청서 편집" |

### 2. 시스템 제공자 시점

"A를 클릭하면 B를 봐요"와 같은 영어식 인과관계 직역 표현을 사용하지 않습니다. 시스템이
사용자에게 서비스를 제공하는 주체이므로 사동, 수여, 의지 표현으로 풀어 씁니다.

서비스가 사람에게 무언가를 제공할 때는 건조하게 서술하기보다 대상에 알맞은 높임 표현과 조사 `께`를 쓰고, `보내 드립니다`나 `안내해 드립니다`처럼 수여 표현으로 풀어서 친절하게 안내합니다.

다만 모든 문장에 높임말을 기계적으로 덧붙이지 않습니다. 사용자가 아닌 시스템 내부 동작이나 사물을 설명하는 자리에는 쓰지 않으며, 사람에게 직접 혜택이나 정보를 전달하는 안내 문장에 한해 적용합니다. 또한 `합니다`를 `하고 있습니다`로 무조건 바꾸지 않고, 원문의 예정, 반복, 진행, 완료 상태를 그대로 보존합니다.

- "탭으로 이동해요" → "탭으로 이동할게요"
- "결과를 봐요" → "결과를 보여드릴게요"
- "가입자에게 인증 번호를 발송할 예정입니다" → "가입자분께 인증 번호를 보내 드릴 예정입니다"
- "회원에게 변경된 이용 약관을 안내하고 있습니다" → "회원분께 변경된 이용 약관을 안내해 드리고 있습니다"

### 3. 무생물 주어를 사람 주어로 전환

추상 명사가 직접 결과를 일으키는 식의 어색한 직역을 피합니다. 상황과 느낌을 묘사하는 동사와
형용사로 자연스럽게 표현합니다.

- "주소가 바뀌어요" → "주소가 바뀌게 돼요"
- "무료 폼으로 돌아가요" → "무료 폼으로 돌아가게 돼요"

### 4. 고맥락 언어의 특성 살리기

- 불필요한 대명사(`나의`, `이것`, `그것은` 등)는 과감히 생략합니다.
- 가리키는 대상이 흐릿한 지시어(`이`, `그`, `이를 통해`, `이에 따라`, `그 기준` 등)를 쓰지
  않습니다. 지시어를 쓸 때는 바로 앞 문장에 가리키는 구체적인 대상이 있는지 확인합니다. 앞
  문장에서 대상을 찾을 수 없거나 두 문장 사이의 논리 과정이 건너뛰어졌다면, 대상을 직접
  쓰거나 빠진 과정을 풀어서 적습니다.
  - "오류 로그를 수집합니다. 이를 통해 서비스 안정성을 높입니다." → "수집한 오류 로그에서
    반복되는 예외 원인을 찾아 수정하여 장애 빈도를 줄입니다."
- 문맥을 먼저 확인해 주어를 적절히 다루어야 합니다.
  - 앞뒤 문맥에서 행동의 주체가 이미 정해져 있고 분명하다면 문장마다 주어를 반복하지
    않습니다.
  - 주어가 빠져서 시스템 자동 처리인지, 사용자 조작인지, 특정 팀의 업무인지 모호해지는
    기획서나 문서, 안내문에는 주어를 분명히 적습니다. "되돌릴 수 없어요" → "이 동작은 되돌릴
    수 없어요"
  - 담당자나 수행 주체가 아직 정해지지 않았다면 임의로 인물이나 조직을 지어내어 주어로 넣지
    않습니다. 주체가 확정된 경우에만 주어를 쓰고, 미정이라면 담당자를 정할 예정이라는 사실을
    적습니다.
    - 주체가 정해진 경우: "백엔드 팀은 배포 직후 에러 추이를 확인해 다음 패치 항목에
      반영하겠습니다."
    - 주체가 미정인 경우: "배포 직후 반복되는 에러 항목을 확인해 수정할 담당자를 정할
      예정입니다."
- 영어권의 간결성(concise) 지침을 한국어에 그대로 대입해 조사와 어미를 떼어내거나 수식어와
  서술어를 명사(체언)로 압축하지 않습니다. 한국어는 조사와 어미로 문장 성분의 관계를
  드러내므로, 체언과 용언만 남기거나 명사를 연달아 붙여 쓰면 문장이 어색해지고 한 번에
  이해하기 어렵습니다. 중복된 내용과 군더더기 수식어를 덜어 내되, 조사와 연결 어미, 동사와
  형용사 서술어는 자연스럽게 살려 씁니다.
  - "권한 검증 로직 개편 통한 보안 강화" → "권한을 검증하는 로직을 개편해 보안을 강화했습니다"
  - "네트워크 연결 끊김 시 재시도 수행" → "네트워크 연결이 끊기면 다시 연결을 시도합니다"
- 접속사(`그리고`, `그래서` 등)를 남발하지 않고 어미로 문장을 자연스럽게 잇습니다.
- 직역투 부사와 불필요한 수식어를 덜어 냅니다. "자동으로 필수 포함돼요" → "항상 포함돼요"
- 소유 표현 `~의`보다 위치와 존재를 나타내는 `~에`를 우선 사용합니다. "이 화면의 옵션이
  없어요" → "이 화면에 옵션이 없어요"
- 받침에 따라 달라지는 조사를 이중 표기하지 않습니다. 사용자 입력에 붙는 조사는 한국어 조사
  처리 라이브러리로 올바르게 선택합니다.

### 5. 상황에 맞게 작성하기

UI와 안내문은 감정을 배제하고 명확하고 간결하며 친절하게 작성합니다. 내부 문서와 기술 문서는
맥락과 이유가 분명히 남도록 작성합니다.

코드 안에서 사용되는 문구(i18n 다국어 문구, 컴포넌트 내 텍스트, 에러 및 검증 메시지 등)를
작성하거나 다듬을 때는 문장만 단독으로 보지 않습니다. 해당 문구가 실제로 렌더링되는 UI 요소의
성격(버튼, 모달 제목과 본문, 토스트 알림, 입력창 하단 오류 등), 노출 조건, 직전과 직후의
사용자 흐름, 포맷팅 변수에 들어가는 실제 값과 주변 문구의 용어를 먼저 확인한 뒤 그 자리에
맞게 작성합니다.

**검증 방법:** 문장을 소리 내어 읽어 봅니다. 영어 원문의 구조나 직역투가 비쳐 보인다면
번역체 문장입니다.

## AI 글쓰기 패턴 배제

기술 문서와 사실을 설명하는 글은 건조하고 명확하게 작성합니다. 다만 UI 문구에는 백과사전식
건조함을 강요하지 않고, 매체와 사용자에게 맞는 친절함을 유지합니다. 영미권에서 선호하는 글
구조(대조를 통한 강조, 선언형 도입과 마무리, 세 항목 묶기, 추상 명사 중심 서술)를 한국어로
그대로 옮긴 직역투 패턴을 피합니다.

### 1. 과장과 거창한 해석 금지

대상의 중요성을 부풀리거나 역사적, 거시적 흐름과 억지로 연결하지 않습니다. 입력과 참고
자료에 없는 평가도 추가하지 않습니다.

- `~로서의 역할을 한다`
- `~의 증거이다`
- `중추적인 역할`, `결정적인 역할`
- `시대의 변화를 반영한다`
- `지울 수 없는 족적을 남겼다`

### 2. 내용 없는 꼬리 문장과 빈 선언문 금지

문장 끝에 실질적인 정보를 더하지 않는 요약구나 수식어를 붙이지 않습니다. 앞 문장의 내용을
바꿔 반복하는 문장도 삭제합니다.

- `~함을 강조하며`
- `~에 기여하며`
- `~를 보여주며`
- `~를 상징하며`

글이나 슬라이드, 문단을 매끄럽게 시작하거나 끝내려고 새로 전달하는 내용 없이 선언만 하는
문장(`~는 분명합니다`, `중요한 것은 ~입니다`, `핵심은 간단합니다` 등)도 붙이지 않습니다. 이런
문장은 아예 없애거나, 뒤에 이어질 구체적인 행동이나 근거를 바로 적습니다.

- "기준은 분명합니다. 중요한 것은 사용자의 대기 시간 단축입니다." → "초기 번들 크기를 줄여 첫
  화면이 뜨는 시간을 앞당겼습니다."

### 3. 홍보성 표현과 모호한 추상어 조합 금지

보도자료나 여행 안내서처럼 감성적이고 화려한 수사를 사용하지 않습니다. 평가가 필요하면
참고 자료에 있는 구체적인 사실을 제시합니다.

- `자랑하는`, `활기찬`, `풍부한`, `매끄러운`
- `숨 막히는`, `획기적인`, `유명한`
- `~의 중심에 자리 잡은`

감성적이거나 문학적인 분위기를 내려고 추상 명사와 동사를 조합한 표현(`결을 살리다`, `농도를
높이다`, `밀도를 더하다`, `온도를 담다` 등)도 사용하지 않습니다. 구체적으로 무엇을 뜻하는지
모호해 독자가 놓친 뜻이 있는지 다시 읽게 만들고, 글 전체를 공허하게 만듭니다. 문학적이거나
부드러운 표현이 필요하더라도 추상어를 겹쳐 쓰는 대신 구체적인 장면, 감각, 변화를 직접
서술합니다.

- "화면 전환의 결을 살리고 안내 문구의 밀도를 더했습니다." → "화면이 바뀌는 애니메이션 시간을
  줄이고 안내 문구에서 겹치는 설명을 덜어 냈습니다."

### 4. 모호한 출처와 억지 유명세 금지

구체적인 출처가 주어지지 않았다면 출처가 있는 것처럼 쓰지 않습니다. 대상을 유명해 보이게
하려고 언론 보도나 소셜 미디어 활동을 덧붙이지 않습니다.

- `전문가들에 따르면`
- `일부 비평가들은`
- `업계 보고서에 따르면`
- `독립적인 언론의 보도를 거쳤으며`
- `소셜 미디어에서 활발히 활동하며`

### 5. 틀에 박힌 결론 금지

요청하지 않은 전망, 도전 과제, 결론 섹션을 만들지 않습니다. 정보가 끝나는 지점에서 글을
마치고 억지 교훈을 덧붙이지 않습니다.

- `이러한 과제에도 불구하고`
- `결론적으로`

### 6. 불필요한 대조 및 비교 구문 금지

굳이 두 가지를 비교하며 문장을 길게 늘이는 대조 구문을 습관적으로 쓰지 않습니다.

- `A는 단순히 B가 아니라 C다`
- `A일 뿐만 아니라 B이기도 하다`
- `A라기보다는 B다`
- `A보다 B에 가깝다`

특히 무엇을 비교하는지 분명하지 않거나 뒤에 오는 서술어가 모호하면 문장이 더 어색해집니다.
앞서 언급된 두 대안을 실제로 대조해야 하는 맥락이 아니라면 비교 대상을 걷어 내고 하고 싶은
말을 바로 씁니다.

- "테스트 자동화는 단순히 배포 시간을 줄이는 일이 아니라 장애 재발을 막는 일입니다." → "테스트
  자동화는 장애 재발을 막는 일입니다."
- "이번 개편은 화면 디자인 수정보다 입력 단계 축소에 가깝습니다." → "이번 개편에서는 입력
  단계를 줄였습니다."

### 7. 모호한 포괄 동사와 사전적 합성어 남발 금지

누가 무엇을 어떻게 하는지 드러나지 않는 포괄 동사(`~와 ~를 함께 봅니다`, `다각도로
살펴봅니다`, `종합적으로 고려합니다` 등)를 쓰지 않습니다. 독자가 실제 동작을 짐작해야 하는
표현 대신 실제로 수행할 행동을 구체적으로 적습니다.

- "서버 지표와 사용자 반응을 함께 봅니다." → "최근 배포 이후의 응답 지연 그래프를 비교하고,
  오류 제보가 몰린 기능과 재현 조건을 정리할 예정입니다."

지나치게 사전적이거나 일상에서 잘 쓰지 않는 한자어 합성어와 비유적 틀(`판단 기준`, `작동
구조`, `운영 관점`, `네 축으로 판단한다`, `차원` 등)을 반복하지 않습니다. 한두 번 쓰이는
정도는 문제가 없지만, 거듭 나오면 읽는 사람은 내용을 이해하기보다 표현을 해석하게 됩니다.
명사 합성어로 뭉뚱그리는 대신 실제로 무엇을 어떻게 할지 동사와 절로 풀어서 씁니다.

- "복구 관점과 확장성 축에서 시스템의 작동 구조를 검토합니다." → "장애가 났을 때 빠르게
  복구할 수 있는지, 트래픽이 몰려도 서버를 쉽게 늘릴 수 있는지 확인합니다."

### 8. 관계 설명 없는 세 항목 나열과 과도한 마크업 금지

글을 그럴듯하게 정돈하려고 내용을 기계적으로 세 항목으로 묶어 나열(`특히 A, B, 그리고 C가
중요합니다` 등)하지 않습니다. 세 가지를 나열하면 겉보기에는 정리된 것처럼 보이지만, 항목
사이의 관계가 설명되지 않으면 단어를 늘어놓은 문장에 그칩니다.

세 항목이 실제로 모두 필요하고 서로 어떻게 연결되는지 분명할 때만 유지합니다. 그렇지 않다면
가장 중요한 내용만 남기거나 각 항목이 뜻하는 구체적인 행동을 풀어서 간결하게 씁니다.

- "특히 배포 기준, 모니터링 방식, 그리고 핵심 알림 설정이 중요합니다." → "이번 배포에서는 결제
  오류가 발생했을 때 담당자에게 즉시 알림이 가도록 설정할 예정입니다."
- `이다`, `있다`로 충분한 문장을 `~로 자리매김하다`처럼 부풀리지 않습니다.
- 볼드체, 이모지, 장식 기호는 내용의 구조를 실제로 분명하게 할 때만 사용합니다.

## 주석 작성 규약

- 코드만으로 의도가 분명하면 주석을 작성하지 않습니다. 주석이 필요하면 동작이 아닌
  **이유**를 작성합니다.
- 구분선 용도의 배너 주석은 사용하지 않습니다.
- 우회책이나 임시방편에는 `// HACK: <사유>`를 붙입니다. 근거가 없으면 코드 리뷰에서 의도한
  우회 구조와 실수를 구별하기 어렵습니다.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall