course-builder: Skill for Claude Code

Coherence Review — Cross-Boundary QA

개별 자산 검증이 아니라 자산 간 경계면 검증이 핵심. "slide가 있는가" 보다 "slide와 transcript가 같은 이야기를 하는가"가 훨씬 중요하다.

검사 순서 (fail-fast)

중요도·실행비용 순으로 정렬. 상위 단계 실패 시 하위는 수행하되 리포트에 "의존 실패" 표시.

1. Structural presence

모든 예상 파일 존재 확인.

course/manifest.json OR _workspace/01_*
course/meta/learning_objectives.json
course/sections/<sec>/section.json
course/sections/<sec>/classes/<cls>/{slide.source.md,slide.html,note.md,transcript.txt}
course/sections/<sec>/quiz.json

2. LO Coverage (critical)

모든 LO는 다음 3개소에 ≥1 등장:

• slide.source.md (footer or body)
• note.md (blockquote 헤더 or 본문 언급)
• quiz.json (lo_ids 필드)

측정: LO registry를 grep으로 전수 검사.

3. Bloom Balance

• 섹션당 Bloom 레벨 ≥3
• Course 전체 ≥4
• Apply+Analyze quiz 합 ≥2 / 섹션

4. Slide ↔ Script 정합

• slide.source.md의 --- 구분 슬라이드 수 N
• transcript.txt의 [slide N] cue 최대값 M
• N == M 필수

5. Note ↔ Slide 정합

• note.md의 [slide K] 모든 K가 1~N 범위
• note가 slide에 없는 새 개념 도입 시 warning (가능하지만 위험)

6. Tone 일관성

• course_spec의 tone 파라미터와 실제 자산 톤 비교
• 한 class 안에서 반말/존댓말 혼재 감지 (한국어)
• 문체 급변 감지 (정규 ML 불필요, 단순 휴리스틱으로 충분)

7. Quiz 사실 검증

• quiz 정답이 note/slide 내용과 모순되는지
• distractor가 실제로 오답인지 (가끔 AI가 정답을 distractor에 넣음)

8. Transcript Speakability

• raw code literal: `(backtick) 포함 여부
• 긴 숫자: \d{4,} 정규식 — 단, 대괄호 디렉티브 [pause:N], [slide N], [emph]...[/emph] 내부 숫자는 제외 (TTS 후처리용 마커이지 발화 대상 아님). 구현: 먼저 \[(pause|slide|emph|/emph)[^\]]*\] 패턴을 공백으로 치환한 뒤 숫자 검사.
• 생 URL: https?:// 검출
• 문장 길이: 20 어절 초과 문장 비율

판정 로직

if (1) fails:
  overall = "revise"; 중단
if (2) 어떤 LO가 0회 등장:
  overall = "revise"
if (3) Bloom 부족:
  overall = "revise"
if (4) cue 수 불일치:
  overall = "revise"
if (5~8) any fail:
  overall = "revise"
else:
  overall = "pass"

리포트 포맷

원칙: atomic dual-write. JSON과 MD를 동일 라운드의 동일 verdict로 한 번에 기록. 중간 저장 후 한 쪽만 overwrite하면 machine gate(JSON)와 사람이 보는 리포트(MD)가 엇갈림 — 실제로 과거 run에서 JSON=pass / MD=REVISE 상태로 빌드가 "성공"한 사례 있음.

_workspace/99_coherence_report.json (machine contract)

{
  "overall": "revise" | "pass",
  "timestamp": "...",
  "course_level": {
    "lo_coverage_pct": 95,
    "bloom_levels": 4,
    "issues": [{"type":"bloom_gap","detail":"..."}]
  },
  "sections": [
    {"section_id":"S1","verdict":"pass","issues":[]}
  ],
  "classes": [
    {"class_id":"S1.C1","verdict":"revise",
     "issues":[
       {"type":"slide_script_mismatch",
        "detail":"slide has 5, script has [slide 6] cue",
        "fix_hint":"Remove [slide 6] from transcript or add slide",
        "route_to":"script-writer"}
     ]}
  ]
}