korean-report-skills
왜 Claude가 만든 한국어 문서는 어딘가 이상할까
내용은 맞는데 문서로 전달하기가 망설여지는 경험. 그 이유를 다섯 가지로 나누고 각각을 규약으로 구성한 스킬셋입니다.
Claude Code · Codex · Cursor 에 적용 가능합니다. → 설치
paper(세로·보고서) · deck(가로·협의자료) — HTML 파일 하나로 구성됩니다.
"디자인이 별로예요"
마크다운을 워드에 붙이면 볼품없고, HTML로 제작 할 경우 매번 일관되지 않은 디자인과 구성으로 표현합니다. 제목 크기도, 표 모양도, 여백도 그때그때 달라집니다.
→ 디자인 시스템을 고정했습니다. 액센트 색 하나, 그림자 없음, 표에 세로 괘선 없음. paper(세로·보고서)와 deck(가로·협의자료) 두 모드뿐이고 섞을 수 없습니다. 같은 요청에 같은 결과가 나옵니다.
"문장이 번역체 같아요"
됐다와 하였습니다가 한 문서에 섞이고, ~하는 것·~에 걸려 있다 같은
번역투가 남습니다. 읽는 사람에게 초안처럼 보입니다.
→ 치환 목록 115건과 어미 규약. 평서체와 합니다체를 섞지 않고, 필요하면 문서와 커버레터를 분리합니다.
| 그냥 쓰면 | 규약 적용 |
|---|---|
| 반토막 넘게 늘었습니다 | 4.2시간에서 9.1시간으로 증가하였다 |
| 모든 사슬이 승인 하나에 걸려 있다 | 승인 이후 착수할 수 있다 |
| 각 절은 근거를 함께 갖는다 | 각 절에 근거를 명시하였다 |
지켜졌는지 확인할 수 있습니다. 규약이 표로만 있으면 지켜졌는지 아무도 모릅니다. 같이 실려 가는 검사기가 문서를 훑어 걸린 곳을 줄·열로 알려줍니다.
$ python korean-report-style/assets/lint.py 보고서.md
보고서.md:5:24 [검토] 반토막이 된다 → 절반 수준으로 낮아진다 (§3 구어체 환언)
보고서.md:5:38 [고침] 했다 → 하였다 (§1 어미)
보고서.md:10:1 [제목] 무엇이 달라지나 → 명사구로 고친다 (§1.1 제목은 명사구)
--fix 는 어미만 자동으로 고칩니다. 넘긴다 → 전달/이관/위임처럼 갈래가 나뉘는
자리는 사람이 고릅니다. 코드 블록·인용문·표는 건너뜁니다 —
나쁜 예를 보여주려면 그 형태를 적어야 하니까요.
조판된 HTML에도 돌아갑니다. 스킬 자신도 이 검사기로 검사받습니다.
"단어를 뭉뚱그려 써요"
넘긴다가 전달인지 이관인지 위임인지 알 수 없습니다. 업무분장·계약 문서에서
이 한 단어에 책임 범위가 걸립니다.
→ 광의 고유어를 협의 한자어로 가르는 표 24행, 그리고 판정법. 목적어를 바꿔 끼워 서로 다른 종류가 모두 자연스러우면 그 동사는 의미역이 넓습니다.
| 광의 | 협의 | 갈라지는 의미 |
|---|---|---|
| 넘긴다 | 전달한다 · 이관한다 · 위임한다 | 데이터인지 업무인지 권한인지 |
| 맞춘다 | 정합한다 · 정렬한다 · 보정한다 | 논리인지 위치인지 값인지 |
| 잡는다 | 검출한다 · 산정한다 · 고정한다 | 이상인지 수치인지 값인지 |
"숫자를 전부 확정된 것처럼 써요"
추정치와 실측치가 같은 무게로 나열됩니다. 읽는 사람은 어디까지 검증된 값인지 알 수 없고, 그대로 인용했다가 나중에 정정해야 합니다.
→ 상태를 주장이 있는 자리에 붙입니다. 범례에만 두지 않습니다.
실측 채움 · 구현됨 외곽선 · 미측정 파선 — 색이 아니라 테두리 형태로
구분하므로 흑백 인쇄에서도 살아남습니다.
"안 된 것만 나열해서 사고 보고서처럼 읽혀요"
~가 안 되고 있었다가 이어지면 같은 사실이라도 문서 전체가 문책 자료가 됩니다.
→ 주어를 '결함'에서 '개선'으로 옮깁니다. 사실을 지우지 않으면서 성격이 바뀝니다.
| 그냥 쓰면 | 규약 적용 |
|---|---|
| 원인 분석에서 드러난 결함 세 가지 | 구조적 개선 — 분류 체계 정비와 자동응답 복구 |
| 템플릿이 죽어 있어서 | 템플릿이 비활성 상태였으므로 |
| 야간 인력을 얼마나 늘릴지 정해 주십시오 | 3명 증원을 산정하였다. 근거는 부록 A. 조정 요청 |
전후 원고 전문과 규칙별 근거는 examples/before_after.md에 있습니다.
덤 — 파일 하나로 끝납니다
결과물은 HTML 1 기입니다. 글꼴·수식·도해가 파일 안에 들어 있어 네트워크 없이 열리고, 인쇄해도 동일하게 출력되고, 메일로 전송 할 수 있습니다.
설치
Claude Code — 이 저장소가 곧 마켓플레이스입니다. 갱신이 자동으로 따라옵니다.
/plugin marketplace add JangHyun-bin/korean-report-skills
/plugin install korean-report@korean-report-skills
Codex — 같은 마켓플레이스를 그대로 씁니다.
codex plugin marketplace add JangHyun-bin/korean-report-skills
codex plugin add korean-report@korean-report-skills
Cursor — 플러그인 체계가 없어 파일로 복사합니다.
npx github:JangHyun-bin/korean-report-skills # 전부
npx github:JangHyun-bin/korean-report-skills cursor # 골라서
npx github:JangHyun-bin/korean-report-skills --project # 이 저장소에만
게시 없이 GitHub 에서 바로 실행됩니다. --remove 로 되돌립니다.
claude.ai 웹 업로드와 node 없는 환경은 INSTALL.md 참조.
첫 문서
npm install # katex
pip install playwright && playwright install chromium
python scripts/new-document.py --title "문서 제목" --mode paper
python 문서_제목.py # 생성 → 빌드 → QA 를 한 번에
만들어진 .py 안의 # 여기부터 고쳐 쓴다 구간을 수정하면 됩니다.
글꼴을 문서에 내장하려면 --font Pretendard-Regular.woff2 를 추가합니다.
또는 이렇게 프롬프팅 할 수 있습니다.
지난주 벤치 결과로 기술보고서 만들어줘
이 문단 말투 좀 다듬어줘
무엇이 들어 있나
korean-report-doc — 제작
SKILL.md |
모드 선택, 빌드 파이프라인, QA 절차, 편집 요청 처리 |
references/design.md |
색 · 타이포 · 컴포넌트 · 인쇄 규약 |
references/figures.md |
도해 7종 |
assets/ |
템플릿 2 · CSS 3층 · figures.py · mathbuild.js |
korean-report-style — 문장
SKILL.md |
문체 · 프레이밍 · 정확성 · 편집 후 정합성 |
references/substitutions.md |
치환 목록 115건 |
assets/lint.py |
문체 검사기. 치환표를 읽어 위반을 줄·열로 낸다 |
doc 이 절차를 규정하고 style 이 문장을 다듬습니다. doc 의 SKILL.md 가 style 을
참조하므로 문서를 만들 때는 둘 다 적용되고, 짧은 글을 다듬을 때는 style 만 적용됩니다.
예시는 모두 가상 사례입니다. 실재하는 기업·공정·수치가 아니며, 도메인은 예시일 뿐 규칙 자체는 분야를 가리지 않습니다.
기여
tests/ 가 이 저장소에서 실제로 발생한 사고의 재발을 방지합니다 — 중복된 CSS 블록,
문서에만 존재하고 구현되지 않은 클래스, 좌표계 역전, 음수 폭, 구버전 수식 마커,
실재하지 않는 파일을 가리키는 문서. 자세한 내용은 CONTRIBUTING.md 참조.
보안 취약점은 공개 이슈가 아니라 Security Advisory 로 신고합니다(SECURITY.md).