tone-fix

한국어 문서, 인포그래픽, 강의자료, 슬라이드 덱, 보고서의 AI 말투와 번역체를 걷어내고, 구조를 세우고, 훑어 읽히게 만드는 스킬. Agent Skills 표준을 따르는 SKILL.md 패키지이며, Claude Code 플러그인으로도 동작한다.

AI 가 쓴 한국어 문서는 첫 화면에서 드러난다. 제목이 질문으로 운을 떼고, 본문이 "저희"로 방어하고, 결론이 "A 가 아니라 B 다"로 힘을 준다.

어휘를 고쳐도 남는 문제가 있다. 요약이 본문의 압축본이고, 왜 이 글을 쓰는지가 없고, L0~L5 같은 코드가 정의 없이 돌아다니고, 문단이 7문장씩 이어진다.

이 스킬은 그 신호를 규칙 30절로 정의하고 세 단계로 걷어낸다.

어휘, 패턴은 스캐너로, 문장, 구조는 판별법으로, 가독성은 검출기로 0건이 될 때까지 교정한다.

Before / After

자리	❌ AI 말투	✅ 교정
제목	데이터, 어떻게 봐야 할까	데이터 품질 점검 우선순위
부제	게임에 외부 SDK를 붙이는 작업은 6 단계로 진행한다	게임에 외부 SDK를 붙이는 6 단계
리드	이 과정을 통해 전체 그림을 이해한다	(삭제)
본문	저희가 통제할 수 없는 일정	외부 일정 의존
본문	내장(embedded) 미디에이터 지원 추가 작업 진행 중	지원 개발 진행 중
본문	강한 스키마 규약 — 기능 1건에 4곳 수정	강한 스키마 규약 탓에 기능 1건에 4곳 수정이 필요
결론	중요한 것은 속도가 아니라 정확도다	정확도가 우선이다
알림	#6~8 이 6/10부터 발화했다	#6~8 이 6/10부터 트리거되었다
계층	모델 종속 nudge 는 L4 어댑터 계층에만	모델 종속 조정 문구는 4단계 모델 어댑터 파일에만
근거	증거가 실무·연구 양쪽에서 수렴한다	근거 두 가지: 실무 보고 A, 연구 B
리드	문제는 두 벤더 가이드가 정반대 조정을 요구한다는 점이다.	두 벤더 가이드는 정반대 조정을 요구한다.
리드	이 문서가 답하는 질문은 세 가지다.	소제목 "모델 교체 문제의 해법 세 가지" + 목록
리드	워크플로우를 6단계로 나누고 모델 의존은 4단계에만 둔다.	워크플로우 6단계. 모델 의존은 4단계 어댑터에만 둔다.
리드	Codex 등가물은 codex exec다.	Codex 등가물 codex exec
번역투	레거시 명령이 은퇴했다	레거시 command 가 deprecated 되었다
리드	Orca 는 experimental 이고 레거시 명령은 deprecated 되어 효과가 없다.	Orca 오케스트레이션은 experimental 이다. ↵ 레거시 명령은 deprecated 되어 효과가 없다.
비교	결함을 더 잡는다	결함을 더 많이 잡는다
의인화	이 문서는 고정할 부분과 갈아 끼울 부분의 경계에 답한다	대상: 고정 범위와 변경 범위의 경계
배치	핵심 문장. 부연 부연 부연	핵심 문장. ↵ (빈 줄) ↵ 부연 부연 부연
요약	훅 없이 본문을 압축한 282자 항목	모델이 바뀔 때 고칠 파일을 하나로 줄인다. + 뒷받침 2문장
리드	Orca (onorca.dev) — Orca 는 ADE 로 …	Orca 는 CLI 에이전트 25종을 격리 worktree 에서 병렬 실행한다.
카드	정보가 제한적. 주요 사업 정보가 전달되지 않음.	정보가 제한적.<br>주요 사업 정보가 전달되지 않음.
스펙	θ 를 넘으면 트리거. 기본 θ 15%	θ 를 넘으면 트리거, 기본 θ 15%
나열	CLAUDE.md·AGENTS.md·skill 파일	CLAUDE.md, AGENTS.md, skill 파일
제목	배경 — 모델 교체마다 반복되는 재작성	배경: 모델 교체마다 반복되는 재작성
제목	결정을 바꾸는 임계치	판단 기준
부연	(정의 표 뒤) 5절의 레이아웃이 이 표의 단계 이름을 쓴다	(삭제)
어휘	단순 임계 알람은 소음이 된다	단순 임계 알람은 노이즈가 된다
어휘	백데이터 원천 / LTV 지평	백데이터 출처 / LTV horizon
목록 도입	소음의 원천은 셋이다. + 목록	노이즈의 세 가지 원인 + 목록

3단계 파이프라인

단계	성격	잡는 것	도구	통과 기준
1단계 패턴 스캔	결정론적	1인칭, 가정형, 상투 제목, 수사의문문, 본문 대시, 발화, ~가 아니라, L0~L5, 근거가 수렴, 문제는 ~는 점이다, 은퇴, 더 잡는다, ~은 셋이다, 소음, 원천, —, · 등 27종	scripts/check_lexical.py	hits: 0
2a단계 문장, 어휘	맥락 판단	미확정 단정, 동의어 중복, 의인화, 구어 어휘	규칙표 판별법	판별법 통과
2b단계 문단, 구조	맥락 판단	요약 훅, 문제제기 절, 단계 정의 표, 절 첫 문장, 목록 도입 명사구	규칙표 판별법	판별법 통과
3단계 가독성	결정론적 + 판단	키프레임 공백, 문단 길이, 볼드 남발, 리드 뒤 줄바꿈, 문장 경계 <br>	scripts/check_md_layout.py, scripts/check_br.py	violations: 0

마지막에 1단계를 다시 돌린다. 2, 3단계 재작성이 새 위반을 만들 수 있다.

What It Catches

규칙 30절을 독자 관점에서 묶은 여섯 갈래.

갈래	신호	교정	규칙
제목, 부제	왜 중요한가 / 한눈에 / ~란? / 이 덱의 구성	명사구로 대상, 결론을 직접 명시	§8, §8.1, §8.3
어조, 주어	우리는 5/29 까지 해결합니다	차주(5/29) 해결 예정입니다	§1, §2, §3, §6, §7
사실 범위	지연될 수 있습니다 / 곧 출시 / 그 외 ~도 ~한다	소스에 있는 사실까지만	§4, §8.2, §8.4
어휘, 번역투	캠페인을 띄운다 / 발화율 65% / L4 계층 / 근거가 수렴한다 / 문제는 ~는 점이다 / 명령이 은퇴했다 / 더 잡는다 / 알람이 소음이 된다	노출한다 / 트리거율 65% / 4단계 어댑터 / 근거 두 가지: A, B / 주장만 / deprecated 되었다 / 더 많이 잡는다 / 노이즈가 된다	§8.3, §8.5, §8.6, §8.8~§8.16
문단, 구조	압축본 요약 / 동기 없는 발견 나열 / 정의 없는 N단계 / 원인은 셋이다 + 목록	훅 + 뒷받침 / 배경 절 / 단계 정의 표 / 노이즈의 세 가지 원인 + 목록	§10
가독성	7문장 문단 / 라벨 볼드 / 리드와 부연이 같은 줄 / 카드에서 둘째 문장이 꺾임	3문장 분할 / 판정 문장 볼드 / 리드 뒤 줄바꿈 / 문장 경계 <br>	§9, §11

How It Checks

말투 교정을 감으로 끝내지 않는다. 스크립트 셋이 단계별 관문이다.

• check_lexical.py: 어휘 신호 27종을 정규식으로 잡는다. --honorific 은 존대 문서에서 평어체 잔존을 추가로 잡는다.
• check_md_layout.py: MD 의 볼드 리드 프레임, 두 절 리드, 리드 뒤 같은 줄 부연, 요약 항목, 문제제기 절, 단계 정의, 목록 앞 개수 예고 문장, 키프레임 공백, 문단 길이, 볼드 남발을 잡고, X는 Y다 복사 구조 리드는 advisories: 로 따로 센다.
• check_br.py: HTML 좁은 블록과 innerHTML 주입 문자열에서 문장 경계 <br> 누락을 잡는다.

모두 python3 표준 라이브러리만 쓴다. 스크립트 0건은 필요조건이다. 미확정 단정, 동의어 중복, 절 첫 문장 같은 판단 규칙은 판별법으로 확인하고 보고에 남긴다.

규칙은 실제 리뷰에서 나온 지적을 옮긴 것이다. 예: "발화라는 단어 금지. 전형적인 AI 표현.", "사람은 근거를 수렴한다고 표현하지 않는다.", "XX 가 답하는 질문은 XX 가지다 → 사람은 이런 표현을 안 써.", "소음이라는 직역보다는 노이즈가 자연스럽다."

Usage

문서, 덱, 인포그래픽, 보고서를 작성, 마무리하는 단계에서 자동으로 활성화된다. 다음과 같은 요청으로도 트리거된다.

"이 문서 AI 말투 좀 고쳐줘"
"제목을 명사구로 바꿔줘"
"번역체 제거해줘"
"이 보고서 가독성 개선해줘"

수동 점검:

python3 scripts/check_lexical.py report.md
python3 scripts/check_md_layout.py report.md
python3 scripts/check_br.py deck.html

Installation

Claude Code 플러그인으로

claude plugin marketplace add bahamoth/cc-marketplace
claude plugin install tone-fix

또는 이 레포를 직접 추가:

claude plugin add bahamoth/tone-fix

Agent Skill 로 (다른 에이전트)

에이전트의 스킬 디렉토리에 클론한다. 경로는 도구마다 다르다. Codex CLI 는 ~/.agents/skills/(개인) 또는 .agents/skills/(프로젝트).

git clone https://github.com/bahamoth/tone-fix ~/.agents/skills/tone-fix

Out of Scope

• 문장의 의미나 사실 내용을 바꾸지 않는다. 사실의 범위를 소스가 확인한 곳까지 좁힐 뿐이다.
• 맞춤법, 띄어쓰기 전반을 교정하는 도구가 아니다.
• 업계 표준 계층 용어(OSI L7, 알림 등급 L1/L2)와 통계의 수렴은 교정 대상이 아니다.
• 영어 인용문 안의 retired, kill 같은 원어 표현은 그대로 둔다.
• 한자어가 현장 어휘인 용어(임계, 기준선, 지출, 노출)는 외래어로 되돌리지 않는다.

Rules

• SKILL.md: 핵심 원칙, 3단계 파이프라인, 마무리 보고 형식
• references/tone-rules.md: 규칙 30절 전문, ❌→✅ 대조표, 판별법, 점검 스크립트 안내
• scripts/: check_lexical.py, check_md_layout.py, check_br.py
• evals/evals.json: eval 5건 (HTML 카드 3건, MD 보고서 1건, MD intent 문서 1건)
• CHANGELOG.md: 규칙 추가 이력