translate-writer

name	translate-writer
description	영어 기술 블로그/문서를 고품질 한국어 블로그 포스트로 변환하는 전문 번역 파이프라인. 이 스킬은 단순히 텍스트를 번역하는 것이 아니라, 저자의 스타일을 학습하고 6개 전문 에이전트(번역기, 번역투 리뷰어, 원문 충실도 검증기, 문장 polish 등)가 협업하여 출판 수준의 번역을 생성합니다. 사용자가 영어 글을 번역하거나 한국어로 옮기고 싶다고 하면 반드시 이 스킬을 사용하세요. URL이나 파일 경로를 주며 번역을 요청하는 경우, "번역해줘", "한국어로", "translate", "번역 블로그", "옮겨줘", "영어 글" 등의 키워드가 포함된 경우 모두 해당합니다. 직접 번역하지 말고 반드시 이 스킬을 호출하세요 — 직접 번역은 스타일 가이드, 용어집, 이중 검증을 활용할 수 없어 품질이 크게 떨어집니다.
argument-hint	<URL 또는 파일경로> [--mode=quick|thorough|perfect] [--analyze] [--skip-review]
allowed-tools	["Read","Write","Edit","Bash","Glob","TodoWrite","Task","AskUserQuestion","WebFetch"]

번역 글쓰기 에이전트 시스템

6개의 전문 에이전트가 협업하여 자연스러운 한국어 번역을 생성합니다.

사용자 요청 (URL/파일) [--mode=quick|thorough|perfect]
  → 오케스트레이터(메인 루프): 인자 파싱·점수 판정·게이트·Edit 적용·보고 전담 — 직접 번역/채점 금지
  → Phase 0: 스타일 가이드 확인 (없으면 translation-style-analyzer 호출)
  → Phase 1: 번역 (content-translator, 스타일 가이드 + 용어집 참조)
  → Phase 2: 이중 검증 (Task 병렬, 최대 3회 반복)
      ├─ translation-reviewer (한국어 품질, 28개 패턴)
      └─ translation-verifier (원문 충실도, T1~T10)
      미달 시 → content-translator에 수정 지시 → 재검증 (3회 미달 시 ✋ GATE 0)
  → Phase 3: Polish 정밀 다듬기 [quick: 건너뛰기]
      polish-agent batch 분석 → 기준 미만 필터링 → ✋ GATE 1 → 순차 개선 (batch 옵션 재사용)
  → Phase 4: ✋ GATE 2 — 사용자 최종 결정
      ✅ 승인 → Phase 5 | 📝 수정 → Phase 1 | 🔧 다듬기 → Phase 3 | ❌ 거절 → 종료
  → Phase 5: 저장 및 학습 (translation-learner)

---

모드별 동작

모드	검토 기준	Polish	소요 시간	용도
--mode=quick	8점	건너뛰기	5-10분	빠른 참고용
--mode=thorough (기본)	8점	9.5점 미만만	15-20분	일반 블로그
--mode=perfect	9점	9.8점 미만 전체	30분+	중요 문서

---

오케스트레이션 원칙

이 스킬은 오케스트레이터-워커 구조로 실행합니다. 메인 루프(Opus 등 상위 모델)는 아래 3원칙을 지키세요.

1. 메인 루프는 오케스트레이션 전용 — 번역·검토·다듬기 결과물을 직접 생성하거나 채점하지 않습니다. 인자 파싱, Task 호출, 점수 판정(에이전트가 보고한 차원 점수에 하드 임계값 규칙 적용), 게이트(AskUserQuestion), 사용자가 선택한 개선안의 Edit 적용, 결과 보고만 수행합니다.
2. 콘텐츠 작업은 전담 서브 에이전트가 수행 — 각 에이전트의 모델은 .claude/agents/ frontmatter의 별칭(haiku|sonnet|opus)을 따릅니다. 메인 루프가 에이전트 대신 번역하거나 점수를 만들어내는 것은 금지입니다.
3. 독립 작업은 병렬로 — Phase 2의 reviewer·verifier처럼 서로 의존하지 않는 Task는 한 메시지에서 동시에 호출합니다.

• ✋ GATE는 항상 메인 루프에서 AskUserQuestion으로 진행합니다.
• 하네스에 따라 Task 도구가 Agent라는 이름으로 노출될 수 있습니다. 같은 도구입니다.

---

현재 스타일 가이드 상태

@.claude/skills/translate-writer/data/style-guide.md

용어집

@.claude/skills/translate-writer/data/glossary.md

최근 피드백

!tail -30 .claude/skills/translate-writer/data/feedback-log.md 2>/dev/null || echo "피드백 로그 없음"

샘플 번역 목록

!ls -la .claude/skills/translate-writer/data/samples/ 2>/dev/null || echo "샘플 없음 - 초기 분석 필요"

---

작업

"$ARGUMENTS" 를 한국어로 번역하세요.

모드 파싱

1. 인자에서 --mode= 추출 (없으면 thorough)
2. 모드별 설정값 적용:
   • quick: review_threshold=8, skip_polish=true
   • thorough: review_threshold=8, polish_threshold=9.5
   • perfect: review_threshold=9, polish_threshold=9.8

실행 단계

Phase 0: 스타일 가이드 확인

1. .claude/skills/translate-writer/data/style-guide.md 읽기
2. [분석 필요] 문자열이 많으면 → 먼저 Task 도구로 스타일 분석 실행:
   • subagent_type: translation-style-analyzer
3. 용어집 확인: .claude/skills/translate-writer/data/glossary.md
4. 스타일 가이드가 준비되면 Phase 1로 진행

translation-style-analyzer 호출 조건:

• style-guide.md에 [분석 필요]가 3개 이상
• --analyze 옵션 사용 시
• samples/ 폴더에 새 파일 추가 후

Phase 1: 번역 (content-translator)

Task 도구로 호출:

- subagent_type: "content-translator"
- prompt에 포함:
  - 입력: [URL 또는 파일 경로]
  - 스타일 가이드 경로: .claude/skills/translate-writer/data/style-guide.md
  - 용어집 경로: .claude/skills/translate-writer/data/glossary.md
  - 번역 생성 및 반환

URL인 경우: WebFetch로 원문 수집 파일인 경우: Read로 파일 읽기

시리즈 자동 감지 (Phase 1 추가)

번역 전 시리즈 여부를 자동으로 확인합니다:

1. URL 패턴 매칭

   • claude.com/blog/* → series: "Claude 공식 블로그 번역"
   • 시리즈 목록: @.claude/skills/translate-writer/data/series.md 참조

2. Frontmatter에 추가

   • 시리즈가 감지되면 Frontmatter에 series 필드 자동 추가

   series: "Claude 공식 블로그 번역"  # URL 패턴 매칭 시
   

3. 감지 실패 시

   • 시리즈 필드 생략 (기존 동작 유지)

Phase 2: 이중 검증 (reviewer + verifier 병렬)

병렬 실행: 두 에이전트를 Task 도구로 동시에 호출합니다.

반복 (최대 3회):
  1. 병렬 실행 — Task 두 건을 한 메시지에서 동시 호출:
     - Task(subagent_type: "translation-reviewer"): 한국어 품질 평가 (4차원 가중치 채점)
       → 자연스러움(40%), 어휘(25%), 흐름(20%), 개발자맥락(15%)
       → 각 차원별 하드 임계값 적용
     - Task(subagent_type: "translation-verifier"): 원문 충실도 평가 (3차원 가중치 채점)
       → 의미 정확성(50%), 기술 정확성(30%), 뉘앙스(20%)
       → 각 차원별 하드 임계값 적용
       (원문 URL/파일 + 번역 파일 모두 전달)
       ⚠️ URL인 경우 반드시 원본 URL을 함께 전달할 것

  2. 결과 판정 (차원별 하드 임계값 + 종합 점수):
     통과 조건:
       - reviewer: 4개 차원 모두 하드 임계값 통과 AND 종합 >= 기준
       - verifier: 3개 차원 모두 하드 임계값 통과 AND 종합 >= 기준

     미달 시 → 구조화된 수정 지시 전달:
       미달 차원만 추출하여 translator에게 전달:
       "자연스러움 차원 5/10 미달(임계값 6). 패턴 #3 수동태 3건, #4 지시대명사 2건 수정."
       "의미 정확성 차원 6/10 미달(임계값 7). T3 왜곡 1건(Line 42) 수정."

루프 조건 (차원별 하드 임계값 + 종합 점수):

• quick: reviewer 종합 8점+ & verifier 종합 8점+ & 모든 차원 하드 임계값 통과, 또는 3회 완료
• thorough: reviewer 종합 8점+ & verifier 종합 8점+ & 모든 차원 하드 임계값 통과, 또는 3회 완료
• perfect: reviewer 종합 9점+ & verifier 종합 9점+ & 모든 차원 하드 임계값 통과, 또는 3회 완료

하드 임계값: 어떤 차원이든 하나라도 미달이면, 종합 점수가 기준 이상이어도 FAIL.

3회 수정 후에도 기준 미만 — ✋ GATE 0 — AskUserQuestion (조건부):

• 사용자에게 상황 보고
• 각 에이전트의 차원별 점수와 하드 임계값 통과 여부 안내
• 어떤 차원이 반복적으로 미달인지 명시
• 계속 진행할지 사용자 결정

Phase 3: Polish 정밀 다듬기

quick 모드: 이 단계 건너뛰기 → Phase 4로

thorough/perfect 모드 — /polish-file 스킬의 로직을 따릅니다:

1. 문장별 분석: /polish-file의 Step 1-2와 동일 — polish-agent batch Task 호출로 문장별 점수·패턴·개선 옵션을 수집
2. 필터링: 기준 점수 미만 문장만 선택 (thorough: 9.5, perfect: 9.8)
3. ✋ GATE 1 — AskUserQuestion: "N개 문장 다듬기 진행?" (지금 다듬기 / 나중에 / 건너뛰기)
4. 순차 개선: Step 1의 batch 분석이 반환한 개선 옵션을 재사용해 문장별로 제시(AskUserQuestion, 옵션 포맷은 /polish 스킬 참조) → 선택 적용(Edit). 파일이 그 사이 수정됐거나 사용자가 재분석을 요청한 문장만 polish-agent를 다시 호출
5. JSON 리포트 저장: .claude/polish-reports/[slug]-[timestamp].json

상세 로직: /polish-file 스킬 참조, 개별 문장 다듬기: /polish 스킬 참조

Phase 4: 사용자 최종 결정

✋ GATE 2 — AskUserQuestion: 게이트에서는 AskUserQuestion 호출 없이 다음 Phase로 진행하지 마세요.

AskUserQuestion으로 사용자에게 질문:

## 번역 검토

**원문**: [원문 제목]
**번역 제목**: [한글 제목]
**모드**: [quick|thorough|perfect]

### Reviewer (한국어 품질)
| 차원 | 점수 | 임계값 | 통과 |
|------|------|--------|------|
| 자연스러움 | X/10 | ≥6 | ✅/❌ |
| 어휘 정확성 | X/10 | ≥6 | ✅/❌ |
| 흐름/연결 | X/10 | ≥6 | ✅/❌ |
| 개발자 맥락 | X/10 | ≥7 | ✅/❌ |
| **종합** | **X/10** | | |

### Verifier (원문 충실도)
| 차원 | 점수 | 임계값 | 통과 |
|------|------|--------|------|
| 의미 정확성 | X/10 | ≥7 | ✅/❌ |
| 기술 정확성 | X/10 | ≥8 | ✅/❌ |
| 뉘앙스 보존 | X/10 | ≥6 | ✅/❌ |
| **종합** | **X/10** | | |

**Polish**: [완료/건너뜀/N개 개선]

---

이 번역을 어떻게 처리할까요?

1. ✅ 승인 - 이대로 저장
2. 📝 수정 요청 - 피드백 입력 후 재번역 (체감 점수 1-10 선택사항)
3. 🔧 추가 다듬기 - Phase 3으로 돌아가기
4. ❌ 거절 - 폐기 (체감 점수 1-10 선택사항)

수정/거절 시 체감 점수 수집: 사용자가 📝 또는 ❌ 선택 시 "1-10점으로 이 번역의 품질을 평가해주세요 (선택사항)"을 추가로 물어봅니다. 이 점수는 calibration divergence 측정에 사용됩니다.

사용자 선택에 따른 처리:

선택	처리
✅ 승인	Phase 5로
📝 수정	피드백 받기 → Phase 1로
🔧 추가 다듬기	Phase 3으로
❌ 거절	translation-learner (부정) → 종료

Phase 5: 저장 및 학습 (translation-learner)

학습 단계는 Task 도구로 호출: subagent_type: translation-learner (승인/거절 여부와 사용자 피드백을 prompt에 포함)

승인된 경우:

1. contents/blog/translation/[slug]/index.md 저장
2. approved-posts/에 백업 저장
3. samples/에 심링크 추가 (ln -s ../approved-posts/<파일명> .) — style-analyzer가 승인된 스타일을 학습
   • Windows에서 ln -s가 복사본을 만들거나 실패하면: git update-index --add --cacheinfo 120000,$(echo -n "../approved-posts/<파일명>" | git hash-object -w --stdin),.claude/skills/translate-writer/data/samples/<파일명> 으로 git 심링크를 직접 등록하고, git ls-files -s로 mode가 120000인지 검증
4. style-guide.md 업데이트 (승인 패턴 강화)
5. feedback-log.md 기록
6. 새 용어 발견 시 용어집 업데이트 제안

거절된 경우:

1. 거절 이유 파악
2. feedback-log.md 기록
3. 필요시 style-guide.md에 "피해야 할 패턴" 추가

---

옵션 처리

옵션	설명	기본값
--mode=quick	빠른 번역 (polish 생략)	-
--mode=thorough	일반 번역 (기본값)	✓
--mode=perfect	꼼꼼한 번역 (높은 기준)	-
--analyze	강제 스타일 재분석	false
--skip-review	검토 루프 스킵 (테스트용)	false

---

에이전트 역할

모델은 각 에이전트 frontmatter의 별칭 기준입니다.

에이전트	모델	역할	점수 체계
translation-style-analyzer	sonnet	기존 번역 분석 → 스타일 가이드 생성	-
content-translator	sonnet	URL/파일 번역	-
translation-reviewer	sonnet	한국어 품질 검토 (28개 패턴)	10점 만점
translation-verifier	opus	원문 충실도 검증 (T1~T10)	10점 만점
polish-agent	haiku	문장 단위 정밀 분석 (10개 핵심 패턴)	10점 만점
translation-learner	sonnet	피드백 학습 → 스타일 가이드 업데이트	-

---

관련 스킬

스킬	용도
/polish	개별 문장 다듬기 (translate-writer Phase 3에서 내부 활용)
/polish-file	파일 전체 문장 품질 분석 + 순차 개선
/blog-writer	원본 한국어 블로그 글 작성 (번역이 아닌 경우)

---

완료 출력

완료 시 아래 템플릿을 참조하여 출력하세요: @.claude/skills/translate-writer/references/output-template.md

---

주의사항

1. draft: true: 모든 번역은 초안으로 생성. 발행은 사용자가 직접.
2. 루프 제한: Translator↔Reviewer+Verifier 이중 검증 루프는 최대 3회.
3. 모드 선택: 목적에 맞는 모드 선택 안내.
4. 피드백 축적: 모든 피드백은 feedback-log.md에 기록.
5. 용어집 존중: glossary.md의 용어를 우선 참조.
6. 백업: style-guide.md 변경 전 항상 style-history/에 백업.
7. 한국어: 모든 출력과 번역은 한국어로.
8. Polish 리포트: 학습 및 추적용으로 보존.
9. 오케스트레이션 원칙: 메인 루프는 콘텐츠를 직접 생성·채점하지 않습니다. 모든 콘텐츠 작업은 전담 에이전트(Task)에 위임하세요.