review-translation by team-attention

---
name: review-translation
description: |
  번역된 한국어 콘텐츠의 품질을 AI로 검증합니다.
  원문과 번역본을 비교하여 정확성, 완전성, 자연스러움, 용어 일관성을 평가합니다.
  Claude, Codex, Gemini CLI 3개 AI로 교차 검증하여 합의된 이슈를 우선 표시합니다.
  사용: /review-translation week1/slug
arguments:
  - name: path
    description: |
      week/slug 또는 week/parent/child 형식의 문서 경로
      - 단일 페이지: week1/how-openai-uses-codex
      - YouTube 챕터: week1/deep-dive-llms/introduction
    required: true
  - name: claude-only
    description: Claude만 사용 (외부 CLI 미설치 시)
    required: false
  - name: skip-integration
    description: 통합 리포트 생성 스킵 (개별 리포트만)
    required: false
---

# review-translation Skill

번역된 한국어 콘텐츠의 품질을 3개 AI(Claude, Codex, Gemini)로 교차 검증합니다.

## 사용법

```
# 기본 (3개 AI 교차 검증)
/review-translation <week/slug>

# Claude만 사용
/review-translation <week/slug> --claude-only

# 통합 리포트 스킵
/review-translation <week/slug> --skip-integration
```

## 예시

```
# 단일 페이지
/review-translation week1/how-openai-uses-codex

# YouTube 개별 챕터
/review-translation week1/deep-dive-llms/introduction
/review-translation week1/prompt-engineering-guide/zeroshot
```

## 입출력

### 입력 파일

| 구조 | 원본 (eng) 경로 | 번역 (kr) 경로 |
|------|----------------|----------------|
| 기본 구조 | `docs/week{N}/{slug}/eng/{file}.md` | `docs/week{N}/{slug}/kr/{file}.md` |
| 레거시 구조 | `docs/week{N}/{slug}/{file}.md` | `docs/week{N}/{slug}/kr/{file}.md` |

**경로 예시:**
```
# 기본 구조 (eng/kr 분리)
week1/deep-dive-llms/introduction
→ 원본: docs/week1/deep-dive-llms/eng/introduction.md
→ 번역: docs/week1/deep-dive-llms/kr/introduction.md

week1/how-openai-uses-codex
→ 원본: docs/week1/how-openai-uses-codex/eng/*.md
→ 번역: docs/week1/how-openai-uses-codex/kr/*.md

# 레거시 구조 (eng 없이 직접)
week1/prompt-engineering-guide/zeroshot
→ 원본: docs/week1/prompt-engineering-guide/zeroshot.md
→ 번역: docs/week1/prompt-engineering-guide/kr/zeroshot.md
```

### 출력 파일

```
.claude/outputs/review-translation/
└── week{N}/{slug}/
    ├── claude-review.json      # Claude 리뷰
    ├── codex-review.json       # Codex 리뷰
    ├── gemini-review.json      # Gemini 리뷰
    └── integrated-report.md    # 통합 리포트

# 챕터별 리뷰 시
.claude/outputs/review-translation/
└── week{N}/{slug}/{chapter}/
    ├── claude-review.json
    ├── codex-review.json
    ├── gemini-review.json
    └── integrated-report.md
```

## 워크플로우

```
/review-translation week1/how-openai-uses-codex
           │
           ▼
┌──────────────────────────────────────┐
│ 1. 파일 읽기                          │
│    - 원본 마크다운                     │
│    - 번역 마크다운                     │
│    - 용어집 (참조)                     │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 2. 프롬프트 생성                       │
│    external-prompt.md 템플릿 사용     │
│    변수 치환: 원본, 번역, 용어집        │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 3. 병렬 AI 리뷰 실행                   │
│ ┌─────────┬─────────┬─────────┐      │
│ │ Claude  │  Codex  │ Gemini  │      │
│ │ (Task)  │ (Bash)  │ (Bash)  │      │
│ └─────────┴─────────┴─────────┘      │
│    동시 실행 (3분 타임아웃)            │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 4. 개별 리포트 저장                    │
│    claude-review.json                │
│    codex-review.json                 │
│    gemini-review.json                │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 5. Task: report-integrator           │
│    3개 리포트 통합                     │
│    → integrated-report.md            │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 6. 결과 요약 출력                      │
│    점수, 합의/개별 이슈, 권장 조치      │
└──────────────────────────────────────┘
```

## 실행 지침

이 스킬이 호출되면 다음 단계를 따르세요.

### Step 1: 경로 파싱 및 파일 읽기

```
경로 구조 확인:
- 2단계 (week1/slug): 디렉토리 전체 또는 단일 파일
- 3단계 (week1/slug/chapter): 개별 챕터

파일 경로 결정 로직:
1. 먼저 eng 디렉토리 확인: docs/week{N}/{slug}/eng/{chapter}.md
2. eng 없으면 레거시 경로: docs/week{N}/{slug}/{chapter}.md
3. 번역은 항상: docs/week{N}/{slug}/kr/{chapter}.md

예시 - week1/deep-dive-llms/introduction:
1. docs/week1/deep-dive-llms/eng/introduction.md 확인 → 있음 ✓
2. docs/week1/deep-dive-llms/kr/introduction.md 읽기
3. docs/glossary.md 읽기 (용어집)

예시 - week1/prompt-engineering-guide/zeroshot:
1. docs/week1/prompt-engineering-guide/eng/zeroshot.md 확인 → 없음
2. docs/week1/prompt-engineering-guide/zeroshot.md 읽기 (레거시)
3. docs/week1/prompt-engineering-guide/kr/zeroshot.md 읽기
4. docs/glossary.md 읽기 (용어집)

파일이 없는 경우:
- 원본 없음: "원본 파일을 찾을 수 없습니다: {경로}" 에러
- 번역 없음: "번역 파일을 찾을 수 없습니다. /translate-reading 먼저 실행해주세요." 에러
```

### Step 2: 프롬프트 생성

```
.claude/agents/review-translation/external-prompt.md 템플릿 읽기

변수 치환:
- {{REVIEWER_NAME}}: 각 AI 이름
- {{DOCUMENT_PATH}}: 문서 경로
- {{ENGLISH_SOURCE}}: 원본 내용
- {{KOREAN_TRANSLATION}}: 번역 내용
- {{GLOSSARY}}: 용어집 내용

프롬프트를 임시 파일로 저장:
- /tmp/review-prompt-codex.txt
- /tmp/review-prompt-gemini.txt
```

### Step 3: 병렬 AI 리뷰 실행

**--claude-only가 아닌 경우**, 3개 AI를 동시에 실행합니다:

#### Claude (Task tool)
```
Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/review-translation/claude-reviewer.md 내용
         + 원본 마크다운
         + 번역 마크다운
         + 용어집
- description: "claude-reviewer - 번역 품질 검증"
```

#### Codex (Bash tool - 동시 실행)
```bash
# 프롬프트 파일 생성
cat << 'PROMPT_EOF' > /tmp/review-prompt-codex.txt
[external-prompt.md 내용에 변수 치환]
PROMPT_EOF

# Codex 실행 (타임아웃 3분)
timeout 180 codex exec "$(cat /tmp/review-prompt-codex.txt)" \
  -o /tmp/codex-review-output.txt 2>/dev/null

# 또는 JSON 모드
timeout 180 codex exec "$(cat /tmp/review-prompt-codex.txt)" --json 2>/dev/null | \
  grep '"type":"assistant"' | tail -1 | jq -r '.message.content[0].text' \
  > /tmp/codex-review-output.txt
```

#### Gemini (Bash tool - 동시 실행)
```bash
# 프롬프트 파일 생성
cat << 'PROMPT_EOF' > /tmp/review-prompt-gemini.txt
[external-prompt.md 내용에 변수 치환]
PROMPT_EOF

# Gemini 실행 (타임아웃 3분, yolo 모드)
timeout 180 gemini "$(cat /tmp/review-prompt-gemini.txt)" -y -o json 2>/dev/null | \
  jq -r '.text' > /tmp/gemini-review-output.txt
```

### Step 4: 개별 리포트 저장

```
출력 디렉토리 생성:
mkdir -p .claude/outputs/review-translation/week{N}/{slug}/

각 AI 결과를 JSON으로 저장:
- claude-review.json
- codex-review.json (Codex 출력에서 JSON 추출)
- gemini-review.json (Gemini 출력에서 JSON 추출)

JSON 파싱 실패 시:
- 원본 출력을 {ai}-review-raw.txt로 저장
- 에러 메시지 표시 후 계속 진행
```

### Step 5: 리포트 통합 (--skip-integration이 아닌 경우)

```
Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/review-translation/report-integrator.md 내용
         + Claude 리뷰 JSON
         + Codex 리뷰 JSON
         + Gemini 리뷰 JSON
         + 문서 경로
- description: "report-integrator - 리포트 통합"

결과: 마크다운 형식의 통합 리포트
Write tool로 integrated-report.md 저장
```

### Step 6: 결과 요약 출력

```
완료 메시지 형식 (3개 AI 모드):

✅ 번역 리뷰 완료!

📊 **종합 점수**: {overall_avg}/10

| 항목 | Claude | Codex | Gemini | 평균 |
|------|--------|-------|--------|------|
| 정확성 | {a1} | {a2} | {a3} | {avg} |
| 완전성 | {c1} | {c2} | {c3} | {avg} |
| 자연스러움 | {n1} | {n2} | {n3} | {avg} |
| 용어 일관성 | {t1} | {t2} | {t3} | {avg} |

📋 **이슈 요약**:
  - 합의된 이슈: {N}건 (Critical {N}, Major {N}, Minor {N})
  - 개별 의견: {N}건

📁 **리포트 저장 위치**:
  .claude/outputs/review-translation/week{N}/{slug}/
  ├── integrated-report.md (통합)
  ├── claude-review.json
  ├── codex-review.json
  └── gemini-review.json

💡 **권장 조치**:
  {합의된 이슈 기반 권장사항}
```

## 옵션

### --claude-only

Claude만 사용하여 리뷰합니다.
- Codex/Gemini CLI 미설치 또는 미인증 시 사용
- 통합 리포트 대신 Claude 리포트만 생성

### --skip-integration

통합 리포트 생성을 스킵합니다.
- 3개 AI 개별 리포트만 저장
- 빠른 검증이 필요할 때 사용

## Agent 파일

- `.claude/agents/review-translation/claude-reviewer.md` - Claude 리뷰 에이전트
- `.claude/agents/review-translation/external-prompt.md` - Codex/Gemini 프롬프트 템플릿
- `.claude/agents/review-translation/report-integrator.md` - 리포트 통합 에이전트

## CLI 요구사항

### Codex CLI
```bash
npm install -g @openai/codex
codex login  # 브라우저 OAuth 인증
```

### Gemini CLI
```bash
npm install -g @google/gemini-cli
gemini  # "Login with Google" 선택
```

## 에러 처리

| 상황 | 처리 |
|------|------|
| 원본 파일 없음 | "원본 파일을 찾을 수 없습니다: {경로}" |
| 번역 파일 없음 | "번역 파일을 찾을 수 없습니다. /translate-reading 먼저 실행해주세요." |
| Codex CLI 미설치 | `which codex` 확인 → Claude만 실행 |
| Gemini CLI 미설치 | `which gemini` 확인 → Claude만 실행 |
| CLI 인증 실패 | "인증 필요: codex login / gemini 재실행" |
| JSON 파싱 실패 | 원본 출력 저장 후 계속 진행 |
| 타임아웃 (3분) | 해당 AI 스킵 후 계속 진행 |

## 점수 기준

| 점수 | 의미 |
|------|------|
| 9-10 | 출판 수준, 수정 불필요 |
| 7-8 | 양호, Minor 수정 권장 |
| 5-6 | 보통, Major 수정 필요 |
| 3-4 | 미흡, 상당 부분 재번역 권장 |
| 1-2 | 불량, 전체 재번역 필요 |

## 향후 확장 (Phase 4)

- `--all-chapters`: 전체 챕터 일괄 리뷰
- `master-report.md`: 챕터별 요약 포함 마스터 리포트
- translate-reading 연계: `--review` 옵션으로 자동 검증