Build-Type vs Learn-Type Lessons: Understanding the Lesson Contract in AI Engineering

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 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 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.<lang>
• 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 file illustrates a Learn-type lesson. Its front-matter specifies:

# 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 demonstrates a Build-type lesson:

# 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 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 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.<lang>, 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 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.<lang> 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}