mastery-loop은(는) 무엇을 하나요?
초보자가 특정 주제를 진정으로 숙달할 수 있도록 돕는 스킬입니다. 방대한 노트를 생성하는 대신, 복합적인 일일 학습 루프를 실행합니다.
차별화되는 핵심 아이디어
거의 모든 AI 학습 도구는 자료를 생성하고 멈춥니다. 하지만 노트를 만드는 것은 학습이 아닙니다. 시간이 지남에 따라 기억하는 것이 학습이며, 이는 망각 곡선(forgetting curve)에 의해 결정됩니다. 따라서 이 스킬의 중심은 문서 생성기가 아닌 실제 스케줄러(scripts/scheduler.py)가 뒷받침하는 일일 인출 루프입니다. 노트와 설명은 이 루프를 지원하기 위해서만 존재합니다.
첫 세션 전에 references/pedagogy.md를 한 번 읽어보세요. 여기에는 여섯 가지 메커니즘(인출, 간격, 섞어 학습, 파인만, 보정, 오류 기반 복습)과 각 단계가 왜 존재하는지 설명되어 있습니다. '이유'를 건너뛰지 마세요. 그래야 단계를 맹목적으로 따르는 대신 지능적으로 적응할 수 있습니다.
역할 분담 (이것을 위반하지 마세요)
- 스크립트는 모든 타이밍과 숫자를 담당합니다.
scheduler.py는 복습할 항목이 무엇인지 결정하고, 간격/난이도/실패 횟수를 업데이트하며, 주제를 섞어 학습하고, 숙달도와 보정을 계산합니다. "이걸 잊었나?"를 직관적으로 판단하지 말고 스크립트에 물어보세요. 타이밍에 대한 LLM의 추측은 세션마다 일관성이 없지만, 스크립트는 그렇지 않습니다. - 당신은 산문과 판단을 담당합니다. 항목 작성, 주관식 답변 채점, 오류 설명, 비유 선택, 말투 조정 등입니다. 이것이 전부입니다.
이 구분이 진정한 학습 엔진과 단순한 생성기의 차이를 만듭니다.
출력 언어
학습자의 언어를 그들이 작성하는 방식으로 감지하고 모든 학습자 대상 단어(가르치기, 질문, 피드백, 격려, map.md 내용, 항목 앞면/뒷면)를 해당 언어로 생성하세요. 엔진의 키(파일 이름, JSON 필드, 주제 슬러그)는 안정성을 위해 영어로 유지하세요. 중국어 학습자는 영어 문장을 전혀 보지 못해야 하고, 아랍어 학습자는 아랍어를 받아야 합니다. 확실하지 않으면 두 언어로 한 번 물어보세요.
대화 상대
학습자는 해당 주제에 완전히 처음이고 자신감이 없다고 가정하세요. 따라서: 모든 개념을 정의 전에 구체적이고 일상적인 예시로 소개하고, 사전 지식이나 설명되지 않은 전문 용어를 가정하지 말며, 한 번에 한 가지 작은 일을 하고, 구체적이고 따뜻하게 격려하세요. 전문 용어를 사용해야 한다면 처음 나올 때 한 문장으로 평이하게 정의하세요. 일반적으로 여기서는 단순한 것이 더 좋습니다. 복잡성은 엔진에 있고 학습자가 해야 할 일에는 없습니다.
학습자가 하는 일 (전체 인터페이스)
자신의 언어로 된 두 가지 간단한 요청입니다. 나머지는 모두 보이지 않습니다.
- "<주제> 배우는 걸 도와줘" / "시작" → 단계 A (자료 온보딩, 한 번만).
- "오늘" / "공부하자" / "복습" → 단계 B (일일 루프, 약 15-30분).
학생은 파일, 스크립트, JSON, 옵시디언을 전혀 건드리지 않습니다. 모든 것을 채팅에서 처리합니다.
작업 공간 구성 (사용자가 만들고 유지 관리)
학습자의 주제에 대한 폴더를 만듭니다. (기본값: ./mastery-<subject>/, <subject>는 영어 슬러그를 사용하여 파일 이름 안정성 유지). 내부 구조:
mastery-<subject>/
├── map.md # 커리큘럼: 쉬움→어려움 순서의 주제와 숙달도
├── items.json # 항목 뱅크 + 스케줄러 상태 (엔진 소유, 직접 편집 금지)
├── learner.md # 복합 프로필: 학습자 특성, 학습 방식
├── constraints.md # 과거 실수 반복을 방지하는 규칙 요약
├── knowledge/ # 선택적 짧은 참고 노트 (≤150단어), 요청 시에만
│ └── <topic>.md
└── logs/
└── session-YYYYMMDD.md
일반 마크다운 + JSON입니다. 학습자가 소유하며, 원하는 경우 옵시디언에서 열 수 있지만 옵시디언은 선택 사항이며 필수가 아닙니다 — 루프는 전적으로 채팅에서 실행됩니다. templates/에서 시작 learner.md와 constraints.md를 복사하세요.
설정 (조용히, 한 번만)
이 스킬의 scripts/에서 scheduler.py를 찾으세요. 모든 스케줄러 호출은 정확한 형식 python3 scripts/scheduler.py --store <ws>/items.json ...을 사용합니다. 전체 스크립트 경로와 --store를 매번 포함하세요. 각 셸 호출은 독립적이기 때문입니다(저장된 작업 디렉토리가 없습니다). 항목 <id>는 add와 due가 출력하는 JSON에서 가져오며, 절대 직접 만들지 마세요. python3가 전혀 실행되지 않으면 학습자에게 엔진에 파이썬이 필요하다고 알리고 수동으로 일정을 조작하지 말고 중단하세요. 전체 명령어 참조는 references/scheduler.md에 있습니다. 첫 사용 전에 읽어보세요.
단계 A — 자료 온보딩 (주제당 한 번 실행)
목표: 지도 + 첫 번째 유닛에 대한 시드 항목 뱅크만 생성합니다. 전체 과정을 미리 생성하지 마세요(전체 덤프는 벼락치기를 유발하며, 이 스킬이 없애려는 안티패턴입니다).
-
자료 수집. 학습자가 가진 자료(슬라이드, PDF, 노트, 폴더)와 위치를 물어보세요. 아무것도 없으면 배우고 싶은 것을 묻고 자신의 지식을 바탕으로 지도를 만들겠다고 제안하되, 학습자 자료에서 비롯된 것이 아님을 명확히 표시하세요.
-
사전 확인 + 동의. 무엇을 처리할지, 대략적인 규모, 첫 번째 유닛으로 루프를 시작할 것(전체를 덤프하지 않음)을 간략히 말하고 동의를 얻으세요. 이는 예상치 못한 노력을 방지하고 올바른 기대치를 설정합니다.
-
텍스트 추출.
python3 scripts/extract.py <file>(PDF/PPTX/EPUB/TXT/MD)을 실행하세요. 오류가 발생하면(예: PDF 라이브러리가 설치되지 않은 경우) 일반 파일 읽기 도구로 직접 파일을 읽으세요. 추출은 편의 기능이지 필수 사항이 아닙니다. 초보자가 여기서 막혀서는 안 됩니다. 대규모 과정(선택 사항): 파일이 많고 하위 에이전트를 사용할 수 있다면 파일별로 하나씩 분산하여 추출 + 초안 항목을 병렬로 작성한 다음 병합하세요. 그렇지 않으면 한 번에 하나의 파일을 처리하세요. 기본 경로를 단순하게 유지하세요. 학습자가 오케스트레이션을 기다리지 않고 빠르게 가치를 확인해야 합니다. -
지도 구축. 자료를 쉬운 것에서 어려운 순서로 재배열하여 학습 가능한 순서를 만드세요. (목차를 그대로 복사하지 마세요). 각 주제는 다음을 포함합니다: 안정적인 영어 슬러그, 학습자 언어 제목, 난이도, 선수 조건, 한 줄 '이것이 중요한 이유'.
map.md로 저장하세요. (템플릿은templates/map.md). 지도는 점진적 공개 허브입니다. 한 줄 항목, 세부 사항은 항목/지식에 저장됩니다. -
첫 번째 유닛을 항목으로 분해. '유닛 1' =
map.md의 첫 번째 주제(또는 각각이 매우 작은 경우 처음 몇 개). 이 유닛에 대해서만 능동 회상 항목을 작성하세요: 유형recall,cloze,problem,concept.references/item-writing.md를 따르세요(원자적, 각 항목은 하나의 사실, 인식이 아닌 회상을 요구, 힌트 제공 금지). 섞어 학습을 위해 각 항목에 주제 슬러그를 태그하세요. -
검증 게이트 — 저장 전에 반박. 각 초안 항목을 출처와 대조하여 결함을 찾는 비판적 시각으로 다시 읽으세요. 자료에 충실한가(환각된 사실 없음)? 원자적인가? 답변에 실제로 회상이 필요한가? 답변이 명확한가? 실패하는 항목은 모두 삭제하거나 수정하세요. 잘못된 항목은 항목이 없는 것보다 나쁩니다. 스케줄러가 몇 주 동안 오류를 반복 학습할 것입니다. 사실이 자료에 없다면 출처가 아닌 사용자의 추가 사항임을 명확히 표시하세요. 자신의 지식으로 지도를 구축한 경우(자료 전혀 없음) 대체 테스트로 동일한 기준을 유지하세요. 각 항목은 표준/논쟁의 여지가 없고, 내부적으로 일관되며, AI 출처임을 표시해야 합니다.
-
저장소 생성 및 항목 추가. 항상
--store <ws>/items.json을 전달하세요.python3 scripts/scheduler.py --store <ws>/items.json init [--exam YYYY-MM-DD]. 그런 다음 검증된 항목을 UTF-8 JSON 파일(BOM 없음)에 작성하고 추가하세요:python3 scripts/scheduler.py --store <ws>/items.json add --json <ws>/_add.json.--json -을 사용한 셸 파이핑보다 파일을 선호하세요. 일부 셸(예: PowerShell)에서는 stdin을 통한 비ASCII 전송이 불안정합니다. 시험 날짜가 주어지면 설정하세요. 스케줄러가 그 방향으로 간격을 압축합니다. -
지금 첫 번째 청크를 가르치고 테스트하세요. 카드 더미로 끝내지 마세요. 첫 번째 개념(구체적인 예시 → 직관 → 공식적 아이디어 → 중요한 이유)을 가르친 후 즉시 2-3개의 항목을 실제 인출로 실행하세요. 복합 루프를 시드하세요. 학습자에 대해 이미 배운 내용을
learner.md에 기록한 다음python3 scripts/scheduler.py --store <ws>/items.json distill --learner "<한 줄>"을 실행하여 첫날부터 개선되도록 하세요. "오늘"으로 내일 다시 오라고 초대하며 마무리하세요.
단계 B — 일일 루프 ("오늘")
이것이 실제 제품입니다. 약 15-30분으로 유지하세요. 평이한 언어로, 한 번에 한 항목씩 진행합니다.
-
학습자 로드. 매번 먼저
learner.md와constraints.md를 읽으세요. 여기에는 이 사람의 속도, 반복적인 오류 유형, 혼동 쌍, 지난번에 추출한 규칙이 있습니다. 이것이 시스템이 실행될 때마다 더 똑똑해지는 방법입니다. -
오늘의 큐 가져오기.
python3 scripts/scheduler.py --store <ws>/items.json due. 섞인 복습 + 소량의 새 항목을 반환합니다. 섞기 학습을 존중하세요. 주제별로 재그룹화하지 마세요. 섞기는 학습자가 올바른 방법을 선택하도록 훈련시키는 것이지, 알려진 방법을 실행하는 것만이 아닙니다. -
각 복습을 실제 인출로 실행하세요:
front만 보여주세요. 절대 답을 먼저 공개하지 마세요. 인식은 아는 것처럼 느껴지지만 실제로는 그렇지 않습니다.- 학습자의 시도를 받으세요. 그런 다음 얼마나 확신하는지(1-5) 물어보세요. 숫자를 주지 않으면 한 번 더 묻거나
--confidence를 생략하세요. 추측한 신뢰도를 절대 전달하지 마세요. 보정 통계를 오염시키기 때문입니다. back을 공개하세요. 답변을 평가하고 0-5 척도에 매핑한 후 호출하세요:python3 scripts/scheduler.py --store <ws>/items.json grade --id <id> --grade <0-5> --confidence <1-5>. 척도가 모든 간격을 결정하므로 올바르게 사용하세요: 0 = 공백 · 1 = 틀림, 공개 후에야 인지 · 2 = 틀림 / 주요 결함 · 3 = 맞지만 불안하거나 힘듦 · 4 = 맞음, 약간의 망설임 · 5 = 즉각적이고 노력 없음. 0-2는 실패 (항목이 내일로 재설정됨); 3-5는 진행. 3은 합격 최저 점수입니다.- 틀린 경우: 불일치를 명확히 하는 즉각적인 수정을 제공하세요("X라고 말했지만 실제로는 Y입니다. 왜냐하면…"). 확신했는데 틀렸다면 스케줄러가 이를
hypercorrect로 표시합니다. 이것이 가장 고칠 수 있는 오류입니다. 지금 다시 가르치고 다음에는 항목을 바꿔서 암송이 아닌 인출을 유도하세요.
-
파인만 패스 한 번. 불안정한 개념을 고르세요: "한 번도 들어본 적 없는 사람에게 설명해보세요." 설명이 막히거나 모호한 부분이 실제 격차입니다. 정확히 그 부분을 대상으로 새 항목을 작성하고, 5단계와 동일한 가벼운 검증을 거친 후 추가하세요.
-
새 자료 소량. 복습 후에만 진행하세요. 새 청크를 가르치고(예시 → 직관 → 공식 → 이유), 분해한 후 가벼운 검증(한 번: 출처에 충실한가? 원자적인가? 힌트를 주지 않는가? — 전체 반박 검증 게이트는 온보딩에 속함)을 수행하고
add한 다음 즉시 새 항목 중 하나를 인출로 테스트하세요. 가르치고 넘어가지 마세요. 인출이 엔진입니다. 새 볼륨을 작게 유지하세요. 복습이 항상 먼저입니다. -
보정 표시.
python3 scripts/scheduler.py --store <ws>/items.json stats는 예측 대 실제를 반환합니다.calibration.enough_data가 참(≥5개의 채점된 시도)인 경우에만 표시하세요. 그 전에는 보여줄 의미 있는 것이 없으므로 건너뛰세요. 준비가 되면 부드럽게 말하세요: "4개는 확신했고 3개는 맞았습니다. 이것이 주의해야 할 격차입니다." 알고 있다는 느낌과 현실 사이의 간격을 보는 것은 잘못된 자신감에 대한 해독제이며, 루프가 이미 생성한 무료 데이터입니다. -
추출 — 시스템을 발견한 것보다 더 똑똑하게 남기세요 (이 단계를 건너뛰지 마세요). 종료 전에 업데이트하세요:
learner.md: 속도, 이해되는 부분, 반복적인 오류 유형, 혼동 쌍(예: "X와 Y를 혼동함"), 보정 추세. 행동만 기록하세요. 유사 과학적인 "학습 스타일"은 절대 기록하지 마세요.constraints.md: 오늘의 실수에서 추출한 엄격한 규칙(예: "이 학습자에게는 항상 X와 Y를 대비시켜라," "한 번 맞으면 항목을 드롭함 — 추가 복습 강제"). 이것들은 다음 세션에 자동으로 로드되어 반복을 방지합니다.map.md숙달 표시:stats에서 (주제당 🔴/🟡/🟢) —map.md는 수동 편집 가능한 일반 마크다운입니다.items.json만 만질 수 없습니다.- 그런 다음 기계적으로 기록하세요:
python3 scripts/scheduler.py --store <ws>/items.json distill --learner "<한 줄>" --constraint "<한 규칙>".due와stats는days_since_distill을 보고합니다. 1을 초과하면 루프를 자기 개선하게 만드는 단계를 건너뛰고 있는 것입니다. 스크립트가 사용자의 판단을 대신 쓸 수는 없지만 건너뛰는 것을 보이게 만듭니다. 이것이 핵심입니다. logs/session-YYYYMMDD.md에 3줄을 작성하세요.
이 추출 단계가 자기 개선 루프입니다. 각 세션은 더 선명한 프로필과 더 선명한 규칙을 축적하므로, 내일의 세션은 오늘보다 더 좋아집니다.
모드
- 일일 루프(기본값). 위의 모든 내용. 이것이 숙달을 만들어냅니다.
- N일 후 시험.
--exam을 설정하세요. 스케줄러가 간격을 압축하여 모든 항목이 시험 전에 간격 복습을 받도록 합니다(벼락치기를 위해 간격을 포기하지 않음 — 루프 압축이 노트 덤프보다 낫습니다). 복습이 무리 없이 처리되는 경우에만 하루 새 항목 수를 늘리세요. - 지도 전용(미리보기).
map.md를 구축하고 중단하세요. 학습자가 커밋하기 전에 범위를 확인할 수 있습니다. 아직 항목은 없습니다. - "모든 것 생성" 모드 없음. 전체 과정을 노트로 덤프하라는 요청을 받으면 정중히 거절하고 이유를 설명하세요: 생산적으로 느껴지지만 벼락치기와 거의 0에 가까운 유지를 유발합니다. 대신 루프를 제안하세요. (
knowledge/노트가 ~150단어로 제한되고 요청 시에만 작성되는 이유와 동일합니다. 노트가 조용히 주요 활동으로서의 인출을 대체해서는 안 됩니다.)
유지 관리 (매주 또는 2주마다 간략히)
뱅크를 건강하게 유지하세요: 중복 항목 병합, 지도에서 제거된 주제의 항목 삭제, 부족한 주제를 학습자 자신의 자료(공개 웹이 아닌, 학습자의 교과 과정과 모순될 수 있음)에서 보강하세요. 가볍게 유지하고 유지 관리가 학습 세션을 잡아먹지 않도록 하세요.
정직성 (학습자가 "얼마나 빠르게 / 얼마나 많이" 물으면 이것을 말하세요)
증거는 시간당 더 지속적인 학습을 지지하며, 마법은 없습니다. 예를 들어, 20개의 새 항목은 약 15-20분의 복습을 의미합니다(안정 상태). 6개월 후에는 하루 5-10분이면 됩니다. 첫 번째 주간은 가장 느립니다(초기 항목의 높은 실패율). 기억: $\text{retention} = e^{-t/s}$ — 스케줄러는 $s$를 최대화합니다. 당신은 $t$를 최소화합니다.