본문으로 건너뛰기

교재PDF에서 LLM-Wiki까지 — Docling 품질 선별 승격 파이프라인

스쿨셰프

2026.07.29

# [사례글] 교재 PDF에서 LLM-Wiki까지 — Docling 품질 선별 승격 파이프라인 구축기

> **작성일:** 2026-07-29  
> **작성자:** SkoolChef LLM-Wiki 운영  
> **관련 정본:** `CLAUDE.Governance.llm-wiki.md` · `DOCLING/050-scripts/` · `070-schema/ingest-policy.md`

---

### QA와 품질 점수

|**QA** (품질 보증)|**품질 점수**(`quality-scorer`)|
|---|---|---|
|**질문**|「깨진 링크·개수 오류 없나?」 | 「내용이 좋은 노트인가?」 |
|**결과**|OK/FAIL/NEEDS_REVIEW / CHECKLIST_PENDING | 0~100점, BEST·FULL·REVIEW |
|**비유**|공장 **출하 검사**|상품 **등급 분류** (A급만 골라 포장)|

**QA는 Quality Assurance의 약어입니다. 품질 보증 또는 품질 관리라고 부릅니다.**

---

## 소개

### 시도하고자 했던 것

경제학 교재 PDF를 Docling(문서 가공 도구)으로 가공한 뒤, 그 결과물을 SkoolChef LLM-Wiki(Obsidian vault·지식 창고)에 안전하게 넣는 지식관리(KM, Knowledge Management) 파이프라인을 만들고 싶었습니다.

구체적으로는 다음을 목표로 했습니다.

1. Docling `outbox`(가공 결과 대기함)에 쌓인 수백~수천 개의 마크다운(.md) 을 체계적으로 분류하고 품질을 점검한다.
2. 위키에 넣을 때 전부 복사하지 않고, 품질이 좋은 문서만 선별한다.
3. 매일 아침 Mac이 자동으로 QA(품질 보증)·재정제·품질 점수를 계산하고, 사람은 승인·검토만 한다.
4. 나중에도 헷갈리지 않도록 운영 규칙을 문서 하나(`CLAUDE.Governance.llm-wiki.md`)에 모은다 — 이 문서가 KM 운영 SSOT(단일 정본)이다.

### 그 이유

처음에는 `promote-manager.py`가 phase-23 **vault**의 806개 파일을 통째로 `010-raw/inbox/`(위키 수신함)에 복사했습니다.  
이 방식은 빠르지만 문제가 많았습니다.

| 문제 | 왜 심각한가 |
|---|---|
| 저품질·파편 문서까지 inbox에 쌓임 | Obsidian 검토 부담 폭증 |
|`ingest-policy.md`§F위반|「outbox 일괄 wiki 복사 금지·선별·승인 후inbox만」 |
| FAIL / NEEDS_REVIEW corpus|아침 알림만 오고 수동으로 .md고치기반복 |
| 폴더·용어 혼란 | `misi`/`gesi`/`ie200` vs `micro-economics` 등 corpus(과목 묶음) 이름 불일치 |

「공장(Docling) → 검사(QA) → 선별 포장 → 창고(LLM-Wiki)」흐름이 필요했고, 그 경계를 코드와 문서로 고정하려 했습니다.

---

## 진행 방법

### 사용한 도구

| 도구 | 역할 |
|---|---|
| Cursor (Agent) | AI 코딩 도우미. 파이프라인 설계·Python/Bash 스크립트 구현·Governance 문서 작성 |
| Docling | 교재 PDF → phase 1~24 단계별 가공 (프로젝트: `CLAUDE/PROJECTS/DOCLING/`) |
| SKOOLCHEF-LLM-WIKI|Obsidian vault·`010-raw/inbox`·`030-wiki` |
| macOS launchd | Mac 스케줄러.매일 09:00자동실행 (`setup-schedule.sh`)|
| Python 3| QA·품질점수·승격 스크립트 (별도 라이브러리 없이 stdlib only) |
| Obsidian | 최종 내용·링크를 사람이 눈으로 검토하는 앱 |

### 전체 구조 (한눈에)

```text
[Docling 공장]   [자동 검사]   [사람 선택]    [위키]
교재 PDF → phase-23 vault → QA + 재정제 → promote-select → Obsidian 검토
(수백~수천 md)  품질 점수표   BEST/FULL 선택  030-wiki 이동
```

- vault: Docling이 만든 개념 노트 묶음 폴더  
- QA: Quality Assurance — 구조·링크·개수 검사  
- promote-select: 「어떤 등급까지 위키 inbox에 복사할지」 사람이 고르는 도구  
- 030-wiki: 최종 공개·MoK 동기화 대상 폴더  

### Cursor에 요청한 핵심 프롬프트 (요약)
아래는 실제 작업 흐름을 반영한 **대표 프롬프트**입니다.한 번에 다 넣기보다,단계별로 나눠 요청했습니다.

1) 문제 인식 · 계획 수립

promote-manager.py가 phase-23 vault 전체 806개 md를 010-raw/inbox에 그대로 복사한다.
ingest-policy §F 「outbox 일괄 wiki 복사 금지」를 위반한다.
품질 점수 기반 자동 선별 + 관리자 라디오 체크리스트로 재설계하자. plan 활용해.

2) 품질 점수 · 승격 구현

Implement the plan: quality-scorer.py, promote-select.py,
promote-manager.py auto 수정, qa-auto-pipeline.sh Step 4 수정, PIPELINE-MAP 업데이트.
BEST = Tier A + score≥80, FULL = score≥60.


3) 자동 재정제

FAIL/NEEDS_REVIEW corpus는 자동으로 정제 1회 추가 진행 후
OK 또는 CHECKLIST_PENDING으로 올리자. 1회 후에도 안 되면 그대로 두고 다음 단계 진행.
아침 알림 → 수동 .md 수정 경로는 기본이 아니게 하자.

4) Governance 정본

CLAUDE.Governance.llm-wiki.md 파일을 SKOOLCHEF-LLM-WIKI에 두고,
앞으로 지식관리 운영상 중요 결정을 명시하는 SSOT로 만들고 참조 연결하자.

### 구현한 스크립트 (역할 요약)

| 파일 | 하는 일 |
|---|---|
|`qa-batch-report.py`|phase-24 전 corpus QA리포트 생성. 판정: OK / CHECKLIST_PENDING /FAIL/NEEDS_REVIEW|
|`qa-auto-repair.py`|FAIL·NEEDS_REVIEW corpus 문서 재정제 1회 (파편 문장 제거 + phase-24 메타 재생성)|
|`qa-auto-pipeline.sh`|QA + 재정제 + 품질 점수를 매일 아침 한 번에 실행하는 쉘 스크립트 |
|`quality-scorer.py`|concept(개념) 문서마다 0~100점· BEST/FULL/REVIEW 등급부여 |
|`promote-select.py`|터미널 라디오 UI(1=BEST, 2=FULL,3=CUSTOM) →inbox에만 복사|
|`setup-schedule.sh`|launchd 등록 (기본 매일 09:00) |

**경로:** `CLAUDE/PROJECTS/DOCLING/050-scripts/`

#### QA 리포트가 저장되는 곳

DOCLING/020-outbox/_qa-batch-report/
  YYYY-MM-DD_HH-MM-SS_qa-batch-report.md   ← 사람이 읽는 요약
  {corpus}_quality-report.json             ← 품질 점수 상세

QA= Quality Assurance(품질 보증). 「이 corpus, 위키에 넣어도 될 구조인가?」를 점검한 일일 검사표입니다.

### QA 판정 한 줄 설명

| 판정 | 의미 (초보자용) |
|---|---|
| OK| 자동 검사 통과 + Obsidian 체크리스트도 완료 |
| CHECKLIST_PENDING | 자동 검사는 대체로 OK. 사람이 Obsidian에서 13항목만 확인하면 됨 |
| NEEDS_REVIEW| 개수 불일치 등 구조 문제 → `qa-auto-repair` 자동 재정제 대상 |
| FAIL| 더 심각한 실패 |

### 품질 점수 기준 (0~100점)

`quality-scorer.py`가 **「내용이 좋은 노트인가」** 를 점수로 매깁니다. (QA와는 별개)

| 항목 | 배점 | 의미 (초보자용) |
|---|---:|---|
| 교재 내 등장 빈도·챕터 수 | 40 | 자주 나오는 핵심 concept(개념)일수록 높음 |
| Tier A/B | 20 | phase-10에서 매긴 중요도 등급 (A가 더 핵심) |
| 굵은 글씨 정의(`...`) | 15 | 「이게 뭔지」 한 줄 정의가 있는지 |
| 개념 간 링크 (crosslink) | 10 | 다른 concept과 wikilink로 연결됐는지 |
| 교재 섹션 링크 5개 이상 | 10 | 근거가 풍부한지 |
| definitions 파일 존재 | 5 | 정의 초안 파일이 있는지 |

승격 등급 (2026-07-29 확정) — `promote-select.py`에서 고르는 옵션

| 옵션 | 조건 | 예상 규모 (micro-economics 기준) |
|---|---|---|
| (1) BEST[추천] | Tier A + 점수 ≥80 | 약 2~7개/corpus |
| (2) FULL| 점수 ≥60 (BEST 포함) | 약 16~26개/corpus |
| (3) CUSTOM| 터미널에서 파일마다 y/n 직접 선택 | 원하는 만큼 |
| REVIEW| 60점 미만 | 기본 승격 대상 아님 (CUSTOM으로만 선택 가능) |

### 실제로 실행한 명령어

매일 자동 (등록 1회)

cd ~/Desktop/WORKSPACE_CLEAN/CLAUDE/PROJECTS/DOCLING
bash 050-scripts/setup-schedule.sh

**수동 전체 파이프라인 (승격 제외)**

```bash
cd ~/Desktop/WORKSPACE_CLEAN/CLAUDE/PROJECTS/DOCLING
bash 050-scripts/qa-auto-pipeline.sh
```

**단계별**

```bash
# 1) QA 리포트 (Quality Assurance — 품질 보증 검사)
python3 050-scripts/qa-batch-report.py

# 2) 문제 corpus 자동 재정제 (필요 시)
python3 050-scripts/qa-auto-repair.py

# 3) 품질 점수표 (0~100점, BEST/FULL/REVIEW)
python3 050-scripts/quality-scorer.py --show

# 4) 관리자 승격 — BEST 권장 (실제 복사 전 --dry-run 권장)
python3 050-scripts/promote-select.py micro-economics
python3 050-scripts/promote-select.py micro-economics --dry-run
```

**스케줄 즉시 테스트 (launchd)**

```bash
launchctl start com.docling.qa-auto-pipeline
```

### LLM-Wiki 폴더 구조 (숫자 접두)

숫자가 작을수록 **처리 전·가까운** 단계, 클수록 **완성·최종** 단계입니다.

| 폴더 | 역할 |
|---|---|
| `010-raw/inbox/{corpus}/` | Docling에서 선별 복사된 후보 문서 (검토 정본 경로) |
| `010-raw/sources/` | 처리 완료 원본 불변 보관 |
| `020-review/`| wiki 편입 전 대기소 (보조)|
| `030-wiki/` | 최종 지식 (Obsidian·MoK 동기화 대상)|
| `070-schema/ingest-policy.md`|vault 「헌법」 —무엇을 어디에 넣을 수 있는지 규칙|

### 캡처·이미지 안내 (직접 첨부 권장)

사례글을 커뮤니티에 올릴 때 아래 화면을 캡처하면 독자가 이해하기 쉽습니다.

| # | 캡처 대상 | 파일/위치 |
|---|---|---|
| 1 |QA 배치 리포트 요약표|`DOCLING/020-outbox/_qa-batch-report/*_qa-batch-report.md`|
| 2 |품질 점수 테이블|`python3 050-scripts/quality-scorer.py micro-economics --show` 터미널|
| 3 |promote-select 라디오UI|`python3 050-scripts/promote-select.py`실행화면|
| 4 | Obsidian inbox 폴더 트리|`010-raw/inbox/{corpus}/concepts/`(승격 실행후)|
| 5 | Governance 문서 목차 | `CLAUDE.Governance.llm-wiki.md` §1~§5 |

---

## 결과와 배운 점

### 무엇이 달라졌나

| Before | After |
|---|---|
| 806개 전량 inbox 복사 | BEST 기준 수 개~수십 개만 선별 복사 |
| FAIL 시 「.md 열어서 수동 수정」 | qa-auto-repair 자동 재정제 → 재검증 |
| 운영 규칙이 대화·코드에 흩어짐 | `CLAUDE.Governance.llm-wiki.md` 한곳에 SSOT |
| 아침 알림 = 곧 수동 작업 | 알림 = 재정제 후에도 미해결일 때만 |

검증 예시: `macro-economics-700` corpus에서 파편 bullet 36건 → 재정제 후 0건, QA 판정 NEEDS_REVIEW → CHECKLIST_PENDING으로 개선.

### 나만의 꿀팁

1. 자동화 경계를 명확히— Mac은 「QA·점수표」까지, 사람은 「승격·Obsidian·030-wiki 이동」만.
2. BEST부터 시작— 처음에는 (1) BEST만 넣고 품질 확인 후 FULL을 고려.
3. `--dry-run` 활용 — `promote-select.py --dry-run --all-best` 로 실제 복사 없이개수만 확인.
4. 리포트 폴더 북마크 — `020-outbox/_qa-batch-report/` 만 보면 하루 QA 상태 파악 가능.
5. Governance §9에 결정 로그 — 「왜 80점으로 올렸지?」를 미래의 나를 위해 남김.

### 시행착오

| 시행착오 | 원인 | 해결 |
|---|---|---|
| `qa-auto-repair` 후에도 NEEDS_REVIEW | `definitions/` 폴더 없는 corpus에서 정의 수 0으로 집계 | vault 구조에 맞게 definitions = concepts 수로 보정 |
| 재정제가 두 번째부터 안 됨 | corpus당 영구 1회 제한 | pipeline 실행마다 1회 (`--pipeline-id`) 로 변경 |
| corpus-first 심볼릭 링크후 QA 5개만 잡힘 | `qa-batch-report`가 symlink 중복 집계 | 실제 디렉터리만 스캔하도록 수정 |
| `phase-` 접두 폴더명 너무 김 | 28,650+ 하드코딩 경로 | corpus-first 심볼릭 링크 뷰 추가 (이름 변경 대신) |

### 아직 도움이 필요한 부분

- Obsidian → `030-wiki/` 이동 은 여전히 수동. (의도적 — wiki 품질 최종 관문)
- broken link(깨진 링크)가 있는 corpus는 자동 재정제만으로는 안 될 수 있음 → 수동 phase 재실행 검토.
- 캡처·스크린샷 은 운영 문서에 아직 미비 — 커뮤니티 게시용으로 보강 예정.

### 앞으로의 계획

1. `promote-select` 실행 후 `020-review/` 심볼릭 링크 자동 생성 (선택).
2. Obsidian 체크리스트 완료 시 corpus 상태를 `docling_fin/index.json`에 반영.
3. `030-wiki/` 편입 시 `_ops/promote-document.py approve` 와 연계 검토.
4. 경제학 5개 corpus에 대해 BEST 승격 1회 실전 후 Governance §9에 결과 기록.

---

## 도움 받은 글 (옵션)

| 참고 | 내용 |
|---|---|
|Karpathy LLM Wiki | wiki를 flat 구조 + wikilink로 운영하는 기본 철학 |
|프로젝트 내부 `070-schema/ingest-policy.md`| raw → wiki 헌법, Docling §F 「일괄 복사 금지」 |
|`DOCLING/.cursor/skills/docling-pipeline/PIPELINE-MAP.md`| phase 1~42 타임라인·스크립트 맵 |
|Cursor Agent + Plan 모드| 대규모 파이프라인을 단계별 todo로 쪼개 구현 |

---

## 부록: 하루 타임라인 (최종본)

```text
[전날 밤]
  Docling phase 1~24 가공 완료

[매일 09:00 — Mac 자동 (launchd)] qa-auto-pipeline.sh
    Step 1    QA 리포트 (Quality Assurance — 품질 보증 검사)
    Step 1.5  FAIL/NEEDS_REVIEW → qa-auto-repair 자동 재정제 1회 → 재검증
    Step 3    재정제 후에도 미해결 시에만 macOS 알림
    Step 4    quality-scorer → 품질 점수 리포트 (BEST/FULL/REVIEW)

[관리자 — 원할 때]
  1) (알림 받았을 때만) _qa-batch-report/ 최신 .md 확인
  2) python3 050-scripts/promote-select.py  → (1) BEST
  3) Obsidian: 010-raw/inbox/{corpus}/ 검토
  4) 승인 → 030-wiki/ 이동
```

---

## 부록: 관련 파일 경로

```text
SKOOLCHEF-LLM-WIKI/
  CLAUDE.Governance.llm-wiki.md    ← KM 운영 SSOT (단일 정본)
  010-raw/inbox/                    ← 승격 후보 (inbox)
  030-wiki/                         ← 최종 지식
  docs/KM-CASE-STUDY-20260729-docling-to-llm-wiki.md  ← 이 사례글

DOCLING/
  050-scripts/qa-auto-pipeline.sh
  050-scripts/qa-batch-report.py   ← QA (Quality Assurance) 리포트
  050-scripts/quality-scorer.py
  050-scripts/promote-select.py
  020-outbox/_qa-batch-report/     ← QA·품질 리포트 저장 폴더
```
## 용어·약어 사전 (초보자용)

이 사례글에는 IT·지식관리 용어가 많이 나옵니다. **처음 보는 단어는 여기서 찾아보세요.**

| 약어·용어 | 풀어 쓰면 | 이 글에서의 의미 |
|---|---|---|
| **QA** | **Quality Assurance** (품질 보증·품질 관리) | Docling 산출물이 **깨지지 않았는지·구조가 맞는지** 자동 검사하는 단계. `qa-batch-report.py`가 매일 리포트를 만듦 |
| **KM** | **Knowledge Management** (지식 관리) | 노트·문서를 모으고, 정리하고, 위키에 반영하는 전체운영|
| ChatGPT·Claude 같은 AI. 여기서는 **LLM이 읽기 좋은 위키**를 만든다는 뜻으로 씀 |
| **LLM-Wiki** |LLM용 위키| SkoolChef 프로젝트의 Obsidian 지식 창고 (`SKOOLCHEF-LLM-WIKI/`) |
| **vault** |금고·보관함|Obsidian에서 **한 프로젝트 폴더 전체**를 부르는 말. LLM-Wiki vault = 위키 폴더 통째|
|**outbox**|발송 대기함|Docling **공장 밖**에 쌓인 가공 결과물.아직 위키에 넣기 전 단계 |
|**inbox**|수신함|위키 **안**의 `010-raw/inbox/`—검토·승인 대기중인 문서가 들어가는 곳 |
| **corpus** | 말뭉치·묶음 | 교재 한 권(또는 한 과목) 단위 묶음. 예: `micro-economics` (미시경제학) |
| **phase** | 단계 | Docling 파이프라인의 작업 순서. phase-23 = 개념 노트 vault, phase-24 = QA 단계 |
| **SSOT** | **Single Source of Truth** (단일 정본) | 「이건 여기 문서가 맞다」고 정해 둔 **공식 기준 문서** 하나 |
| **Governance** | 거버넌스·운영 규칙 | 누가 무엇을 어떻게 할지 정한 **운영 헌법** 문서 |
| **Obsidian** | 옵시디언 | 마크다운 노트를 링크로 연결해 보는 **데스크톱 메모 앱** |
| **MoK** | **Map of Knowledge** (지식 지도) | LLM-Wiki를 브라우저에서 탐색하는 UI (Mother of Knowledge 계열) |
| **Docling** |독링|PDF등을 구조화된 마크다운으로 바꾸는 **문서 가공 파이프라인**프로젝트 |
| **BEST/FULL/REVIEW**|승격 등급 이름|BEST=핵심만, FULL=넓게,REVIEW=점수 낮아 보류·직접 선택|
| **Tier A/B**|등급|개념의 **중요도** (A가 더 핵심). Docling phase-10에서 부여 
| **FAIL**|실패|QA에서 **자동 검사 통과 못 함**|
| **NEEDS_REVIEW**| 검토 필요 | 구조·카운트 등 **문제가 있어 사람·재정제가 필요** |
| **CHECKLIST_PENDING** | 체크리스트 대기 | 자동 검사는 대체로 OK, **Obsidian에서 사람이 13항목 체크**만 남음 |
| **launchd** | 런치디 | macOS **예약 실행** (매일 09:00에 스크립트 자동 실행) |
| **CLI** | **Command Line Interface** | 터미널에서 `python3 ...` 처럼 **명령어로 실행**하는 방식 |
| **dry-run** | 모의 실행 | **실제 복사·저장 없이** 결과만 미리 보기 (`--dry-run`) |
| **wikilink** | 위키 링크 | `[[수요]]` 처럼 다른 노트로 연결하는 Obsidian 링크 |
---

*이 문서는 2026-07-29 Docling 품질 선별 승격 파이프라인 구축 작업을 바탕으로 작성되었습니다. 운영 규칙의 최신 정본은 항상 `CLAUDE.Governance.llm-wiki.md`를 따릅니다.*
2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

꾸
꾸기작2026.08.07

교재 PDF를 inbox에서 LLM-Wiki로 승격시키는 과정을 QA(품질 보증)와 품질 점수라는 두 축으로 나눠 설계하신 부분이 명확합니다. '깨진 링크·개수 오류 없나'와 '내용이 좋은 노트인가'를 서로 다른 질문으로 분리해 각각 스크립트를 배정하신 구조가 체계적입니다.

0~100점으로 채점해 BEST/FULL/REVIEW로 등급을 나누고, FAIL·NEEDS_REVIEW corpus는 자동 재정제를 1회만 시도한 뒤 그래도 안 되면 그대로 두고 다음 단계로 넘어가게 하신 규칙이 실용적입니다. 아침 알림을 받고 수동으로 .md를 고치는 반복 작업을 기본 경로에서 빼기로 한 결정도 자동화의 방향을 잘 잡은 것 같습니다.

CLAUDE.Governance.llm-wiki.md를 단일 정본(SSOT)으로 두고 운영상 중요 결정을 여기에 명시적으로 연결해두신 부분이 나중에 규칙이 흩어지는 걸 막아줄 것 같습니다. quality-scorer.py, promote-select.py, promote-manager.py로 역할을 나눠 구현하신 스크립트 구성도 재사용하기 좋은 구조입니다.

IT·지식관리 용어가 많이 나올 수 있는 글인데 초보자를 위한 용어·약어 사전까지 따로 만들어두신 배려도 좋습니다. launchd로 스케줄까지 연결해 파이프라인이 계속 돌아가게 하신 다음 단계도 응원합니다!

DECK 프로필 이미지
DECK2026.08.07

806개 파일을 한꺼번에 옮긴 방식은 결국 사람의 수정 부담을 크게 남겼습니다. 그래서 한 묶음씩 검사하고 사람이 골라 올리도록 바꾼 뒤, 파편 항목 36건이 사라진 결과가 더 반갑고요. 매일 쌓이는 후보를 고르는 실제 화면이 곁들여지면 선택 기준도 더 와닿겠네요.

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기