ko-doc: 독자에 맞춘 한국어 문서 작성

왜 이 스킬이 필요한가

모델이 한국어 문서를 쓰면 "2026-07-22 분석(…)의 후속. 7월엔 A + B만 대조 → C를 놓쳤다(D → E 피드백)." 같은 문장이 나온다. 정보 밀도는 높지만 문장마다 서술어가 없고, 문장 사이의 관계를 독자가 스스로 복원해야 해서 "툭툭 끊기는 AI 말투"로 읽힌다. 처음 읽는 사람, 특히 비개발자는 여기서 멈춘다.

같은 내용을 사람이 쓰면 이렇게 된다.

2026-07-22 분석(링크)의 후속 분석입니다. 7월엔 스킨 코드 및 관리자 마이앱 목록만 대조해서, 관리자가 직접 주입하는 스크립트 레이어가 분석 대상에서 제외되었습니다. 따라서 이번엔 라이브 렌더를 기준으로 재측정하였고, 아래는 그 결과입니다.

차이는 세 가지다. 문장마다 주어와 서술어가 있고, "따라서"처럼 앞뒤 관계가 드러나며, 마지막 문장이 독자에게 다음에 무엇이 오는지 알려준다. 이 스킬은 그 차이를 규칙으로 만든 것이다.

영어권의 AI 말투 목록(humanizer)은 대부분 한국어에도 그대로 적용되지만, 한국어에서 가장 흔한 패턴인 체언 종결·괄호 문장·가운뎃점 나열·화살표는 그 목록에 없다. 그래서 humanizer 패턴은 참고 파일로 두고, 여기서는 한국어 고유 패턴과 영역별 문체를 다룬다.

작업 순서

독자를 확인한다. 사용자가 독자를 이미 말했으면 그대로 쓰고, 아니면 AskUserQuestion으로 한 번 묻는다. (아래 "독자" 절)
문서의 목적과 독자가 할 일을 한 줄로 정한다. "이 문서를 읽고 X를 결정해 달라", "Y를 알아두면 된다"처럼. 이 한 줄이 문서 첫머리에 들어가고, 문단 순서를 정하는 기준이 된다.
초안을 쓴다. 영역별 규칙(본문·표 셀·제목)을 따른다.
린트를 돌린다. python3 scripts/lint.py <파일>로 체언 종결, 화살표, 대시, 괄호 문장, 번호 제목, 수평선을 잡는다. 린트는 기계적으로 잡히는 것만 본다.
문장을 하나씩 다시 읽는다. 린트가 못 잡는 것(허수아비 대조, 한 줄 마무리, 무게 잡기, 부사 중첩)을 본다. 이 단계를 건너뛰면 초안 문체가 그대로 나간다. 초안은 거의 항상 메모체로 나오기 때문에, 검사 단계가 곧 이 스킬의 실체다.
노션에 올릴 때는 아래 "노션 업로드" 절을 따른다.

독자

사용자가 독자를 말하지 않았으면 AskUserQuestion으로 묻는다. 선택지는 넷이다.

독자	용어	순서	제목 태그 어휘
비개발자 (사업부·커머스·운영)	기술 용어는 처음 나올 때 풀어 쓴다. "ScriptTag"는 "앱이 자동으로 넣는 스크립트", "렌더"는 "화면에 그려진 결과". 파일 경로·ID는 표에만	결정할 것 → 이유 → 근거. 근거는 부록이나 표로 뺀다	`[결정 요청]`, `[확인 요청]`, `[알아둘 것]`
마케터	도구 이름과 이벤트 이름(purchase, view_item)은 그대로 쓴다. 코드 경로는 풀어 쓴다	영향받는 도구·이벤트 → 결정할 것 → 근거	`[마케팅팀 결정 요청]`, `[영향 있음]`, `[자동 유지]`
개발자	파일 경로, 식별자, 실측 명령을 그대로 쓴다	결론 → 근거 → 재현 방법	`[이식 대상]`, `[확인 필요]`, `[추정]`
혼합	본문은 비개발자 기준, 근거와 경로는 부록 페이지나 표로 분리	결정 사항을 앞에, 기술 근거를 뒤에	독자별 태그를 섹션마다 붙인다

독자가 정해지면 같은 사실도 다르게 쓴다. "GTM-5RJVW4L 컨테이너의 __gaawe 태그 78개가 CSS 셀렉터 트리거에 묶여 있다"는 개발자용이고, 비개발자에게는 "구글 태그 매니저에 등록된 클릭 추적 78개가 지금 화면의 구조에 묶여 있어서, 새 스킨에서는 오류 없이 수집이 멈춥니다"가 된다.

영역별 규칙

문서는 본문, 표 셀, 제목의 세 영역으로 이루어지고 영역마다 허용되는 문체가 다르다. 메모체 자체가 나쁜 게 아니라 본문에 번지는 것이 문제다.

본문

모든 문장을 서술어로 끝낸다. 전달용 문서는 "~~입니다/~~했습니다"로 통일한다. "~의 후속.", "정리 대상", "확인 필요", "유지", "동일" 같은 체언 종결은 본문에서 금지한다.
한 문장에 주장 하나만 담고, 문장 사이의 관계를 접속어("그래서", "다만", "그 결과")로 쓴다.
문단의 첫 문장에서 독자가 할 일을 밝힌다(알아둘 것인지, 결정할 것인지, 확인할 것인지).
괄호에는 약어, 수치, 링크, 두세 단어의 보충만 넣는다. 한 문장 분량의 설명은 별도 문장으로 뺀다.
화살표(→), 가운뎃점(·) 나열, 빗금(/), 물결(~) 축약, 대시(—, –)를 본문 문장에서 쓰지 않는다. 가운뎃점 나열은 쉼표와 "그리고"로, 화살표는 접속어로, 대시는 쉼표나 별도 문장으로 푼다.
부사를 두 개 겹치지 않는다. "오류 없이 조용히 동작하지 않습니다"는 "오류 메시지 없이 수집이 멈춥니다"로 쓴다. 안 일어나는 일보다 일어나는 일을 서술한다.
아무도 하지 않은 주장을 세워 놓고 부정하지 않는다. "전부 걷어낸다는 게 아닙니다. 두 종류로 나눕니다"는 "두 종류로 구분하여 정리합니다"로 쓴다. 고칠 때는 "~가 아니라" 절만 잘라내고 뒤 문장은 그대로 둔다. 새 문맥을 덧붙이지 않는다.
앞 문단을 되풀이하는 한 줄 마무리("바로 그 문제입니다", "이게 핵심입니다")는 새 사실을 담은 문장으로 바꾸거나 지운다.
굵게는 독자가 그 단어만 보고 판단해도 되는 자리(결정 요청의 주어, 뒤집힌 판정)에만 쓴다. 문장마다 굵게가 있으면 아무것도 강조되지 않는다.

표 셀

명사형 종결을 허용한다. 순서는 "판정어(부연)"이다. 미실측(공유 크롬의 관리자 세션 만료), gtm.js 404 (아무것도 안 함, 정리 대상).
화살표와 대시 대신 괄호로 부연한다. 사라짐 → 남길 것은 이식은 사라짐(남길 것은 이식)으로 쓴다.
굵게를 쓰지 않는다.
파일명, 식별자, 이벤트 이름은 인라인 코드로 표시한다.
표 앞에는 표를 어떻게 읽으라는 문장을 한 줄 둔다. 열 이름만으로는 판정어의 기준(실측인지 추정인지, 어느 날짜 기준인지)이 전달되지 않는다.

제목

명사구로 끝낸다. "외주(ATEM PLUS) 관리자 운영 방식", "같은 픽셀이 두 군데에서 찍히는 문제".
번호를 붙이지 않는다. 노션과 대부분의 뷰어는 목차를 자동으로 만든다.
대시로 부제를 붙이지 않는다. 독자나 요구 행위를 표시할 때는 앞에 대괄호 태그를 붙인다. [마케팅팀 결정 요청] 같은 픽셀이 두 군데에서 찍히는 문제.
제목 바로 아래 첫 문장에서 제목을 되풀이하지 않는다.

문서 구조

첫머리에 목적, 독자, 독자가 할 일을 한 문단으로 쓴다. 개정판이면 무엇이 왜 바뀌었는지도 여기에 쓴다.
결론과 요청을 앞에, 근거를 뒤에 둔다. 조사한 순서가 아니라 독자가 결정하는 순서로 배치한다.
섹션 사이에 수평선(---)을 넣지 않는다. 제목이 구분자다.
근거 데이터가 많으면 부록 페이지나 별도 파일로 분리하고 본문에서 링크한다. 본문에 표가 다섯 개를 넘으면 분리 신호다.
"실측"과 "추정"을 구분해 적는다. 확인하지 못한 것은 못 했다고 쓰고, 추정에는 근거를 붙인다.

humanizer 패턴 중 한국어에도 적용되는 것

references/humanizer-3.0.0.md의 패턴 가운데 다음은 언어와 무관하게 적용된다. 초안을 검사할 때 이 번호들을 훑는다.

§1 부정 대조(not X but Y), §2 한 줄 마무리와 파편 문장, §3 격언체("핵심은", "본질적으로"), §4 도입부 뜸 들이기, §5 없는 반론 반박
§6 규칙적 삼중 나열(한국어에서는 가운뎃점 사슬로 나타난다), §8 대시, §9 한정어 겹치기
§13 의미 부풀리기("중요한 전환점", "큰 의미"), §15 "~~하며/~~하여" 꼬리로 의미 부풀리기, §17 출처 없는 권위("전문가들은")
§19 장식용 굵게, §20 장식 제목(이모지, 화살표, 수평선, 번호), §22 챗봇 잔재, §24 제목 반복

§7(같은 주어 반복), §10(하이픈), §18(be동사 회피), §21(둥근 따옴표)은 한국어에 해당 사항이 거의 없다.

한국어에서 모델이 자주 쓰는 단어(§12 대응)는 아직 목록이 짧다. 지금까지 확인된 것은 "핵심", "정확한", "실체", "일체", "전반", "확정", "특히", "결국", "사실상", "그대로"이며, 실제 문서에서 더 발견되면 references/examples.md에 추가한다.

예시

references/examples.md에 나쁜 예와 고친 예를 규칙별로 짝지어 두었다. 초안을 쓰기 전에 한 번 읽고, 검사 단계에서 비슷한 문장이 있으면 그 예를 따른다. 사용자가 직접 고쳐 준 문장이 원본이므로 그 문체가 기준이다.

예외

knowledge/ 실측 기록, 커밋 메시지, 코드 주석, 자기만 보는 작업 메모는 압축 기록이 맞는 자리다. 이 스킬을 적용하지 않는다.
사용자가 직접 쓴 문장을 고치는 작업이면 사용자의 문체를 규칙보다 우선한다.

노션 업로드

노션 MCP로 올릴 때는 다음을 지킨다.

표는 <table header-row="true"><tr><td>…</td></tr></table> 형식을 먼저 쓴다. 파이프 표는 변환이 불안정하다. 다만 replace_content로 긴 본문을 통째로 올릴 때 HTML 표가 문자 그대로(\<table …) 새는 경우가 있었고, 그때는 파이프 표가 정상 표로 들어갔다(2026-09-22 실측). 어느 쪽이든 올린 뒤 아래 확인 단계를 거친다.
본문에 HTML 태그처럼 보이는 문자열(<head>, , <upsell-widget-*>)을 넣지 않는다. 파서가 태그로 해석한다. "head 태그", "External Script Start 블록"처럼 풀어 쓴다.
기존 페이지를 replace_content로 교체할 때 하위 페이지가 있으면 <page url="…">제목</page> 태그를 본문에 포함해야 삭제되지 않는다.
제목에 번호를 넣지 않는다. 노션 목차가 번호를 대신한다.
올린 뒤 반드시 fetch로 다시 읽어 표가 table 블록으로 들어갔는지, 번호 목록이 끊기지 않았는지 확인한다. 깨졌으면 형식을 바꿔 다시 올린다.
코드 블록에는 언어를 적는다(bash, json). 비워 두면 노션이 javascript로 표시한다.
번호 목록의 항목 사이에 코드 블록이나 보충 문단이 들어가면, 그 블록을 네 칸 들여써서 앞 항목의 하위로 넣는다. 들여쓰지 않으면 노션이 목록을 끊어 다음 항목이 1부터 다시 시작한다(2026-09-22 실측).

ko-doc

SKILL.mdskills/ko-doc/SKILL.md