knowledge-absorb — 새 자료를 지식 저장소에 "동일한 방식"으로 흡수

~/.claude/knowledge/ 의 기존 33개 소스는 동일한 구조로 관리된다:

sources/{source-id}/source.{pptx|pdf|md}
sources/{source-id}/slides/slide-NN.md         (verbatim 슬라이드/문단 본문)
images-pool/{source-id}/*.png                  (이미지 + phash dedup)
images-pool/_meta.jsonl                        (OCR + Vision 메타)
cards/{topic}/{card-id}.md                     (concept/case/tool/framework 카드)
cards/{topic}/index.md                         (허브/클러스터/브리지/전체 테이블)
topics/{topic}.md                              (L1 요약)
refs/courseware/{folder}/content.md            (L2 추출본, 필요 시)

이 스킬은 새 자료 하나를 위 구조로 변환하고, cards_lint exit 0 까지 도달시킨다.

언제 이 스킬을 사용하는가

사용자가 아래 중 하나를 제공하며 "지식화 / 카드로 만들어 / 자료 추가 / 소스 흡수"를 요청:

• PPTX / PDF 파일 — 로컬 경로
• Notion 페이지 — URL 또는 page ID
• 링크드인 게시물 — URL 또는 복사한 텍스트 + 이미지
• 브런치 글 — URL
• 뉴스레터 — URL 또는 Maily/Substack export
• 일반 웹 URL — 블로그/미디엄 글
• Markdown/HTML 파일 — 이미 구조화된 문서
• 강의자료 폴더 — Notion export + 이미지 번들

지식화 파이프라인 (7 스텝, 순서 엄수)

Step 0  소스 ID 결정 + 타입 감지
Step 1  원본 복사 + slides/ 정규화        (포맷별 분기)
Step 2  이미지 풀 구축 + OCR/Vision        (knowledge-ingest/scripts 재사용)
Step 3  카드 제안 (사용자 확인 게이트)      (아래 원칙 + scaffold_cards.py)
Step 4  카드 스캐폴딩 + frontmatter       (scaffold_cards.py + cards_lint.py)
Step 5  본문 집필 (Haiku subagent + apply_bodies)
Step 6  크로스링크 + 토픽 index 리프레시    (코퍼스 전역)
Step 7  cards_lint + 인용 감사 + 리포트

Step 0 — 소스 ID 결정

네이밍 규칙 (source-id)

• kebab-case
• 최대 6 토큰
• 시간 정보가 있으면 포함 (예: smsg-240903, classu-onplanet-0908)
• 이미 있는지 확인: ls ~/.claude/knowledge/sources/ | grep <keyword>
• 중복이면 --force 로 재처리할지 확인

타입 감지

Step 1 — 정규화 (포맷별)

목표: 모든 경로가 sources/{source-id}/slides/slide-NN.md 형식을 산출하도록 한다.

1.PPTX / 1.PDF — ingest.py 위임 (기본 경로)

python ~/.claude/skills/knowledge-ingest/scripts/ingest.py \
  --source-path "/path/to/file.pptx" \
  --source-id {source-id} \
  --budget-usd 0.5

이 한 줄이 Step 1~2 를 통합 처리 (slides + 이미지 + OCR + Vision).

PPTX ingest 직후 필수 후처리 2건 (빠뜨리면 교안 소환 시 링크·이미지가 안 딸려온다):

# 1) 하이퍼링크 추출 → sources/{id}/links.jsonl
python3 ~/.claude/knowledge/scripts/extract_pptx_links.py --pptx-dir ~/.claude/knowledge/sources/{source-id}
# 2) 슬라이드에 AUTO-ASSETS 블록(이미지 캡션+링크) 주입 — retriever 교안 surface가 이 블록을 읽는다
python3 ~/.claude/knowledge/scripts/inject_slide_assets.py
# 검증: grep -l "AUTO-ASSETS" ~/.claude/knowledge/sources/{source-id}/slides/*.md | wc -l  → 0이면 실패

1A. Notion 페이지

1. MCP notion-fetch 로 페이지 본문 markdown 가져오기
   → mcp__<notion-mcp-server>__notion-fetch({page_id: "..."})
2. 하위 블록 · 이미지 URL 수집
3. 이미지는 로컬로 다운로드 → images-pool/{source-id}/
4. markdown 을 의미 단위(H2/H3 헤딩 또는 문단 그룹)로 분할
5. 각 덩어리를 slide-NN.md 로 저장 (프론트매터 + 본문)

슬라이드 frontmatter (spec §5.5):

---
source_id: {source-id}
slide: {N}
title: "{첫 H2 or 생략}"
images: [{img-id}, ...]
---

1B. 링크드인 게시물

1. 게시물 URL 또는 본문 텍스트 + 첨부 이미지 수집
2. 본문을 문단 단위로 분할 (1 slide = 1 문단 또는 카드)
3. 첨부 이미지를 images-pool 에 저장, 파일명 `img-NNN{a|b|c}.png`
4. OCR pass: `knowledge-ingest/scripts/ocr.py` 활용
5. Gemini Vision pass (선택): 시각 중심 카드뉴스면 필수

1C. 브런치 글

1. 브런치 RSS/fetch 로 HTML → markdown (markitdown 활용 가능)
2. 본문 이미지는 HTML 에서 <img src="..."> 긁어서 저장
3. H2/H3 헤딩으로 slide 분할

1D. 뉴스레터 (Maily/Substack)

1. 웹 fetch → markdown
2. CTA/광고 섹션 제거
3. H2 기준 slide 분할

1E. 일반 웹 URL

1. WebFetch 로 가져와 markdown 추출 (또는 markitdown CLI)
2. 의미 단위로 slide 분할

1F. Markdown / HTML 파일

1. 파일 복사 → sources/{source-id}/source.md
2. H2/H3 기준 분할
3. 이미지 상대 경로를 images-pool 로 복사 + 재링크

1G. 디렉토리 (Notion export)

Notion 에서 export 한 폴더 전체 — content.md + images/ 서브폴더 구조.

1. 폴더 통째로 sources/{source-id}/ 아래로 복사
2. 메인 markdown 을 H2/H3 분할
3. 이미지는 images-pool 로 이동/복사

1H. 강의 녹화 영상 (recording-augmented) — fc-google·classu 검증 패턴

같은 강의의 덱 PPTX가 이미 허브 소스로 존재할 때, 녹화 영상의 강사 육성을 별도 {덱소스}-recording 소스로 흡수해 짝을 맺는다 (예: classu ↔ classu-recording).

# 1. 전사 (resumable — 수 시간 걸리므로 백그라운드로. mlx-whisper large-v3 한국어)
python3 ~/.claude/knowledge/scripts/transcribe_lecture_videos.py <영상폴더> <전사출력폴더>
# 2. 나레이션 슬라이드 생성 (kind: narration frontmatter)
python3 ~/.claude/knowledge/scripts/make_narration_slides.py <전사폴더> {덱소스}-recording "강의명"

카드 원칙 (classu-recording 8카드 2026-07-07 검증):

• 육성 전용(spoken-only) 콘텐츠만 카드화 — 카드 생성 전 기존 덱 소스 카드를 grep해서 슬라이드에 이미 있는 주제는 스킵. 말로만 전한 실습 워크스루·스토리·메시지 템플릿이 카드감
• 인용은 나레이션 slide-NN.md에서 verbatim (구어체 그대로 — 그게 authentic)
• images: [] (나레이션엔 이미지 없음; 명확히 대응되는 덱 이미지가 있으면 id 참조 가능)
• ⚠️ macOS 파일명은 NFD(자모 분해) — 파일명 매칭 정규식에 한글을 쓰지 말 것 (선두 숫자만)

1I. Notion DB 증분 갱신 (linkedin-archive 패턴, 2026-07-07 검증)

이미 흡수된 소스의 마스터가 Notion DB일 때 (예: <your-source> ← DB collection://<db-id>):

1. 현재 최고 slide 번호와 최신 date 확인: ls sources/{id}/slides/ + 최신 슬라이드 frontmatter
2. DB에서 그 날짜 이후 행만 SQL 쿼리(notion-query-data-sources) → 결과를 즉시 체크포인트 JSON으로 저장 (page URL 포함 — 중단 대비, 재쿼리 방지)
3. 각 행을 notion-fetch로 본문 verbatim 수집, 다음 slide 번호부터 시간순 append
   • ⚠️ Notion rate limit 공격적(429 collection_router_upstream): fetch 간 ~40초 대기, 429 시 60초 backoff ≤4회, 그래도 실패면 스킵·목록화 후 마지막에 재시도. 병렬 금지 — 단일 순차
   • 빈 페이지(본문 수 자 미만)는 "정당 스킵"으로 기록 (fetch 실패와 구분)
4. post_id 기준 idempotent — 이미 있는 글 스킵. 세션 한도로 중단돼도 체크포인트+기존 파일로 이어받기
5. 새 글 전부 카드화 금지 — 두드러진 신규 주제만 2-3카드

⚠️ 1A~1G 의 정규화 단계는 scripts/normalize_text_source.py 에 공통 로직이 있다 (아래 참조).

🔴 이미지 편입 강제 게이트 (2026-07-06 신설) — 과거 MD/Notion ingest가 텍스트만 흡수하고 이미지 ~668장을 누락한 사고의 재발 방지. Step 1 완료 직후 반드시 검증한다:

# 원본에 이미지가 있는데 풀에 0장이면 ingest 실패로 간주하고 멈춘다
find <원본폴더> \( -name '*.png' -o -name '*.jpg' -o -name '*.jpeg' -o -name '*.webp' \) | wc -l
ls ~/.claude/knowledge/images-pool/{source-id}/ 2>/dev/null | wc -l

두 값이 크게 어긋나면 scripts/ingest_md_images.py 패턴(MD의 ![alt](path) 순서·주변 텍스트로 slide 매핑, alt 텍스트를 ocr 필드에 시드)으로 편입 후 진행한다. 이미지 없는 ingest는 카드 images: 빈값 → extract가 이미지 없이 반환 → 교안에서 강의 캡처를 못 쓰는 하류 장애로 이어진다.

Step 2 — 이미지 풀 + OCR/Vision

PPTX/PDF 는 Step 1 에서 자동 처리됨. 다른 포맷은:

python ~/.claude/skills/knowledge-ingest/scripts/pass1.py --source-id {source-id}
# OCR (Tesseract kor+eng) + 장식 이미지 제거 heuristic
python ~/.claude/skills/knowledge-ingest/scripts/run_vision_batch.py --source-id {source-id}
# Gemini Vision Pass 2 — 비장식 이미지에 한국어 설명 생성

결과가 images-pool/_meta.jsonl 에 append 된다.

Step 3 — 카드 제안 (사용자 확인 게이트)

카드 제안·스캐폴딩 절차 (스크립트: ~/.claude/skills/knowledge-cards-build/scripts/ — 스킬 아님, 라이브러리 디렉토리):

• concept-rebuild 원칙 — 한 소스당 2~6장 카드 (1소스=1카드 아님)
• type picking:
  • concept — 정의/원칙/멘탈 모델
  • case — 구체 프로젝트/수치/결과
  • tool — 특정 SW/서비스 활용법
  • framework — 반복 가능한 다단계 방법론
• topic 배치 — ai-basics, career-growth, data-analytics, dooh, linkedin-branding, marketing, marketing-ai 중 가장 적합한 곳
• 카드 ID 형식 — {source-id}-{concept-slug} (예: smsg-240903-dooh-flywheel)
• 엔티티 연동 (필수) — 카드가 다루는 도구/플랫폼은 summaries/entities.jsonl의 canonical 표기를 aliases에 포함시킨다. 레지스트리에 없는 새 도구면 행을 추가 (id/canonical/aliases/status; 모르면 status=active + note "미검증").
• aliases / keywords (필수) — 각 제안에 aliases(영한 동의어·표기변형·자연어 검색표현)와 keywords(본문 핵심어)를 포함한다 (Contextual BM25 검색 필드). 제안 단계에서 비워두면 Step 5 body-fill 에서 반드시 채운다.

제안 리스트를 사용자에게 제시하고 승인을 받는다. 승인 없이 스캐폴딩 금지.

Step 4 — 카드 스캐폴딩

승인된 각 제안에 대해:

# scaffold_cards.py 호출 (Python) 또는 수동으로
# scaffold_cards.py 는 aliases/keywords 를 proposal 에서 받아 emit 한다
# (proposal 에 없으면 [] placeholder — Step 5 에서 반드시 채울 것)
cat > ~/.claude/knowledge/cards/{topic}/{card-id}.md <<'EOF'
---
id: {card-id}
topic: {topic}
type: {concept|case|tool|framework}
title: "{title}"
summary: "{한 줄 요약}"
tags: [tag1, tag2, tag3]
aliases: [영한 동의어, 표기변형, 자연어 검색표현]
keywords: [본문 핵심어1, 핵심어2]
source:
  source_id: {source-id}
  slide_files: [sources/{source-id}/slides/slide-NN.md, ...]
images: [{img-id}, ...]
related_cards: []
created: 2026-04-22
updated: 2026-04-22
---

## 배경

## 핵심 포인트

## 인용 (원본 그대로)

## 시사점
EOF

cards/{topic}/index.md 전체 테이블에 | {card-id} | {type} | {title} | {source-id} | {n-images} | 행 추가.

Step 5 — 본문 집필 (Haiku + apply 패턴)

신규 카드 body 는 메인 세션에서 쓰지 않고 Haiku subagent 에 위임.

5-1. Staging 디렉토리 준비

mkdir -p /tmp/knowledge-absorb/bodies

5-2. Haiku subagent 호출

Agent 도구 + subagent_type: general-purpose + model: haiku.

프롬프트 핵심 (자세히 풀어 작성):

당신은 한국어 지식 카드 본문 작성자입니다. 각 카드에 대해:

1. `sources/{source-id}/slides/slide-NN.md` 파일들을 직접 Read
2. 다음 4개 섹션을 한국어 평서체로 작성:
   ## 배경 — 이 개념/사례의 맥락 (2~3문장)
   ## 핵심 포인트 — 불릿 4~6개, 각 한 문장
   ## 인용 (원본 그대로)
     > {슬라이드에서 복사한 한 문장 verbatim}
     > — sources/{source-id}/slides/slide-NN.md
     (2~3개 인용)
   ## 시사점 — 마케터/데이터/커리어 관점 해석 (2~3문장)
3. 결과를 /tmp/knowledge-absorb/bodies/{card-id}.body.md 에 저장
4. 인용은 반드시 slide 원문 복사 — 콜론 추가/어순 변경 금지
5. 원문에 없으면 인용 삭제 (fabrication 금지)
6. 카드 frontmatter 의 aliases/keywords 가 비어 있으면 채운다:
   - aliases: 영한 동의어·표기변형·자연어 검색표현 5~10개
     (예: [캔버스, ChatGPT Canvas, 랜딩페이지, landing page])
   - keywords: slide 원문에 실제로 등장하는 본문 핵심어 5~8개

5-3. 메인 세션에서 body apply

# /tmp/knowledge-absorb/apply_bodies.py
# 각 staging 파일을 해당 카드의 frontmatter 아래 본문으로 교체
for body_file in Path("/tmp/knowledge-absorb/bodies").glob("*.body.md"):
    card_id = body_file.stem.replace(".body", "")
    # cards/**/{card_id}.md 찾아서 frontmatter 보존 + body 교체

참고 구현: /tmp/classu-scaffold/apply_bodies.py (P5 에서 사용).

Step 6 — 크로스링크 + 토픽 Index 리프레시 (전역)

신규 카드가 추가되었으므로 corpus-wide 재계산:

python ~/.claude/skills/knowledge-absorb/scripts/relink_and_curate.py
# 내부적으로:
# 1. link_related_cards.py      — tag-jaccard + char-bigram 스코어링
# 2. symmetrize_links.py         — A→B 면 B→A 보장, MAX_LINKS=6
# 3. curate_topic_indexes.py     — 허브/클러스터/브리지/전체 테이블 재작성
#    └─ build_card_catalog.py 자동 호출 → summaries/cards.jsonl 카탈로그 재생성

토픽 index 만 다시 만들 때도 아래를 실행하면 카탈로그가 함께 갱신된다 (필수):

python3 ~/.claude/skills/knowledge-absorb/scripts/curate_topic_indexes.py

참고: /tmp/classu-scaffold/ 의 P6·P7 스크립트가 원본.

Step 7 — Lint + 인용 감사 + 리포트

cd ~/.claude/knowledge && python3 \
  ~/.claude/skills/knowledge-cards-build/scripts/cards_lint.py
# exit 0 필수

python3 ~/.claude/skills/knowledge-absorb/scripts/audit_new_quotes.py \
  --source-id {source-id}
# FAITHFUL 비율 확인 — 90% 미만이면 DISTORTED 카드 재추출

완료 리포트 작성

~/.claude/knowledge/docs/YYYY-MM-DD-absorb-{source-id}.md 생성:

• 신규 카드 수 + 토픽 분포
• 이미지 n장
• FAITHFUL / PARTIAL / DISTORTED 인용 비율
• related_cards 신규 링크 수
• DISTORTED 잔여가 있으면 hotspots 에 추가

운영로그 append + git 커밋 (필수 마무리)

# 1. log.md 에 한 줄 append (append-only — 기존 줄 수정 금지)
echo "- $(date +%F) [ingest] {source-id}: 카드 N장 ({topics}), 이미지 M장, FAITHFUL XX%" \
  >> ~/.claude/knowledge/log.md

# 2. 텍스트만 git 커밋 — 절대 bare `git add -A` 금지 (13GB 바이너리 스캔 유발)
cd ~/.claude/knowledge
git add -u && git add '*.md' '*.jsonl' '*.json'
git commit -m "ingest: {source-id} (N cards)"

참고: 매주 월 09:00 cron 이 scripts/weekly_maintenance.sh(lint + quote audit + index/카탈로그 재생성 + log append + 텍스트-only 커밋)를 돌리지만, ingest 직후의 log append 와 커밋은 이 파이프라인이 직접 수행한다.

금지 사항

1. 사용자 승인 없이 카드 스캐폴딩 금지 (Step 3 게이트)
2. 메인 세션에서 카드 body 를 직접 작성하지 않는다 (Haiku subagent 경유)
3. 인용을 paraphrase 하지 않는다 (slide verbatim)
4. 이미지 파일 이름을 임의로 변경하지 않는다 (phash dedup 영향)
5. source-id 변경·재사용은 기존 카드의 citation 이 깨지므로 금지 (중복이면 --force 로 재처리)

인덱스·로그 업데이트 (빠뜨리지 말 것)

~/.claude/knowledge/index.md                   ← 소스 맵 테이블에 행 추가
~/.claude/knowledge/source-log.md              ← ingest.py 가 자동 upsert
~/.claude/knowledge/summaries/cards.jsonl      ← 카드 카탈로그 (curate_topic_indexes.py 가 자동 재생성)
~/.claude/knowledge/summaries/courseware.jsonl ← JSONL 행 추가 (grep 용)
~/.claude/knowledge/topics/{topic}.md          ← 관련 섹션 보강 (중복 체크)
~/.claude/knowledge/log.md                     ← `- YYYY-MM-DD [ingest] ...` 한 줄 append (수동, 필수)

체크리스트

• Step 0: source-id 결정 + 중복 체크
• Step 1: slides/*.md 정규화 완료
• Step 2: images-pool + _meta.jsonl 갱신
• Step 3: 카드 제안 (aliases/keywords 포함) → 사용자 승인
• Step 4: 카드 스캐폴딩 + index 테이블 행 추가
• Step 5: Haiku subagent 로 body 작성 (aliases/keywords 채움) → apply 완료
• Step 6: relink + symmetrize + curate 실행 (summaries/cards.jsonl 재생성 확인)
• Step 7: cards_lint exit 0, FAITHFUL 90%+
• 완료 리포트 작성 + source-log.md / summaries.jsonl 갱신
• log.md 에 [ingest] 한 줄 append
• git 텍스트-only 커밋 (git add -u && git add '*.md' '*.jsonl' '*.json')

스크립트 (scripts/)

이 스킬은 다음 헬퍼 스크립트를 포함한다:

• normalize_text_source.py — Notion/LinkedIn/브런치/웹 URL/MD 를 slide-NN.md 로 변환
• relink_and_curate.py — P6+P7 전역 재계산 (link + symmetrize + curate)
• audit_new_quotes.py — 신규 카드의 인용 FAITHFUL 비율 측정

각 스크립트는 python3 scripts/{name}.py --help 로 사용법 확인.

관련 리소스

• 상위 개념 가이드: ~/.claude/knowledge/USAGE.md
• 글로벌 규칙: ~/.claude/CLAUDE.md "지식·인용 시스템"
• 설계 스펙: ~/.claude/knowledge/docs/2026-04-18-knowledge-system-redesign.md
• 선행 스킬:
  • ~/.claude/skills/knowledge-ingest/scripts/ — PPTX/PDF 파이프라인 라이브러리 (Step 1~2; 스킬 아님, REFERENCE.md 참조)
  • ~/.claude/skills/knowledge-cards-build/scripts/ — 스캐폴더·린터 라이브러리 (Step 3~4; 스킬 아님)
  • knowledge-query — 후보 스캔 (Step 6 이후 검증용)
• 참조 구현 (P4~P7): /tmp/classu-scaffold/ 에 남겨둔 스크립트 세트
  • link_related_cards.py, symmetrize_links.py, curate_topic_indexes.py, audit_quotes_v2.py, apply_bodies.py, apply_quote_fixes_v2.py

흡수 후에는?

새 카드가 추가되면 knowledge-cite 스킬이 다음 컨텐츠 작업에서 자동으로 활용한다 (Step 1 /knowledge-query 가 새 카드를 picking). 별도 통지 불필요.

저장소 규칙 (Hard rule · 2026-07-06)

새 소스는 반드시 이 스킬을 통해 ~/.claude/knowledge/ 허브로 흡수한다. 프로젝트 로컬 knowledge-base/ 등에 content.md 형태로 직접 추출·저장하는 것 금지 (허브-로컬 이중화가 생겨 인용 체계가 깨진다 — 2026-07-06 KB 통합 정리 참조: docs/2026-07-06-kb-hub-consolidation.md).