| name | review-translation |
| description | 번역된 한국어 콘텐츠의 품질을 AI로 검증합니다.
원문과 번역본을 비교하여 정확성, 완전성, 자연스러움, 용어 일관성을 평가합니다.
Claude, Codex, Gemini CLI 3개 AI로 교차 검증하여 합의된 이슈를 우선 표시합니다.
사용: /review-translation week1/slug
|
| arguments | [{"name":"path","description":"week/slug 또는 week/parent/child 형식의 문서 경로\n- 단일 페이지: week1/how-openai-uses-codex\n- YouTube 챕터: week1/deep-dive-llms/introduction\n","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 - 동시 실행)
cat << 'PROMPT_EOF' > /tmp/review-prompt-codex.txt
[external-prompt.md 내용에 변수 치환]
PROMPT_EOF
timeout 180 codex exec "$(cat /tmp/review-prompt-codex.txt)" \
-o /tmp/codex-review-output.txt 2>/dev/null
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 - 동시 실행)
cat << 'PROMPT_EOF' > /tmp/review-prompt-gemini.txt
[external-prompt.md 내용에 변수 치환]
PROMPT_EOF
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
npm install -g @openai/codex
codex login
Gemini CLI
npm install -g @google/gemini-cli
gemini
에러 처리
| 상황 | 처리 |
|---|
| 원본 파일 없음 | "원본 파일을 찾을 수 없습니다: {경로}" |
| 번역 파일 없음 | "번역 파일을 찾을 수 없습니다. /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 옵션으로 자동 검증
