개념 정리본 생성 규칙

정리본은 학습 목표 단위의 이론 카드다. 웹 앱(오답 뒤 학습 흐름)과 과별 PDF 학습서가 같은 원본을 쓴다.
계약은 schemas/frontmatter.md 의 「개념 정리본(concept)」·「오답 뒤 학습 흐름」 절이 원본이다 — 필드 이름은 거기서 확인한다.

무엇을 쓸지는 큐가 정한다(고르지 말 것)

python pipelines/concept_queue.py --limit <오늘 상한>

• [note] — 목표는 있는데 정리본이 없는 오답 → 정리본을 새로 쓴다.
• [link] — 목표가 없는 오답 → 문항에 objective 를 붙이고, 그 목표의 정리본이 없으면 이어서 쓴다.
• [touch] — 목표의 정리본은 이미 있고, 새로 틀린 보기만 그 정리본의 pitfalls[].covers 에 없다.
  새 정리본을 쓰지 않는다. 기존 혼동 항목으로 설명되면 그 항목의 covers 에 <문항id>:<보기> 만 더하고,
  아니면 혼동 항목을 하나 추가한다(오답을 일반화해서 — 추측 금지). 본문을 고쳤으면 version 을 올리고,
  바꾼 서술만 해리슨으로 대조한다. 정리본이 쌓일수록 대부분의 오답은 이 가벼운 손질이 된다.
• 오답은 학습 기록(state/learning_sync/events.json)과 오답 목록(state/wrong_sync/*.json) 두 곳에서 온다(2026-09-23).
  학습 흐름(2026-09-18) 전의 오답은 오답 목록에만 있고, 대개 학습 목표가 없어 [link] 로 나온다 — 목표부터 붙인다.
• [restyle] — 판형 2(note_form: 2)로 아직 옮기지 않은 옛 정리본(note·link·touch 가 비었을 때만 나온다).
  새로 쓰지 않고 있는 내용을 판형 2 로 다시 배치한다 — 아래 「판형 2」 절 · 「판형 2로 옮기기」.
• 큐가 비어 있으면 아무것도 만들지 않는다(학습 기록이 아직 저장소에 없을 때가 대부분 — 정상이다).

학습 목표(objective) 정하기

• id 형식 cn.<과>.<주제>.<목표> — 소문자·숫자·하이픈. 파일은 content/concepts/<과 폴더>/<id>.md.
• 질환명으로 합치지 않는다. 같은 질환이라도 평가 목표가 다르면 다른 정리본이다
  (예: cn.derm.pityriasis-versicolor.diagnosis ≠ …treatment).
• 이미 있는 목표로 묶을 수 있으면 새로 만들지 말고 그 문항에 기존 id 를 붙인다(python pipelines/concept_queue.py 의
  「이미 정리본이 있는 오답 목표」 수가 그 결과다).
• 문항에는 objective 와 함께 가능하면 distractors(보기별 tempting·answer_first·discriminator·when_right·split)와
  case_path(도식 노드 경로, 문항에 없는 정보는 state: unknown)를 적는다 — 형식은 린터가 본다.

자리 정하기 — 기본틀 슬롯(outline)

정리본은 과별 학습서 안에서 해리슨 21판의 서술 순서로 꽂힌다. 그 자리를 frontmatter outline: 에 적는다.

python pipelines/outline.py --book 순환기내과 --gaps     # 그 과의 빈 자리
python pipelines/outline.py --find "arrhythmia"          # 슬롯·해리슨 장 제목 검색(PDF 를 열지 않는다)

• 슬롯 id 는 h<장번호>(해리슨이 다루는 주제) 또는 손으로 정한 id(ob.labor·peds.neuro 처럼 해리슨에 없는 과).
• 한 슬롯에 정리본이 여러 개 있어도 된다(같은 장 안의 다른 학습 목표). 순서만 정해 줄 뿐이다.
• 적을 자리가 마땅치 않으면 content/outline/subjects.yaml 에 슬롯을 추가한다(해리슨 장은 한 과에만).
• 비워 두면 책 맨 뒤 「배치 대기」로 가고 린터가 WARN 을 낸다.

대조 — 해리슨이 기본이다(2026-09-22)

정리본을 다 쓴 뒤 그 슬롯의 해리슨 장을 읽고 핵심 서술(기전·기준·치료 선택·금기)을 하나씩 대조한다.

python pipelines/outline.py --harrison <슬롯>     # 대조할 장 · 인쇄쪽 · 드라이브 문서 ID

• 클라우드 루틴: 출력에 드라이브 문서 ID 가 있으면 Google Drive 커넥터 read_file_content(fileId) 로 그 문서만 읽는다
  (===== [H21 p.N] ===== 뒤가 인쇄쪽 N). 원본 PDF(434 MB)는 읽지 않는다.
• PC: python pipelines/harrison_read.py --slot <슬롯> --grep <말> 로 원본에서 그 장만.
• 해리슨과 맞는 서술에 [[harrison-21: <장>장 p.<쪽>]], 출처에 harrison-21(kind textbook · verified: text ·
  checked 에 무엇을 몇 쪽에서 확인했는지)을 단다. 해리슨과 다르면 고치거나 차이를 본문에 밝힌다(합치지 않는다).
• 해리슨에 없는 서술(지침 세부 수치·최신 약제 등)은 다른 출처로 남기고, 원문을 못 봤으면 [[?출처]] 그대로 둔다.
• 드라이브 문서가 없으면 대조하지 않은 채로 둔다 — 린터가 「해리슨 대조 없음」 WARN 을 남기고,
  다음 PC 세션에서 python pipelines/harrison_split.py --needed 로 그 장을 올린 뒤 대조한다.
• 해리슨이 다루지 않는 슬롯(산부인과·소아과 손 슬롯 등)은 대조 대상이 아니다(--harrison 이 알려 준다).

[variant] — 틀린 문항마다 변형 2개(2026-09-23 사용자 채택)

「오답 → 변형 문항 → 간격을 두고 다시 출제」. 앱은 틀린 날 +1일·+7일(사용자가 바꿀 수 있음)에 「오늘 다시 풀 것」을
띄우고, 그 문항에서 나온 변형(of: <문항id>)을 먼저 낸다. 큐 [variant] 는 예정일이 이른 것부터 나온다.
정리본의 variants 에 틀린 문항마다 둘을 더한다(version 올림):

• A. 단서를 바꿔 답이 바뀌는 변형(flip: true) — 같은 환자 뼈대에서 결정적 단서 하나만 바꿔 원래의 혼동 대안이
  정답이 되게 한다. 씨앗은 문항의 design.switch.condition(큐의 「씨앗」 칸) → 없으면 design.discriminator → 해설.
  예: 「소변검사·크레아티닌 정상」 → 「단백뇨 3+·크레아티닌 2.1」 ⇒ 정답이 항바이러스제에서 스테로이드+리툭시맙으로.
• B. 겉모습을 바꿔도 답은 그대로인 변형(flip: false) — 나이·성별·내원 경위·검사 이름·제시 순서를 바꾸고 결정적 단서는
  남긴다. 이야기가 아니라 단서로 풀었는지 본다.
• 두 변형 모두 of: <틀린 문항 id>, changed: "<무엇을 바꿨나 → 그래서 답이 어떻게 됐나>", context(한 줄),
  보기 5개(같은 범주·길이 비슷), answer, explanation(바뀐 단서가 왜 답을 바꾸는지/왜 안 바꾸는지).
• 형식은 원래 문항의 시험을 따른다 — KMLE 문항이면 한국어 국시형, USMLE 문항이면 영어 USMLE형(/gen-kmle 문항 형식).
  원래 발문을 그대로 베끼지 않는다. 새 사실·수치는 정리본 sources 로 뒷받침되는 것만.
• [note] 로 정리본을 새로 쓸 때도 그 목표의 틀린 문항마다 같은 방식으로 변형 둘을 함께 쓴다(다음 실행에 [variant] 로 다시 나오지 않게).

[dist] — 내가 고른 오답 보기의 설명(선지 보정, 2026-09-23)

내가 실제로 고른 오답 보기에 문항의 distractors.<보기> 가 없으면 큐에 나온다. 그 문항 파일(큐의 path — KMLE·USMLE 만,
영상 문항은 빌더 파생물이라 제외)에 그 보기 하나의 설명을 더하고 문항 version 을 올린다:
tempting(이 보기가 왜 그럴듯한가 — 보기 자체의 이유, 학습자의 속마음을 추측하지 않는다) · answer_first(왜 정답이 먼저인가) ·
discriminator(둘을 가르는 소견 — 문항 안의 정보로) · when_right(이 보기가 정답이 되는 조건, 있으면).
해설과 모순되면 해설을 고치지 말고 보고에 남긴다(문항 내용 변경은 사람 검토).

시험 쟁점 절 — 시험 답이 갈릴 수 있는 곳은 따로 모은다(2026-09-23)

사용자 지시: 충돌 지점 · 맥락 차이 · 새 연구로 논란인 내용은 본문에 섞지 말고 따로 뺀다. 학교 정리본(의대_정리본_제작 CLAUDE.md
「시험 쟁점 부록 규칙」)과 같은 규칙이다. 본문 · criteria 는 시험 답으로 쓸 기준 하나로 쓰고, 갈리는 곳은
## 권고와 예외 다음 · (심화) 앞의 ## 시험 쟁점 — 충돌·맥락·새 근거 절에 모은다.

• 종류 — 충돌(같은 질문에 자료마다 답이 다르다) · 맥락(대상 · 정의 · 나라 · 시점이 달라 숫자가 다르다: 한국 vs 미국, KMLE vs USMLE) ·
  새 근거(해리슨 21판 · 지침 판 이후 개정 · 새 약 · 새 시험).
• 한 항목 = 글머리 하나, 네 칸 고정:
  - **Z1 충돌 · <제목>** — 시험 기준: … [[출처]] / 다른 기준: … [[출처: 쪽]] / 왜 다른가: … / 시험에서는: KMLE … · USMLE …
• 「다른 기준」도 읽은 것만 쓴다 — 기억으로 「옛 지침은 …」이라고 쓰지 않는다(원문 못 봤으면 [[?출처]]).
• 해리슨과 대조해 어긋난 곳이 없으면 절에 한 줄: - 해당 없음(대조: 해리슨 N장 p.#~#). 대조하지 못했으면 절을 두지 않는다(린터의 「해리슨 대조 없음」 WARN 이 남는다).
• [touch] 로 손볼 때 이 절이 없는 옛 정리본이면, 바꾼 서술을 대조하면서 함께 만든다.

해리슨을 읽어야 할 때 — 그 장만 읽는다

python pipelines/harrison_read.py --slot h255                 # 그 슬롯의 장 전체(기본 12,000자)
python pipelines/harrison_read.py --chapter 255 --grep "QT"   # 그 장에서 맞는 줄만
python pipelines/harrison_read.py --chapter 255 --pages 1925  # 인쇄쪽으로 더 좁히기

4,132쪽 PDF 를 통째로 뒤지지 않는다. 읽은 쪽은 [[harrison-21: 255장 p.1925]] 처럼 인용하고
sources[].verified: text 로 올린다(본문을 저장소 파일로 저장하지 않는다 — 교과서 저작권).

판형 2 — 정리본 모양(2026-09-25, 새 정리본은 모두)

사용자 요청: 「이전 모델이 만들던 오답 정리본을 더 좋은 스타일로」. 감사(77개)에서 나온 약점 — 첫 줄이 결론이 아니라 배경,
「이 발문을 보면 이 개념」이 없음, 질환 교과서 골격(정의·병태·감별·검사·치료)을 목표와 무관하게 채움, 같은 판단을
summary·criteria·도식·checks·본문에서 5~6번 되풀이, 도식 노드에 기준 목록을 통째로 넣어 도식이 길어짐, 한·영 용어 짝 없음.
본보기: content/concepts/dermatology/cn.derm.pityriasis-versicolor.treatment.md (옛 판을 판형 2 로 옮긴 것).

frontmatter

• note_form: 2 — 판형 2 표지. 이게 있어야 모양 예산 검사(WARN)가 돈다.
• title ≤ 40자, 「질환 — 판단 한 구절」(예: 「어루러기 — 치료 수준은 범위·재발이 정한다」). objective 는 동사 하나(목표가 둘이면 정리본 둘).
• summary 3~5줄, 한 줄 ≤ 110자, 앞 두 줄은 머리말 고정:
  1. 결론: … — 정답 판단 한 문장.
  2. 시험 단서: … — 이 개념을 떠올리게 하는 발문 단서(나이·상황·검사값). 영어 용어를 괄호로 한 번(USMLE).
  3. 왜: … — 정답이 혼동 대안보다 먼저인 기전 한 구절.
     4~5. 쓰지 않는 약·예외·수치 기준(단위·적용 대상 포함).
• pitfalls — 틀린 보기마다 하나 이상(covers: [<문항id>:<보기>]). contrast = 「A vs B」 또는 「오해?」, point = 가르는 소견 + 이유.
• 기준·치료·감별이 둘 이상 갈리면 tables 로(section 은 붙일 본문 절 제목과 글자까지 같게). 표에 있는 것을 본문에서 다시 늘어놓지 않는다.
• 첫 등장 용어는 「한국어(English)」 — 국시 용어와 USMLE 용어를 함께. 약어는 풀어 쓴 뒤.
• diagram — 판단 목표면 필수(기전 목표만 생략). 노드 글 판단 ≤ 30자 · 나머지 ≤ 40자 · 갈래 라벨 ≤ 14자.
  기준 목록·용량·예외·쓰지 않는 약은 노드에 넣지 말고 diagram_notes·표로. 노드는 9개 안팎.

본문 — 목표 종류에 맞춰 고른다(질환 교과서 골격을 채우지 않는다). 절 제목 예:

• ## 판단 — 왜 <정답>이 먼저인가 (글머리 3~5개, 각 ≤ 2문장) — 치료·다음 처치·검사 선택 목표의 첫 절
• ## 기전 — <정상>에서 <이상>으로 (≤ 600자, 소견이 생기는 이유까지)
• ## 가르는 소견 — … (감별표를 여기에 붙인다 · 정상/음성 결과의 해석 한계)
• ## 선택 — … (적응·금기·재평가, 치료표를 여기에)
• ## 권고와 예외 → ## 시험 쟁점 — 충돌·맥락·새 근거 → (심화) 는 의학 내용만(문항 풀이 요령은 summary 「시험 단서」로).
• 정의·역학은 목표에 필요할 때만 위 절 안에 한두 줄. 본문 전체 2,500자 안팎.
• 아래 「깊이 규칙」의 필수 요소는 줄이지 않고 자리만 옮긴다.

판형 2로 옮기기 — [restyle]

1. 옛 정리본을 다 읽는다. 새 사실·수치·출처를 더하지 않는다(재배치만). 의학 내용을 고쳐야 할 곳이 보이면 고치지 말고 보고에 남긴다.
2. 위 판형대로 frontmatter 를 다시 짠다 — summary 머리말 셋, 틀린 보기별 pitfalls(python pipelines/concepts.py 가 가리키는 연결 문항의 오답 보기),
   되풀이되던 판단은 표·도식 한 곳에만.
3. 도식 노드 글을 예산 안으로 줄이고, 뺀 조건은 diagram_notes 로 옮긴다(도식 id·갈래는 문항 case_path 가 가리키므로 id 는 바꾸지 않는다).
4. 본문 절을 목표에 맞게 다시 묶는다. 표 section 을 새 절 제목에 맞춘다.
5. note_form: 2, version +1, updated 오늘. python pipelines/concepts.py 오류 0 · 이 정리본 판형 2 WARN 0.
   하루 상한은 루틴 프롬프트가 정한다(시간 예산 안에서 1~2개).

내용 — 깊이 규칙(빼지 않는 요소)

절 순서는 판형 2 대로 목표에 맞춰 고른다. 어느 순서든 원인·치료명 나열로 설명을 대신하지 않는다. 다음은 분량을 줄이려고 빼지 않는다:
정상 생리와 병태생리의 연결 · 소견이 생기는 이유 · 수치의 단위·적용 조건 · 정상/음성 결과의 해석 한계 ·
치료의 적응·금기·예외 · 효과와 재평가 기준 · 근거와 검토 상태.

역할을 나눈다 — summary=전체 관계, 본문=이유, tables=차이 비교, diagram=흐름,
diagram_notes=그림만으로 전달되지 않는 조건·예외, pitfalls=혼동하기 쉬운 점(오답을 일반화해서).
pitfalls[].covers 에 <문항id>:<보기> 를 적으면 학습서가 그 오답을 중복해서 싣지 않는다.
학습자가 왜 그 보기를 골랐는지 추측하지 않는다(린터가 막는다).

근거 — 확인한 것만

• 본문·표·혼동 항목의 수치와 권고에는 [[출처id: 쪽·절·표]] 로 위치를 단다.
• sources[].verified 는 실제로 어디까지 봤는지다: text(권고 본문 대조) · abstract(초록만) · citation(서지만).
  text 가 아니면 화면·PDF 에 † 가 붙는다. 원문을 못 본 주장은 [[?출처id]].
• 교과서는 G:\내 드라이브\교과서\ 의 Harrison(인쇄쪽 = PDF 인덱스 − 40)·Guyton(스캔본, 렌더해서 읽기)을 인용할 수 있다.
  논문·지침은 PubMed·기관 쪽에서 실제로 열어 본 뒤 서지와 쪽수를 적는다. 없는 출처·안 본 쪽수를 만들지 않는다.
• 논문·지침에는 pmid 를 붙인다(DOI 만 두지 않는다 — 개정·철회 추적은 PMID 로 한다). 컨테이너가 PubMed 를 막아
  PMID 를 못 찾으면 DOI 만 두어도 된다(학습서 워크플로가 DOI 로 PMID 를 찾아 본다). 기억으로 적은 DOI 는 checked 에 그렇게 쓴다.
• 다른 나라·기관의 기준은 criteria 행을 나눠 쓰고 설명 없이 합치지 않는다(KMLE/USMLE 는 exams 로 구분).
• review_status: unreviewed 로 둔다. 사람이 본 뒤에만 reviewed+reviewed_by+review_note.

도식

decision_diagram.py 규격: 세로, 판단 노드는 갈래 2개 이상·조건 라벨 필수, 「추가 정보 필요(info)」 노드 1개 이상,
순환 없음, 결론 노드에서 선이 나가지 않는다. 한 쪽에 읽을 크기(배율 ≥ 0.78)로 들어가야 한다 —
python pipelines/concepts.py 가 ERROR 로 막는다(2026-09-24 대동맥 박리 도식 하나가 그날 모든 학습서를 멈췄다).
안 들어가면 노드 글부터 줄이고(판단 ≤ 30자), 그래도 층이 9개를 넘으면 단계를 합치거나 의미 단위로 나눈다.
배치(선·라벨 위치)는 코드가 정한다 — 노드 순서·선 모양을 글로 맞추려 하지 않는다.

검증 — 커밋 전 필수

python pipelines/concepts.py                     # 정리본 계약·도식 크기·근거 표시·판형 2 예산 검사(오류 0이어야 함)
python pipelines/lint_questions.py <objective 를 붙인 문항들>
python pipelines/export_concepts_web.py          # docs/concepts.js (publish.py 가 자동 실행하지만 미리 확인)

정리본을 만들었으면 과별 PDF 학습서는 다음 06:30 KST 실행이 자동으로 반영한다(.github/workflows/books.yml).