# Build-Type vs Learn-Type Lessons: Understanding the Lesson Contract in AI Engineering > Understand the difference between Build-type and Learn-type lessons in AI engineering. Build lessons require runnable code and tests, while Learn lessons focus on concepts and quizzes. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: deep-dive - Published: 2026-08-29 --- **TLDR:** In the `rohitg00/ai-engineering-from-scratch` repository, **Build-type** lessons require learners to construct a functional artifact with runnable code, unit tests, and an `outputs/` directory, while **Learn-type** lessons focus on conceptual understanding through explanatory content and quizzes without mandatory executable deliverables. The lesson contract defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) establishes a structured taxonomy for educational content in the AI Engineering from Scratch curriculum. This contract uses a **`Type:`** field to classify every lesson as either **Learn**, **Build**, or **Reference**, creating distinct pedagogical pathways for theoretical comprehension versus practical implementation. ## What Is the Lesson Contract? The lesson contract is the pedagogical specification defined in the repository's root [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file. It mandates that every lesson include front-matter metadata declaring its **`Type:`** classification. According to the source code, this classification determines the lesson's structure, deliverables, and validation criteria. The three recognized types are **Learn**, **Build**, and **Reference**, though Learn and Build represent the primary instructional modes. ## Key Differences Between Build-Type and Learn-Type Lessons ### Pedagogical Purpose **Learn-type** lessons introduce concepts, theory, or background material. Their primary goal is answering *why* something works. **Build-type** lessons guide the learner to *construct* a functional artifact from scratch, focusing on *how* to implement concepts and reinforcing theory through executable code. ### Required Deliverables **Learn-type** lessons deliver explanatory markdown, diagrams, and assessment quizzes. They do not require runnable code or an `outputs/` directory. In contrast, **Build-type** lessons must include: - A complete, runnable implementation located at `code/main.` - Comprehensive unit tests - A shipped artifact placed under `outputs/` (such as a trained model, data file, or deployable skill) ### Execution and Validation Requirements **Learn-type** lessons are read-only experiences with no execution requirements. **Build-type** lessons must execute successfully using commands like `python3 main.py` or `npx tsx` and pass all automated tests. The build process validates that the learner has produced working code rather than just theoretical understanding. ## Implementation Examples from the Repository ### Learn-Type Lesson Example The [`phases/11-llm-engineering/01-prompt-engineering/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/11-llm-engineering/01-prompt-engineering/docs/en.md) file illustrates a **Learn-type** lesson. Its front-matter specifies: ```markdown # Prompt Engineering > Master the art of crafting effective prompts. **Type:** Learn **Languages:** Python **Prerequisites:** None **Time:** ~15 minutes ``` This lesson contains conceptual explanations and quizzes but no mandatory executable code deliverable. ### Build-Type Lesson Example Conversely, [`phases/07-transformers-deep-dive/14-build-a-transformer-capstone/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/07-transformers-deep-dive/14-build-a-transformer-capstone/docs/en.md) demonstrates a **Build-type** lesson: ```markdown # Build a Transformer from Scratch > Implement a minimal transformer model end‑to‑end. **Type:** Build **Languages:** Python **Prerequisites:** Self‑attention, positional encoding **Time:** ~45 minutes ``` This lesson requires the learner to produce a working transformer implementation, complete with tests and an artifact in the `outputs/` directory. ## The Reference-Type Distinction While this analysis focuses on Learn and Build types, the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) contract also defines **Reference-type** lessons. These serve as documentation or lookup resources rather than sequential instruction, completing the three-tier taxonomy. ## Summary - The **`Type:`** field in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) classifies lessons as **Learn**, **Build**, or **Reference**. - **Learn-type** lessons prioritize conceptual understanding through markdown explanations and quizzes without requiring runnable code. - **Build-type** lessons mandate executable implementations in `code/main.`, unit tests, and physical artifacts in the `outputs/` directory. - **Build-type** lessons must successfully execute and pass validation, while **Learn-type** lessons remain read-only. - The repository uses these distinctions to balance theoretical knowledge with hands-on engineering skill development. ## Frequently Asked Questions ### Can a lesson be both Learn-type and Build-type? No. According to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) contract, each lesson must declare a single type in its front-matter. However, a Learn-type lesson can serve as a prerequisite for a Build-type lesson, creating a progression from theory to implementation. ### What happens if a Build-type lesson fails execution? The lesson contract requires that Build-type lessons execute successfully using standard commands like `python3 main.py` or `npx tsx`. If execution fails or tests do not pass, the lesson does not meet the contract requirements and cannot be considered complete. ### Are there specific file path requirements for Build-type lessons? Yes. Build-type lessons must place their primary implementation at `code/main.` and their generated artifacts in an `outputs/` directory. This standardized structure allows automated validation tools to locate and test the deliverables consistently across the curriculum. ### Do Learn-type lessons ever contain code examples? While Learn-type lessons may include code snippets for illustration, they do not require runnable implementations or the `outputs/` directory. The code serves explanatory purposes only, and no execution validation is performed.