How the Build It / Use It Teaching Methodology Works in ai-engineering-from-scratch

The "Build It / Use It" methodology follows a six-beat lesson flow (MOTTO → PROBLEM → CONCEPT → BUILD IT → USE IT → SHIP IT) where learners first implement algorithms from raw mathematics without frameworks, then redeploy the same logic using production libraries like PyTorch to demystify abstraction layers.

The ai-engineering-from-scratch repository organizes its curriculum around a first-principles approach to machine learning engineering. Every lesson follows a rigid pedagogical structure designed to bridge the gap between mathematical theory and production deployment. At the core of this system lies the Build It / Use It split, explicitly defined in the repository's README.md and AGENTS.md files as the "spine" of the curriculum.

The Six-Beat Lesson Flow

Each lesson in the repository adheres to a strict six-beat narrative arc. According to the source documentation, the flow progresses through MOTTO → PROBLEM → CONCEPT → BUILD IT → USE IT → SHIP IT. The Build It / Use It phases form the central pedagogical mechanism, flanked by conceptual framing at the start and artifact generation at the end. This structure repeats across all 503 lessons, ensuring consistent knowledge transfer from theory to implementation.

Build It: First-Principles Implementation

The Build It phase requires learners to implement core algorithms using only the language's standard library or minimal numeric dependencies like NumPy. This framework-free approach forces engagement with the raw mathematics and control flow underlying each technique.

In phases/<phase-id>/<lesson-id>/code/, you will find the "build-it" versions deliberately free of deep-learning frameworks. For example, in phases/03-deep-learning-core/01-the-perceptron/code/perceptron_numpy.py, the perceptron implementation uses only NumPy arrays and manual matrix operations. This constraint provides first-principles understanding: you trace every variable, inspect gradients manually, and debug edge cases without black-box APIs hiding the internals.

# phases/03-deep-learning-core/01-the-perceptron/code/perceptron_numpy.py

import numpy as np

class Perceptron:
    def __init__(self, n_features):
        self.w = np.zeros(n_features + 1)   # bias as last weight

    def predict(self, X):
        Xb = np.hstack([X, np.ones((X.shape[0], 1))])   # add bias term

        return np.where(Xb @ self.w > 0, 1, 0)

    def fit(self, X, y, lr=0.1, epochs=10):
        Xb = np.hstack([X, np.ones((X.shape[0], 1))])
        for _ in range(epochs):
            for xi, yi in zip(Xb, y):
                if self.predict(xi[:-1].reshape(1, -1)) != yi:
                    self.w += lr * (yi - self.predict(xi[:-1].reshape(1, -1))) * xi

Running python -m unittest discover verifies that these implementations produce mathematically correct results before proceeding to the abstraction layer.

Use It: Production Framework Integration

The Use It phase takes the exact same algorithmic skeleton and reimplements it using target production frameworks such as PyTorch, JAX, or scikit-learn. These versions sit alongside the "build-it" code in the same lesson folder, often in separate files like perceptron_torch.py or model_torch.py.

This contrast makes the library's behavior transparent. By re-using the same mathematical logic you coded manually, you see precisely how the framework handles tensor operations, autograd, and optimization. The "magic" of a loss.backward() call transforms into an understandable pipeline when you have already implemented the gradient calculation by hand.

# phases/03-deep-learning-core/01-the-perceptron/code/perceptron_torch.py

import torch
import torch.nn as nn

class PerceptronTorch(nn.Module):
    def __init__(self, n_features):
        super().__init__()
        self.linear = nn.Linear(n_features, 1)   # bias built-in

    def forward(self, x):
        return (self.linear(x) > 0).float()

    def fit(self, X, y, lr=0.1, epochs=10):
        optimizer = torch.optim.SGD(self.parameters(), lr=lr)
        criterion = nn.BCEWithLogitsLoss()
        X = torch.tensor(X, dtype=torch.float32)
        y = torch.tensor(y, dtype=torch.float32).unsqueeze(1)
        for _ in range(epochs):
            optimizer.zero_grad()
            logits = self.linear(X)
            loss = criterion(logits, y)
            loss.backward()
            optimizer.step()

Ship It: Exporting Reusable Artifacts

The final beat, Ship It, requires exporting a reusable artifact from the lesson's outputs/ directory. These artifacts take the form of prompts, skills, agents, or MCP servers that demonstrate concrete, runnable outcomes.

For instance, after completing the perceptron lesson, the phases/03-deep-learning-core/01-the-perceptron/outputs/skill-perceptron.md file contains a deployable skill encapsulating the learned concept. This reinforces the learning loop by proving the code works in a production context, not just in an educational sandbox.

Key Files Supporting the Methodology

Several critical files in the repository enforce and document this pedagogical structure:

• README.md – Contains the explanation of the six-beat flow and explicitly defines the Build It / Use It split as the curriculum's spine.
• AGENTS.md – A contract file that reiterates the methodology for agent-related lessons, reinforcing that the split applies across all learning modules.
• phases/<phase>/<lesson>/code/ – Houses paired implementations (framework-free and framework-specific) for every algorithm in the course.
• site/build.js – The static site generator that renders the curriculum's structure, including the Build It / Use It narrative, for the web UI.

Summary

• The Build It / Use It methodology follows a strict six-beat flow: MOTTO → PROBLEM → CONCEPT → BUILD IT → USE IT → SHIP IT.
• Build It implementations live in phases/<phase-id>/<lesson-id>/code/ and use only standard libraries or NumPy to teach first-principles mathematics.
• Use It versions wrap the same logic in production frameworks (PyTorch, JAX) to demonstrate how abstraction layers mirror manual implementations.
• Ship It generates reusable artifacts (skills, agents, MCP servers) stored in outputs/ directories, proving production viability.
• The structure is enforced by README.md and AGENTS.md, with validation through unit tests that verify both implementations produce identical results.

Frequently Asked Questions

Why implement algorithms twice in the same lesson?

Implementing the algorithm first from scratch and then with a framework creates a cognitive bridge between theory and practice. When you have manually coded the gradient descent update loop in NumPy, the PyTorch optimizer.step() call transforms from magic into a predictable operation that you could replicate by hand if needed.

Which production frameworks does the "Use It" phase typically employ?

According to the repository structure, the Use It phase commonly employs PyTorch, JAX, and scikit-learn, though the specific framework depends on the lesson's target domain. The key constraint is that the framework implementation must mirror the logic of the manually-coded version exactly.

How does the repository verify that both implementations are equivalent?

Each lesson includes unit tests runnable via python -m unittest discover that assert both the framework-free and framework-specific implementations produce identical predictions on the same validation data. This verification ensures the abstraction layer has not introduced mathematical errors.

Where are the completed lesson artifacts stored for reuse?

After the Ship It step, reusable artifacts are stored in the lesson's outputs/ directory. These files (located at paths like phases/<phase>/<lesson>/outputs/) contain prompts, skills, or MCP server configurations that can be dropped directly into downstream production projects.

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