polish git:20261001.4223847A

Immutable. This exact content never changes and is served at /api/v1/blob/7dc2dd34b4ed5f40.

---
name: polish
description: 한국어 텍스트에서 어색하고 장황한 표현을 찾아 자연스러운 문장으로 고칠 것을 제안한다. 사용자가 "/polish", "$polish", "윤문", "윤문 검증", "이 문서 다듬어줘", "어색한 표현 찾아줘"를 요청할 때, 한국어 문서·PR 본문·테이블 comment 를 작성한 직후 셀프 체크할 때, CI 에서 PR 리뷰 코멘트를 생성할 때 사용한다. 압축 조어·은유 설계 문장·명사 나열 직역투·발음만 한글로 옮겨 적은 영어 표기를 찾아 수정을 제안한다.
---

# polish: 한국어 윤문 검증

한국어 텍스트에서 어색하고 장황한 표현을 찾아 자연스러운 문장으로 고칠 것을 제안한다. 룰 본문은 이 문서에 두지 않으므로, 아래 절차로 룰 파일을 로드해 그 시점의 최신 룰로 검증한다. Claude Code 와 Codex 에 같은 파일이 설치되며, 두 클라이언트에서 같은 절차를 따른다.

## 1. 룰 로드와 병합

아래 순서로 로드해 병합한다. 항목은 합집합으로 합치고, 같은 항목이 충돌하면(예: 기본 룰의 금지어를 프로젝트가 허용) 나중에 로드된 쪽이 이긴다.

1. 플러그인 내장 `default-rules.md` (이 SKILL.md 와 같은 디렉토리): 항상 베이스
2. 개인 `~/.agents/better-korean-rules.md`: 있으면 병합
3. 프로젝트 `<repo root>/.agents/better-korean-rules.md`: 있으면 병합 (개인 룰보다 우선)

`.agents/` 는 클라이언트에 종속되지 않는 위치라서 Claude Code 와 Codex 가 같은 룰 파일을 읽는다. `~/.claude/better-korean-rules.md` 나 `<repo root>/.claude/better-korean-rules.md` 가 있으면 읽지 않고, 보고서 머리에 "`.agents/` 로 옮기세요" 경고를 낸다. 같은 파일을 두 곳에 두면 한쪽만 갱신되어 클라이언트마다 결과가 달라지므로, 두 경로를 모두 읽지 않는다.

프로젝트·개인 룰 파일에는 예외 선언을 둘 수 있다 (예: "이 프로젝트에서는 `감사`(audit) 허용"). 보고서 머리에 어떤 룰 소스들이 로드됐는지 명시한다.

## 2. 검증 대상 결정

- **인자로 파일 경로가 오면** 그 파일 전체.
- **인자가 없으면** `git diff HEAD`(스테이징 포함)에서 **추가된 텍스트 줄**만. 대상이 없으면 사용자에게 무엇을 검증할지 묻는다.
- **셀프 체크**: 문서·PR 본문·comment 를 작성한 직후라면, 방금 작성한 산출물을 대상으로 같은 절차를 수행한다.

문서 본문, 주석, comment, PR 본문처럼 사람이 문장으로 읽는 한국어 텍스트를 검증하고, 코드 블록 내부와 식별자, URL 은 제외한다. 룰 파일 자체(`default-rules.md`, `summary-rules.md`, `better-korean-rules.md`, `better-korean-summary.md`)와 AGENTS.md 의 better-korean 블록은 금지어를 이름으로 부르는 글이므로 검증 대상에서 제외한다.

## 3. 두 패스 검증

### grep 패스 (확정 위반)

이 스킬 디렉토리의 `scripts/grep-pass.sh` 를 `scripts/grep-pass.sh <룰 파일...> -- <대상 파일...>` 로 실행하면 코드 블록을 제외한 후보 목록이 나온다. 이 스크립트는 병합된 룰의 「금지어 목록」에서 `금지어 → "대체 표현"` 쌍을 파싱해 대상 텍스트를 검색한다. 스크립트를 실행할 수 없으면 같은 절차(금지어 쌍을 파싱한 뒤 코드 블록을 제외하고 검색)를 직접 수행한다.

- 히트마다 예외 조항(이미 익숙하게 널리 쓰이는 단어, `[미확인]`/`[추정]` 마커, 식별자 안의 부분 문자열)에 해당하는지 확인하고, 해당하면 버린다.
- 남은 건마다 `위치(file:line) / 금지어 / 대체 제안` 을 기록하고, 대체 제안은 룰의 대체 표현을 해당 문장에 맞게 활용한 완성 문장으로 쓴다.

### 판독 패스 (LLM 판단)

병합된 룰의 「패턴 룰」을 기준으로 대상 텍스트를 문단 단위로 판단한다. 은유로 압축한 설계 문장, 명사 나열식 직역투, 정의 없이 등장한 새 용어, "관측"이 문맥에 맞는지, 목록에 없는 압축 조어 신조어, "박다" 계열, 한자 혼용이 판단 대상이다.

- 건마다 `위치 / 위반 룰 / 근거(왜 위반인지 한 문장) / 수정 제안 문장` 을 기록한다.
- 확신이 낮은 건은 버리지 말고 "판단 필요" 표시로 남긴다 (최종 판정은 작성자의 몫이다).

## 4. 보고

### 대화형 (채팅)

머리에 로드된 룰 소스를 밝히고 `위치 | 층(grep/판독) | 위반 룰 | 수정 제안` 표로 보고한다. 수정 적용은 사용자 확인 후에만 한다.

### CI (PR 리뷰)

개별 코멘트를 낱개로 달지 않고, **인라인 코멘트 전체와 최종 요약을 하나의 리뷰 세션(pull request review)으로 묶어 한 번에 제출**한다 (`gh api repos/{owner}/{repo}/pulls/{n}/reviews` 에 `comments[]` 와 `body` 를 함께 전달, `event: COMMENT`).

- 인라인 코멘트 중 grep 패스 확정 위반은 GitHub suggestion 블록으로 달아 원클릭 적용이 가능하게 한다.
- 인라인 코멘트 중 판독 패스 위반은 근거와 제안 문장을 포함해 단다.
- 리뷰 본문(요약)에는 어떤 룰 위반이 몇 건 발견되어 무엇을 제안했는지 간단히 적고, **작성자의 판단이 필요한 항목**(판독 패스에서 확신이 낮은 건, suggestion 으로 확정하지 못한 건)은 별도 목록으로 명시한다.
- CI 를 실패시키지 않도록 항상 exit 0 으로 끝낸다.

## 5. 작성 시점에 룰을 적용하는 설정 (선택)

검증은 설치만 하면 동작하지만, 글을 쓰는 시점부터 룰을 적용하려면 세션마다 룰이 지침으로 주입되어야 한다. 주입에는 요약본을 쓴다. 전체 룰은 금지어별 대체 표현까지 들어 있어 세션당 수천 토큰을 쓰므로, 작성 시점에는 원칙만 추린 요약본을 주입하고 대체 표현은 검증 시점에 전체 룰로 확인한다.

요약본도 전체 룰과 같은 순서로 병합한다.

1. 플러그인 내장 `summary-rules.md` (이 SKILL.md 와 같은 디렉토리)
2. 개인 `~/.agents/better-korean-summary.md`: 있으면 뒤에 이어 붙임
3. 프로젝트 `<repo root>/.agents/better-korean-summary.md`: 있으면 뒤에 이어 붙임

주입은 지침 파일 안의 생성 블록으로 한다. 이 스킬 디렉토리의 `scripts/sync-rules-block.sh <지침 파일> <요약본...>` 을 실행하면 지침 파일 안의 `<!-- better-korean:begin -->` … `<!-- better-korean:end -->` 블록이 병합된 요약본으로 갱신되고, 블록이 없으면 끝에 추가되며, 블록 밖은 바뀌지 않는다. 플러그인 내장 요약본은 설치 위치가 버전마다 달라 import 로 가리킬 수 없고, Codex 의 AGENTS.md 는 import 문법 자체가 없으므로, 두 클라이언트 모두 같은 방식을 쓴다.

- **Claude Code**: 대상은 프로젝트 CLAUDE.md 또는 개인 `~/.claude/CLAUDE.md`.
- **Codex**: 대상은 레포 AGENTS.md 또는 글로벌 `~/.codex/AGENTS.md`. Codex 는 두 파일을 합쳐 기본 32 KiB(`project_doc_max_bytes`)까지만 읽으므로 블록은 한쪽에만 두고, 스크립트가 출력하는 크기 경고를 확인한다.

설정은 사용자가 고르는 것이며, 설치나 스킬 실행이 사용자의 CLAUDE.md·AGENTS.md 를 자동으로 수정하지 않는다. 이 스킬을 한 레포에서 처음 실행했을 때 현재 클라이언트의 지침 파일에 블록이 없으면, 보고 끝에 "작성 시점에도 룰을 적용하도록 CLAUDE.md(또는 AGENTS.md)에 요약 룰 블록을 넣을까요?"라고 한 번 묻고, 동의할 때만 스크립트를 실행한다. 사용자가 거절하면 그 레포에서 다시 묻지 않는다.

## 6. 룰을 계속 추가하는 피드백 루프

룰 파일은 `.agents/` 하위에 있어 눈에 덜 띄고 갱신을 잊기 쉬운데, 룰 리스트를 계속 늘려 가는 것이 이 플러그인 운영의 핵심이므로 스킬이 그 일을 챙긴다.

- **세션 중 사용자가 표현을 정정하면**(예: "이 단어 어색해", "이렇게 바꿔줘") 이 스킬의 검증 결과에 대한 반응이든 일반 대화 중이든 "이 항목을 윤문 룰 리스트에 추가할까요?"라고 묻는다.
- 추가처는 두 갈래로 제안한다. **프로젝트 룰**(`.agents/better-korean-rules.md`, 팀과 공유)이나 **개인 룰**(`~/.agents/better-korean-rules.md`, 모든 프로젝트에서 사용) 중 하나이고, 파일이 없으면 만들면서 형식(default-rules.md 와 같은 구조)을 갖춘다.
- 추가할 항목은 grep 으로 검색되는 `금지어 → "대체 표현"` 형식이 우선이고, 패턴으로 반복될 정정이면 「패턴 룰」에 문장으로 추가한다.
- 요약본에도 반영할지 함께 판단한다. 금지어 한 단어 추가는 요약본에 넣지 않고, 새 패턴 룰이나 새 금지어 범주처럼 글을 쓰는 시점에 알아야 할 원칙이면 같은 스코프의 요약본(`better-korean-summary.md`)에 한 줄로 추가할지 묻는다.
- 요약본이 바뀌었고 AGENTS.md 에 better-korean 블록이 있으면, `scripts/sync-rules-block.sh` 를 다시 실행해 블록을 갱신할지 묻는다.