# Constraints on Code Files Within Lessons in AI Engineering From Scratch > Discover the constraints for code files in AI Engineering From Scratch lessons. Ensure executable, deterministic, and self-contained code with mandatory tests for effective learning. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: internals - Published: 2026-09-02 --- **Every lesson in the AI‑Engineering‑From‑Scratch curriculum must adhere to strict architectural rules governing source code under the `code/` directory, ensuring each lesson is executable, deterministic, and self‑contained with mandatory test coverage.** The **constraints on code files within lessons** are codified in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and enforced automatically by [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py). These rules guarantee that learners encounter only original implementations that compile, run, and terminate predictably while maintaining traceability back to educational documentation. ## Mandatory Executable Entry Points Each lesson must provide a runnable entry point file named `main.` (e.g., [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts)) located in the lesson’s `code/` directory. According to the specifications in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), this file must execute cleanly with canonical language commands—such as `python3 main.py` or `node main.js`—and terminate with exit code 0. The implementation must be **self‑terminating**, prohibiting infinite loops, endless `stdin` listeners, or hangs caused by missing environment variables or API keys. ## Documentation and Traceability Requirements The first 4–6 lines of every `main` file must contain a header comment block that references the lesson’s documentation path ([`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)) and cites relevant RFCs or specification sources. This requirement ensures that every implementation remains traceable to its educational context and underlying standards. For example, a compliant Python lesson begins with: ```python # ------------------------------------------------------------ # docs/en.md: phases/01-getting-started/01-hello-world/docs/en.md # RFC: https://datatracker.ietf.org/doc/html/rfc2119 # ------------------------------------------------------------ # A simple “Hello, world!” example that prints a deterministic string. ``` ## Language Consistency and Dependency Allowlists The **language match** constraint requires strict parity between the lesson’s front‑matter `**Languages:**` field and the files present in `code/`. If a lesson lists Python, a [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) must exist. Furthermore, all source files may only import libraries from the curriculum’s language‑specific allowlist (e.g., `numpy`, `torch` for Python), maintaining a "stdlib‑first" approach. External dependencies beyond the allowlist are strictly prohibited to preserve portability and reduce cognitive load. ## Testing and Determinism Standards Every lesson must ship a `code/tests/` directory containing **at least five** unit tests. These tests must execute using the language’s standard‑library test runner—such as `python3 -m unittest discover` or `npx tsx --test`—and validate deterministic behavior. The code must produce reproducible output, requiring fixed random seeds where randomness is necessary. This determinism ensures that learners and CI systems receive identical results across executions. ## Original Implementation and Hard Rules The curriculum mandates that all code be written from scratch for the lesson’s pedagogical purpose. Direct copies of external curriculum repositories or proprietary implementations are disallowed. Only RFCs, official specifications, or academic papers may be cited as references. This rule reinforces the repository’s focus on building AI systems from first principles rather than assembling pre‑built components. ## CI Enforcement and Validation The repository includes [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), which programmatically validates that `code/` is non‑empty, that a `main.*` file exists, that declared languages match present files, and that the test suite meets the minimum count requirement. Pull requests that violate any of these constraints are automatically blocked, ensuring that only compliant lessons reach the main branch. ## Summary - **Executable entry point**: Every lesson needs a runnable `main.` that exits with code 0. - **Header documentation**: The first 4–6 lines must cite [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) and relevant RFCs. - **Language alignment**: Front‑matter languages must match the `main.` files present in `code/`. - **Dependency restrictions**: Only allowlisted libraries may be imported. - **Testing minimum**: At least five deterministic unit tests must reside in `code/tests/`. - **Original work**: Implementations must be written from scratch, not copied. - **Automated validation**: [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) enforces all constraints during CI. ## Frequently Asked Questions ### What happens if a lesson violates the header comment requirement? The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) CI script will detect the missing documentation reference and block the pull request. The header comment serves as a mandatory link between the implementation and its educational context in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md). ### Can I use external libraries not on the allowlist for a lesson? No. The dependency allowlist exists to keep the curriculum "stdlib‑first" and ensure all lessons remain reproducible across environments. Only libraries explicitly listed in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) for your target language are permitted. ### Why must lessons include at least five unit tests? The minimum test count ensures comprehensive coverage of edge cases and deterministic behavior. This requirement prevents trivial implementations and guarantees that learners interact with well‑verified code that behaves predictably across different systems. ### How does the repository prevent infinite loops in lesson code? The constraints explicitly prohibit infinite loops, blocking `stdin` waits, and hanging due to missing secrets. Additionally, the CI validation checks that all `main` files terminate and exit with code 0, catching non‑terminating implementations before merge.