scaffold-exercises

Scaffold Exercises

Create the exercise directory structure that passes pnpm ai-hero-cli internal lint , then commit using git commit .

Directory Naming

• Chapter：exercises/ within XX-section-name/(for example,01-retrieval-skill-building）
• Exercise: XX.YY-exercise-name/within a chapter (for example,01.03-retrieval-with-bm25）
• Chapter number = XX, exercise number = XX.YY
• Names are dash-case (lowercase, hyphens)

Exercise Variants

Each exercise needs at least one of these subfolders:

• problem/ - Student workspace with TODOs
• solution/ - Reference implementation
• explainer/ - Concept material, no TODOs

When scaffolding, default to explainer/unless the plan specifies otherwise.

Required Files

Each subfolder (problem/、solution/、explainer/) needs a readme.md：

• Not empty(must have real content, even a single-line title is fine)
• No broken links

When scaffolding, create a minimal readme with a title and description:

# 练习标题

描述在这里

If a subfolder has code, it also needs a main.ts(>1 line). But for stubs, a readme-only exercise is fine.

Workflow

1. Parse the plan - Extract chapter names, exercise names, and variant types
2. Create directories - For each path mkdir -p
3. Create stub readmes - One readme.md
4. Run lint - pnpm ai-hero-cli internal lint validation
5. Fix any errors - Iterate until lint passes

Lint Rules Summary

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

• Each exercise has subfolders (problem/、solution/、explainer/）
• At least one of problem/、explainer/ or explainer.1/ exists
• In the main subfolder, readme.md exists and is not empty
• No .gitkeep files
• No speaker-notes.md files
• No broken links in readmes
• No pnpm run exercise commands in readmes
• Each subfolder needs main.ts, unless it is readme-only

Moving/Renaming Exercises

When renumbering or moving exercises:

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

Example:

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

Example: Scaffolding from a 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 stubs:

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"