scaffold-exercises

演習のひな形作成

pnpm ai-hero-cli internal lint に合格する演習ディレクトリ構成を作成し、git commit でコミットします。

ディレクトリ名

• セクション：exercises/ 内の XX-section-name/（例：01-retrieval-skill-building）
• 演習：セクション内の XX.YY-exercise-name/（例：01.03-retrieval-with-bm25）
• セクション番号 = XX、演習番号 = XX.YY
• 名前はダッシュケース（小文字、ハイフン区切り）にします

演習の種類

各演習には、次のサブフォルダーのうち少なくとも1つが必要です。

• problem/ - TODO を含む学生用ワークスペース
• solution/ - 参照実装
• explainer/ - TODO を含まない概念的な教材

ひな形を作成する場合、計画に別の指定がなければ、デフォルトで explainer/ を使用します。

必須ファイル

各サブフォルダー（problem/、solution/、explainer/）には、次の条件を満たす readme.md が必要です。

• 空ではないこと（タイトル1行だけでも、実際の内容が必要です）
• リンク切れがないこと

ひな形を作成する場合は、タイトルと説明を含む最小限の readme を作成します。

# Exercise Title

Description here

サブフォルダーにコードがある場合は、main.ts（2行以上）も必要です。ただし、ひな形では readme のみの演習でもかまいません。

ワークフロー

1. 計画を解析する - セクション名、演習名、種類を抽出します
2. ディレクトリを作成する - 各パスに対して mkdir -p を実行します
3. ひな形の readme を作成する - 各種類のフォルダーに readme.md を1つ作成し、タイトルを記載します
4. lint を実行する - pnpm ai-hero-cli internal lint で検証します
5. エラーを修正する - lint に合格するまで繰り返します

lint ルールの概要

リンター（pnpm ai-hero-cli internal lint）は次の項目を確認します。

• 各演習にサブフォルダー（problem/、solution/、explainer/）があること
• problem/、explainer/、explainer.1/ のいずれかが少なくとも1つ存在すること
• 主要なサブフォルダーに readme.md が存在し、空ではないこと
• .gitkeep ファイルがないこと
• speaker-notes.md ファイルがないこと
• readme にリンク切れがないこと
• readme に pnpm run exercise コマンドがないこと
• readme のみの場合を除き、各サブフォルダーに main.ts が必要であること

演習の移動・名前変更

演習の番号を変更したり移動したりする場合：

1. ディレクトリの名前変更には mv ではなく git mv を使います（Git の履歴を保持します）
2. 並び順を維持できるよう、番号のプレフィックスを更新します
3. 移動後に lint を再実行します

例：

git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings

例：計画からひな形を作成する

次のような計画がある場合：

Section 05: Memory Skill Building
- 05.01 Introduction to Memory
- 05.02 Short-term Memory (explainer + problem + solution)
- 05.03 Long-term Memory

次を作成します。

mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer

次に、ひな形の readme を作成します。

exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"