당신의 과목, 당신의 패턴, 당신의 오답, 당신의 치트시트.
당신의 자료에서 출발해 한 과목에 영속적으로 머무는 학습 그래프를 만드는 Claude Code 플러그인입니다 — 모든 산출물이 일반 실러버스가 아니라 당신의 손끝에서 빚어집니다.
English README · taewoopark.com — 저자 사이트
PAIDEIA 패밀리 — 하나의 학습 엔진, 모든 에이전트 런타임
| 플랫폼 | 저장소 | 설명 |
|---|---|---|
 |
PAIDEIA | 원본 — Claude Code 플러그인. |
 |
PAIDEIA-codex | OpenAI Codex CLI 에디션. |
 |
PAIDEIA-opencode | opencode 에디션. |
 |
PAIDEIA-Hermes | hermes-agent 플러그인. |
 |
PAIDEIA-mcp | 독립형 로컬 MCP 서버 — Alt 로컬 모델에서 PAIDEIA 구동. |
 |
PAIDEIA-Alt | Exam Radar — Alt 강의 캡처 플러그인 (altalt.org). |
일반적인 학습 도구는 평균적인 실러버스를 가르칩니다. Paideia는 당신의 실러버스를 가르칩니다 —
당신의 교수님 강의노트, 당신의 숙제 경향, 당신의 필기, 당신의 오답에서 출발해서요. 모든 산출물은 당신이 직접 편집할 수 있는 마크다운 파일입니다.
고대 그리스에서 **Παιδεία(파이데이아)**는 수동적인 학생에게 사실을 주입하는 일이 아니었습니다. 그것은 원전과의 구조화된 만남, 스승 아래에서의 연습, 그리고 피드백을 더 깊은 수정으로 되돌려 보내는 성찰적 대화를 통한 — 한 인간을 평생에 걸쳐 형성해 가는 일이었습니다.
이 플러그인은 그 순환을 수학·물리·공학 과목의 시험 준비라는 구체적이고 한정된 문제에 맞추어 구현합니다.
ingest ──▶ analyze ──▶ drill ──▶ grade ──▶ weakmap ──▶ cheatsheet
▲ │
└────────────────── feedback loop ───────────────────────┘
각 단계는 당신의 코스 폴더에 영원히 남는 마크다운 파일 하나씩을 남깁니다. 휘발되는 것은 없고, API 뒤에 숨는 것도 없습니다. 다음 자금 한파가 닥쳐도 멈추는 것이 없습니다.
대부분의 학습 도구는 당신의 과목, 당신의 교수님, 당신의 실수에 맞춰 개인화되지 못합니다 — 이들이 파는 상품 자체가 "일반적인 커리큘럼"이기 때문입니다.
- Coursera, edX, Khan Academy — 고정된 커리큘럼. 당신 교수님이 실제로 어디를 강조하시는지 알 길이 없습니다.
- Quizlet, Anki, Brainscape — 카드 하나하나를 당신이 직접 큐레이션해야 하고, 당신 과목의 해답지에서 패턴을 뽑아 주지 않습니다.
- Chegg, Course Hero — 범용 해답지. 당신 과목의 반복되는 관용구(idiom) 중심으로 정리되어 있지 않습니다.
- Brilliant, Duolingo Max, Khanmigo — 범용 문제집. 당신이 지난달 HW2에서 뭘 틀렸는지 알지 못합니다.
- ChatGPT Study Mode, Gemini "Deep Study", NotebookLM — 과목별 영속 상태가 없습니다. 세션을 새로 열 때마다 콜드 스타트이고, 지난주의 실수는 이번 주 드릴에 반영되지 않습니다 — 당신이 매번 다시 업로드하고 다시 설명하지 않는 한요.
이들 중 어느 것도 당신 앞에 놓인 그 특정 자료를 기반으로 이해를 형성하지 못합니다. 모든 학생에게 같은 답을 내어 줄 뿐이지요. Paideia는 반대 방향입니다: 모든 산출물이 당신 폴더의 강의노트·교재 챕터·숙제·풀이·필기 시도에서 파생되고, 당신이 직접 편집할 수 있는 평범한 마크다운으로 영구히 누적됩니다.
| 축 | Paideia | 일반적인 교육 SaaS / LLM 챗 |
|---|---|---|
풀이 패턴 (P1..Pk) |
당신 과목의 해답지에서 직접 추출하고, 당신의 파일을 인용합니다 | 범용 교과서 목록, 혹은 없음 |
| 드릴 우선순위 | 당신 교수님의 숙제 강조도(HW 밀도 = 시험 티어)로 가중됩니다 | 고정 커리큘럼 또는 당신의 감 |
| 치트시트 | 당신의 errors/log.md — 당신이 실제로 틀린 것으로 구성됩니다 |
실러버스 보일러플레이트 |
| 세션 간 과목 상태 | 마크다운 + YAML로 영속, 작업할수록 축적됩니다 | 대화 초기화, 이력은 유료 티어 |
| 산출물이 마음에 안 들 때 | 에디터로 .md를 열어 수정, 저장 |
읽기 전용 UI |
| 지난 학기 준비를 다음 학기로 | 과목 폴더를 fork해서 차이만 수정 | 처음부터 다시 |
| 자신의 이해에 대한 버전 관리 | 어떤 산출물이든 git log / git diff |
외부에 노출되지 않음 |
| 산출물이 있는 곳 | 당신의 디스크, 텍스트 파일로 | 원격 DB, 유료 티어에서만 내보내기 |
플러그인은 유료 도구인 Claude Code를 써서 무거운 일을 처리하지만, 그 결과물은 전부 당신 디스크 위의 평범한 마크다운입니다. 나중에 다른 모델 러너로 옮기시거나 Claude Code 구독을 잠시 중단하셔도, course-index·patterns·오류 로그·weakmap·치트시트는 여전히 당신이 열어 읽고, 수정하고, diff할 수 있습니다. 플러그인은 뼈대이고, 학습 그래프는 당신의 것입니다.
기본 설정에서 OCR은 이미 사용 중이신 Claude Code 세션 안의 Claude 네이티브 비전으로 처리됩니다. 필기 PDF를 기기 밖으로 내보내고 싶지 않으시다면 ollama pull qwen3-vl:8b로 약 6 GB 모델 가중치를 한 번 내려받으면, 그 뒤 모든 OCR이 로컬 Qwen3-VL 추론으로 전환됩니다. 어느 쪽을 고르시든 이후의 산출물(패턴, 커버리지, weakmap, 치트시트, 오류 로그)은 전부 당신 디스크 위의 평범한 마크다운입니다.
대부분의 "똑똑하게 공부하는 법"은 사각지대부터 공략하라고 말합니다. 그러나 이 조언은 방향이 반대입니다. 교수님은 이미 숙제를 배정하는 것으로 시험 포인트의 위치를 알려 주셨습니다. 숙제가 몰린 절은 🔥🔥 Exam-primary이고, 숙제가 전혀 없는 절은 ⚪ Low-risk일 뿐 "숨겨진 함정"이 아닙니다. 교수님의 침묵은 그 주제가 시험 범위 바깥이라는 가장 강력한 신호입니다.
Paideia의 우선순위는 이 원리를 명시적으로 반영합니다. 모든 드릴 명령이 기본값으로 이 티어링을 따릅니다.
| 티어 | 해당 절의 숙제 수 | 처리 방식 | 모의고사 점수 비중 |
|---|---|---|---|
| 🔥🔥 Exam-primary | 3+ | 가장 먼저, 가장 강도 높게 드릴 | ≥70% |
| 🔥 Exam-likely | 2 | 그 다음 드릴 | ~25% |
| 🟡 Exam-possible | 1 | 가볍게 복습 | ≤5% |
| ⚪ Low-risk | 0 | 참조·독서 용도만 | 0 |
/paideia:quiz all, /paideia:mock, /paideia:hwmap hot 모두 이 가중치를 존중합니다. 만약 사용자가 ⚪ 절을 굳이 드릴하겠다고 요청하면, 플러그인은 한 번은 따라 주지만 출제 확률이 낮다는 경고를 덧붙입니다. 제한된 시간은 상상 속 함정보다 훨씬 가치 있기 때문입니다.
paideia_actual_claude_cut_fast.mp4
Claude Code CLI에서 실행한 모습.
그리고 Claude 데스크톱 앱에서 — 같은 플러그인이 analyze · hwmap 산출물을 나란히 렌더링합니다:
summary.md — /paideia:analyze가 생성한 주제 트리
|
patterns.md — /paideia:analyze가 추출한 풀이 패턴 카드
|
coverage.md — /paideia:analyze가 만든 절 → 출제 확률 매핑
|
/paideia:hwmap — HW 밀도 기반 드릴 우선순위
|
권장 환경: Paideia는 Claude 데스크톱 앱에서 가장 매끄럽게 동작합니다 — 마크다운·LaTeX·표가 에이전트 출력 시점에 그대로 렌더링되어, analyze·hwmap 산출물을 대화창에서 곧바로 읽으실 수 있습니다. CLI(위 영상)를 선호하신다면, Obsidian을 코스 폴더에 걸어 함께 쓰시기를 권합니다. 아래 읽기 팁: Obsidian을 쓰세요 섹션을 참고해 주세요.
| 단계 | 하는 일 | 명령 | 산출물 |
|---|---|---|---|
| 대면 (Encounter) | 교수님이 보낸 신호를 읽습니다 | /paideia:ingest |
converted/**/*.md — 모든 강의노트·교재 챕터·숙제·풀이를 깨끗한 마크다운으로 |
| 구조화 (Structure) | 과목 고유의 문법을 추출합니다 | /paideia:analyze |
course-index/{summary,patterns,coverage}.md — 주제 트리, 반복되는 풀이 패턴 (P1..Pk), 숙제 밀도 기반 출제 티어 |
| 연습 (Practice) | 교수님이 실제로 시험하는 것에 가중치를 두어 능동 회상을 수행합니다 | /paideia:quiz, /paideia:twin, /paideia:blind, /paideia:chain, /paideia:mock |
quizzes/, twins/, chain/, mock/ — 종이에 풀 문제들 |
| 성찰 (Reflection) | 손으로 쓴 답안이 채점 결과로 바뀝니다 | /paideia:grade |
answers/converted/<name>.md + errors/log.md — Claude 비전(기본) / Ollama Qwen3-VL / Tesseract 중 선택한 엔진으로 OCR, 전략 기반 채점 |
| 진단 (Diagnosis) | 오류를 우선순위가 매겨진 약점 리포트로 압축합니다 | /paideia:weakmap |
weakmap/weakmap_<ts>.md — append-only 이력 |
| 증류 (Distillation) | 오류에서 출발한 한 장짜리 인쇄물을 만듭니다 | /paideia:cheatsheet, /paideia:derive, /paideia:pattern |
cheatsheet/final.md, derivations/<slug>.md — 실제로 필요한 것만 참조 |
보조 명령: /paideia:hwmap은 숙제 밀도 기반 출제 확률을 띄워 줍니다. /paideia:init-course는 새 코스 폴더를 부트스트랩합니다.
필수 (두 설치 경로 공통)
- Python 3.9+ (플러그인이 의존성을 확인하고 설치를 제안합니다)
- Unix 계열 쉘 (
bash/zsh). 부트스트랩과 채점 명령이 heredoc·mkdir -p·mktemp·서브쉘 백그라운드 실행을 쓰기 때문에, Windows 네이티브cmd/ PowerShell은 현재 지원하지 않습니다. - macOS:
brew install poppler tesseract tesseract-lang - Linux (Debian/Ubuntu):
apt-get install poppler-utils tesseract-ocr tesseract-ocr-kor - Windows: WSL2를 설치하신 뒤, WSL 쉘 안에서 위의 Linux 경로를 그대로 따라 주세요.
poppler와tesseract를PATH에 올려 두셨다면 Git Bash도 동작합니다.
선택 — --ocr=ollama 모드를 쓰고 싶을 때만 (페이지 이미지가 기기 밖으로 전혀 나가지 않습니다)
ollama+qwen3-vl:8b모델 (~6 GB). macOS:brew install ollama. Linux: ollama 설치 스크립트. 이후ollama pull qwen3-vl:8b.
Ollama를 설치하지 않으셔도 괜찮습니다. 기본 OCR 엔진은 Claude 자체의 비전 기능이라, 별도로 설치할 것도 Claude Code 외에 추가로 구독할 서비스도 없습니다.
Paideia의 산출물 — summary.md, patterns.md, coverage.md, /paideia:hwmap 표 — 은 데스크톱 앱에서 에이전트가 출력하는 그대로 인라인 렌더링됩니다 (위 스크린샷 참고). 별도의 리더를 띄울 필요가 없어 가장 매끄러운 경험이 됩니다.
-
claude.ai/download에서 Claude 데스크톱 앱을 설치하고 로그인해 주세요. macOS / Windows / Linux 모두 지원됩니다.
-
새 대화창을 열고 각 줄을 한 번에 하나씩 메시지로 보내 주세요:
/plugin marketplace add https://github.com/OPTIMETA/PAIDEIA.git/plugin install paideia@paideia-marketplace -
이제 모든 대화창에서 18개의
/paideia:슬래시 명령을 쓰실 수 있습니다. 이어서 아래 코스별 부트스트랩으로 넘어가세요.
터미널을 선호하신다면, 먼저 Claude Code CLI를 설치하신 뒤 동일한 두 명령을 claude 안에서 각 줄을 한 번에 하나씩 실행해 주세요:
/plugin marketplace add https://github.com/OPTIMETA/PAIDEIA.git
/plugin install paideia@paideia-marketplace
URL을 전부 적는 이유가 있습니다 —
owner/repo짧은 형태를 쓰면 CLI가 SSH를 먼저 시도하기 때문에, GitHub에 SSH 키가 등록돼 있지 않은 환경에서는 실패합니다. HTTPS URL을 쓰면 언제나 동작합니다.
설치가 끝나면 18개의 슬래시 명령이 /paideia: 네임스페이스로 제공됩니다. CLI를 쓰신다면 아래 읽기 팁: Obsidian을 쓰세요 섹션을 참고해 Obsidian을 함께 설정해 두세요 — 터미널은 수식을 렌더링하지 못합니다.
해당 코스용으로 쓰실 폴더 안에서 Claude Code를 여신 뒤 다음을 실행해 주세요.
/paideia:init-course
이 명령은 대화식으로 다음을 수행합니다.
- Python / poppler / tesseract 의존성을 확인하고, 누락된 항목은 설치를 제안합니다 (ollama는 아래 4단계에서
ollama엔진을 선택하신 경우에만 점검합니다) - 이 코스에서 사용할 인터페이스 언어(
en기본값 또는ko)를 묻습니다. 이후 이 폴더의 모든 paideia 프롬프트, 드릴 안내, 생성되는 MD 본문은 선택하신 언어로 출력됩니다. 구조적 토큰(파일 경로, 슬래시 커맨드명, 패턴 IDP1, P2, …, YAML 키, tier 마커)은 언어와 무관하게 항상 영어로 유지됩니다 COURSE_NAME,EXAM_DATE,EXAM_TYPE,USER_WEAK_ZONES값을 입력받습니다- 기본 OCR 엔진을 고릅니다 —
claude(네이티브 비전, 추가 설치 없음) /ollama(로컬 Qwen3-VL, 약 6 GB 모델을 백그라운드에서 받음) /tesseract(가장 가볍고 빠름, 필기 정확도는 낮음) - 디렉토리 골격을 생성합니다 (
materials/,converted/,course-index/,quizzes/,mock/,twins/,chain/,derivations/,cheatsheet/,weakmap/,answers/converted/,errors/) .course-meta(INTERFACE_LANG+OCR_ENGINE을 담고 있으며/paideia:grade,session_start.py,vision_ocr.py, 모든 슬래시 커맨드가 읽습니다)와 프로젝트 수준CLAUDE.md를 작성합니다- 이 폴더 전용 statusline(
scripts/statusline.py)과SessionStart훅(scripts/session_start.py)을.claude/settings.json에 함께 걸어 둡니다. statusline은 이 폴더에 들어와 있을 때만paideia · <COURSE> · D-N · <phase> · P<k> ↑를 표시하고, 훅은 새 대화가 열릴 때마다 같은 신호(D-N·phase·최다 실수 패턴)를 2줄 리마인더로 첫 턴 컨텍스트에 출력합니다 git init을 수행해 첫 키 입력부터 준비 과정이 버전 관리되도록 합니다
개별 채점 호출에서는 엔진을 그때그때 덮어쓰실 수 있습니다. 예: /paideia:grade --ocr=claude path/to/answer.pdf.
언어 지원이 추가되기 전에 초기화한 코스라면 .course-meta에 INTERFACE_LANG 필드가 없습니다 — 플러그인은 이 경우를 en으로 처리하여 모든 프롬프트와 출력을 영어로 전환합니다. 기존 코스를 계속 한국어로 쓰고 싶으시면 .course-meta에 한 줄만 추가해 주세요:
INTERFACE_LANG: ko
이게 마이그레이션의 전부입니다. 재초기화는 필요 없습니다. 신규 코스는 /paideia:init-course 2단계의 언어 선택을 통해 자동으로 설정됩니다.
/paideia:init-course를 실행하고 나면 코스 폴더가 다음과 같이 구성됩니다.
my-course/
├── .course-meta # 코스명, 시험일, 인터페이스 언어(en|ko), OCR 엔진 설정
├── CLAUDE.md # Claude Code가 매 턴 읽는 프로젝트 규칙
├── .gitignore # 답안 PDF, 정답 키, OCR 임시물 제외
├── .claude/
│ └── settings.json # 이 폴더 전용 PAIDEIA statusline 설정
│
├── materials/ # 직접 원본을 넣는 곳 (PDF 또는 MD)
│ ├── lectures/ # 강의노트 / 슬라이드
│ ├── textbook/ # 교재 챕터
│ ├── homework/ # 과제 문제지
│ └── solutions/ # 과제 풀이 / 예제 풀이
│
├── converted/ # 자동 생성된 마크다운 — 직접 수정하지 마세요
│ ├── lectures/ # /paideia:ingest의 산출물 (비전으로 전사한 LaTeX)
│ ├── textbook/
│ ├── homework/
│ └── solutions/
│
├── course-index/ # 지식 베이스 — /paideia:analyze가 생성
│ ├── summary.md # 주제 트리 (§1, §1.1, §2, …)
│ ├── patterns.md # 반복되는 풀이 패턴, P1, P2, … 라벨
│ ├── coverage.md # HW ↔ § 매핑 + 🔥🔥 / 🔥 / 🟡 / ⚪ 시험 티어
│ └── radar.md # 강의 강조 신호 — /paideia:alt가 임포트
│
├── answers/ # 직접 필기 스캔 PDF를 넣는 곳
│ └── converted/ # /paideia:grade가 OCR한 마크다운을 여기에 씁니다
│
├── errors/
│ └── log.md # append-only YAML 오류 로그 (/weakmap, /cheatsheet의 원천)
│
├── quizzes/ # /paideia:quiz — 문제마다 숨겨진 _answers.md 형제
├── mock/ # /paideia:mock — 모의고사 (숨겨진 _sol.md 형제)
├── twins/ # /paideia:twin — 같은 패턴, 다른 표면
├── chain/ # /paideia:chain — 다중 패턴 통합 문제
├── derivations/ # /paideia:derive — 참조용 유도 모음
├── cheatsheet/ # /paideia:cheatsheet — 오류 기반 한 장 요약 (+ 선택적 PDF)
└── weakmap/ # /paideia:weakmap — 시간순, append-only 이력
직접 손으로 관리하시는 디렉토리는 두 개뿐입니다.
materials/— 원본 PDF(또는 MD)를 해당 하위 폴더에 넣어 주세요.answers/— 필기 스캔 PDF를 루트에 넣어 주세요. OCR 결과는answers/converted/아래에 생깁니다.
나머지 디렉토리는 모두 슬래시 명령이 만들어내는 산출물이니, 언제든 삭제하고 재생성하시거나, git log <dir>로 시간에 따른 자기 진전을 확인하시거나, Obsidian을 폴더 전체에 걸어 vault로 여시면 됩니다.
Claude 데스크톱 앱이 아닌 CLI에서 Paideia를 운용하신다면 이 도구를 함께 쓰시기를 권합니다. Paideia는 모든 것을 LaTeX 수식($...$, $$...$$)이 포함된 평범한 마크다운으로 씁니다. 어떤 에디터로도 읽으실 수 있지만, **Obsidian**이 가장 자연스러운 선택입니다.
- 별도 설정 없이 MathJax로
$...$,$$...$$수식을 렌더링합니다 - 백링크를 통해
quizzes/q_<ts>.md에서 인용된converted/lectures/chN.md §K로 클릭 한 번에 이동할 수 있습니다 - 코스 폴더 전체가 그 자체로 볼트(vault)입니다 — Obsidian을
~/courses/my-course로 향하게 하면, 모든 파일이 검색 가능한 그래프가 됩니다 - 완전히 오프라인, 무료, 로컬에서 동작합니다. Paideia의 철학과 정확히 맞닿아 있습니다 — 당신의 필기, 당신의 디스크, 당신의 도구
마크다운 수식 확장을 설치한 VS Code도 가능합니다. 다만 터미널은 — 마크다운 프리뷰를 얹더라도 — 수식을 읽기에 적합하지 않으니 억지로 맞추지 마세요.
Obsidian이 '읽는 쪽' 동반자라면, **Alt**는 강의가 들어오는 '담는 쪽' 동반자입니다. Alt는 강의를 녹음·전사하고, 그 안에서 OPTIMETA의 Exam Radar 플러그인이 교수가 입으로 강조한 정도로 토픽을 추려 줍니다. 그 결과를 /paideia:alt로 Paideia에 흘려보내면 비로소 고리가 닫힙니다 — 강의를 듣고 → 담고 → 시험 신호를 뽑고 → 중요한 것만 공부하는 전 과정이 흩어진 도구가 아니라 하나의 워크플로우가 됩니다. 강의 쪽은 Alt가, 깊은 개인 학습은 Paideia가, 그 사이의 다리는 Exam Radar가 맡습니다.
cp ~/textbooks/ch*.pdf ~/courses/my-course/materials/textbook/
cp ~/lecture-notes/wk*.pdf ~/courses/my-course/materials/lectures/
cp ~/hw/hw*.pdf ~/courses/my-course/materials/homework/
cp ~/hw/hw*_sol.pdf ~/courses/my-course/materials/solutions/Claude Code에서:
/paideia:ingest # 모든 PDF → 비전 파이프라인 (병렬 에이전트, LaTeX 충실)
/paideia:analyze <약점 힌트> # 패턴 + 커버리지 + 요약 생성
/paideia:hwmap hot # 🔥🔥 exam-primary 영역 띄우기
/paideia:quiz all 20 # 광범위 진단, 20문항
# 종이에 풀고 (40분), answers/diagnostic.pdf로 스캔
/paideia:grade # 로컬 qwen3-vl OCR + 전략 채점
/paideia:weakmap # 우선순위 약점 리포트
/paideia:blind hw3-p2 # 이미 풀어 본 문제의 전략만 점검
/paideia:twin hw3-p2 # 같은 패턴, 새로운 표면의 변형 문제
/paideia:chain 3 # 3개 패턴이 결합된 통합 문제
/paideia:quiz weakmap 5 # 최신 weakmap을 겨냥한 5문항
/paideia:mock 90 # 숙제 밀도로 가중된 90분 모의고사
# 종이에 풀고 answers/mock_<ts>.pdf로 스캔
/paideia:grade # 모의고사 채점
/paideia:cheatsheet --pdf # 오류에서 출발한 한 장짜리 치트시트
/paideia:weakmap # 약점 구역을 한 번 더 훑기
/paideia:weakmap # 상위 3개만. 새로운 것을 배우지는 마세요.
| 명령 | 용도 |
|---|---|
/paideia:init-course |
새 코스 폴더 부트스트랩 (의존성 확인, 골격, 메타데이터 입력, 백그라운드 ollama pull) |
/paideia:doctor [--fix] |
설치 + 워크스페이스 진단 (Python, poppler, tesseract, Ollama/Qwen3-VL, 코스 폴더, .course-meta, 쓰기 경로, statusline 와이어링). --fix는 권한이 필요 없는 문제만 자동 복구 |
/paideia:ingest [--force] |
materials/**의 모든 PDF를 converted/**의 마크다운으로 변환. 비전 파이프라인(PDF당 하나씩 병렬 에이전트, LaTeX 충실)으로 일괄 처리합니다. |
/paideia:analyze [힌트] |
course-index/{summary,patterns,coverage}.md 구축 |
/paideia:reindex [--fix] |
멱등·analyze 미호출 재색인: retired coverage.md 마커 → canonical 어휘 재작성; errors/log.md nature/phase facet 디스크 물질화 (헤더 키 == 데이터 키). 아토믹, 바이트 보존. |
/paideia:graph [--rebuild] |
course-index/concept-graph.md 생성 — INTERFACE_LANG 노드 라벨, 문서순 C-ID, Obsidian 위키링크가 있는 mermaid 개념 그래프. 빌트 인덱스만 읽음 (analyze 팬아웃 없음). |
/paideia:hwmap hot|<§> |
숙제 밀도 순으로 🔥🔥 Exam-primary 절 띄우기 |
/paideia:pattern <§|Pk|키워드> |
course-index에 있는 패턴 카드 표시 |
/paideia:derive <타겟> |
derivations/<slug>.md에 정돈된 참조 유도 저장 |
/paideia:quiz <주제|§|weakmap> [N] |
N개 연습 문항 생성, 답은 형제 _answers.md에 숨김 |
/paideia:blind <problem-id> |
이미 본 문제의 전략만 확인하는 드릴 (재풀이 아님, 접근 기술) |
/paideia:twin <problem-id> |
같은 패턴, 새 표면의 변형 문제 |
/paideia:chain <N> |
N개 패턴을 묶은 통합 문제 |
/paideia:mock <분> |
숙제 밀도 가중 모의고사 전체 |
/paideia:grade [--ocr=<engine>] [경로] |
.course-meta의 엔진 선택(Claude 비전 / Ollama / Tesseract)으로 OCR 후 전략 채점, errors/log.md에 누적 기록 |
/paideia:weakmap [개념] |
weakmap/weakmap_<ts>.md에 저장되는 우선순위 약점 리포트 |
/paideia:cheatsheet [--pdf] |
오류 주도 한 장짜리 치트시트 |
/paideia:alt [붙여넣기] |
OPTIMETA Exam Radar(Alt 플러그인) 내보내기를 임포트 → course-index/radar.md + coverage.md의 강의 강조 열 + 골드존 weakmap |
/paideia:ingest는 materials/**의 모든 PDF를 동일한 비전 파이프라인으로 처리합니다. pdfplumber를 본문 위주 자료(교재, 과제)의 빠른 경로로 먼저 시도해 봤지만, 실제로는 신뢰할 수 없었습니다 — 얼핏 본문처럼 보이는 페이지도 수식·도표·다단 레이아웃·여백 주석이 섞이는 순간 조용히 단어 샐러드로 망가졌습니다. 코스마다 재조정이 필요한 카테고리별 휴리스틱과 폴백을 유지하느니, 모든 파일을 한 경로로 통일하는 편이 더 단순하고 안정적입니다.
| 원본 | 방법 |
|---|---|
materials/**/*.pdf |
비전 파이프라인 (병렬 에이전트, LaTeX 충실) |
materials/**/*.md |
프로비넌스 헤더를 붙여 통과 복사 |
파이프라인이 동작하는 방식: 각 페이지를 dpi=160로 PNG 렌더링하고, 어떤 에이전트가 읽기를 시작하기 전에 모든 PNG의 긴 변을 ≤1800 px로 축소합니다 (Claude의 다중 이미지 요청은 2000 px 초과 이미지를 강하게 거부하며, 16:9 슬라이드를 dpi=160으로 렌더링하면 이 한계를 쉽게 넘습니다). 그 뒤 PDF당 하나씩 general-purpose 에이전트를 병렬로 띄우고, 각 에이전트는 자신의 페이지를 순차적으로 읽어(Read 호출을 병렬로 묶으면 같은 한계에 걸립니다) LaTeX 마크다운으로 전사합니다. 30페이지를 넘는 PDF는 연속 페이지 구간별로 여러 에이전트에 나눠 전사한 뒤 하나의 출처 헤더 아래로 이어 붙이므로, 두꺼운 교재 챕터가 단일 에이전트의 컨텍스트를 넘치게 하는 일이 없습니다. 결과는 ℏ ∂ p2 ℏ 2 ∂ 2 p ̂ 같은 파편이 아니라 $$\hat H = -\frac{\hbar^2}{2m}\partial_x^2 + V(x)$$ 같은 깔끔한 수식입니다. 실제 13강 208페이지 양자역학 강의 전체가 [?] 마커 0개로 통과했습니다.
자세한 내용은 plugins/paideia/skills/pdf/VISION.md에 있습니다.
사용자는 채팅에 수식을 타이핑하지 않습니다. 종이에 풀고, PDF로 스캔하고, 그 PDF를 answers/에 떨어뜨리신 뒤 /paideia:grade를 실행하시면 됩니다. 플러그인은 세 엔진 중 선택하신 엔진으로 스캔본을 마크다운으로 바꿉니다. 기본 엔진은 코스별 .course-meta의 OCR_ENGINE으로 지정하며, 개별 호출에서는 /paideia:grade --ocr=<engine>로 덮어쓰실 수 있습니다.
| 엔진 | 기본값? | 동작 방식 | 이럴 때 고르세요 |
|---|---|---|---|
claude |
예 | pdftoppm으로 페이지별 PNG 렌더링 → Claude가 각 PNG를 직접 읽어 한 번에 마크다운으로 합성. 별도 모델도, 서브프로세스도, 설치도 필요하지 않습니다. |
가장 마찰이 적은 기본 경로. 한국어·LaTeX 모두 강하고 모델 로딩 지연도 없습니다. |
ollama |
선택 | vision_ocr.py --engine=ollama — 로컬 Qwen3-VL 8B, 실패 시 자동으로 tesseract로 폴백합니다. |
페이지 이미지조차 Anthropic 서버에 보내고 싶지 않으실 때. 최초 ollama pull qwen3-vl:8b (~6 GB)가 필요합니다. |
tesseract |
선택 | vision_ocr.py --engine=tesseract — pytesseract (INTERFACE_LANG=en이면 eng, ko면 eng+kor)를 사용합니다. |
가장 빠르고 가볍습니다. 타이핑된 스캔엔 괜찮고, 필기엔 정확도가 낮습니다. |
세 엔진 모두 answers/converted/<stem>.md에 <!-- SOURCE: ... --> / <!-- TIER: ... --> 헤더 코멘트를 남기므로, /paideia:grade가 OCR 신뢰도가 낮을 때 그에 맞게 태도를 바꿀 수 있습니다.
기본 엔진(claude)은 의도적으로 가장 마찰이 적은 선택으로 잡았습니다 — Claude Code에 이미 포함된 것만으로 충분합니다. ollama 엔진은 페이지 이미지 자체에 대해 단단한 프라이버시 경계를 원하실 때를 위해, tesseract 엔진은 다른 엔진을 쓸 수 없을 때의 안정적인 하한선으로 남겨져 있습니다.
손으로 쓴 수식의 OCR 잡음은 엄격한 대수식 채점을 사실상 쓸모없게 만듭니다 — 한 글자 ∫ ↔ ∑ 오독이 전체를 무너뜨리기 때문입니다. 더 중요한 사실은, 시험의 실제 병목은 패턴 인식이지 산수가 아니라는 점입니다. 그래서 채점기는 문항마다 세 가지를 확인합니다.
- 패턴 (Pattern) —
course-index/patterns.md에서 올바른 Pk를 골랐는지 - 변수 (Variables) — 올바른 치환 / 기저 / 인덱스 / 경로를 식별했는지
- 최종 형태 (End-form) — 최종 표현의 모양(차원, 점근, 구조)이 맞는지
오류는 타입이 지정된 분류(pattern-missed | wrong-variable | wrong-end-form | algebraic | sign | definition)와 함께 YAML 형태로 errors/log.md에 기록됩니다. 이 로그가 /paideia:weakmap의 씨앗이자, /paideia:cheatsheet --pdf의 유일한 입력이 됩니다.
/paideia:analyze는 일반적인 "미적분 기법" 목록을 배포하는 도구가 아닙니다. 당신 과목의 실제 해답지를 읽어 반복되는 풀이 패턴을 추출하고, P1, P2, … 로 라벨을 붙인 뒤, 당신 자신의 converted/solutions/ 파일을 인용하는 worked instance를 함께 제공합니다. 패턴은 당신 과목 고유의 관용구이지 어떤 교과서의 것도 아닙니다. 복소해석 수업에서 P3는 "닫힌 경로 + Jordan's lemma + 본질 특이점에서의 residue"일 수 있고, 선형 시스템 수업에서 P3는 "부분분수 + 복소극점을 갖는 역Laplace"일 수 있습니다. 각 분야는 자신만의 손놀림을 가지고 있고, 그것은 과목 자신을 통해서만 드러납니다.
weakmap/ 디렉토리는 절대 덮어쓰지 않습니다. /paideia:weakmap을 호출할 때마다 weakmap/weakmap_<ISO-timestamp>.md가 새로 생성됩니다. git log weakmap/를 통해 어떤 약점이 가장 먼저 무너졌는지, 어떤 약점이 끈질기게 남아 있었는지, 진단 모의고사 이후 어떤 새로운 약점이 등장했는지 정확히 확인할 수 있습니다. "자신의 이해를 시간 축 위에서 git diff한다"는 발상이 실제로 구현된 지점이 이곳입니다.
/paideia:init-course는 이 폴더 전용 .claude/settings.json을 작성해 Claude Code의 statusline 슬롯이 scripts/statusline.py를 호출하도록 걸어 둡니다. 표시 형식은 다음과 같습니다.
paideia · <COURSE_NAME> · D-<시험까지 남은 일수> · <phase> · P<top-miss> ↑
- **
<phase>**는 달력이 아니라 디스크 위 산출물로부터 도출됩니다. 산출물이 실제로 생겨야만 단계가 넘어갑니다.setup—course-index/patterns.md가 아직 없음 →/paideia:ingest+/paideia:analyzediag— 패턴은 있으나 퀴즈가 아직 없음 →/paideia:quiz all 20으로 전체 진단drill— 퀴즈는 있으나 모의고사가 아직 없음 →/paideia:blind·/paideia:twin·/paideia:quiz weakmap반복mock— 모의고사가 있고 치트시트가 아직 없음 →/paideia:cheatsheet --pdf로 압축cram—cheatsheet/final.{md,pdf}존재 → 테이퍼링, weakmap 재독, 새 개념은 학습하지 않기cool—D-0(시험 당일)은 위 모든 분기를 덮어씁니다
- **
<top-miss>**는 최신weakmap/weakmap_*.md에서 가장 빈번한pattern:태그입니다 (weakmap이 없으면errors/log.md로 폴백).↑는 "이 패턴부터 훑으세요" 표시입니다. - 컬러는 형광색 팔레트에서
sha1(session_id)해시로 결정적으로 선택됩니다. 같은 세션 안에서는 색이 고정되고, 세션이 바뀌면 색도 바뀝니다. 순전히 장식 — 색 자체에 정보는 담겨 있지 않습니다. - 조용한 폴백 — 현재 CWD에
.course-meta가 없으면 스크립트는 아무것도 출력하지 않고, Claude Code는 기본 statusline으로 돌아갑니다. 항상 걸어 두어도 안전합니다.
한 코스에서만 끄고 싶다면 그 코스의 .claude/settings.json을 지우거나 편집하시고, 전역에서 끄려면 ~/.claude/settings.json을 편집하세요. 형식이나 색을 바꾸고 싶다면 plugins/paideia/scripts/statusline.py 한 파일(~180 줄)만 만지면 됩니다.
PAIDEIA/
├── .claude-plugin/marketplace.json # 마켓플레이스 매니페스트
├── LICENSE # MIT
├── README.md # 영문
├── README.ko.md # 본 파일
└── plugins/paideia/
├── .claude-plugin/plugin.json # 플러그인 매니페스트
├── README.md # 빠른 참조 카드
├── skills/
│ ├── pdf/
│ │ ├── SKILL.md # 라우팅 결정 트리 + 참조용 추출기
│ │ └── VISION.md # 기본 인제스트 파이프라인 — PDF당 병렬 비전 에이전트
│ ├── vision-ocr/SKILL.md # Claude 비전(기본) + Ollama Qwen3-VL + tesseract
│ ├── course-builder/SKILL.md # ingest + analyze 파이프라인
│ ├── exam-drill/
│ │ ├── SKILL.md # 드릴 기본 단위 (twin, blind, chain, mock)
│ │ └── twin-recipe.md # 변형 생성 불변식 규칙
│ ├── answer-processing/SKILL.md # 필기 OCR 결과의 전략 채점
│ └── alt-import/SKILL.md # Exam Radar(Alt) 내보내기 임포트 → radar.md + coverage 강의 강조 열
├── commands/ # 18개 슬래시 명령
│ ├── init-course.md doctor.md ingest.md analyze.md
│ ├── reindex.md graph.md hwmap.md pattern.md
│ ├── derive.md quiz.md blind.md twin.md
│ ├── chain.md mock.md grade.md weakmap.md
│ ├── cheatsheet.md
│ └── alt.md
└── scripts/
├── paideia_lib.py # 공용 코어: .course-meta 파싱, D-day 계산, phase 상태 머신, RETIRED_TO_CANONICAL
├── log_tool.py # errors/log.md 전용 결정론적 기록기 — 스키마 검증, source별 멱등
├── doctor.py # /paideia:doctor: 설치 + 워크스페이스 진단, 권한 불필요 --fix
├── reindex.py # /paideia:reindex: 아토믹·analyze 미호출 coverage.md 마커 재작성 + errors/log.md facet 물질화
├── verify_tool.py # /paideia:grade 기호 프리플라이트: math-verify로 LaTeX/SymPy 동치 검사, 미설치 시 정직한 다운그레이드
├── vision_ocr.py # 선택적 사용: --ocr=ollama|tesseract 경로에서 쓰는 ollama qwen3-vl + tesseract 드라이버
├── statusline.py # Claude Code statusline 슬롯용 — `paideia · <COURSE> · D-N · <phase> · P<k> ↑`를 출력
└── session_start.py # SessionStart 훅: 새 세션 첫머리에 "phase / 최다 실수 / 다음 명령" 2줄 리마인더 출력
- 터미널은 수식 읽기에 나쁩니다. Claude는 마크다운 파일을 만들고, 당신은 그것을 (가능하면 Obsidian에서) 읽습니다.
- 풀이를 타이핑하는 일은 느리고 오류에 취약합니다. 종이에 풀고 스캔하면, 플러그인이 로컬에서 OCR을 처리합니다.
- OCR 잡음은 피할 수 없습니다. 그래서 채점은 전략 기반(패턴 / 변수 / 최종 형태)으로 이뤄집니다 — 라인별 대수 검증이 아니라요. 실제 시험 채점자가 보는 것과 동일한 관점이기도 합니다.
- 패턴은 당신 과목의 풀이에서 추출되어야 합니다 — 범용 목록에서가 아니라요. 각 분야는 고유한 관용구를 가지며, 그 관용구는 해당 과목 자신을 통해서만 드러납니다.
- 당신의 오류는 가장 가치 있는 학습 신호입니다 — 교과서보다, 강의보다 더요. 치트시트는 실러버스가 아니라
errors/log.md에서 생성됩니다. - 숙제 밀도가 시험을 알려 줍니다. 당신의 시간은 유한하니, 점수가 있는 곳에 쓰세요.
- 모든 것이 직접 편집 가능합니다. 패턴·weakmap·치트시트·오류 로그 전부 당신 git 이력 안의 평범한 마크다운/YAML입니다.
P3이 틀린 것 같으면 고쳐 쓰시면, 다음 드릴부터 그 수정본이 사용됩니다. 지난 학기 과목 폴더를 fork해서 이번 학기용으로 차이만 수정하셔도 됩니다. 플러그인은 뼈대이고, 학습 그래프는 당신의 것입니다.
수학 과목이 아닌 경우에도 쓸 수 있나요? 문제-패턴 추출을 중심으로 설계되어 있어, 정량 분야에서 강점을 가장 잘 드러냅니다: 수학, 물리, 전자공학, 전산 이론, 머신러닝 이론, 통계, 공학 등입니다. 역사나 문학 같은 과목에서도 인제스트와 요약은 동작하지만, 드릴 명령은 "문제에 풀이 패턴이 존재한다"는 전제를 두고 있습니다.
한국어·영어가 섞인 자료도 되나요?
됩니다. 인제스트와 OCR이 eng+kor로 설정되어 있고, 패턴과 채점 응답도 원자료의 언어 구성을 그대로 따라갑니다.
그냥 ChatGPT / Claude / Gemini에게 공부 도와 달라는 것과 뭐가 다른가요?
과목별 영속성입니다. LLM 챗은 당신이 2주 전 HW2에서 놓친 패턴을 기억하지 못하고, 당신 교수님이 어느 절을 실제로 강조하시는지에 대한 랭킹이 없으며, "당신의 전형적인 실수 유형"이라는 개념 자체가 없습니다. Paideia는 그 모든 것을 당신 디스크의 마크다운 파일에 써 넣습니다. errors/log.md가 append-only이기 때문에, 오늘 호출한 /paideia:weakmap은 과목 시작 이후의 모든 /paideia:grade 기록을 반영해서 작성됩니다. 일반 챗 세션은 아무리 똑똑해도 열 때마다 백지 상태입니다.
패턴 / 치트시트 / weakmap이 마음에 안 들면 직접 고칠 수 있나요?
네. 산출물을 평범한 마크다운으로 두는 이유가 정확히 그것입니다. P3이 틀린 것 같으면 course-index/patterns.md를 열어 다시 쓰시면 됩니다 — 이후 드릴은 그 수정본을 사용합니다. 치트시트가 엉뚱한 걸 강조한다면 잘라 내시면 됩니다. 플러그인은 뼈대이고, 학습 그래프의 모양은 당신이 잡으십니다.
Ollama / Qwen3-VL이 꼭 필요한가요?
아니요. 기본 OCR 엔진은 Claude 자체의 비전 기능입니다 — 이미 사용 중이신 Claude Code 세션 안에서 동작하고, 추가로 설치할 것이 없습니다. Ollama + qwen3-vl:8b는 페이지 이미지까지 기기 안에 붙잡아 두고 싶으실 때(= Anthropic 서버에도 보내지 않고 싶으실 때)를 위한 선택 경로입니다. tesseract는 설치를 최소로 하고 싶거나 타이핑된 스캔만 다루실 때를 위한 세 번째 옵션입니다.
qwen3-vl:8b를 선택했는데 제 기기가 감당하지 못하면요?
vision_ocr.py 드라이버가 Ollama 실패 시 자동으로 tesseract로 폴백합니다 (코스의 INTERFACE_LANG이 en이면 eng, ko면 eng+kor). 또는 .course-meta의 OCR_ENGINE을 claude로 바꾸시거나 --ocr=claude를 붙이시면 Ollama를 완전히 우회할 수 있습니다.
여러 과목에서 재사용할 수 있나요?
네 — 각 과목은 자신만의 폴더 안에 자신의 .course-meta, course-index/, errors/log.md, weakmap/을 가집니다. 과목 간에 공유되거나 섞이는 것이 없습니다. 그때그때 작업하실 과목 폴더 안에서 Claude Code를 여시면 됩니다.
LLM이 매긴 채점 결과를 믿어도 되나요?
채점은 전략 기반(대수식 검증이 아니라 패턴 매칭)이며, 채점기는 course-index/patterns.md의 패턴을 인용하고, 모든 채점은 errors/log.md에 감사 가능한 YAML 항목으로 남습니다. 혹시 채점이 잘못되었다면 해당 YAML 항목만 수정하시면 됩니다 — 다음 /paideia:weakmap이 수정 사항을 반영합니다.
제 데이터는 외부로 나가지 않나요?
PDF·마크다운·오류 로그·weakmap은 모두 로컬 코스 폴더 안에만 머물며, 어떤 제3자 서비스로도 업로드되지 않습니다. 플러그인이 일으키는 네트워크 트래픽은 선택하신 OCR 엔진에 따라 달라집니다. claude(기본)를 고르시면 페이지 이미지는 이미 쓰고 계신 Claude Code 세션을 따라 흐릅니다(= 평소 Claude Code 대화에서 이미 일어나는 경로와 동일, 새로운 무언가가 추가되지는 않습니다). ollama를 고르시면 최초 모델 다운로드 이후에는 어떠한 데이터도 기기 밖으로 나가지 않습니다. tesseract는 아무 때도 네트워크를 타지 않습니다.
MIT. 자유롭게 쓰시고, 본인 과목에 맞춰 fork하거나 수정하셔도 됩니다 — 이 플러그인의 핵심은 플러그인이 만들어 주는 학습 그래프가 고정된 제품이 아니라 당신이 모양을 잡을 수 있는 산출물이라는 점에 있습니다.
일반적인 커리큘럼은 평균적인 학생을 가르칩니다. Παιδεία — 한 명의 학생을 위한 형성.