# How Learning Paths Are Defined and Tested in the AI Engineering From Scratch Curriculum

> Discover how AI Engineering From Scratch defines and tests its learning paths using JSON manifest files and automated scripts. Ensure curriculum integrity and discoverable content.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Learning paths in the rohitg00/ai-engineering-from-scratch repository are defined as JSON manifest files stored in the `learning-paths/` directory and automatically validated by [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), which verifies lesson existence, prerequisite ordering, and schema conformance through the [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) CI pipeline.**

The curriculum structures its educational content into modular **learning paths** that guide users through specific skill tracks like "Using Coding Agents" or "Agentic AI Engineer." These paths are declared in machine-readable JSON files and enforced by a comprehensive auditing system that prevents broken or logically invalid curricula from merging into the main branch.

## Defining Learning Paths via JSON Manifests

### Core Schema and File Structure

Each learning path is defined by a JSON manifest file located in the repository root under `learning-paths/`. For example, the manifest at [`learning-paths/using-coding-agents.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/learning-paths/using-coding-agents.json) follows a strict schema containing the following fields:

- **`title`**: The human-readable name of the learning track
- **`description`**: A brief overview of the path's objectives and target outcomes
- **`lessons`**: An ordered array of lesson slugs (e.g., `"01-intro-to-coding-agents"`) that define the sequence of study
- **`prerequisites`** *(optional)*: Global prerequisites that must be satisfied before starting the path
- **`metadata`** *(optional)*: Additional attributes such as difficulty level, estimated completion time, or target role

The lesson slugs declared in the `lessons` array directly correspond to directories under the `phases/` folder. This decouples the manifest from the physical folder layout, allowing the curriculum to evolve without breaking internal references.

### Lesson Slug Resolution

The mapping between manifest entries and physical content relies on directory conventions. Each slug in the `lessons` array must resolve to an existing path under `phases/` following the pattern `phases/<phase-number>-<slug>/<lesson-slug>/`. This convention ensures that the declarative JSON definitions remain tightly coupled to the actual lesson content while maintaining flexibility for structural reorganizations.

Below is a representative example from [`learning-paths/using-coding-agents.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/learning-paths/using-coding-agents.json):

```json
{
  "title": "Using Coding Agents",
  "description": "Learn how to harness autonomous coding agents to build software faster.",
  "lessons": [
    "01-intro-to-coding-agents",
    "02-prompt-engineering",
    "03-agent-loop",
    "04-advanced-deployment"
  ]
}

```

## Automated Testing of Learning Path Integrity

### Existence Verification with audit_lessons.py

The primary validation logic resides in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py). This script performs an **existence check** by iterating through the `lessons` array of each manifest and confirming that the referenced directories actually exist within the `phases/` structure. If a manifest references a slug that lacks a corresponding physical directory, the script immediately flags the error.

### Prerequisite Ordering Validation

Beyond simple existence checks, the audit script validates logical consistency by examining prerequisite relationships. Each lesson directory contains a [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file with front-matter metadata defining that lesson's specific prerequisites. The script cross-references these declarations against the ordering in the learning path manifest to ensure that no lesson appears before its prerequisites are satisfied. If a lesson declares a dependency that appears later in the sequence, the validation fails.

### Schema Conformance and Cross-Path Consistency

The validation enforces strict **schema conformance** by verifying that every manifest contains mandatory fields (`title`, `description`, `lessons`) and that the `lessons` field is a properly formatted array. Additionally, a global audit mechanism checks for **cross-path consistency**, ensuring that no two learning paths list the same lesson under incompatible prerequisite constraints, thereby preventing contradictory learning experiences across different tracks.

Here is a simplified excerpt from [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) demonstrating the core validation logic:

```python
import json, pathlib, sys

def load_path(path_file: pathlib.Path):
    data = json.loads(path_file.read_text())
    for slug in data["lessons"]:
        lesson_dir = pathlib.Path("phases").glob(f"*/*-{slug}")
        if not any(lesson_dir):
            sys.exit(f"❌ Lesson {slug} referenced in {path_file.name} does not exist.")
    print(f"✅ {path_file.name} passes validation")

```

## CI/CD Pipeline Integration

The validation system is fully automated through the GitHub Actions workflow defined in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml). This workflow triggers [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) on every push and pull request targeting the main branch. If the audit script detects any broken references, invalid prerequisite ordering, or schema violations, the CI job fails immediately, blocking the merge and ensuring that only well-formed learning paths reach production.

## Summary

- **Learning paths** are defined as JSON manifests in the `learning-paths/` directory, with each file specifying a title, description, and ordered list of lesson slugs
- Lesson slugs must resolve to physical directories under `phases/` as validated by [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)
- The audit script enforces prerequisite ordering by checking front-matter metadata in each lesson's [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file
- Schema conformance and cross-path consistency checks prevent malformed or contradictory curriculum definitions
- The [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) CI workflow automatically runs these validations on every pull request, ensuring curriculum integrity

## Frequently Asked Questions

### What file format are learning paths stored in?

Learning paths are stored as **JSON manifest files** inside the `learning-paths/` directory. Each file follows a structured schema containing the path title, description, and an ordered array of lesson slugs that define the curriculum sequence.

### How does the audit script verify lesson prerequisites?

The audit script in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validates prerequisites by parsing the front-matter metadata within each lesson's [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file. It ensures that prerequisite lessons appear earlier in the learning path sequence than the lessons that depend on them, preventing logical ordering errors.

### Where is the continuous integration configured for curriculum validation?

The CI configuration resides in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml). This GitHub Actions workflow automatically executes the audit script on every push and pull request, failing the build if any learning path contains broken references or invalid prerequisite chains.

### Can learning paths have overlapping lessons?

Yes, lessons can appear in multiple learning paths, but the global audit in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) performs **cross-path consistency checks** to ensure that shared lessons do not have conflicting prerequisite requirements across different paths, preventing contradictory learning experiences.