eval-summary

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	불량, 전체 재작성 필요