Constraints on Code Files Within Lessons in AI Engineering From Scratch

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 and enforced automatically by 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.<ext> (e.g., main.py, main.ts) located in the lesson’s code/ directory. According to the specifications in 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) 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:

# ------------------------------------------------------------

# 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 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, 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.<ext> that exits with code 0.
• Header documentation: The first 4–6 lines must cite docs/en.md and relevant RFCs.
• Language alignment: Front‑matter languages must match the main.<ext> 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 enforces all constraints during CI.

Frequently Asked Questions

What happens if a lesson violates the header comment requirement?

The 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.

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 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.

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