Walid-Ahmed/flashcard-deck

플래시카드 덱

주제를 질문-답변 카드 덱으로 변환합니다. 각 카드는 일반 개념을 먼저 가르치고, 깔끔하게 인쇄되며, YouTube 동영상으로 제작될 수 있습니다. 카드는 하나의 Python 파일(deck.py)과 작은 헬퍼들로 작성되며, 번들 스크립트가 모든 것을 렌더링하므로 하나의 카드 수정은 한 번의 편집과 한 번의 재빌드로 해결됩니다.

작업은 네 단계로 진행됩니다. 사용자에게 시간이 많이 걸리거나 무언가를 게시하는 각 단계 전에 반드시 물어보십시오. 덱은 사용자가 필요로 하는 내용을 다룰 때만 유용하며, 동영상은 인코딩에 수 분이 걸리기 때문입니다.

1. 인터뷰: 무엇을 만들지 질문합니다.
2. 계획: 주제와 카드 질문을 제안하고 승인을 받습니다.
3. 카드: deck.py를 작성하고, 렌더링하고, 모든 카드를 검토하며, 맞지 않는 부분을 수정합니다.
4. 추가 사항 (원하는 경우에만): 동영상, 썸네일, 게시.

1. 인터뷰

바로 만들기 시작하지 말고 질문부터 합니다. 사용자가 클릭으로 답할 수 있도록 AskUserQuestion 도구를 사용하십시오. 한 번의 호출로 모든 질문을 합니다(최대 4개 질문 가능). 사용자의 메시지나 열린 프로젝트가 이미 답변한 질문은 건너뜁니다. 먼저 "(권장)" 표시와 함께 권장 옵션을 제시하십시오.

다음에 대해 질문하십시오. 도구는 최대 4개의 질문을 받을 수 있으므로, 소스가 사용자 자료이고 다섯 번째 질문이 필요할 경우 두 번째 호출에서 마지막 질문을 하십시오.

• 소스: 카드가 다룰 내용. 예: 사용자가 이미 가지고 있는 자료 (파일 또는 폴더: PDF, 슬라이드, Word/Markdown 노트, 과정, 리포지토리, 기존 플래시카드), 이 리포지토리, 당신의 지식에서 비롯된 주제, 또는 사용자가 붙여넣을 노트. 요청이 이미 소스를 명시했다면 건너뜁니다.
• 자료를 얼마나 밀접하게 따를지 (소스가 사용자 자료인 경우에만): 자료 내용만 따름 (권장), 자료에 더해 누락된 기본 내용을 "추가됨"으로 표시, 또는 자료를 시작점으로 사용.
• 대상 및 깊이: 초급 (카드당 하나의 개념, 쉬운 용어), 중급 (개념과 짧은 코드 예제), 고급 (장단점, 경계 사례).
• 최대 카드 수: 최대 10개 (빠른 세트), 최대 20개 (권장), 최대 40개 (전체 과정), 또는 제한 없음 (자료가 필요한 만큼). 사용자는 다른 숫자를 입력할 수 있습니다. deck(..., max_cards=N)으로 기록합니다. 덱이 이 한도를 초과하면 빌드가 중지되므로 나중에 카드를 분할해도 조용히 제한을 위반할 수 없습니다. 카드가 많다는 것은 카드 길이가 길어진다는 것이 아니라 주제가 더 많다는 것을 의미합니다.
• 출력물: 카드 이미지와 PDF만 (권장), 동영상 포함, 동영상과 썸네일 포함. 동영상은 어느 쪽이든 카드 승인 후에 제공됩니다.

그런 다음, 아직 알려지지 않은 경우 일반 텍스트로 질문합니다(도구 불필요): 모든 카드에 표시될 덱 제목(예: "FastAPI" 또는 "Kubernetes"), 출력물 저장 위치(현재 프로젝트에 flashcards/ 폴더나 새 폴더 제안), 그리고 코드 예제가 소스 프로젝트 이름을 명시해도 되는지 아니면 일반적인 이름을 유지해야 하는지. 사용자 자신의 자료인 경우, 각 카드가 출처(예: "Ch. 3, p. 42")를 표시해야 하는지도 물어보십시오.

2. 계획

먼저 소스를 읽습니다. 사용자가 이미 가지고 있는 자료라면 지금 references/existing-material.md를 읽으십시오. PDF, 슬라이드, Word 파일, 폴더, 기존 플래시카드를 읽는 방법, 모든 자료를 매핑하여 누락 없이 충실하게 따르고 각 카드를 해당 페이지로 연결하는 방법을 다룹니다. 당신의 지식에서 비롯된 주제라면 선택된 수준의 학습자에게 필요한 것이 무엇인지 결정하십시오. 그런 다음 덱을 짧은 목록으로 제안합니다: 학습 순서대로 주제를 나열하고, 각 주제 아래에 각 카드의 질문을 한 줄씩 제시합니다. 파일별이 아니라 개념별(HTTP 기초, 유효성 검사, 인증)로 그룹화하십시오. 주제당 39개의 카드를 목표로 합니다. 작은 덱(약 12카드 미만)은 24개 카드로 구성된 2~3개 주제여도 괜찮습니다.

계획을 최대 카드 수 이내로 유지하고, 분할을 위한 여유를 남겨두십시오. 자료에 최대 허용 카드 수보다 더 많은 카드가 필요한 경우 핵심 아이디어를 먼저 다루고, 포함되지 않은 주제나 섹션을 나열한 후 제한을 높일 것을 제안합니다.

계획을 보여주고 카드를 작성하기 전에 승인, 변경 또는 삭제를 요청하십시오. 잘못된 주제로 40개의 카드를 작성하는 것은 가장 시간 낭비가 크므로, 이 확인은 한 번의 왕복 통신 가치가 있습니다.

3. 카드

deck.py 작성, 첫 번째 주제부터

references/deck_template.py를 출력물이 위치할 곳 옆에 복사합니다. 첫 번째 주제의 카드를 작성하고, 해당 주제만 렌더링한 후(--topic 1), 사용자에게 두세 개의 카드를 보여주고 스타일과 깊이가 적절한지 물어보십시오. 그런 다음 나머지를 작성합니다. 카드 3에서 사용자가 더 짧은 카드를 원했다는 것을 알게 되는 것은 저렴하지만, 카드 40에서 알게 되는 것은 그렇지 않습니다. 첫 번째 카드를 작성하기 전에 references/components.md를 읽으십시오: 모든 구성 요소(리드 문장, 상자, 단계, 표, 코드 예제, 콜아웃, 다이어그램)와 사용할 HTML이 나와 있습니다.

좋은 카드를 작성하는 방법과 그 이유:

• 개념 우선. 질문과 시작 문장(lead)은 어디에나 적용되는 일반적인 아이디어를 서술합니다. 프로젝트별 코드는 "예: ..."라는 캡션이 있는 example(...) 상자에 넣어 독자가 규칙을 배우고 한 가지 사례를 보게 합니다. 예제 프로젝트가 일반적인 관행과 다른 경우 예제 주석에 그렇게 명시하십시오.
• 카드당 하나의 아이디어. 두 개의 분리된 아이디어를 결합하는 질문("X가 무엇이고, 어떻게 배포합니까?")은 두 개의 카드가 필요합니다. 대조("X는 Y와 어떻게 다릅니까?") 또는 함께 있을 때만 의미가 있는 쌍은 하나의 아이디어입니다.
• 리드, 그 다음 구조, 그 다음 예제. 한두 문장의 답변, 그 다음 이를 분석하는 두세 개의 상자, 단계 또는 작은 표, 그 다음 선택적 콜아웃과 코드 예제. 독자는 리드만으로도 답변을 얻을 수 있어야 합니다.
• 바닥글은 기억해야 할 한 줄로, 15단어 미만입니다. 태그는 아이디어를 나타내는 한두 단어입니다.
• 명확하고 정확한 표현. 짧은 문장. 실제 상태 코드, 함수 이름, 명령어를 명명하고, 암시하지 마십시오.
• 다이어그램은 무언가를 추가할 때만: 흐름, 실패 경로가 있는 의사 결정, 또는 URL이나 메시지의 부분. 표가 이미 구조를 보여주는 카드에는 사용하지 않습니다.
• 상호 참조는 찾을 위치를 알려줍니다: "앱 구조의 카드 4는 서버 측을 보여줍니다."

렌더링 및 확인

python3 <skill-dir>/scripts/build_deck.py deck.py --out OUT_DIR             # 모든 카드, PDF, README
python3 <skill-dir>/scripts/build_deck.py deck.py --out OUT_DIR --topic 1   # 한 주제, 빠른 확인

<skill-dir>은 이 SKILL.md가 있는 폴더입니다. python3을 사용하거나, python이 Python 3인 경우 python을 사용하십시오. 스크립트는 playwright와 Pillow (pip install playwright pillow)가 설치된 Python과 Google Chrome 또는 playwright install chromium이 필요합니다. 각 카드를 2400 x 1698 px A4 가로 PNG로 렌더링하고, 각 카드의 내용이 (높이와 너비에) 맞는지 확인하며, 맞지 않는 카드는 중지하고 이름을 알립니다. 그런 다음 주제당 하나의 PDF, print/all-cards.pdf, README.md를 작성합니다.

• 반복 내용: 맞춤 검사는 크기를 측정할 뿐 의미는 알지 못합니다. 단계나 리드를 반복하는 상자가 있는지 찾아서 잘라내십시오.
• 최대치 초과: 덱에 max_cards보다 많은 카드가 있으면 빌드가 중단됩니다. 가장 덜 중요한 카드를 병합하거나 삭제하거나, 사용자에게 제한을 높이도록 요청하십시오. 임의로 제한을 높이지 마십시오.
• 카드가 맞지 않음: 텍스트를 줄이거나, 상자를 삭제하거나, 두 개의 카드(예: "9a"와 "9b", 또는 두 개의 질문)로 분할하십시오. 맞추기 위해 글꼴 크기를 줄이지 마십시오. 카드는 인쇄되었을 때 읽을 수 있어야 합니다.
• 렌더링 후 모든 카드를 PNG를 열어 확인하십시오. 맞춤 검사는 넘침을 잡아내지만, 혼란스러운 카드, 오해의 소지가 있는 다이어그램, 오타는 잡아내지 못합니다. 수정하고 다시 렌더링하십시오. --topic N은 한 주제를 빠르게 다시 렌더링합니다.
• 여유 공간은 정상입니다. 빌드는 1200 x 849 카드에서 CSS px 단위의 여유 공간을 보고합니다(PNG는 그 두 배입니다). 간단한 카드는 종종 150~350 px의 빈 공간을 남기며, 이는 읽기와 인쇄에 좋습니다. 채우기 위해 카드를 늘리지 마십시오. 카드가 약 400 px 이상을 남기고 얇게 느껴진다면 다이어그램이나 예제를 넣거나 인접한 카드와 병합하는 것이 좋을 수 있습니다.

4. 추가 사항: 동영상, 썸네일, 게시

사용자가 원할 때만, 그리고 카드를 승인한 후에 진행합니다. 어떤 동영상 스타일을 원하는지 묻고, 인코딩에 대략 얼마나 걸리는지 알려줍니다(노트북에서 카드당 약 15초 인코딩).

python3 <skill-dir>/scripts/build_videos.py deck.py --cards OUT_DIR --out VIDEO_DIR [--mode both|questions|cards]
python3 <skill-dir>/scripts/build_thumbnails.py deck.py --cards OUT_DIR --out VIDEO_DIR/thumbnails [--mode both|questions|cards]

• --mode both (기본값): 각 질문을 답이 숨겨진 상태와 시간 막대(6초)와 함께 보여준 후, 전체 카드(12초)를 보여줍니다.
• --mode questions: 퀴즈, 각 질문을 10초 동안 보여주고 답변은 없습니다.
• --mode cards: 리뷰, 각 전체 카드를 15초 동안 보여줍니다.
• 모든 모드는 주제당 하나의 동영상과 모든 카드를 포함하는 하나의 동영상을 만들며, 모드 이름(-questions, -cards)으로 명명되어 스타일이 서로 덮어쓰지 않습니다. build_thumbnails.py에도 동일한 --mode를 전달하여 이름이 일치하도록 하십시오.
• 모든 동영상에는 인트로와 주제 제목 화면, 그리고 YouTube가 클릭 가능한 섹션으로 변환하는 챕터가 포함된 .txt 설명이 있습니다. 챕터는 최소 10초 이상이어야 하며, 이는 YouTube에서 요구하는 사항입니다.
• 동영상에는 ffmpeg가 필요합니다. 동영상은 용량이 크므로 VIDEO_DIR을 git 리포지토리 외부에 유지하십시오.
• 썸네일은 각 동영상과 일치하도록 명명된 1280 x 720 JPEG입니다. topic(..., hook="A · B · C")는 각 주제 제목 아래의 작은 줄을 설정합니다.
• 빌드 후, YouTube에 붙여넣을 수 있는 제목과 설명을 제공하십시오: 주제와 훅이 포함된 70자 미만의 제목, 시작 줄, 주제별 글머리 기호, 모든 링크, .txt 파일의 챕터가 포함된 설명.

푸시, 게시 또는 업로드하기 전에 물어보십시오. 이러한 작업은 다른 사람에게 도달합니다. 덱의 코드 예제가 다른 사람의 과정이나 리포지토리에서 비롯된 경우 공개하기 전에 이를 언급하고 크레딧 표시를 제안하십시오(deck(..., credit="...")는 README에 하나를 추가합니다).

나중에 덱 변경하기

deck.py를 편집하고 build_deck.py를 다시 실행하십시오. 모든 카드, PDF, README를 재빌드하고 삭제된 카드의 이미지를 제거합니다. 사용자가 업데이트를 원하는 경우에만 동영상을 재빌드하고, --descriptions-only는 동영상 설명만 다시 작성합니다.

이 스킬의 파일

• scripts/build_deck.py: 카드, 맞춤 검사, PDF, README.
• scripts/build_videos.py, scripts/build_thumbnails.py: 추가 사항.
• scripts/flashcards/: deck.py가 임포트하는 헬퍼(__init__.py), 렌더러(engine.py), 카드 스타일시트(card.css: 인쇄 친화적, 흰색 바탕에 색상 윤곽선, 고정 A4 가로).
• references/components.md: 예제와 함께 모든 카드 구성 요소. 카드 작성 전에 읽으십시오.
• references/deck_template.py: 복사할 작동하는 작은 덱.
• references/existing-material.md: 사용자 자신의 노트, PDF, 슬라이드, 리포지토리 또는 플래시카드에서 덱 구축. 해당 자료가 소스인 경우 읽으십시오.