Walid-Ahmed/flashcard-deck

フラッシュカードデッキ

トピックを、最初に一般的な概念を教え、きれいに印刷でき、YouTube動画にもできる質疑応答カードのデッキに変換します。カードは1つのPythonファイル（deck.py）と小さなヘルパーで記述され、バンドルされたスクリプトがそこからすべてをレンダリングするため、1枚のカードの修正は1回の編集と1回のリビルドで済みます。

作業は4つの段階に分かれます。ユーザーの時間を消費したり、何かを公開したりする各段階の前に確認を取ってください。デッキはユーザーが必要とするものをカバーして初めて有用であり、動画のエンコードには数分かかるからです。

1. インタビュー: 何を作るか尋ねます。
2. 計画: トピックとカードの質問を提案し、承認を得ます。
3. カード作成: deck.pyを書き、レンダリングし、すべてのカードを確認し、合わないものを修正します。
4. 追加機能（必要な場合のみ）: 動画、サムネイル、公開。

1. インタビュー

まず構築せずに質問から始めます。AskUserQuestionツールを使用して、ユーザーが回答をクリックできるようにします。すべての質問を1回の呼び出しで行います（最大4つの質問まで）。ユーザーのメッセージや開いているプロジェクトですでに回答されている質問はスキップします。推奨オプションがある場合は、最初に（推奨）とマークして提示します。

以下について質問します。ツールは最大4つの質問まで受け付けるため、ソースがユーザーの教材であり、5つ目の質問が必要な場合は、最後の質問を2回目の呼び出しで行います。

• ソース: カードがカバーする内容。以下のようなオプション: ユーザーがすでに持っている教材（ファイルまたはフォルダ: PDF、スライド、Wordまたはマークダウンノート、コース、リポジトリ、既存のフラッシュカード）、このリポジトリ、あなた自身の知識からのトピック、またはユーザーが貼り付けるノート。リクエストにすでにソースが指定されている場合は、これをスキップします。
• どの程度忠実に従うか（ソースがユーザーの教材の場合のみ）: 教材のみに従う（推奨）、教材に加えて不足している基本事項を追加としてマークする、または教材を出発点として使用する。
• 対象者と深さ: 初心者（1つの概念に1枚のカード、平易な言葉）、中級者（概念と短いコード例）、上級者（トレードオフ、エッジケース）。
• 最大カード数: 最大10枚（クイックセット）、最大20枚（推奨）、最大40枚（フルコース）、または制限なし（教材が必要とするだけ）。ユーザーは他の任意の数値を入力できます。deck(..., max_cards=N)として記録します。デッキがそれを超えるとビルドが停止するため、後でカードを分割しても静かに制限を超えることはありません。カード数が多いほどトピックが増えるのであって、1枚のカードが長くなるわけではありません。
• 出力: カード画像とPDFのみ（推奨）、動画も追加、または動画とサムネイルも追加。動画はカードが承認された後であれば、どちらにせよ作成可能です。

次に、まだ不明な場合は、平文で（ツール不要）尋ねます。すべてのカードに表示されるデッキタイトル（例：「FastAPI」や「Kubernetes」）、出力の保存先（現在のプロジェクト内のflashcards/フォルダ、または新しいフォルダを提案）、コード例でソースプロジェクトの名前を明記してもよいか、それとも汎用的に保つべきか。ユーザー自身の教材の場合は、各カードに出典（例：「第3章、p.42」）を表示するかどうかも尋ねます。

2. 計画

まずソースを読みます。ユーザーがすでに持っている教材の場合は、今すぐreferences/existing-material.mdを読んでください。PDF、スライド、Wordファイル、フォルダ、既存のフラッシュカードの読み方、教材全体をマッピングして何も見逃さない方法、忠実に従う方法、各カードを元のページに紐付ける方法が説明されています。あなた自身の知識からのトピックの場合は、選択されたレベルの学習者に必要なものを決定します。次に、デッキを短いリストとして提案します。学習順のトピックと、各トピックの下に各カードの質問を1行ずつ並べます。ファイルごとではなく、概念（HTTPの基礎、バリデーション、認証）でグループ化します。トピックあたり3～9枚のカードを目指します。小さなデッキ（約12枚未満）は、2～3トピック、各2～4枚で問題ありません。

計画を最大カード数内に収め、分割用に1～2枚の余裕を残します。教材に最大カード数以上のカードが必要な場合は、まず核となるアイデアをカバーし、次に除外されたトピックやセクションをリストアップし、制限を引き上げる提案をします。

計画を表示し、カードを書く前に承認、変更、または削減を求めます。間違ったトピックで40枚のカードを書くのは最も時間の無駄なので、この確認は1往復の価値があります。

3. カード作成

まず最初のトピックからdeck.pyを書く

出力先の隣にreferences/deck_template.pyをコピーします。最初のトピックのカードを書き、そのトピックだけをレンダリングし（--topic 1）、ユーザーに2、3枚表示して、スタイルと深さが適切かどうかを尋ねます。その後、残りを書きます。カード3枚目でユーザーがより短いカードを望んでいたことに気づくのは安上がりですが、40枚目で気づくのはそうではありません。最初のカードを書く前にreferences/components.mdを読んでください。すべての構成要素（リード文、ボックス、ステップ、テーブル、コード例、コールアウト、図）とそれに使用するHTMLが示されています。

良いカードの書き方とその理由：

• 概念を最初に。 質問と冒頭の文（lead）は、どこにでも当てはまる言葉で一般的なアイデアを述べます。プロジェクト固有のコードは、「例：...」というキャプション付きのexample(...)ボックスに入れます。これにより、読者はルールを学び、次に1つのケースを見ます。サンプルプロジェクトが一般的なプラクティスと異なる場合は、その例のコメントにその旨を記載します。
• 1枚のカードに1つのアイデア。 2つの別々のアイデアを結合する質問（「Xとは何か、そしてそれをどうデプロイするか？」）は2枚のカードが必要です。対比（「XとYの違いは？」）や、一緒にしか意味をなさないペアは1つのアイデアです。
• リード、構造、例の順。 1～2文の回答、次にそれを分解する2～3のボックス、ステップ、または小さなテーブル、オプションのコールアウトとコード例。読者はリードだけで回答を得られるようにします。
• フッターは覚えるべき一文、15語未満。タグはアイデアを表す1～2語です。
• 平易で正確な表現。 短い文。実際のステータスコード、関数名、コマンドを名前で指定し、ほのめかさないようにします。
• 図は追加価値がある場合のみ: フロー、失敗パスを含む決定、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   # 1つのトピック、クイック確認

<skill-dir> はこのSKILL.mdがあるフォルダです。python3、またはそれがPython 3である場合はpythonを使用します。スクリプトにはPythonとplaywright、Pillow（pip install playwright pillow）、およびGoogle Chromeまたはplaywright install chromiumが必要です。すべてのカードを2400x1698ピクセルのA4横向きPNGとしてレンダリングし、各カードのコンテンツが収まるか（高さと幅）をチェックし、収まらないカードがあるとビルドを停止してそのカードを報告します。次に、トピックごとに1つのPDF、print/all-cards.pdf、およびREADME.mdを書き出します。

• 繰り返しコンテンツ: 収まりチェックはサイズを測定するもので、意味をチェックするものではありません。ステップやリードを繰り返すボックスを見つけて削除します。
• 最大数を超えた場合: デッキがmax_cardsより多くのカードを持つとビルドが停止します。最も重要でないカードをマージするか削除するか、ユーザーに制限の引き上げを依頼します。自分で制限を引き上げないでください。
• カードが収まらない場合: テキストを短くする、ボックスを削除する、または2枚のカードに分割します（例：「9a」と「9b」、または2つの質問）。フォントを小さくして詰め込まないでください。印刷しても読める状態を保つ必要があります。
• レンダリング後、すべてのカードを確認する PNGを開いて。収まりチェックはオーバーフローを検出しますが、わかりにくいカード、誤解を招く図、タイポは検出しません。修正して再レンダリングします。--topic N は1つのトピックをすばやく再レンダリングします。
• 余白は正常です。 ビルドは1200x849のカード上のCSS px単位で余白を報告します（PNGはその2倍です）。シンプルなカードでは150～350pxが空くことがよくあり、それは読みやすさと印刷に問題ありません。カードを埋めるためにパディングしないでください。カードに約400px以上の余白があり、薄く感じられる場合は、図や例を追加する価値があるか、隣接するカードにマージする価値があるかもしれません。

4. 追加機能: 動画、サムネイル、公開

ユーザーが希望し、カードが承認された後のみ。どの動画スタイルにするか尋ね、エンコードにかかるおおよその時間を伝えます（ラップトップでカード1枚あたり約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秒間表示。
• どのモードでも、トピックごとに1つの動画と全カードを含む1つの動画を作成し、モード名（-questions、-cards）をファイル名に含めるため、スタイルが上書きされることはありません。build_thumbnails.pyにも同じ--modeを渡して名前を一致させます。
• すべての動画にはイントロとトピックタイトル画面、およびチャプターをYouTubeがクリック可能なセクションに変換する説明文（.txt）が含まれます。チャプターは少なくとも10秒間であり、これはYouTubeの要件です。
• 動画にはffmpegが必要です。動画は大きいため、VIDEO_DIRはgitリポジトリの外に置いてください。
• サムネイルは1280x720の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、スライド、リポジトリ、またはフラッシュカードからデッキを構築する方法。ソースがそれである場合に読んでください。