エクササイズのスカフォールディング

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 も必要です (1 行以上)。ただし、スタブの場合は readme のみのエクササイズで問題ありません。

ワークフロー

1. 計画をパース - セクション名、エクササイズ名、バリエーション型を抽出
2. ディレクトリを作成 - 各パスに対して mkdir -p を実行
3. スタブ readme を作成 - 各バリエーションフォルダに 1 つの readme.md をタイトル付きで作成
4. lint を実行 - pnpm ai-hero-cli internal lint で検証
5. エラーを修正 - lint が合格するまで繰り返し

Lint ルールサマリー

linter (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"