ai-engineering-from-scratch: The AI Curriculum That Teaches Itself
A 20-phase, multi-language course that turns lessons, quizzes, artifacts, and agent skills into one executable learning system.
- ai-engineering-from-scratch treats curriculum as software, with state, contracts, and outputs that an agent can navigate.
- The repo's real breakthrough is its learning loop, where skills, lessons, quizzes, and artifacts work together as a teachable runtime.
- Its from-scratch, multi-language structure makes the course useful for understanding fundamentals and for seeing how those fundamentals survive in real tooling.
- The project is powerful because it produces reusable artifacts at the end of each lesson, not just conceptual understanding.
The curriculum that behaves like software
Most AI courses are static. This repo is not. It behaves like a learning application with state, routes, contracts, and outputs, which means both humans and agents can move through it without guessing where to go next.
Most AI material teaches in scattered pieces. A paper here, a fine-tuning post there, a flashy agent demo somewhere else. The pieces rarely line up. You ship a chatbot but can't explain its loss curve. You hook a function to an agent but can't say what attention does inside the model that's calling it. This curriculum is the spine.
That is the core claim behind ai-engineering-from-scratch. It is a 20-phase curriculum with hundreds of lessons, but the size is not the point. The point is that the repository is structured so the next step can be discovered, taught, tested, and archived as an artifact.
Why the agent layer is the real breakthrough
The most unusual part of the repo lives in .claude/skills and LEARNING.md. That layer gives the curriculum a host contract, so an agent can read learner state, fetch the next lesson, teach step by step, then update progress after the quiz and artifact are done.
That is a stronger pattern than a normal course index. It turns curriculum into a runtime. The repository can answer the practical question every learner has: what should happen next?
Every lesson is a contract
The lesson structure is disciplined. A lesson ships with conceptual docs, runnable code, a quiz, and outputs that behave like a finished deliverable. That is a very different contract from a tutorial that stops at explanation.
| Dimension | Typical AI tutorial | This repo |
|---|---|---|
| Lesson unit | Notebook or article | Doc, code, quiz, outputs |
| Completion signal | You reached the end | You produced something reusable |
| Validation | Reader self-assessment | Structured quiz plus code |
| Portability | Hard to reuse | Artifacts can be carried forward |
| Audience | Humans only | Humans and agents |
# Lesson contract
- docs/en.md: concept and explanation
- code/: runnable implementation
- quiz.json: assessment
- outputs/: shipped artifactThe effect is subtle but important. The repo stops being a pile of lessons and becomes a reproducible workflow for learning AI engineering the way engineers actually work: by reading, building, validating, and shipping.
The roadmap is the database
The site generator treats ROADMAP.md as source material, then parses lesson status and structure into navigable site state. That is classic documentation-as-truth thinking, but applied with enough discipline that the course can be rendered, filtered, and traversed like an application.
| Trait | Static curriculum site | This repo |
|---|---|---|
| Source of truth | Pages and navigation | Markdown roadmap plus build parser |
| Structure | Mostly linear | Linear plus learning paths |
| State | Implicit | Explicit lesson metadata |
| Maintenance | Manual reorganization | Build process consumes repo structure |
| Navigation | Browse and hope | Parse, route, and continue |
This matters because curriculum tends to rot. A source-of-truth roadmap slows that decay. It also makes the project legible to agents, which is increasingly the point.
From first principles to shipped artifacts
The from-scratch philosophy is the pedagogical spine. Concepts are introduced at the level of math and core mechanics first, then re-expressed with tools and frameworks later. That sequence changes what the learner notices.
| Learning mode | What you get | What you miss |
|---|---|---|
| Framework-first | Fast application | The mechanism underneath |
| From-scratch-first | Mechanistic understanding | Less immediate convenience |
| Artifact-driven | Something reusable at the end | More work per lesson |
| Notebook-only | Quick exposition | Little carryover |
The payoff is practical. If a lesson ends with a prompt, a skill, an MCP server, or another reusable asset, the student is not only absorbing ideas. They are leaving with a tool.
def lesson_complete(doc, quiz, code, outputs):
return all([doc, quiz, code, outputs])
assert lesson_complete(True, True, True, True)Why this beats a typical AI course
Compared with framework-first courses, this repo is broader and more demanding. Compared with classic from-scratch repos, it is more operational. Compared with static curricula, it is agent-aware.
| Repository class | Strength | Blind spot |
|---|---|---|
| Framework-first AI course | Fast path to building | Shallow mechanics |
| Python-only from-scratch repo | Deep conceptual clarity | Narrow scope |
| Static curriculum site | Easy to browse | Hard to execute |
| ai-engineering-from-scratch | Operational learning system | Higher maintenance cost |
The combination is the point. It pairs breadth, depth, multi-language parity, and an agent-facing interface in one place. That is rare, even among ambitious open-source learning projects.
The cost of this approach
There is a downside to all this structure. Strict lesson contracts are harder to maintain than loose notes. Multi-language parity raises the review burden. And when everything is formalized, the curriculum can become heavy to evolve.
That said, the trade-off is defensible. A curriculum that is meant to be consumed by agents needs shape. Otherwise it becomes just another beautiful folder of markdown files.