| name | eval-summary |
| description | readings.ts의 요약 필드가 원본 kr 마크다운과 비교하여 잘 작성되었는지 평가합니다.
이슈별로 개선사항을 제안하고 사용자 컨펌 후 readings.ts를 수정합니다.
사용: /eval-summary week1 또는 /eval-summary week1/slug
|
| arguments | [{"name":"path","description":"week{N} 또는 week{N}/slug 형식\n- 주차 전체: week1 (해당 주차의 요약 필드가 있는 모든 리딩 검증)\n- 개별 리딩: week1/deep-dive-llms\n","required":true},{"name":"skip-apply","description":"수정 적용 없이 리포트만 생성","required":false},{"name":"auto-apply","description":"사용자 확인 없이 모든 수정 자동 적용","required":false}] |
eval-summary Skill
readings.ts의 요약 필드를 원본 kr 마크다운과 비교하여 품질을 평가합니다.
사용법
/eval-summary week1
/eval-summary week1/deep-dive-llms
/eval-summary week1/how-openai-uses-codex
/eval-summary week1 --skip-apply
/eval-summary week1 --auto-apply
검증 대상 필드
| 필드 | 설명 | 타입 |
|---|
tldr | TL;DR 전체 요약 | string |
learningGoals | 학습 목표 배열 | string[] |
chapterSummaries | 챕터별 요약 | ChapterSummary[] |
motivation | 동기부여 섹션 | object |
keyTakeaways | 핵심 요점 | object[] |
검증 기준
| 기준 | 설명 |
|---|
| 정확성 | 원문 내용을 정확히 반영하는가 |
| 완전성 | 중요한 내용이 누락되지 않았는가 |
| 간결성 | 불필요하게 길거나 중복되지 않았는가 |
| 일관성 | 용어와 어조가 일관되는가 |
입출력
입력 파일
| 소스 | 경로 |
|---|
| readings.ts | src/content/readings.ts |
| kr 마크다운 (기본) | docs/week{N}/{slug}/kr/index.md |
| kr 마크다운 (부모) | docs/week{N}/{slug}/kr/_index.md |
출력 파일
.claude/outputs/eval-summary/
└── week{N}/{slug}/
└── evaluation-report.json
워크플로우
/eval-summary week1/slug
│
▼
┌─────────────────────────────────┐
│ 1. 경로 파싱 │
│ week{N} → 주차 전체 │
│ week{N}/slug → 개별 리딩 │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 2. 데이터 로드 │
│ - readings.ts 요약 필드 │
│ - kr 마크다운 파일 │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 3. Task: summary-evaluator │
│ 요약 vs 원본 비교 검증 │
│ → JSON 이슈 리포트 │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 4. 이슈별 사용자 컨펌 │
│ (--skip-apply가 아닌 경우) │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 5. 승인된 수정사항 적용 │
│ Edit tool로 readings.ts │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 6. 결과 요약 출력 │
└─────────────────────────────────┘
실행 지침
이 스킬이 호출되면 다음 단계를 따르세요.
Step 1: 경로 파싱 및 대상 리딩 수집
경로 구조 확인:
- 1단계 (week1): 주차 전체 검증
→ readings.ts에서 week === 1인 모든 리딩 추출
→ 요약 필드(tldr, learningGoals, chapterSummaries, motivation, keyTakeaways)가
하나 이상 있는 리딩만 필터링
- 2단계 (week1/slug): 개별 리딩 검증
→ readings['week1/slug'] 추출
대상 리딩 수집 로직 (주차 전체 시):
1. Read tool로 src/content/readings.ts 파일 읽기
2. 해당 주차의 모든 리딩 키 추출
3. 요약 필드가 있는 리딩만 필터링
4. 각 리딩에 대해 검증 수행
Step 2: 데이터 로드
각 리딩에 대해:
1. readings.ts에서 요약 필드 추출:
- tldr (YouTube 콘텐츠)
- learningGoals (YouTube 콘텐츠)
- chapterSummaries (YouTube 콘텐츠)
- motivation (동기부여 섹션)
- keyTakeaways (핵심 요점)
2. kr 마크다운 파일 경로 결정:
- isParent === true && children 있음:
→ docs/week{N}/{slug}/kr/_index.md
- 그 외:
→ docs/week{N}/{slug}/kr/index.md
3. Read tool로 kr 마크다운 파일 읽기
파일이 없는 경우:
- kr 마크다운 없음: "번역 파일을 찾을 수 없습니다: /translate-reading 먼저 실행해주세요."
- 요약 필드 없음: "검증할 요약 필드가 없습니다." (해당 리딩 스킵)
Step 3: summary-evaluator 에이전트 호출
Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/eval-summary/summary-evaluator.md 내용
+ "## 입력 데이터"
+ "### 리딩 키: {week/slug}"
+ "### readings.ts 요약 필드:"
+ [tldr, learningGoals, chapterSummaries, motivation, keyTakeaways를 JSON으로]
+ "### 원본 kr 마크다운:"
+ [마크다운 전체 내용]
- description: "summary-evaluator - {slug} 요약 품질 검증"
에이전트가 JSON 형식으로 이슈 리포트를 반환합니다.
JSON 블록(```json ... ```) 추출하여 파싱합니다.
Step 4: 리포트 저장
출력 디렉토리 생성:
mkdir -p .claude/outputs/eval-summary/week{N}/{slug}/
결과 저장:
Write tool로 evaluation-report.json 저장
--skip-apply 옵션인 경우:
→ 리포트 내용 출력 후 종료
→ Step 5, 6 스킵
Step 5: 이슈별 사용자 컨펌 (--skip-apply가 아닌 경우)
이슈를 severity 순서로 정렬: critical → major → minor
각 이슈에 대해:
--auto-apply 옵션인 경우:
→ 모든 이슈 자동 승인
그 외:
→ AskUserQuestion tool 사용
AskUserQuestion 호출 예시:
questions:
- question: "이 수정사항을 적용하시겠습니까?"
header: "[Major] {field}"
options:
- label: "적용"
description: |
현재: "{current}"
수정: "{suggested}"
이유: {reason}
- label: "건너뛰기"
description: "이 이슈를 무시하고 다음으로 진행"
multiSelect: false
사용자 선택 처리:
- "적용": approvedIssues 배열에 추가
- "건너뛰기": skippedIssues 배열에 추가
- "Other" (직접 입력): customFixes 배열에 추가 (사용자 입력값 사용)
Step 6: 승인된 수정사항 적용
approvedIssues와 customFixes의 각 항목에 대해:
1. Read tool로 src/content/readings.ts 파일 읽기
2. 해당 리딩 키 위치 찾기: 'week{N}/{slug}':
3. 수정할 필드 위치 찾기
4. Edit tool로 수정 적용:
- old_string: 현재 값
- new_string: suggested 또는 custom 값
필드별 수정 방법:
- tldr: tldr: '...' 라인 찾아서 교체
- learningGoals: learningGoals: [...] 블록 찾아서 교체
- chapterSummaries: chapterSummaries 배열 내 특정 항목 교체
- motivation: motivation: {...} 블록 찾아서 교체
- keyTakeaways: keyTakeaways 배열 내 특정 항목 교체
주의: 한글 포함 시 Edit tool 사용 (Write 대신)
→ 정확한 old_string 매칭 필요
Step 7: 결과 요약 출력
완료 메시지 형식:
✅ 요약 평가 완료!
📊 **검증 결과**
- 검증된 리딩: {N}개
- 발견된 이슈: {N}건
- Critical: {N}건
- Major: {N}건
- Minor: {N}건
📝 **적용된 수정** (--skip-apply가 아닌 경우)
- 승인됨: {N}건
- 건너뜀: {N}건
📁 **리포트 저장 위치**
.claude/outputs/eval-summary/week{N}/{slug}/evaluation-report.json
💡 **다음 단계**
pnpm build # TypeScript 검증
pnpm dev # 웹에서 확인
옵션
--skip-apply
수정 적용 없이 리포트만 생성합니다.
- 이슈 발견 후 사용자 컨펌 과정 스킵
- 리포트 파일만 저장하고 종료
--auto-apply
사용자 확인 없이 모든 수정을 자동 적용합니다.
- 발견된 모든 이슈의 suggested 값을 자동 적용
- 주의: 검토 없이 적용되므로 사용 시 주의 필요
Agent 파일
.claude/agents/eval-summary/summary-evaluator.md - 요약 품질 평가 에이전트
이슈 유형
| 유형 | 설명 |
|---|
inaccuracy | 원문과 다른 내용 |
omission | 중요 내용 누락 |
redundancy | 불필요한 반복 |
inconsistency | 용어/스타일 불일치 |
verbosity | 불필요하게 긴 표현 |
심각도
| 레벨 | 기준 |
|---|
critical | 핵심 내용 오류, 심각한 누락 |
major | 중요 정보 누락/왜곡 |
minor | 표현 개선, 일관성 문제 |
에러 처리
| 상황 | 처리 |
|---|
| kr 마크다운 없음 | "번역 파일을 찾을 수 없습니다: /translate-reading 먼저 실행해주세요." |
| readings.ts에 리딩 없음 | "리딩을 찾을 수 없습니다: /upload-reading 먼저 실행해주세요." |
| 요약 필드 없음 | "검증할 요약 필드가 없습니다." (해당 리딩 스킵) |
| JSON 파싱 실패 | 원본 출력 저장 후 수동 검토 안내 |
점수 기준
| 점수 | 의미 |
|---|
| 9-10 | 우수, 수정 불필요 |
| 7-8 | 양호, Minor 수정 권장 |
| 5-6 | 보통, Major 수정 필요 |
| 3-4 | 미흡, 상당 부분 재작성 권장 |
| 1-2 | 불량, 전체 재작성 필요 |
