# AI Engineering from Scratch Lesson Anatomy: The Complete Repository Structure > Explore the AI Engineering from Scratch repository structure. Learn how lessons are organized for reproducible builds, automated testing, and consistent knowledge transfer. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: architecture - Published: 2026-08-28 --- **Every lesson in the repository follows a strict, self-contained folder structure governed by [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md), ensuring reproducible builds, automated testing, and consistent knowledge transfer across documentation, code, and assessments.** The `rohitg00/ai-engineering-from-scratch` curriculum treats each concept as a deployable unit. Understanding the lesson anatomy is essential for contributors building new material and learners navigating the codebase. Each lesson functions as an isolated package containing narrative documentation, from-scratch implementations, deterministic tests, reusable AI artefacts, and a standardized six-question assessment. ## The Seven Core Components of Every Lesson The repository enforces a uniform directory tree. Every lesson resides at `phases///` and must contain the following artefacts to satisfy the lesson contract. ### Documentation Layer ([`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)) Human-readable pedagogy lives in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md). This file must begin with YAML frontmatter strictly defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md): ```markdown --- title: "Linear Regression from Scratch" type: Build languages: ["Python", "TypeScript"] prerequisites: [] time: "~20 minutes" --- ``` The body follows with learning objectives, narrative walkthroughs, and mathematical explanations. The `type` field classifies the lesson as Build, Theory, or Integration, determining how the static site generator processes the content. ### Implementation Layer (`code/main.*` and `code/tests/`) The executable core sits in the `code/` directory. A header comment must cite the canonical documentation path: ```python # main.py – implementation for “Linear Regression from Scratch” # Docs: https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/01-foundations/01-linear-regression/docs/en.md def predict(x, w, b): """Return w·x + b.""" return w * x + b def train(xs, ys, lr=0.01, epochs=1000): """Simple gradient-descent trainer for a single-dimensional line.""" w, b = 0.0, 0.0 n = len(xs) for _ in range(epochs): dw = sum((predict(x, w, b) - y) * x for x, y in zip(xs, ys)) / n db = sum(predict(x, w, b) - y for x, y in zip(xs, ys)) / n w -= lr * dw b -= lr * db return w, b ``` **Test requirements** mandate five or more deterministic unit tests in `code/tests/`: ```python import unittest from main import predict, train class TestLinearRegression(unittest.TestCase): def test_predict(self): self.assertAlmostEqual(predict(2, 3, 1), 7) def test_train_convergence(self): xs = [0, 1, 2] ys = [1, 3, 5] # y = 2x + 1 w, b = train(xs, ys, lr=0.1, epochs=500) self.assertAlmostEqual(w, 2, places=1) self.assertAlmostEqual(b, 1, places=1) if __name__ == '__main__': unittest.main() ``` Run these with the language’s standard runner (e.g., `python3 -m unittest discover`). ### Artefact Layer (`outputs/`) Reusable AI components—**prompts**, **skills**, **agents**, and **MCP servers**—ship as markdown files in `outputs/`. Each file follows the frontmatter schema from [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md), enabling other lessons or external systems to import them programmatically. ### Assessment Layer ([`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)) Comprehension is validated via [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), which must contain exactly six questions: one pre-assessment, three checkpoint questions, and two post-assessment items. The schema requires zero-indexed `correct` fields: ```json { "lesson": "01-linear-regression", "title": "Linear Regression from Scratch", "questions": [ { "stage": "pre", "question": "What does linear regression aim to model?", "options": [ "A non-linear curve", "A straight line", "A probability distribution", "A decision tree" ], "correct": 1, "explanation": "Linear regression models the linear relationship between variables." }, { "stage": "check", "question": "Which term controls the step size in gradient descent?", "options": ["bias", "learning rate", "epoch count", "feature scaling"], "correct": 1, "explanation": "The learning rate scales the gradient update." } ] } ``` ### Optional Extensions (`notebook/`) Data-science and experimentation-heavy topics may include a Jupyter notebook at `notebook/lesson.ipynb`. While not mandatory, notebooks provide interactive exploration layers atop the deterministic `main.*` implementation. ## The Blueprint Files That Govern Structure Two canonical documents enforce the lesson anatomy across the repository. ### [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) — The Lesson Contract Located at the repository root, [[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specifies the exact frontmatter keys required in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) (title, type, languages, prerequisites, time) and the JSON schema for [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json). It acts as the single source of truth for validation scripts that gate pull requests. ### [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) — The Folder Blueprint [[`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md)](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) provides the directory skeleton and markdown templates for output artefacts. Contributors copy this template when scaffolding new lessons, ensuring that `phases/02-neural-nets/03-backpropagation` follows identical structural rules to `phases/01-foundations/01-linear-regression`. ## Real-World Example: Linear Regression Applying the lesson anatomy to the first foundations phase produces the following tree: ``` phases/01-foundations/01-linear-regression/ ├── code/ │ ├── main.py │ └── tests/ │ └── test_main.py ├── docs/ │ └── en.md ├── outputs/ │ ├── prompt-linear-regression.md │ └── skill-linear-regression.md ├── notebook/ │ └── lesson.ipynb └── quiz.json ``` This structure satisfies all automation in the repository: the static site generator parses [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), CI runs `code/tests/`, and the assessment platform ingests [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) without manual configuration. ## Summary - **Every lesson is a self-contained directory** under `phases///` following the blueprint in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md). - **Documentation mandates frontmatter** (title, type, languages, prerequisites, time) as specified in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). - **Code must include** a `main.*` implementation with header comments linking to docs, plus five or more deterministic tests in `code/tests/`. - **Reusable AI artefacts** (prompts, skills, agents) ship as markdown in `outputs/` with structured frontmatter. - **Assessment requires** a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) with exactly six questions (1 pre, 3 check, 2 post) using zero-indexed correct answers. - **Validation** relies on [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) as the lesson contract and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) for tracking completion status. ## Frequently Asked Questions ### What is the required folder structure for a lesson? Each lesson must reside at `phases///` and contain [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), `code/main.*`, `code/tests/`, `outputs/`, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json). The [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) file provides the exact skeleton, while optional `notebook/` directories support interactive experimentation. ### How does the [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file need to be formatted? The file must contain exactly six questions following the schema in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md): one pre-assessment question, three checkpoint questions, and two post-assessment questions. Each question object requires `stage`, `question`, `options` (array), `correct` (zero-indexed integer), and `explanation` fields. ### Where are reusable AI artefacts stored within a lesson? Prompts, skills, agents, and MCP servers live in the `outputs/` directory as individual markdown files. These files include YAML frontmatter defining their type and metadata, allowing other lessons or external systems to import them programmatically. ### What validates that a lesson follows the correct anatomy? [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) serves as the lesson contract, defining the required frontmatter for documentation and the JSON schema for quizzes. Automated tooling in the repository validates pull requests against this contract, ensuring every new lesson maintains the structural integrity required by the curriculum generator and testing pipelines.