KMLE/USMLE 문제 생성 규칙

필드

schemas/frontmatter.md 의 문제형 규격을 그대로 따른다. 특히:

• answer_separated: true 필수. stem에는 정답 힌트를 넣지 않는다.
• id 는 state.next_id('kmle') 또는 next_id('usmle') 로만 발급.
• topic 은 16개 임상 과목 기준(내과/외과/소아/산부인과/…)에서 고른다.
• design(출제 설계·정보 역할) 필수 — 2026-09-19 이후 문항. 아래 「출제 설계 먼저」 참고.

저장 경로

• KMLE → content/kmle/{연도}/{id}.md
• USMLE → content/usmle/{id}.md

USMLE 전용 규칙

• frontmatter에 step("Step 1" 또는 "Step 2")과 exam_subject를 넣는다.
  없으면 indexer.py --check에서 실패하고 웹/CLI 퀴즈에 분류되지 않는다.
  • Step 1 과목: Pharmacology, Immunology, Biochemistry, Microbiology, Pathology, Physiology
  • Step 2 과목: Internal Medicine, Surgery, Neurology, Pediatrics, Obstetrics & Gynecology, Psychiatry
• stem·보기는 실제 시험 형식대로 영문, 해설·design 은 한글(핵심 용어 영어 병기)로 쓴다.
  design.findings[].item 은 stem 의 영문 표현 그대로 인용한다(문항에 있는 정보만 인용할 수 있다).
• 본문 ## 정답 및 해설은 - **키**: 값 불릿 구조를 유지한다
  (export_usmle_web.py가 이 텍스트를 파싱해 웹/CLI 해설로 사용).
• 생성 후 반드시 python pipelines/export_usmle_web.py로 docs/questions_usmle.js를
  재생성해 같은 커밋에 포함한다(안 하면 개인 페이지에 새 문항이 안 뜬다).

품질 규칙

1. 최근 recent_topics() 로 나온 주제는 피한다(중복 방지).
2. 임상 추론형으로 작성: 단순 암기보다 판단(진단·감별·검사 선택·치료·금기·기전)을 묻는다 — 목표 배분은 「판단 단계 구성」.
3. confidence 는 출처의 신뢰도다(교과서·가이드라인이 일치하면 high, 논쟁적이면 medium/low).
   의학적으로 검증됐다는 표시가 아니다 — 생성 모델이 스스로 매긴 confidence 를 검토의 대체물로
   쓰지 않는다. 검토 완료 표시는 사람이 review_status: reviewed + reviewed_by + review_note 로만 한다.
4. 생성 직후 스스로 정답의 타당성을 한 번 검증한다. 의학적 정확도는 자기검증에 한계가 있으므로,
   애매하면 문제를 버리고 다시 만든다. 근거를 확인하지 못한 주장은 확인한 것처럼 쓰지 않는다.

출제 설계 먼저 — design (2026-09-18 개정의 핵심)

문항을 쓰기 전에 네 가지를 정하고 frontmatter design 에 남긴다. 문항은 이 설계를 평가하도록 쓴다.

필드	무엇을 적나
target	무엇을 평가하는가 — 진단·감별·검사 선택·치료·다음 처치·기전·금기·예후 중 하나
decision	정답을 고르게 하는 핵심 판단 한 문장
rival	학습자가 실제로 혼동할 대안(보기 letter 1~2개)
discriminator	그 대안과 정답을 가르는 소견
steps	정답까지 필요한 판단 단계 수(1~4) — 난이도의 근거
chain	판단 사슬: steps 개의 「단서 → 결론」 한 줄씩(2026-09-24 이후 문항 필수 — 개수가 steps 와 다르면 ERROR). 예: "촉지 자반 + 크리오글로불린 + C4 저하 → 혼합 크리오글로불린혈증" · "신염·운동신경병 없음 → 경증–중등증" · "HCV RNA 양성 + 경증 → 항바이러스제". 채점 뒤 앱이 보여 줘 학습자가 어느 단계에서 갈렸는지 찾는다
findings	주요 정보의 역할(아래) — {item, role, why} 목록, 10개 이하
summary	핵심 판단 요약 2~3문장 — 주요 소견에서 정답으로 이어지는 근거
switch	(선택) {choice, condition} — 어떤 조건이 바뀌면 다른 보기가 더 적절해지는가

평가 대상과 보기가 맞아야 한다. 치료를 묻는다면 치료 결정을 가르는 정보(범위·중증도·금기·
동반질환)가 보기 선택을 실제로 바꿔야 한다. 예: 어루러기 「가장 적절한 치료는?」에서 보기에 경구 아졸이
없으면 병변 범위·첫 발병·면역 상태는 답에 아무 영향을 주지 못한다 → 실제 경쟁 대안을 보기로 넣는다.

정보의 역할(findings[].role) — 하나의 정보가 여러 역할을 가질 수 있다

• key — 정답을 지지하는 결정적 소견
• rule_out — 경쟁 진단의 가능성을 낮추는 정상·음성 소견
• management — 중증도·금기·치료 선택에 영향을 주는 정보
• background — 판단에 영향이 적지만 임상적으로 자연스러운 배경 정보

item 은 발문·활력징후·검사에 실제로 있는 표현을 그대로 인용한다(린터가 문항에 없는 정보를 인용하면
ERROR). 영상·심전도 그림의 소견은 영상:·심전도: 로 시작해 적는다. 모든 자료를 하나씩 적지 않는다 —
판단에 쓰였거나 학습자가 끌려가기 쉬운 정보만 고른다. 아무도 끌려가지 않을 정상값은 생략한다.

정상 소견·배경 정보 — 의도된 설계다 (삭제·축소 금지)

실제 시험처럼 여러 정보 가운데 중요한 단서를 골라 감별과 치료를 결정하는 능력을 훈련하려는 것이다.
「문항이 길다」「정상 소견이 많다」는 이유만으로 정보를 빼거나, 핵심 단서만 남긴 형태로 바꾸지 않는다.
학습 목표: 각 소견의 진단적·치료적 중요도 판단 · 의미 있는 정상·음성 소견 활용 · 중요도 낮은 정보에
끌려가지 않기 · 충분한 정보 속에서 제한된 시간에 최선의 답 고르기. 「정상은 무시하고 비정상만 찾으면
된다」는 풀이 습관을 강화하지 않는다 — 정상·음성 소견이 대안을 낮추거나 처치를 바꾸는 문항을 꾸준히 섞는다.

1. 활력징후는 정상이라도 항상 준다. 실제 시험은 예외 없이 혈압·맥박·호흡·체온 4종을 제시한다.
   다만 형식을 채웠다고 문항 품질이나 난이도가 높아지는 것은 아니다.
2. 정상·음성 소견은 역할이 있을 때 의미가 있다. 경쟁 진단의 가능성을 낮추거나(rule_out) 처치를
   바꾸는(management) 정상 소견을 의도적으로 넣는다. 단 정상·음성이라는 이유만으로 특정 질환을
   「완전히 배제한다」고 쓰지 않는다 — 「가능성을 낮춘다」가 정확하다(린터가 단정 표현을 검토 신호로 띄운다).
3. 자연스러운 자료만. 그 상황의 실제 환자에게 시행하고 주어질 자료를 쓴다. 배경 정보를 넣으려고
   임상적으로 부자연스러운 검사 목록을 만들지 않는다(예: 첫 발병 어루러기에 HIV 검사·배양). 병력으로
   주는 것이 자연스러우면 병력으로 준다(「당뇨병·면역억제제 복용 없음」).
4. 경미한 이상값은 우연한 소견으로 해석 가능한지, 정답의 유일성을 해치지 않는지 확인하고 넣는다
   (background + why 로 「왜 결정적이지 않은지」를 남긴다).
5. 소견은 서술하되 해석을 괄호로 떠먹이지 않는다(에포님 금지). 예: 밀어도 벗겨지지 않으며(니콜스키 음성) 처럼 소견 + (징후명 양성/음성) 을 함께 쓰면 답을 알려주는 것이다. 소견 서술('문지르면
   벗겨진다') 또는 징후 결과('니콜스키징후: 음성')를 labs 한 줄로 — 둘 중 하나만. 구조화 자료에
   넣은 값은 stem 산문에서 되풀이하지 않는다.
6. 보기 5개는 동질적·평행하게, 길이도 고르게. 전부 같은 층위(전부 약물 / 전부 처치 / 전부 진단).
   정답만 유독 길거나 정답만 복합 처치면 길이·완결성이 정답을 누설한다.
7. 정답 단어 비노출. stem·질문에 정답 보기의 핵심 단어(진단명·약물명)를 넣지 않는다.

난이도(difficulty 1~5) — 추론 구조로 매긴다, 길이로 매기지 않는다

정상값의 수, 검사 항목의 수, 지문 길이만으로 난이도를 높게 매기지 않는다. 아래를 본다:
필요한 판단 단계(design.steps) · 경쟁 선택지의 그럴듯함 · 여러 소견을 통합해야 하는 정도 ·
진단 이후 치료나 다음 행동까지 결정해야 하는 정도.

값	인지 수준	판별 기준
1	단순 회상	한 개 사실을 바로 떠올리면 풀림
2	기본 적용	전형적 제시 → 진단/약물 1:1. 특징적 단서 하나로 풀림
3	임상 추론	소견을 종합해 감별 후 최적 선택. 최소 1개 대안을 소견으로 낮춰야 함
4	2차 추론	진단 뒤 다음 단계·기전·금기까지. 정답까지 2단계 이상(steps ≥ 2)
5	함정·통합	매력적 오답이 실제로 경쟁하거나, 하면 안 되는 것·기초의학 통합 요구

• 특징적 단서 하나로 풀리는 기본 문항도 필요하다 — 일괄 금지하지 않는다(difficulty 1~2로 정직하게).
  다만 복합 추론(difficulty ≥ 4)을 목표로 만든 문항이 실제로는 키워드 하나로 풀리면 수정 대상이다
  (린터가 difficulty ≥ 4 인데 steps < 2 면 WARN, 결정적 단서가 하나뿐인 진단 문항은 검토 신호).
• 정답을 알려주는 단서가 중복되는 것(예: KOH·우드등이 모두 같은 진단을 가리킴)은 교육 목적에 따라
  판단한다 — 진단이 아니라 치료를 묻는 문항이면 진단 단서가 겹쳐도 결함이 아니다.
• 목표 분포: 하루 세트에서 difficulty 35가 다수(암기형 12는 과목당 최대 1개).

판단 단계 구성 — 하루 세트(2026-09-23 사용자 채택 「판단 단계를 높인다」)

사용자는 본2 — 내신은 끝나 가고 국시·USMLE 대비가 목적이다. 실제 시험은 「진단 → 중증도·금기 확인 → 처치」처럼
여러 단계를 잇는 문항이 많으므로 하루 세트를 이렇게 맞춘다(lint_questions.py 가 끝에 구성 WARN 을 낸다):

• 판단 3단계 이상(steps ≥ 3) 40 % 이상 · 1단계(단순 회상) 10 % 이하.
• 한 평가 목표(target) 50 % 이하, 「치료」+「다음 처치」 합 55 % 이하 — 둘은 같은 판단 축이라 합쳐서 센다.
  진단·감별·검사 선택·기전(USMLE Step 1)·금기·예후를 섞는다.
• 단계는 판단이지 정보량이 아니다. 3단계 문항은 사슬의 각 줄이 다른 단서로 다른 결정을 내려야 한다
  (같은 진단을 세 번 확인하는 것은 1단계다).
• 세트를 짜기 전에 python pipelines/item_stats.py --brief 로 내 약한 평가 목표를 보고 그 목표를 세트에 조금 더 넣는다
  (구성 기준은 지킨다). 묶음이 작으면 「판단할 만큼 쌓이지 않음」 — 그때는 구성 기준만 따른다.

난이도를 올리는 구조적 장치 (difficulty ≥ 4 는 최소 2개)

1. 2차 질문: "진단은?" 대신 "다음 단계는?", "기전은?", "금기인 것은?"
2. 정답 단어 비노출: 소견으로 유추하게 하고, 정답 힌트가 새면 다시 만든다.
3. 동질적·매력적 오답: 같은 범주로 맞추고 흔한 오개념을 심는다. design.rival 에 가장 경쟁하는
   대안을 적는다. 명백히 틀린 장식성 보기는 금지.
4. 기초의학 연계(Step 1) / 함정(Step 2): 금기·순서 오류를 오답으로 배치.
5. 정답 위치 무작위: 문항마다 정답 위치를 따로 정한다(앱은 보기를 셔플하지 않는다). 글자 수만 고르게 맞추고
   ABCDE 순서로 돌리면 번호만 보고 풀린다(린터 mix WARN).

답이 문항 밖·보기 모양으로 새지 않게

답은 문항 안의 판단으로만 가려져야 한다. 아래는 린터가 새 문항에서 잡는다.

1. subtopic 에 결론을 넣지 않는다. subtopic 은 질환군·주제만(「Herpes Zoster」). 「… — Oral Valacyclovir」처럼
   진단·약·처치를 붙이면 검색·새 자료 목록에서 답이 보인다(앱은 이제 채점 전에 숨기지만 다른 화면엔 남는다).
   린터 WARN subtopic-conclusion(「 — 」가 있으면).
2. 한정어를 오답 표지로 쓰지 않는다. 「단독·만·없이·항상·절대 / only·alone·without」가 오답에만 붙으면 요령으로 풀린다
   거울쌍(「X 없이」 vs 「X 뒤」, 「단독 먼저」 vs 「A 뒤 B」) 중 하나가 정답인 구성도 금지.
   예후 문항에서 정답만 좋은 경과(나머지 넷은 나쁜 경과)로 만들지 않는다. 린터 WARN qualifier-tell.
3. 단서를 쌓아 steps 를 부풀리지 않는다. 같은 진단을 가리키는 결정적 단서를 셋 넘게 겹치면 1단계다. stem 이 진단을 말해 놓고 기전·사실을 묻는 문항은 steps 1 · difficulty ≤ 2.
4. management 정보는 그것이 바꾸는 보기가 있어야 한다. 「임신 가능성 없음」「간기능 정상」을 넣었으면 그 정보로 탈락하거나
   살아나는 보기가 보기 안에 있어야 한다. 보기는 같은 시점·층위로 — 급성 통풍 발작 문항에 요산저하제를 섞지 않고
   실제 경쟁 대안(경구 스테로이드 등)을 넣는다. 적응이 전혀 없는 장식성 보기(서맥에 아미오다론) 금지.
5. 오답 설명은 rival 보기부터 distractors 로. 새 문항은 최소 design.rival 보기에 distractors.<보기>
   (tempting·answer_first·discriminator·when_right)를 쓴다 — 틀렸을 때 앱이 바로 보여 주고 [dist] 큐가 줄어든다.
6. 용어 — USMLE 는 검사 이름·값·참고치를 영어·미국 단위로(린터 ERROR usmle-labs-korean).
   KMLE 는 한 세트 안에서 같은 대상을 한 용어로(갑상선/갑상샘, 담관/쓸개관, 아밀라아제/아밀레이스를 섞지 않는다), 백혈구 등 단위는 /μL.

자료 구조 — 차트형 제시

frontmatter의 vitals·labs 를 쓰면 웹이 박스로 렌더한다(schemas/frontmatter.md).

• labs 에는 참고치(ref)를 함께 줘 학습자가 정상·이상을 스스로 가리게 한다. 이상값뿐 아니라 그 상황에서
  실제로 함께 나오는 정상값도 준다 — 그 정상값이 무엇을 낮추는지는 design.findings 에 적는다.
• 다장기 통합: 활력징후+검사+영상소견(텍스트)+기관 소견을 함께 주어 통합 판단을 요구할 수 있다.
• 영상 한계: X선·CT·조직·안저 등은 이 스킬에서 다루지 않는다(오픈데이터 영상 세트가 맡는다).

심전도 문항에 figure 를 능동적으로 넣는다 (다양성)

하루 생성 세트마다 심전도 판독 문항을 최소 1개 포함하고, frontmatter에 figure 를 넣어 실제 파형을
붙인다. 파형이 곧 정답이니 정답과 반드시 일치시킨다. design.findings 에는 심전도: … 로 인용한다.

① 합성(리듬형) — 기본: figure: {type: ecg, rhythm: afib, rate: 112}

• 가능한 rhythm: sinus·brady·tachy·afib·flutter·vtach·vfib·cavb·asystole.
• 합성 금지: 브루가다·STEMI·각차단 등 ST/복합체 모양·12유도형.

② 실데이터 12유도 — 모양 기반 진단은 여기로. 커밋된 에셋만 참조:
figure: {type: ecg12, source: assets/ecg/ptbxl-00172-crbbb.json}
사용 가능한 커밋 에셋(assets/ecg/README 참조): ptbxl-00172-crbbb, ptbxl-00180-clbbb,
ptbxl-08191-ami, ptbxl-00270-imi, ptbxl-00001-norm, mitdb-100.

해설 템플릿 — 고정(LOCK)

## 정답 및 해설 본문은 아래 불릿을 항상 - **키**: 값 으로 채운다(웹이 항목별 박스로 렌더).

1. 정답근거 — 이 환자 소견 → 정답까지의 핵심 논리(2차 추론이면 단계 명시).
2. 오답감별 — 정답 외 모든 보기를 letter별 하위 불릿으로. 가능하면 「왜 떠올릴 수 있는지」와
   「이 증례에서 왜 우선순위가 낮은지」를 연결한다. 명백히 관련 없는 오답에 억지로 그럴듯한 이유를
   붙이지 않는다(그런 보기는 애초에 동질적 오답으로 바꾼다).

   - **오답감별**:
     - (A) …
     - (C) …

3. 임상핵심 — 다음 문제에서도 쓸 수 있는 판단 기준 한 줄.
4. 출처 — 근거(교과서·가이드라인). 논쟁적이면 confidence 하향.

• 정보 선별(결정적 단서 · 의미 있는 정상·음성 · 비중 낮은 정보 · 핵심 판단 요약 · 조건 전환)은 본문에
  다시 쓰지 않는다 — design 에서 웹이 「정보를 어떻게 선별했는가」 블록으로 그린다(채점 후에만,
  요약은 펼치고 단서별 분류는 접어서). 이미 쓴 해설을 반복하지 말고 판단 기준만 남긴다.
• switch 는 교육적으로 유용한 문항에 한해 한 가지만. 단일 소견만 바꾸면 충분하지 않은 상황을 과장하지 않는다.
• 관리·처치형/감별표가 유용한 문항은 appendix.가이드라인 에 결정표를 추가. appendix.최신지견·참고문헌 병기.

검증 — 형식 검사와 내용 검토를 나눈다

1) 형식 검사(코드) — 커밋 전 필수

python pipelines/lint_questions.py content/kmle/2026/kmle-2026-0129.md   # 또는 여러 파일

• ERROR 0 이어야 커밋한다(에포님 떠먹임·오답감별 누락·design 누락/오류·문항에 없는 정보 인용 등).
• WARN 중 subtopic-conclusion·qualifier-tell·세트 mix(정답 순서·목표 편중·3단계 비율)는 고치고 커밋한다.
  나머지 WARN(활력징후 부재·정답 보기만 김·정보 역할 과다·난이도와 판단 단계 불일치)은 고치거나, 남기는 이유를 보고에 적는다.
• REVIEW 는 내용 검토 신호다 — 판정이 아니므로 실패로 치지 않는다. 신호가 없다고 검증된 것도 아니다.

2) 내용 검토(사람) — 생성 후

python pipelines/review_questions.py --date 2026-09-19 --out review.md

검토지에서 다음을 확인한다: 단일 최선의 답이 성립하는가 · 정상·음성 소견의 의미를 과장하지 않았는가 ·
추가 정보가 정답·해설과 모순되지 않는가 · 정보가 많아도 목표 판단을 평가하는가 · 해설이 문제에 없던
사실을 끼워 넣지 않았는가 · 검사·치료 근거가 해당 시험의 국가·진료 맥락(KMLE=한국, USMLE=미국)에 맞는가.
확인한 문항만 review_status: reviewed·reviewed_by·review_note 를 적는다(린터가 근거 없는 reviewed 를 막는다).
근거를 확인하지 못한 임상적 주장이 있으면 needs_revision 으로 둔다.

3) 오답 뒤 학습 흐름 필드 — objective 필수, distractors 는 rival 보기부터

• objective: 2026-09-21 이후 새로 만드는 KMLE·USMLE 문항에는 반드시 붙인다. 이 문항이 평가하는
  학습 목표의 정리본 id(content/concepts/<과>/cn.*.md). 기존 목표로 묶을 수 있으면 그 id 를 쓰고, 새 목표면
  id 만 붙여 둔다 — 정리본은 내가 그 문항을 틀렸을 때 /gen-concept 큐가 자동으로 집어 간다(하루 상한 안에서).
  같은 원리를 묻는 문항은
  같은 id 로 모은다. 질환명이 같아도 목표(진단/치료/검사 선택)가 다르면 다른 id. 정리본이 없으면 id 만 붙여도 된다 —
  학습서에 「정리본 작성 대기」로 잡히고, 다음에 정리본(schemas/frontmatter.md concept 계약)을 쓴다.

• distractors: 보기별 tempting·answer_first·discriminator(+타당할 때만 when_right, 도식 노드 split).
  「학습자가 ~를 모른다」 식으로 쓰지 않는다(린터 ERROR). case_path 는 정리본 도식의 노드를 선을 따라 적고,
  문항이 주지 않은 정보는 state: unknown 으로 남긴다(음성으로 채우지 않는다).

• 정리본의 출처는 실제로 확인한 것만(PubMed·기관 쪽) 적고 checked 에 무엇을 대조했는지 쓴다. 확인 못 한 세부는
  「본문 대조 전(검토 항목)」으로 적는다. review_status: unreviewed 로 두고 사람만 reviewed 로 바꾼다.

• 정리본 자체를 쓸 때는 /gen-concept(판형 2)을 따른다.

커밋 전 문항 자가 점검(체크리스트)

• design 을 문항보다 먼저 정했고, 보기가 그 판단을 실제로 가르는가?
• 혼동 대안(rival)이 실제로 경쟁하고, 구분 소견이 문항 안에 있는가?
• 정상·음성 소견을 「배제」로 과장하지 않았는가? 부자연스러운 검사를 끼워 넣지 않았는가?
• difficulty 가 정보량이 아니라 판단 단계·대안의 그럴듯함을 반영하는가?
• 활력징후 4종 · 에포님 떠먹임 없음 · 보기 동질·평행 · 정답 위치 무작위(순환 아님)
• subtopic 에 결론 없음 · 한정어·거울쌍 없음 · management 정보가 바꾸는 보기가 있음 · USMLE 검사명 영어
• 오답감별이 보기별 하위 불릿이고, 관련 없는 오답에 억지 이유를 붙이지 않았는가?

본문 구조(사람이 읽는 부분)

## 문제
{stem}

- A. …
- B. …

## 정답 및 해설
> 정답: {answer}
{explanation}