# korean-report-style

Adopt this skill: https://proskills.md/skills/other/janghyun-bin-korean-report-skills-plugins-korean-report-skills-korean-report-sty

Page: https://proskills.md/skills/other/janghyun-bin-korean-report-skills-plugins-korean-report-skills-korean-report-sty
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: plugins/korean-report/skills/korean-report-style/SKILL.md
size: 16004
upstream: https://github.com/janghyun-bin/korean-report-skills/blob/main/plugins/korean-report/skills/korean-report-style/SKILL.md

````text
---
name: korean-report-style
description: Korean-language conventions for technical reports, progress updates, meeting agendas, software handoffs, architecture documents, runbooks, API references, model evaluations, and consortium deliverables — prose register, framing of shortfalls and risks, terminology accuracy, and structural integrity after edits. Use this whenever writing or revising any Korean document intended for colleagues, partners, clients, or evaluators — 진행현황, 중간보고, 기술보고, 연구노트, 코드베이스 인수인계, 운영 문서, 협의 아젠다, 회의록, 제안서 — and also when the user asks to soften, reframe, tighten, or "말투를 바꿔달라" on Korean text. Apply it even for internal-only documents; the register rules are not about audience politeness but about the document reading as a report rather than as speech.
---

# 한국어 보고 문서 문체

기술·사업 문서의 한국어 서술 규약. 시각 디자인 규약(색·타이포·도해)과 제작 절차는
`korean-report-doc` 스킬이 담당하며, 이 스킬의 범위는
**문장과 프레이밍**에 한정한다.

원칙 하나로 요약하면 이렇다. **문서는 말이 아니라 기록이다.** 말할 때 자연스러운 표현이
문서에서는 대개 어긋난다.

예시는 가상 사례 「A사 — 인라인 계측 체계 확립과 수율 개선」에서 가져왔다.
도메인은 예시일 뿐이고 규칙 자체는 분야를 가리지 않는다.

---

## 1. 문체

### 1.1 제목은 명사구

서술형 제목은 논평처럼 읽히고 문서 개정 시 낡는다. 제목은 주제를 지시하고, 주장은 본문이 한다.

| 쓰지 않는다 | 쓴다 |
|---|---|
| 일정이 말하는 것 | 일정 시사점 |
| 필터는 제 역할을 하였다 | 검출 필터의 정상 동작 |
| CD는 같은 웨이퍼 안에서도 흔들린다 | 웨이퍼 내 CD 편차 |
| 4번이 기술적으로 가장 중요하다 | 4번의 기술적 우선순위 |
| 현재 시스템은 편차 문제를 덮고 있다 | 증상 억제의 구조와 그 대가 |

한정이 필요하면 줄표를 쓴다 — `오버레이 — 핵심이자 약점`, `상한 2.5 nm와 고객 규격의 여유`.

`~하는 방법`·`~하는 과정`·`~하는 이유`·`~할 때`·`~할 것`·`~하기`처럼
관형절이나 동작 명사화로 끝나는 제목도 간결한 명사구로 교정한다. 이미 명사구인
`처리 방법`·`저장 과정`·`운영 시`·`확인 사항`은 유지한다.

**예외**: 도해(SVG) 안의 제목은 그림이 말하는 주장이므로 문장이어도 된다.

### 1.2 구어체 환언 금지

기술적 사실을 일상어로 바꾸면 그 사실이 곁말처럼 읽힌다.

| 쓰지 않는다 | 쓴다 |
|---|---|
| 검사 장비가 보는 전부 | 검사 장비의 검출 범위 |
| 모델이 내는 것 | 모델의 출력 |
| 크기를 재는 것이 싸다 | 크기를 재는 편이 비용이 낮다 |
| 반토막이 된다 | 절반 수준으로 낮아진다 |
| 25%가 흔들린다 | 25%의 편차가 있다 |
| 레시피를 외운 것이 된다 | 레시피에 과적합한 결과에 가깝다 |
| 기준 웨이퍼에 갇혀 | 기준 웨이퍼에 고정되어 |
| 틀린 검출을 거르는 법 | 오검출의 기각 |
| 손도 대지 못한다 | 관여하지 않는다 |
| 기반을 다진다 | 기반을 확립한다 |
| 하는 일 (표 항목) | 역할 |

### 1.3 의인화·물리 은유 금지

주어가 사람이나 사물이 아니면 동사도 그것의 것이 아니어야 한다.
분야 표준 비유라도 서술 문체와 충돌한다.

**판정법 — 주어를 사람이나 물건으로 바꿔 본다.** 그 자리에서 자연스러우면 전용된 비유다.

- `로트가 흐른다` → "물이 흐른다"의 전용 → 물리 은유
- `문서가 다룬다` → "사람이 사안을 다룬다"의 전용 → 약한 의인화
- `다이가 죽는다` → "사람이 죽는다"의 전용 → 의인화

| 쓰지 않는다 | 쓴다 |
|---|---|
| 다이가 죽는다 | 다이가 불량으로 판정된다 |
| 양품이 살아남는다 | 양품이 잔존한다 |
| 결함이 웨이퍼를 갉아먹는다 | 결함이 수율을 저하시킨다 |
| 파티클이 앉는다 | 파티클이 부착된다 |
| 챔버가 늙었다 | 챔버가 노후화되었다 |
| 한 로트가 분산을 독점한다 | 한 로트가 분산의 대부분을 차지한다 |
| 로트가 흐른다 | 로트가 공정을 통과한다 |
| 본 문서는 …를 다룬다 | 본 문서는 …로 한정한다 · …를 정의한다 |
| 세션이 살아 있다 | 세션이 유지된다 |
| 큐가 밀린다 | 큐에 적체가 발생한다 |
| 값이 튄다 | 값에 이상치가 발생한다 |

**단, 용어는 원형을 유지한다.** `킬러 디펙트` · `뉴슨스` · `드리프트` · `빈닝`은 비유가 아니라
이름이며, 번역하면 정밀도가 떨어진다. 판정법을 적용하기 전에 그 말이
**개념의 이름인지 서술인지**를 먼저 가른다.

코드베이스 인수인계에서는 `graph가 살아 있다`·`prompt와 condition이 싸운다`처럼
영문 식별자와 한국어 은유가 결합하는 경우가 많다. bare verb를 전역 규칙으로 만들지 않고
주어와 술어가 결합된 표현만 선택적으로 검토한다. 상세 기준과 사례는
`references/software-handoff.md`를 참조한다.

그래서 다음 한 줄이 두 규칙의 경계를 보여준다 — **이름은 남기고 서술만 수정한다.**

<!-- style-teaching -->
| 킬러 디펙트가 다이를 죽인다 | 킬러 디펙트가 다이 불량을 유발한다 |
|---|---|

### 1.4 어미는 문어체

| 쓰지 않는다 | 쓴다 |
|---|---|
| 됐다 · 됐고 · 됐으며 · 변경됐는가 | 되었다 · 되었고 · 되었으며 · 변경되었는가 |
| 통합돼 있다 · 호출돼야 한다 | 통합되어 있다 · 호출되어야 한다 |
| 했다 · 했고 · 했으나 | 하였다 · 하였고 · 하였으나 |

도해 라벨과 표 셀에도 동일하게 적용한다.

검증된 활용형만 치환하고, `돼`·`됐`을 단독으로 전역 치환하지 않는다. 인용문·코드 블록·
inline code·교육용 표는 제외한다. 남의 말을 옮긴 자리까지 문어체로 바꾸면 인용이 아니게 된다.

**한 문서에서 평서체와 합니다체를 섞지 않는다.** 둘은 독자와의 거리가 다르므로
혼용하면 문서가 초안처럼 읽힌다. 문서 본문은 평서체로 쓰고, 송부 메일·요청문은 합니다체로 분리한다.

| 구분 | 어미 | 용도 |
|---|---|---|
| 평서체 | `~한다` · `~이다` | 기술보고 · 정의서 · 연구노트 · 진행현황 |
| 합니다체 | `~합니다` · `~입니다` | 송부 메일 · 협의 요청문 · 대외 안내 |

> ✗ 검사 레시피가 확정됐습니다. 로트가 들어오면 빈닝이 돌아간다.
> ✓ 검사 레시피를 확정하였다. 로트가 투입되면 빈닝이 수행된다.

한 문서 안에 두 체가 필요하면 **문서와 커버레터를 분리**한다.

**README · 문서 카탈로그 · 저장소 문서는 평서체다.** 대외 안내로 보이지만 읽는 사람이
결정을 내리기 위해 참조하는 문서이며, 같은 저장소의 다른 문서와 어체가 달라지면 안 된다.
안내 문서가 규약과 다른 어체를 쓰면 규약을 스스로 부정하는 것이 된다.

### 1.5 번역투 제거

| 쓰지 않는다 | 쓴다 |
|---|---|
| 각 절은 근거를 함께 갖는다 | 각 절에 근거를 명시하였다 |
| 모든 사슬이 승인 하나에 걸려 있다 | 승인 이후 착수할 수 있다 |
| 계측 축은 수치를 냈다 | 계측 체계는 수치를 확보하였다 |
| 양산 적용 창 | 양산 적용 가용 기간 |
| ~를 성립시키는 사슬 | 준비 단계의 선행 관계 |

### 1.6 문서의 자기 설명 배제

초록 자리에 사용법이 들어가면 정보가 밀려난다.

> ✗ 본 문서는 무엇을 넣을지 정하기 위한 내부 검토 자료다. 각 절은 후보와 그 근거,
>   그리고 그 자리에서 받아야 할 결정을 함께 담는다.
>
> ✓ 분기 품질보고를 3주 앞두고 현재 상태를 정리한다.

절 제목이 「요약」이면 성격은 이미 전달된다. 구성 안내가 정말 필요하면 한 문장으로 줄인다.

### 1.7 과장·위협 표현 금지

소요와 위험은 사실로 적고, 압박으로 적지 않는다.

| 쓰지 않는다 | 쓴다 |
|---|---|
| 하루면 끝난다 | (삭제하거나) 선행조건 |
| 이번 분기에 시작하지 않으면 양산 일정이 위험하다 | 착수 시점 확정 필요 |
| 웨이퍼 한 장이면 30분 | (삭제) |
| 착수가 늦어질수록 회복이 어려워진다 | 착수 시점을 먼저 확정한다 |
| 양산 검증이 유일한 답 | 양산 조건 검증이 필요하다 |

### 1.8 어휘 선택 — 정밀도 기준

**쉬운 말이 기준이 아니라 정밀도가 기준이다.** 한자어와 영문은 격식을 위해서가 아니라
의미역을 좁히기 위해 쓴다. 정밀도가 향상되지 않으면 쓰지 않는다.

#### 광의 고유어를 협의 한자어로

고유어 동사는 의미역이 넓어 계약·규격 문서에서 해석이 분기한다.

**판정법 — 그 동사에 목적어를 바꿔 끼워 본다.** 서로 다른 종류의 목적어가 모두 자연스러우면
의미역이 넓은 것이므로 협의어로 대체한다.

- `넘긴다` → 데이터를 / 업무를 / 권한을 넘긴다 → 전부 성립 → **전달 · 이관 · 위임**으로 분리 <!-- style-exempt -->
- `늘다` → 정밀도가 / 비용이 / 기간이 늘다 → 전부 성립 → **향상 · 증가 · 연장**으로 분리
- `갈린다` → 해석이 / 승패가 / 길이 갈린다 → 전부 성립 → **분기 · 결정 · 분리**로 분리 <!-- style-exempt -->

아래 표는 **자주 나타나는 예시이며 목록이 아니다.** 표에 없는 동사도 판정법으로 검사한다.

| 광의 | 협의 | 갈라지는 의미 |
|---|---|---|
| 다룬다 | 한정한다 · 규정한다 · 정의한다 | 범위 획정인지 정의인지 |
| 나눈다 | 구분한다 · 분류한다 · 배분한다 | 경계인지 유형인지 몫인지 |
| 맞춘다 | 정합한다 · 정렬한다 · 보정한다 | 논리인지 위치인지 값인지 |
| 바꾼다 | 변환한다 · 대체한다 · 개정한다 | 형식인지 대상인지 문서인지 |
| 넘긴다 | 전달한다 · 이관한다 · 위임한다 | 데이터인지 업무인지 권한인지 |
| 지운다 | 삭제한다 · 제거한다 · 소거한다 | 항목인지 요소인지 값인지 |
| 늦춘다 | 순연한다 · 유예한다 | 일정인지 의무인지 |
| 적는다 · 적었다 | 명시한다 · 기재한다 · 기록한다 | 규정인지 항목 입력인지 이력인지 |
| 나온다 · 나와야 | 도출된다 · 산출된다 · 확정된다 | 결과인지 계산인지 승인인지 |
| 넣는다 | 포함한다 · 등재한다 · 삽입한다 | 범위인지 목록인지 위치인지 |
| 뺀다 | 제외한다 · 차감한다 | 범위인지 수량인지 |
| 붙인다 | 부착한다 · 부기한다 · 첨부한다 | 표기인지 주석인지 파일인지 |
| 만든다 | 생성한다 · 작성한다 · 구축한다 | 데이터인지 문서인지 환경인지 |
| 고친다 | 수정한다 · 보완한다 · 개정한다 | 오류인지 미비인지 문서인지 |
| 잡는다 | 검출한다 · 산정한다 · 고정한다 | 이상인지 수치인지 값인지 |
| 둔다 · 두면 | 배치한다 · 유지한다 · 설정한다 | 위치인지 상태인지 값인지 |
| 긋는다 | 획정한다 · 구획한다 | 범위인지 구역인지 |
| 막는다 | 차단한다 · 방지한다 | 경로인지 사태인지 |
| 는다 · 늘어난다 | 향상된다 · 증가한다 · 연장된다 | 품질인지 수량인지 기간인지 |
| 갈린다 | 분기한다 · 분리된다 | 해석인지 대상인지 |
| 올라간다 · 내려간다 | 상승한다 · 하락한다 | (수치는 상승·하락, 위치는 이동) |
| 생긴다 | 발생한다 · 형성된다 | 사태인지 구조인지 |

**교정안도 이 표를 통과해야 한다.** 다른 절에서 제시한 「쓴다」 쪽 문장에
광의 고유어가 남아 있으면 규칙이 자기모순이 된다.

> `이관`과 `전달`을 함께 「넘긴다」로 적으면 책임 범위가 무너진다.
> 업무분장 문서에서 「이관」과 「추가 수행」의 구분이 쟁점이 되는 일이 실제로 있다.

#### 표기 층위

| 층위 | 표기 | 예 |
|---|---|---|
| 식별자 · API · enum | **영문 원문 그대로** | `waferId` · `InspectionStarted` · `SUCCESS` · `retryLimit 3` |
| 기술 개념 | 영문 또는 정착 번역 | `payload` · `endpoint` / 좌표계 · 정합 · 계측 |
| 행위 · 관계 서술 | 한자어 | 한정한다 · 이관한다 · 순연한다 · 산정한다 |

**enum 값과 필드명은 번역하지 않는다.** `SUCCESS`를 「성공」으로 적으면 코드와 문서가 어긋난다.
**규격·API에 등장하는 말은 한글 음차보다 영문 표기**를 쓴다. 원어와 1:1로 대응해야 검색·대조가 된다.

| 쓰지 않는다 | 쓴다 |
|---|---|
| 세션 키 · 페이로드 | `session key` · `payload` |
| 엔드포인트 · 콜백 | `endpoint` · `callback` |

**단, 분야에 정착한 개념어는 한글 음차를 유지한다.** `드리프트` · `뉴슨스` · `빈닝`은
규격상의 이름이 아니므로 영문으로 되돌리면 읽기 비용만 증가한다. 판정 기준은
**코드·API 문서에 같은 철자로 존재하는가**이다.

#### 정밀도 없는 격식체는 제거

| 쓰지 않는다 | 쓴다 |
|---|---|
| 상기 · 하기 · 여히 | 위 · 아래 · 다음과 같이 |
| 익일 · 명기 · 요망 | 다음 날 · 명시 · (동사로) 요청한다 |
| 스캐폴드 | 구성안 |
| 공정 정본 | 공정 기준 문서 |
| 풋프린트 | 점유 면적 |

**한 문장에 영문과 한자어를 겹쳐 쌓지 않는다.** 밀도가 아니라 탁도가 상승한다.

> ✗ 검사 endpoint의 payload를 canonical ID로 정합 후 전달 요망
> ✓ 검사 endpoint의 payload를 표준 ID 기준으로 정합한 뒤 전달한다

조직 내부에서 굳어진 용어는 그대로 두되, 외부 문서에서는 처음 나올 때 한 번 풀어 쓴다.

---

## 2. 프레이밍

### 2.1 결함 서사를 역량 서사로

같은 사실이라도 주어가 '결함'이면 문서 전체가 사고 보고서가 된다.
주어를 '측정 역량'으로 옮기면 사실을 삭제하지 않으면서 성격이 바뀐다.

> ✗ 2.2 계측이 드러낸 결함 넷
> ✓ 2.2 구조적 개선 — 인라인 계측 체계 확립과 수율 향상

| 쓰지 않는다 | 쓴다 |
|---|---|
| 검출 결함의 71%가 뉴슨스로 버려지고 있었다 | 검사–빈닝 기준 연결 — 검출률과 계측 시간을 동시에 개선 |
| 수율 벤치가 양산 조건으로 측정되지 않았다 | 양산 조건 기준 수율 벤치 확립 |
| 인라인 계측이 수율 분석에 못 들어갔다 | 인라인 데이터의 수율 분석 체인 편입 |
| 장비 매칭 검증이 사흘간 중단되었다 | 장비 매칭 검증 경로 복구 |
| 세 공정이 합쳐서 실패하였다 | 세 공정이 서로의 계측 기준을 참조하지 않는 구조였다 |
| 추가 계측 필요(오버레이 미달) | 오버레이 계측 보강 대상 |

### 2.2 결과 우선 구조

각 항목은 **수치로 시작**하고 배경은 후행 배치한다. 배경이 선행하면 문제 서술이 되고,
결과가 선행하면 성과 서술이 된다.

```
#### ① 검사–빈닝 기준 연결 — 검출률과 계측 시간을 동시에 개선
📊 결과 · 유효 검출률 4/7 → 5/7 · 웨이퍼당 계측 ~900 → ~590초

(그 다음에 배경과 원인)
```

### 2.3 리스크는 대응과 함께

리스크만 나열하면
````

## File: README.md
upstream: https://github.com/janghyun-bin/korean-report-skills/blob/main/README.md

````text
<img src="docs/assets/logo.svg" width="30" align="middle" alt=""> <b>korean-report-skills</b>

[![tests](https://img.shields.io/badge/tests-564%20tests-3fb950)](../../actions)
[![release](https://img.shields.io/badge/release-v1.20.1-0066cc)](../../releases)
[![plugin](https://img.shields.io/badge/plugin-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20OpenCode-8957e5)](INSTALL.md)
[![license](https://img.shields.io/badge/license-Apache--2.0-d29922)](LICENSE)

# Claude가 쓴 글이 어딘가 이상할 때 <!-- style-exempt -->

내용은 올바르더라도 번역체, 모호한 수치, 들쭉날쭉한 페이지 배치가 남으면 문서는 아직
초안처럼 보입니다.

`korean-report-style`은 문체와 근거를 다듬고, `korean-report-doc`은 그 내용을
일관된 `layout`으로 구성합니다. 이어서 HTML `typesetting`과 렌더 검사를 수행하고,
필요하면 PDF와 검수용 스크린샷까지 생성합니다.

여기서 `layout`은 페이지와 요소의 배치를, `typesetting`은 CSS·글꼴·수식을 반영해
최종 HTML을 만드는 처리 단계를 뜻합니다.

글만 다듬을 때는 `korean-report-style`을 사용합니다. HTML이나 PDF까지 필요할 때는
`korean-report-doc`을 함께 사용합니다. Claude Code, Codex, Cursor, OpenCode에서
사용할 수 있습니다.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.png">
  <img src="docs/assets/banner-light.png" alt="paper 보고서와 deck 협의자료 — 스킬이 생성한 문서 세 장">
</picture>

## 두 스킬의 역할

| 스킬 | 맡는 일 | 결과 |
|---|---|---|
| `korean-report-style` | 문체, 프레이밍, 용어, 상태·근거 표기, 편집 후 정합성 검토 | 수정 원고와 lint 결과 |
| `korean-report-doc` | 문서 구조, `paper`·`deck` 모드의 `layout`, 도해, 수식, HTML `typesetting`, 렌더 QA | 자립형 HTML과 선택적 PDF |

문체 스킬은 어미만 바꾸는 교정기가 아닙니다. 실측과 추정을 구분하고, 주장에 근거가
있는지 확인하며, 리스크와 대응이 함께 적혀 있는지도 살핍니다. 문서 스킬을 함께 쓰면
이 검토를 공통 디자인 시스템과 브라우저 렌더 검사까지 이어 갑니다.

## 사용 예

설치한 뒤에는 평소처럼 작업을 요청하면 됩니다.

```text
지난주 벤치 결과로 기술보고서를 작성해 줘.
이 문단을 외부 협력사에 전달할 보고 문체로 수정해 줘.
이 진행현황에서 미측정 수치와 근거가 없는 주장을 표시해 줘.
회의에서 검토할 쟁점과 결정 요청을 가로형 협의자료로 만들어 줘.
```

스킬 이름을 직접 적을 필요는 없습니다. 명시적으로 선택하려면 Codex에서는
`$korean-report-doc`, Claude Code에서는 `/korean-report-doc`처럼 요청할 수 있습니다.

설명이나 요약만 요청하면 대화 안에서 답하고, 별도의 문서 파일은 만들지 않습니다.
HTML이나 PDF처럼 완성된 산출물을 요청하면 문서 제작 절차를 시작합니다.

## 결과물

문서의 목적에 따라 `paper`와 `deck` 중 하나를 선택합니다.

| 항목 | `paper` | `deck` |
|---|---|---|
| 잘 맞는 문서 | 기술보고, 벤치마크, 진행현황, 연구노트 | 회의자료, 아젠다, 협의자료, 의사결정 요청 |
| 방향 | 세로 | 가로 |
| 페이지 흐름 | 내용이 이어지는 연속 문서 | 한 섹션을 한 페이지에 배치 |

두 모드는 글자 크기와 페이지 구조, 인쇄 규칙이 다릅니다. 하나의 문서 안에서는
두 모드를 섞지 않습니다.

완성된 HTML은 CSS, 사용된 KaTeX CSS와 글꼴을 한 파일 안에 담습니다. 실행할 때
외부 자원을 요청하지 않으므로 네트워크가 없는 환경에서도 열고 인쇄할 수 있습니다.
PDF는 이 HTML을 자동화 브라우저로 인쇄해 생성합니다.

아래 이미지는 같은 가상 원고를 브라우저 기본 스타일로 저장한 HTML과 `paper` 모드로
`typesetting`한 결과를 나란히 보여 줍니다.

<table>
<tr>
<th width="50%">브라우저 기본 스타일</th>
<th width="50%">paper 모드 적용</th>
</tr>
<tr>
<td><img src="docs/assets/ba_before.png" alt="브라우저 기본 스타일로 표시한 가상 문서"></td>
<td><img src="docs/assets/ba_after.png" alt="paper 모드를 적용한 가상 문서"></td>
</tr>
</table>

문체 규칙은 표현뿐 아니라 수치의 상태, 주장과 한계, 의사결정 요청의 근거에도
적용됩니다.

<img src="docs/assets/ba_after_body.png" alt="도해와 상태 배지가 포함된 가상 문서 본문" width="100%">

전후 원고와 규칙별 근거는 [examples/before_after.md](examples/before_after.md)에서 볼 수
있습니다. 예시에 등장하는 기업, 공정, 인물, 수치는 모두 가상입니다.

## 설치

| 환경 | 권장 설치 방식 | 설치 식별자 |
|---|---|---|
| Claude Code | GitHub `marketplace` 플러그인 | `korean-report@korean-report-skills` |
| Codex | GitHub `marketplace` 플러그인 | `korean-report@korean-report-skills` |
| OpenCode | npm 플러그인 | `korean-report-skills` |
| Cursor | npm 파일 복사 | `korean-report-skills` |

### Claude Code

```text
/plugin marketplace add JangHyun-bin/korean-report-skills
/plugin install korean-report@korean-report-skills
```

### Codex

```bash
codex plugin marketplace add JangHyun-bin/korean-report-skills
codex plugin add korean-report@korean-report-skills
```

### OpenCode

`opencode.json`의 `plugin` 배열에 npm 패키지를 등록합니다.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["korean-report-skills"]
}
```

OpenCode를 다시 시작하면 package의 `config` hook이 두 스킬의 경로를 추가합니다.
이 방식에는 별도의 `npm i -g`나 `npx` 복사가 필요하지 않습니다.

### Cursor와 파일 복사 설치

`npx` 설치기는 Claude Code, Codex, Cursor의 스킬 디렉터리에 두 스킬을 복사합니다.
OpenCode의 npm 플러그인 등록과는 다른 설치 방식입니다.

```bash
npx korean-report-skills                 # Claude Code · Codex · Cursor
npx korean-report-skills cursor          # Cursor만 선택
npx korean-report-skills --project       # 현재 프로젝트에 설치
npx korean-report-skills --remove        # 복사한 스킬 제거
```

설치 후 새 세션을 시작하고 스킬 목록에서 `korean-report-doc`과
`korean-report-style`을 확인합니다. 갱신, 제거, 프로젝트 설치, claude.ai 업로드 절차는
[INSTALL.md](INSTALL.md)에 정리되어 있습니다.

## 문서 제작과 검수

문서 파일은 다음 순서로 만들어집니다.

```text
자료와 원고
  → Python 생성기와 문서 구조
  → 원시 HTML
  → Node와 KaTeX로 수식 렌더링, CSS 삽입, 자산 내장
  → 자립형 HTML
  → 브라우저 렌더 QA
  → 선택적 PDF와 검수용 스크린샷
```

### 문체 검사

`korean-report-style`의 lint는 Markdown과 HTML의 가시 텍스트를 검사합니다.
치환 목록 134건과 제목, 문맥 의존 표현, 어미 규칙, 형태소 규칙, 서식 규칙을
여섯 갈래로 구분합니다.

| 갈래 | 의미 |
|---|---|
| 고침 | 검증된 어미 활용형이며 `--fix`로 수정 가능 |
| 검토 | 문맥을 확인한 뒤 선택해야 하는 표현 |
| 제목 | 명사구가 아닌 제목 |
| 의심 | `--heuristic`에서만 확인하는 문맥 의존 표현 |
| 형태 | 형태소로 판정하는 어간·활용·어체 혼용 |
| 서식 | 문장이 아니라 마크업의 결함 — 이모지, 라벨 목록, 제목 되풀이 |

검사 결과는 일반 텍스트뿐 아니라 JSON, GitHub annotation, SARIF로도 출력할 수 있습니다.
의미가 달라질 수 있는 용어나 문맥 의존 표현은 자동으로 수정하지 않습니다.

### 렌더 검사

HTML을 브라우저로 렌더한 뒤에는 다음 항목을 확인합니다.

- 수식 marker와 template token의 잔존 여부
- 문서와 표의 가로 넘침
- CSS token과 본문 글꼴 stack 적용
- SVG `viewBox` clipping과 캡션 누락
- `deck` section의 인쇄 페이지 초과

페이지 분할, 과도한 빈 공간, 제목의 고립, 다크 타일의 인쇄 반전처럼 수치만으로
판정하기 어려운 항목은 스크린샷과 PDF를 함께 확인합니다.

## 지원 범위와 현재 한계

문서 제작에는 진행현황, 중간보고, 기술보고, 연구노트, 벤치마크 보고, 협의자료,
회의 아젠다, 제안서가 포함됩니다. 문체 규칙은 코드베이스 인수인계, 아키텍처 문서,
runbook, API reference, 모델 평가, 회의록, 컨소시엄 산출물에도 적용할 수 있습니다.

현재 범위는 다음과 같습니다.

- 한국어 기술·사업 문서를 대상으로 합니다. 다른 언어의 문체와 `layout` 규칙은 아직
  포함하지 않습니다.
- 제공된 수치와 서술의 정합성은 검사하지만, 입력 자료에 없는 사실이나 근거를 새로
  확정하지 않습니다.
- 기준 결과물은 자립형 HTML이며, 필요하면 PDF를 함께 생성합니다. 네이티브 `.docx`와
  `.pptx` 파일은 생성하지 않습니다.
- 법률·규제 적합성이나 외부 사실의 정확성을 보증하지 않습니다. 기한, 의무, 책임이
  포함된 문장은 사용자가 제공한 근거 문서와 대조해야 합니다.

본문 글꼴은 동봉한 Pretendard 공식 subset(OFL 1.1)을 기본으로 HTML에 내장합니다. 다른 글꼴을
쓰려면 사용 권한이 있는 WOFF2 파일을 `--font`로 지정합니다. subset에 없는 한글 음절은 시스템
글꼴로 표시되며 빌드가 해당 글자를 알립니다.

## 필요한 실행 환경

`korean-report-style`의 형태소 검사에는 `kiwipiepy`가 필요합니다. 없으면 검사기가 종료 코드 3(일부 검사 미수행)을 반환합니다.
`korean-report-doc`으로 HTML을 빌드하려면 Node 20 이상과 KaTeX가 필요합니다.
렌더 QA, 스크린샷, PDF 출력에는 Python 3.11 이상, Playwright, Chromium이 필요합니다.

```bash
npm install katex
python3 -m pip install kiwipiepy playwright
python3 -m playwright install chromium
```

## 소스 저장소에서 직접 실행

이 절은 설치된 플러그인의 사용법이 아니라, 저장소에서 생성기와 빌드 도구를 직접
실행하려는 개발자를 위한 안내입니다.

저장소의 Node 의존성은 `npm install`로 설치합니다. 위의 Python 실행 환경을 준비한 뒤
다음 명령으로 문서 뼈대를 만들 수 있습니다.

```bash
npm install
python3 scripts/new-document.py --title "문서 제목" --mode paper
python3 문서_제목.py
```

생성된 Python 파일에서 본문, 표, 도해를 수정합니다. 다른 본문 글꼴을 쓰려면 실행할 때
WOFF2 경로를 지정합니다.

```bash
python3 문서_제목.py --font 다른글꼴-Regular.woff2 --font 다른글꼴-SemiBold.woff2
python3 scripts/qa.py 문서_제목.html --pdf --shot shots/
```

문체 검사와 저장소 회귀 검사는 다음 명령으로 실행할 수 있습니다.

```bash
python3 plugins/korean-report/skills/korean-report-style/assets/lint.py 초안.md
python3 plugins/korean-report/skills/korean-report-style/assets/lint.py 초안.md --fix
npm test
```

## 저장소 구조

```text
plugins/korean-report/
  skills/
    korean-report-doc/
      assets/                 template, CSS, figures.py, mathbuild.js, qa.py
      references/             design·figure 규칙
    korean-report-style/
      assets/lint.py          문체 검사기
      references/             치환 규칙·software handoff heuristic
.claude-plugin/               Claude Code·Codex marketplace 선언
.opencode/                    OpenCode npm plugin adapter
bin/install.js                Claude Code·Codex·Cursor file-copy 설치기
scripts/                      생성기, QA, 패키징, 이미지 생성
tests/                        정합성·회귀·end-to-end 검사
```

문체 규칙은 Markdown 표를 단일 원천으로 사용합니다. `base.css`에는 공통 디자인 token,
`paper.css`와 `deck.css`에는 모드별 규칙이 있습니다. 도해의 SVG class도 같은 token을
사용합니다.

새 문체 규칙과 문맥 heuristic은 현재 구조 안에서 추가할 수 있습니다. 새 출력 모드,
글꼴 정책, 언어 지원을 추가하려면 template, builder, QA, 회귀 검사를 함께 변경해야
합니다.

## 기여와 보안

기여 절차와 회귀 검사 기준은 [CONTRIBUTING.md](CONTRIBUTING.md)에 있습니다. 보안
취약점은 공개 issue 대신 [Security Advisory](../../security/advisories/new)로 신고합니다.
세부 정책은 [SECURITY.md](SECURITY.md)에서 확인할 수 있습니다.

## 라이선스

[Apache-2.0](LICENSE)
````
