rzhang569/study-guide

복습 가이드

시험마다 하나의 자체 포함된 HTML 페이지를 생성합니다. 이 페이지는 일반 파일로 구성된 강좌 폴더를 scripts/build.py로 빌드하여 만듭니다. 페이지는 세 부분으로 구성됩니다.

• 노트: 강의별로 한 섹션. 모든 주장은 슬라이드 페이지를 인용합니다. 각 주제에는 평이한 언어 상자, 작업 예제, 그림, 빨간색 "함정" 상자가 포함됩니다. 각 섹션 끝에는 학생이 바로 읽은 내용을 스스로 테스트할 수 있는 연습 상자가 있습니다.
• 연습 센터: 네 개의 탭이 있습니다.
  • 모든 선택지에 대한 즉각적인 피드백과 설명이 있는 연습 문제 뱅크;
  • 부분 점수가 있는 단계별 단답형;
  • 실제 시험 비율에 맞춘 별도 풀의 시간 제한 모의고사;
  • 자동으로 채워지는 오답 노트.
• 진도 보고서: 페이지가 자동으로 유지 관리합니다. 나중에 이를 읽고 학생이 실제로 틀린 부분을 타겟으로 하는 새로운 문제를 작성합니다.

엔진(assets/engine.js)과 스타일(assets/page.css)은 완성되어 테스트되었으므로, 여러분의 작업은 콘텐츠와 문제를 만드는 것입니다. 페이지를 유용하게 만드는 대부분은 참조 파일에 있습니다. 해당 단계에 도달하면 읽어보십시오.

작업을 시작하기 전에...	읽을 파일
강의 섹션을 작성할 때	references/content-standard.md
문제를 작성하거나 검토할 때, 또는 모의고사를 보정할 때	references/question-bank.md
필드 이름, 진도 형식 또는 데이터베이스 문서를 확인할 때	references/data-format.md

examples/demo/는 완전한 소규모 강좌(가상의 PROB 101, 세 개 강의)입니다. 어떻게 보여야 할지 확실하지 않으면 해당 소스(sections/*.html, practice.json, mock.json, short.json)의 패턴을 복사하세요.

assets/engine.js, assets/page.css 또는 빌드된 review.html은 읽지 마세요. build.py가 이들을 인라인으로 포함하며, 수만 개의 토큰이고 수정할 필요가 없습니다.

아래 명령에서 <skill-dir>는 이 SKILL.md가 포함된 폴더입니다. python3가 없으면(Windows에서 흔함) python 또는 py -3을 사용하세요.

1. 시험이 무엇인지 파악하기

무엇이든 쓰기 전에 이 사실들을 알아내십시오. 가능할 때 직접 찾아보고, 찾을 수 없는 것만 학생에게 물어보십시오.

• 시험: 날짜와 시간, 시간(분), 해당 강의 범위, 형식, 허용 자료. 형식은 문제 유형, 각 유형의 개수와 배점을 의미합니다. 자료는 노트 시트, 계산기 또는 없음을 의미합니다.
• 출처: 슬라이드(PDF 또는 링크), 독서 자료, 강좌 웹사이트, 공식 연습 문제, 퀴즈 결과 또는 샘플 시험.
• 학생: 페이지에 사용할 언어(lang: 인터페이스용 zh 또는 en; 콘텐츠는 학생의 언어로 작성), 배경 지식 수준. "전혀 모르겠다"고 말하는 학생은 거의 모든 주제에 평이한 언어 상자가 필요합니다.

탐색할 수 있다면 강좌를 직접 조사하십시오: 일정 페이지, 강의 계획서, 게시된 퀴즈 결과. 학생에게 알릴 가치가 있는 패턴을 찾으십시오(예: "수업 중 체크포인트 문제는 특정 슬라이드 바로 뒤에 나옴" 또는 "공식 문제 은행이 시험과 같은 형식을 사용함"). 물류 정보는 페이지의 히어로 섹션에 넣으십시오.

강의 계획서에서 강좌의 AI 정책을 확인하십시오. 일부 강좌는 AI 생성 학습 자료를 금지하거나 과제에 AI 도움을 금지합니다. 정책이 이를 금지하는 경우, 구축하기 전에 학생에게 알리십시오. 채점된 숙제 답변을 페이지에 절대 넣지 마십시오.

2. 스포일러 없이 모의고사 보정하기

학생들은 종종 공식 샘플 시험을 한 번의 시간 제한 연습을 위해 아껴두고 싶어합니다. 따라서 그 문제를 읽지 말고 대신 측정하십시오.

python3 <skill-dir>/scripts/count_exam.py sample_exam.pdf

이 스크립트는 질문, 선택지 또는 시나리오 텍스트를 절대 출력하지 않습니다. 다음을 출력합니다.

• 페이지 수, 질문 수, 질문당 선택지 수;
• 배점, 시간 제한, 표지 지시사항(계산기, 노트);
• 시나리오를 공유하는 부분 제목과 질문 범위("질문 11–14 …");
• 이전 자료를 참조하는 질문 수.

출력을 사용하여 모의 섹션(유형 및 개수)과 시간 제한을 설정하십시오. 이전 시나리오를 재사용하는 단답형과 같은 이전 자료를 참조하는 질문은 시험 구조를 설명할 때 해당 시나리오와 함께 속합니다.

스크립트가 무엇을 알려줄 수 없으면, 알 수 없음으로 보고하고 학생에게 표지 페이지를 보도록 요청하십시오. 질문 내부의 단어나 숫자를 출력하는 자체 프로브를 작성하지 마십시오. 우연한 "총계" 또는 "%"조차도 질문의 주제를 암시하며, 방정식의 숫자는 질문을 드러냅니다.

샘플이나 답안 키를 열기 전에 물어보십시오. 학생이 읽는 것을 허용하더라도, 보정(구조, 난이도, 스타일)에만 사용하십시오. 그 질문이나 시나리오를 페이지에 절대 복사하지 마십시오.

3. 강좌 폴더 설정하기

python3 <skill-dir>/scripts/build.py --init <course-dir>

이렇게 하면 데모 강좌가 복사됩니다. 그런 다음 course.json을 편집하십시오.

• title, lang 및 lectures. 강의 레이블은 문제와 그룹이 사용하는 것과 정확히 일치해야 합니다(예: "L1" 또는 "L5–L6").
• storageKey: 강좌와 시험별로 고유해야 합니다(예: "bio201-mt1"). 진도가 이 키 아래에 저장되므로, 학생이 시작한 후에는 절대 변경하지 마십시오.
• mock.sections: 시험 순서대로 질문 유형당 하나의 항목, 실제 시험지와 일치하는 개수.
• mock.minutes: 선택할 시간 제한 옵션. 실제 시간을 포함하고, 모의고사가 긴 질문을 생략한 경우 비례적으로 더 짧은 옵션도 제공하십시오.

데모의 섹션과 질문을 교체하면서 삭제하십시오. 모든 필드는 references/data-format.md를 참조하십시오.

4. 섹션 작성하기

강의당 하나의 파일을 sections/에 작성하십시오(10-l1.html, 20-l2.html, …). 물류 정보를 위한 00-hero.html과 마지막 함정 목록도 포함하십시오. 각 강의는 <section class="part" id="...">입니다. 연습 상자는 연습 그룹이 "sec"로 해당 id를 가리키면 자동으로 나타납니다.

references/content-standard.md에는 전체 레시피와 모든 구성 요소의 HTML이 있습니다. 간단히 말해: 모든 주장을 인용하고, 어려운 강의는 용어집과 비유로 시작하고, 각 주제에 한 줄 요약, 공식 전에 구체적인 예, 평이한 언어 상자, 그림이 도움이 되는 곳에 그림, 참/거짓 문제가 왜곡하는 내용에 대한 함정 상자를 제공하십시오.

5. 문제 작성하기

세 개의 문제 은행이 있습니다. references/question-bank.md에는 규칙과 감사 체크리스트가 있습니다.

• practice.json: 강의당 8–15문제. 단일 선택, 참/거짓, 다중 선택 및 빈칸 채우기, 가끔 플래시카드를 혼합합니다. 모든 선택지에는 자체 설명이 있습니다.
• mock.json: 자체 문제, 연습 문제의 복사본이 절대 아닙니다. 각 유형에서 한 시험지가 뽑는 양의 약 두 배를 목표로 하여, 반복 시험지가 다르도록 합니다. 실제 시험 스타일과 일치해야 합니다.
• short.json(선택 사항): 시험의 단답형 유형에 대한 단계별 버전. 각 단계는 허용적인 빈칸 채우기, 선택 또는 모범 답안에 대한 자체 확인입니다.

6. 빌드 및 확인

python3 <skill-dir>/scripts/build.py <course-dir>

오류는 빌드를 중단합니다. 경고는 문제 은행 검사에서 발생하며, 이유가 없으면 수정하십시오. 다음과 같은 패턴을 지적합니다.

• 너무 많은 문제에서 정답이 가장 긴 선택지인 경우;
• 하나의 글자가 너무 자주 표시된 정답인 경우;
• 모든 다중 선택 문제가 동일한 개수의 답변을 가지는 경우;
• 모의 문제가 숫자만 바뀐 연습 문제인 경우.

--strict를 추가하여 경고가 빌드를 종료 코드 2로 중단하게 하여(페이지는 여전히 작성됨) 깨끗해질 때까지 계속 수정할 수 있습니다. 그런 다음 <course-dir>/review.html을 브라우저에서 열고 확인하십시오.

• 콘솔에 오류가 없고 수식이 렌더링되는지;
• 연습 문제, 단답형 단계, 전체 모의 시험지가 작동하는지;
• 375px 너비에서 페이지를 가로로 스크롤하지 않는지(그림과 표는 자체 상자 내에서 스크롤됨);
• 그림의 텍스트가 선, 화살표 또는 다른 텍스트와 겹치지 않는지(스크린샷을 찍으십시오).

7. 전달하기

• 로컬(모든 에이전트): 파일 경로를 제공하십시오. 진도는 해당 브라우저의 localStorage에 저장됩니다. 연습 센터의 진도 내보내기 버튼은 학생에게 다시 붙여넣을 수 있는 JSON을 제공합니다.
• claude.ai 아티팩트(Claude 전용, 실험적, 아직 종단 간 테스트되지 않음): 빌드된 HTML을 게시하고 db 기능을 부여하십시오. window.claude.use("db")를 사용할 수 있으면 엔진이 진도를 progress/practice 및 progress/mock 문서에 미러링하고 progress/report에 요약을 유지합니다. 이에 의존하기 전에 게시된 페이지에서 한 문제에 답하고 progress/report를 다시 읽으십시오. 문서가 없으면 학생에게 진도 내보내기를 대신 사용하라고 알리십시오.

학생에게 페이지 사용 방법을 두세 줄로 알려주십시오: 섹션 읽기, 연습 상자 풀기, 마지막에 가까워질수록 모의고사 보기, 하루 전날 오답 노트 보기.

8. 피드백 루프 닫기

학생이 돌아오면, 무엇이든 변경하기 전에 진도를 읽으십시오. 그들이 붙여넣거나 보낸 내보낸 JSON(report 필드) 또는 아티팩트 동기화가 작동하는 경우 progress/report 데이터베이스 문서를 사용하십시오. 보고서에는 다음이 나열됩니다.

• 강의별 첫 시도 정확도;
• 놓친 모든 연습 문제와 학생이 답한 내용 및 정답;
• 놓친 단답형 단계;
• 모의고사 기록 및 마지막 시험지의 오답 및 플래그된 문제.

그런 다음:

1. 약점을 몇 줄로 명명하십시오. 첫 시도 정확도가 약 80% 미만인 강의, 반복되는 오해, 계속 실패하는 단답형 단계를 세십시오. 또한 확실하지 않다고 플래그되었지만 정답을 맞춘 문제도 세십시오. 이는 불확실한 지식입니다.
2. 각 약점에 대해 새로운 문제를 작성하십시오. 동일한 개념을 다른 단어, 숫자 또는 시나리오로 다시 질문하십시오. 그들이 놓친 문제를 절대 반복하지 마십시오. 새 ID로 practice.json에 추가하고, 모의 풀이 얇은 경우 mock.json에도 추가하십시오.
3. 문제뿐만 아니라 설명도 수정하십시오. 오해가 반복되면 섹션이 아마도 그것을 잘못 설명하고 있을 것입니다. 그 정확한 혼동을 대상으로 하는 평이한 언어 상자, 작업 예제 또는 그림을 추가하십시오.
4. 다시 빌드한 다음, 학생에게 무엇이 변경되었고 어디인지 알리십시오.

편집 시 기존 진도 유효성 유지

레코드는 storageKey, 문제 id 및 원래 선택지 인덱스로 키가 지정됩니다. 따라서:

• storageKey와 기존 id를 유지하십시오.
• 답변된 문제에서 선택지를 재정렬, 삽입 또는 삭제하지 마십시오(대신 새 문제를 추가하십시오).
• 다른 문제에 기존 id를 재사용하지 마십시오.
• 문제의 의미나 답이 변경되면 새 id를 부여하고 이전 id를 제거하십시오. 제거된 id의 레코드는 무시되며, 잘못 읽히지 않습니다.

엔진은 id의 시드로 선택지 표시 순서를 섞으므로 저장된 인덱스는 올바르게 유지됩니다. 답이 표시되는 글자를 변경하려면 선택지를 재정렬하는 대신 "show"를 설정하십시오(references/data-format.md 참조). 문제 줄기와 설명의 오타나 표현 수정은 항상 안전하며, 섹션 HTML 편집도 마찬가지입니다.

학생들이 요청한 사항

다음 교훈은 실제 시험에 사용된 복습 페이지를 구축하면서 얻은 것입니다.

• 추상적인 설명은 효과적이지 않았습니다. 학생들은 먼저 구체적인 숫자("동전을 10번 던져...")를 요청했고, 그 다음 공식을 요청했으며, 유도 과정은 접어서 시험 범위 밖이라고 표시했습니다.
• 연습하기 전에 여러 강의를 공부하는 것은 지루했습니다. 그래서 각 섹션은 자체 연습 상자로 끝납니다.
• 형식에 대한 깐깐함은 짜증을 유발했습니다. 예를 들어 1/2 대신 0.5라고 틀렸다고 표시되는 경우입니다. 엔진은 숫자 답변을 값으로 비교합니다. accept에 텍스트 변형을 나열하십시오.
• 학생들은 답변 패턴을 빨리 배웠습니다. 정답이 일반적으로 가장 긴 선택지였고, 모든 다중 선택 문제에 3개의 답변이 있었으며, 정답이 항상 B였습니다. 빌드는 처음 두 가지를 감사합니다. 엔진은 표시 순서를 섞습니다.
• 연습 문제를 재사용한 모의고사는 이해도가 아닌 기억력을 측정했습니다. 그래서 모의 풀이 분리되어 있습니다.
• 학생들은 선택지 텍스트를 선택하여 복사할 수 있기를 원했고, 시간이 다 되면 자동으로 제출되는 타이머를 원했습니다.