scaffold-exercises

Set up the practice framework

Create a practice directory structure that passes pnpm ai-hero-cli internal lint , then commit with git commit .

Directory naming

• Sections：exercises/ under XX-section-name/(e.g. 01-retrieval-skill-building）
• Exercises: XX.YY-exercise-name/under a section (e.g. 01.03-retrieval-with-bm25）
• Section number = XX, exercise number = XX.YY
• Names use dash-case (lowercase, hyphens)

Exercise types

Each exercise needs at least one of the following subdirectories:

• problem/ - Student workspace, containing TODOs
• solution/ - Reference implementation
• explainer/ - Conceptual material, without TODOs

When creating placeholders, use explainer/by default, unless the plan specifies another type.

Required files

Each subdirectory (problem/、solution/、explainer/) needs a readme.mdthat satisfies:

• Not empty(must have actual content, even just a one-line heading is fine)
• No invalid links

When creating placeholders, create a minimal readme containing a title and description:

# 练习标题

这里写描述

If the subdirectory has code, it also needs a main.ts(>1 line). But for placeholders, an exercise containing only a readme is also acceptable.

Workflow

1. Parse the plan - Extract section names, exercise names, and types
2. Create directories - Run mkdir -p
3. Create placeholder readmes - One readme.md
4. Run lint - pnpm ai-hero-cli internal lint verification
5. Fix errors - Iterate until lint passes

Lint rule summary

Linter（pnpm ai-hero-cli internal lint) checks:

• Each exercise has a subdirectory (at least one ofproblem/、solution/、explainer/）
• problem/、explainer/ or explainer.1/ exists
• A non-empty readme.md
• No .gitkeep files
• No speaker-notes.md files
• No invalid links in the readme
• No pnpm run exercise commands in the readme
• Except for readme-only exercises, each subdirectory needs main.ts

Move/rename exercises

When renumbering or moving exercises:

1. Use git mv(not mv) to rename directories—preserves git history
2. Update numeric prefixes to maintain order
3. Re-run lint after moving

Example:

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

Example: Create placeholders according to the plan

Given the following plan:

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

Create:

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

Then create readme placeholders:

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"