AI 에이전트가 쓰는 어색한 한국어를 고치는 Claude Code 플러그인이다.
에이전트의 한국어 출력에는 영어식 구조와 은유가 남을 수 있다. 옮길 원문이 없어도 출력 패턴을 보면 이를 의심할 수 있다. korean-writing은 판정 절차로 이런 패턴을 검토한다. 플러그인을 설치하면 규칙을 주입하고 파일을 자동으로 검사한다.
이 플러그인은 문서를 대신 작성하거나 자료를 조사하지 않는다. 출발어 간섭으로 설명할 수 없는 일반 생성 결함을 포괄적으로 평가하지도 않는다.
- Claude Code로 한국어 문서, README, 커밋 메시지, 주석을 쓸 때 결과가 번역기처럼 느껴진다
- 문장마다 em dash, 한국어에 없는 세미콜론, 장식용 이모지가 반복된다
- "이미지를 앉힌다", "화면을 걷어낸다"처럼 뜻은 통하지만 한국어에서 쓰지 않는 표현이 나온다
- 에이전트가 처음부터 자연스러운 한국어를 쓰게 하고 싶다
교정 전 문장이다.
본 문서가 서 있는 자리를 먼저 밝히고, 결제창을 그리는 로직은
결국 서버에 의해 처리됩니다 🚀
교정한 문장이다.
이 문서의 맥락을 먼저 밝힙니다. 결제창을 표시하는 로직은 서버가 처리합니다.
몸의 은유인 서 있는 자리를 뜻에 맞는 표현으로 바꾼다.
행위자를 주어로 세운다.
연결 어미 뒤의 쉼표와 장식용 이모지도 뺀다.
금지 목록만으로는 한계가 있다.
- 목록 밖 표현을 잡지 못한다. "걷어낸다"를 넣어도 "앉힌다"와 "물린다"는 빠져나간다
- 굳은 표현을 구별하지 못한다. "화면을 그린다"는 정착했지만 "이미지를 앉힌다"는 정착하지 않았다
한국어에는 "쌓다", "앞뒤", "위아래"처럼 고유한 공간 은유도 있다. 물리 동사를 일괄로 금지하면 자연스러운 표현까지 막는다.
그래서 목록 대신 판정 순서를 둔다. 먼저 이 동사가 부르는 상황 틀이 대상과 맞는가를 묻는다. 틀이 어긋나면 한국어에서 실제로 이 결합을 쓰는가를 다시 묻는다. 첫 물음은 목록 밖 표현을 잡는다. 두 번째 물음은 과잉 교정을 막는다.
claude plugin marketplace add HarryJhin/korean-writing
claude plugin install korean-writing@korean-writing-marketplace세션에서는 /plugin marketplace add, /plugin install 명령도 쓸 수 있다.
사용에는 Claude Code만 필요하다.
직접 개발하거나 테스트할 때만 Node 24(.nvmrc)가 필요하다.
claude plugin marketplace update korean-writing-marketplace카탈로그를 캐시하므로 새 버전을 받으려면 갱신해야 한다.
세션에서는 같은 명령을 실행한 뒤 /reload-plugins로 재시작 없이 적용한다.
설치는 repo 이름인 HarryJhin/korean-writing으로 한다.
업데이트는 마켓플레이스 이름인 korean-writing-marketplace으로 한다.
새 버전은 plugin.json의 version을 올렸을 때만 배포한다.
설치한 뒤 따로 켤 것은 없다. 플러그인은 세 가지 흐름으로 동작한다.
"이 내용을 한국어로 정리해 줘"처럼 요청하면 writing-korean 규칙을 자동으로 로드한다.
"이 문서 번역투 고쳐 줘", "AI 냄새 빼 줘"라고 요청해도 같은 규칙을 로드한다. 새 파일은 저장하라고 명시했을 때만 만든다. 원본 파일을 덮어쓰려면 먼저 확인을 받는다.
세션이 시작될 때와 서브에이전트가 생성될 때 규칙을 컨텍스트에 넣는다. 이 주입은 에이전트가 처음부터 어색한 표현을 쓰지 않도록 유도한다. 한글 문서를 저장하면 남은 위반을 찾아 고치게 한다.
| 구성 요소 | 하는 일 |
|---|---|
writing-korean 스킬 |
글쓰기 규칙의 단일 출처(SoT)다. 새로 쓸 때와 고칠 때 모두 로드한다 |
| 이론 근거 문서 | 판정 절차 각 단계의 출처와 원문 확인 범위를 밝힌다 |
| PostToolUse 훅 | 한글 텍스트 파일(.md/.markdown/.txt)을 저장할 때 결정론 규칙 위반을 검사한다 |
| SessionStart 훅 | 세션이 시작될 때마다 규칙을 컨텍스트에 넣는다 |
| SubagentStart 훅 | 서브에이전트가 생성될 때 같은 규칙을 넣는다. 세션 시작 주입이 닿지 않는 곳을 맡는다 |
훅 세 종류는 다음 시점에 동작한다.
flowchart LR
S([세션 시작]) --> H1[SessionStart 훅]
A([서브에이전트 생성]) --> H2[SubagentStart 훅]
H1 --> CTX[규칙을 컨텍스트에 주입]
H2 --> CTX
CTX --> W[에이전트가 한국어를 쓴다]
W --> SAVE([파일 저장])
SAVE --> H3[PostToolUse 훅]
H3 --> CHK{코드·인용 밖 본문에<br/>Rule 1 위반이 있나}
CHK -->|없음| OK([통과])
CHK -->|있음| FIX[위반을 알리고 고치게 한다]
주입은 사전에 유도한다. 검사는 사후에 위반을 잡는다. 응답 자체를 사후 차단하지는 않는다.
규칙은 두 층위로 나뉜다. Rule 1은 이 플러그인이 한국어 본문에서 기계 검사 대상으로 정한 표기 패턴을 뜻한다. 플러그인은 세션이 시작될 때 Rule 1을 규칙으로 주입하고 파일을 저장할 때 위반을 검사한다. 문맥 판단 없이 검사할 수 있는 표기만 Rule 1에 넣는다. 형태론처럼 판단이 필요한 구성은 Rule 1에 넣지 않는다.
| 패턴 | 대신 |
|---|---|
| em dash(U+2014) 삽입구 | 쉼표, 괄호, 문장 분리 |
| 장식용 이모지 | 텍스트로 |
| 본문 속 세미콜론 | 마침표로 문장을 나눔 |
나머지 규칙은 판단이 필요하므로 스킬이 다룬다. 앞 단계에서 문제를 찾으면 그 단계에서 고치고 멈춘다.
| 단계 | 묻는 것 | 근거 |
|---|---|---|
| 0단계 목적 | 이 텍스트가 용어를 남길 곳인가, 뜻으로 되돌릴 곳인가 | Skopos 이론 |
| 1단계 뜻 | 여러 뜻 가운데 틀린 쪽을 골랐는가 | 어휘 의미 선택 |
| 2단계 상황 틀 | 이 동사가 부르는 틀이 대상과 맞는가 | 프레임 의미론 |
| 3단계 결합 | 한국어에서 실제로 이 결합을 쓰는가 | 연어·사용 기반 언어학 |
| 4단계 분류 | 무엇이 틀렸는지에 따라 어떤 교정을 하는가 | MQM 오류 차원 |
절차와 별개로 문장 층위 규칙 세 가지를 둔다.
| 규칙 | 다루는 것 |
|---|---|
| Rule 2 출발어 통사 간섭 | 연결어미 뒤 쉼표, 수동 직역, 과잉 명사화, -의 연쇄, 이중 조사, 대명사 반복 |
| Rule 3 문장 구조 | 내포와 삽입의 깊이, 쉼표로 이은 긴 절 |
| Rule 4 일관성·정직 | 존댓말 등급 일관, 날조 금지 |
전문은 skills/writing-korean/SKILL.md에 있다.
단계별 적용례는 examples.md에 있다.
원문이 없어도 출력에서 관찰되는 출발어 간섭은 다룬다. 다만 이 관찰만으로 실제 출발어를 확정하지는 않는다. 출발어 간섭으로 설명할 수 없는 일반 생성 결함을 포괄적으로 평가하지 않는다. v3.0.0에서 다음 항목을 폐기했다.
- 슬롭 어휘군, 형식명사, 문두 접속사, hedging, 균일한 문장 리듬
- 글 구성과 전개(장면 도입, 소제목 레지스터, 결론 응축)
- 서식과 강조 절제(볼드·불릿·괄호 병기·콜론 헤딩·분류사 앞 숫자 표기)
이 계열은 별도 지침으로 다루는 편이 맞다. 한 스킬에 섞으면 판정 기준이 둘로 갈려 어느 쪽도 제대로 작동하지 않는다.
훅은 fail-open으로 동작한다. 입력이 이상하거나 파일이 없으면 조용히 통과해 세션을 막지 않는다. 한글이 없는 파일과 코드 파일은 검사하지 않는다. Rule 1은 언어 일반의 문체 판정이 아니라 이 플러그인의 검사 정책이다. 한글 텍스트 문서에서 코드와 인용 블록 밖 본문에 위반이 있으면 고친다.
검사에서 제외하는 구간은 두 가지뿐이다.
- 코드: 펜스 블록과 인라인 코드
- 인용 블록:
>줄
인용은 원문을 그대로 실어야 하므로 검사에서 뺀다. 영어 논문 인용에는 세미콜론과 em dash가 정당하게 들어갈 수 있다. 이를 규칙에 맞춰 고치면 인용을 날조하게 된다.
파일 단위로 검사를 끄는 수단은 없다. 예외는 구간에만 적용한다. 인용을 담은 문서도 인용 밖 본문은 그대로 검사한다.
판정 절차의 각 단계는 번역학과 인지언어학의 1차 출처에 기댄다. 서지와 확인 범위는 theory-translation.md에 있다. 이 문서는 원문으로 확인한 내용과 확인하지 않은 내용까지 기록한다.
한국어 관련 수치는 3표 적대 검증을 통과한 딥리서치 결과와 1차 확인한 수치에만 기댄다.
- 작문 딥리서치 리포트: 번역투, 문장 구조, 한국어 실증
- 2차 보강 리포트: 한국어 관계절 실증, 이중 피동 빈도
- im-not-ai 갭 심사: 현재 Rule 2와 Rule 3에 남은 항목의 조사 이력, KatFishNet(ACL 2025) 수치 1차 확인 기록
3차 리포트는 글 구성, 주제문, 서식을 다뤘다. v3.0.0은 이 계열 규칙을 폐기했다. 따라서 3차 리포트는 현재 규칙의 근거에서 빠지고 조사 기록으로 남는다.
nvm use # Node 24 (.nvmrc)
node --test # 라이브러리·스킬 구조·훅 테스트규칙 본문은 skills/writing-korean/SKILL.md 한 곳에서만 고친다.
결정론 규칙 정규식을 바꾸면 Rule 1 표와 lib/prose-checks.js를 함께 맞춘다.
훅 주입 본문인 hooks/inject-rules.mjs도 손으로 맞춰야 하므로 함께 확인한다.
권위 버전은 .claude-plugin/plugin.json의 version이다.
package.json은 이 값을 미러링한다.
버전을 올릴 때마다 CHANGELOG.md 항목과 v{version} 태그를 남긴다.
라이선스는 MIT이며 LICENSE에서 전문을 확인할 수 있다. 문체 규칙의 귀속 고지는 NOTICE.md에 있다.