---
name: k-write
description: |
  한국어 산문(보고서, 공지, 제안서, 기획서, 소개글, 블로그, 이메일, 회고, 문서 초안)을 새로 쓰거나 다시 써야 할 때 사용한다.
  Claude는 자료 수집·구조 설계·사실 검증만 맡고, 실제 한국어 문장은 Antigravity CLI(agy)가 쓴다.
  트리거: "보고서 써줘", "글 써줘", "공지 작성해줘", "제안서 초안", "한국어로 정리해줘", "이 글 다시 써줘", "문장 다듬어줘".
  제외: 코드, 커밋 메시지, 로그·표만 있는 산출물, 짧은 대화 답변, 영어 문서.
argument-hint: "[--revise <파일>] [--out <파일>] [--length <글자수>] [--tone 합니다체|한다체|해요체] [--model <모델>] <무엇을 쓸지>"
allowed-tools:
  - Bash
  - Read
  - Write
  - Glob
  - Grep
  - AskUserQuestion
---

# k-write

한국어 문장 생성을 `agy`(Antigravity CLI)에 위임하는 스킬.

## 원칙

1. **Claude는 한국어 산문을 직접 쓰지 않는다.** 자료를 모으고, 구조를 짜고, 결과를 검증한다.
2. **agy가 쓴 문장을 Claude가 고쳐 쓰지 않는다.** 문제가 있으면 브리프를 고쳐 다시 호출한다. 허용되는 손질은 아래 "기계적 편집"뿐이다.
3. **agy는 브리프에 있는 사실만 쓴다.** 자료 수집 책임은 Claude에게 있다.

```
사용자 요청
  → Claude: 자료 수집 · 구조 설계 · 브리프 작성
    → agy CLI (gemini-3.1-pro-high): 한국어 본문 생성
      → Claude: 사실 대조 · 조립 · 저장
```

---

## 0. 적용 여부

산문이면 적용한다. 다음은 적용하지 않고 Claude가 그냥 처리한다.

- 코드, 설정 파일, 커밋 메시지, PR 제목
- 표·수치만 있는 산출물, 파일 목록
- 두세 문장짜리 대화 답변
- 영어 등 한국어가 아닌 문서

애매하면 적용한다. 사용자가 "네가 직접 써"라고 하면 적용하지 않는다.

## 1. 자료 수집

브리프에 넣을 사실을 먼저 확보한다. 여기가 Claude의 본업이다.

- 요청에 언급된 파일·디렉터리를 읽는다(Read/Glob/Grep).
- 대화 맥락에 이미 있는 수치·결정·일정을 끌어온다.
- 코드베이스가 근거면 실제로 확인한다. 추정으로 채우지 않는다.

**막히면 최소한만 묻는다.** 문서 종류·독자·분량·마감처럼 결과가 달라지는 항목만 AskUserQuestion으로 한 번에 묻는다. 톤이나 제목 같은 건 기본값으로 정하고 넘어간다.

기본값: 문서 종류는 요청에서 추론, 어미는 `합니다체`, 분량은 문서 종류 관행(공지 400자 / 보고서 1500자 / 제안서 3000자).

## 2. 브리프 작성

브리프는 **문장이 아니라 재료**다. Claude가 여기서 산문을 쓰면 스킬의 의미가 없다. 항목을 나열한다.

작업 디렉터리에 `.k-write/brief-<슬러그>.md`로 저장한다(없으면 만든다).

```markdown
<자료>
문서 종류: 팀 주간 보고 (마크다운)
독자: 팀장, 유관 부서 3명
분량: 1200자 내외
어미: 합니다체
목적: 이번 주 진행 상황과 다음 주 계획 공유

사실:
- 결제 모듈 리팩터링 완료, PR #412 머지 (7/25)
- 결제 실패율 2.1% → 0.4%
- 배포는 7/28 오전, 롤백 없음
- 다음 주: 정산 배치 이관, 담당 박준호
- 미해결: 환불 API 타임아웃, 원인 미확인

구조:
1. H1 제목
2. 요약 (3문장 이내, 불릿 금지)
3. H2 이번 주 진행 (불릿)
4. H2 다음 주 계획 (불릿)
5. H2 이슈 (미해결 항목만)

금지:
- 성과를 부풀리지 않는다. 원인 미확인 항목을 해결된 것처럼 쓰지 않는다.
</자료>
```

브리프 규칙:

- `<자료>` … `</자료>` 태그로 감싼다.
- **사실**은 검증된 것만. 불확실하면 `(미확인)`을 붙여 그대로 넘긴다.
- **구조**는 제목 단계까지 지정한다. 지정하지 않으면 agy가 마음대로 늘린다.
- **분량**은 공백 포함 글자 수로 적는다.
- 사용자가 준 원문·인용은 브리프에 그대로 넣는다. Claude가 요약해서 넘기지 않는다.
- 브리프 본문은 8,000자를 넘기지 않는다(명령줄 한도). 넘으면 3번의 섹션 분할로 간다.

## 3. 호출 계획

| 조건 | 방식 |
|------|------|
| 완성본 2,000자 이하 | 한 번에 호출 |
| 2,000자 초과, 또는 브리프가 8,000자 초과 | 섹션별로 나눠 호출 + `--conversation`으로 이어쓰기 |

섹션 분할 시:

1. 첫 호출: 공통 배경 + 첫 섹션 브리프 → 출력의 `CID=` 값을 받는다.
2. 이후 호출: `--conversation <CID>`. 지침과 공통 배경은 다시 보내지 않는다.
3. 각 브리프 첫 줄에 `이어서 같은 문서의 "<섹션명>" 섹션만 쓴다. 앞 섹션 내용을 되풀이하지 않는다.`를 넣는다.

## 4. agy 호출

스크립트 경로는 설치 방식에 따라 다르다. 아래 한 줄을 **매 호출마다 그대로** 쓴다(플러그인 설치와 로컬 스킬 설치 모두에서 동작한다).

```bash
KW="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/k-write}"; KW="${KW:-$HOME/.claude/skills/k-write}"; \
bash "$KW/scripts/agy-write.sh" \
  --brief .k-write/brief-weekly.md \
  --out   .k-write/sec-1.md
```

Bash 도구 `timeout`은 **300000ms(5분)** 로 준다. 섹션이 여러 개면 호출을 나눠 각각 5분을 준다.

옵션:

| 옵션 | 기본값 | 설명 |
|------|--------|------|
| `--brief <파일>` | (필수) | 브리프 경로 |
| `--out <파일>` | stdout | 결과 저장 경로 |
| `--conversation <CID>` | — | 이어쓰기. 지침 재전송 안 함 |
| `--model <이름>` | `gemini-3.1-pro-high` | `agy models`로 목록 확인 |
| `--style <파일\|none>` | `prompts/write.ko.md` | 지침 교체. 다시 쓰기는 `prompts/revise.ko.md` |
| `--timeout <기간>` | `300s` | agy print 타임아웃 |

stderr로 나오는 요약을 읽는다.

```
CID=b03776dc-...   ← 이어쓰기에 쓸 값
STATUS=SUCCESS
CHARS=337          ← 생성 글자 수(공백 포함, 개행 제외)
OUT=.k-write/sec-1.md
```

`CHARS`가 요청 분량의 ±15%를 벗어나면 브리프의 분량 줄을 고쳐 **다시 호출한다**. Claude가 늘리거나 줄이지 않는다.

## 5. 조립과 검증

섹션 파일을 순서대로 이어 붙여 최종 문서를 만든다. 그 다음 반드시 확인한다.

- [ ] 브리프에 없는 숫자·날짜·인명·기관명·링크가 들어갔는가 → 있으면 해당 문장 삭제 후 재호출
- [ ] 사실이 브리프와 어긋나는가 (수치 반올림, 날짜 바뀜 포함)
- [ ] `[확인 필요: …]` 표시가 남아 있는가 → 자료를 보강해 재호출하거나 사용자에게 묻는다
- [ ] 글 전체가 코드펜스로 감싸였는가 (스크립트가 벗기지만 재확인)
- [ ] `다음은 ~입니다` 같은 메타 문장, 인사말이 붙었는가
- [ ] 섹션 경계에서 같은 내용이 반복되는가
- [ ] 제목 단계(H1/H2)가 브리프 구조와 맞는가
- [ ] 어미가 문서 전체에서 하나로 통일됐는가

### 기계적 편집 (Claude가 해도 되는 것)

- 섹션 파일 이어 붙이기, 빈 줄 정리
- 제목 단계·번호 맞추기
- 메타 문장, 코드펜스, 인사말 삭제
- 중복 문단 삭제
- 브리프에 어긋나는 숫자·고유명사를 브리프 값으로 되돌리기
- 링크·파일 경로·코드 블록을 브리프 원본대로 교정

### 금지 (반드시 재호출)

- 문장 다시 쓰기, 표현 바꾸기, 어미 손보기
- 문단 새로 쓰기, 연결 문장 끼워 넣기
- 분량 맞추려고 내용 늘리거나 줄이기

## 6. 다시 쓰기 모드 (`--revise`)

기존 한국어 원고(사용자 초안, Claude가 예전에 쓴 글 포함)를 손볼 때.

```bash
# 브리프 = 요구사항 + 원고 전문
KW="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/k-write}"; KW="${KW:-$HOME/.claude/skills/k-write}"; \
bash "$KW/scripts/agy-write.sh" \
  --brief .k-write/brief-revise.md \
  --style "$KW/prompts/revise.ko.md" \
  --out   .k-write/revised.md
```

브리프 형식:

```markdown
<자료>
요구사항: 번역투와 AI 티를 걷어낸다. 구조와 사실은 그대로 둔다. 분량은 원고의 ±10%.
어미: 합니다체

원고:
(원고 전문을 그대로 붙여넣는다)
</자료>
```

원고가 8,000자를 넘으면 섹션 단위로 나눠 `--conversation`으로 이어서 처리한다. 결과는 원고와 **사실 대조**를 반드시 거친다(수치·고유명사가 바뀌는 사고가 가장 흔하다).

## 7. 보고

최종 파일을 저장한 뒤 이렇게 보고한다.

```
작성 완료 — <최종 파일 경로>
모델: gemini-3.1-pro-high | 호출: N회 | 분량: <글자 수>자 (요청 <요청>자)
검증: 브리프 대조 통과 / [확인 필요] N건
```

`[확인 필요]`가 남았으면 무엇이 빠졌는지 항목으로 알린다. 본문 전체를 대화창에 다시 붙여넣지 않는다. 사용자가 요청하면 Read로 보여준다.

## 에러 처리

| 증상 | 대응 |
|------|------|
| `ERROR: agy CLI를 찾을 수 없다` | Antigravity CLI 설치와 PATH 확인 안내. `C:\Users\<user>\AppData\Local\agy\bin` |
| `ERROR: 프롬프트 …바이트 … 한도 초과` | 브리프를 섹션으로 나눠 `--conversation`으로 이어 호출 |
| `ERROR: agy가 권한 문제로 응답을 내지 못했다` 또는 `빈 응답을 냈다` | 브리프에 파일을 읽거나 명령을 실행하라는 지시가 있다. 자료를 브리프 안에 직접 넣는다 |
| `STATUS` 가 `SUCCESS`가 아님 | 원문 메시지를 그대로 사용자에게 전달. 모델을 `gemini-3.1-pro-low`로 낮춰 재시도 |
| 5분 타임아웃 | 섹션을 더 잘게 나눈다. 또는 `--model gemini-3.6-flash-high` |
| 응답이 영어로 나옴 | 브리프 첫 줄에 `한국어로만 쓴다`를 추가해 재호출 |

## 규칙 요약

- 한국어 산문은 agy가 쓴다. Claude는 재료와 검증을 맡는다.
- 결과가 마음에 안 들면 브리프를 고쳐 다시 호출한다. 문장을 직접 손보지 않는다.
- 브리프에 없는 사실이 나오면 삭제하거나 재호출한다.
- 브리프와 결과는 `.k-write/`에 남겨 재호출·비교에 쓴다.