How AI Engineering Curriculum Lessons Are Organized with Code, Docs, and Outputs Directories

The repository structures every lesson under phases/<phase-slug>/<lesson-slug>/ with three mandatory subdirectories—docs/ for explanations, code/ for implementations, and outputs/ for reusable artifacts—enabling a consistent Learn → Build → Reference workflow across the entire curriculum.

The rohitg00/ai-engineering-from-scratch repository implements a rigorous lesson-centric layout that standardizes how educational content is packaged, tested, and reused. Each lesson follows a strict three-directory contract defined in AGENTS.md, ensuring that automated tooling can discover, validate, and publish curriculum modules without manual metadata entry.

The Three-Pillar Directory Structure

Every lesson resides at phases/<phase-slug>/<lesson-slug>/ and must contain three core subdirectories. This convention applies universally, from foundational tutorials to advanced capstone projects.

docs/ Directory

The docs/ subdirectory holds the human-readable lesson explainer in en.md. This file uses frontmatter to declare machine-readable metadata including the lesson type, programming language, prerequisites, and estimated completion time.

For example, in phases/19-capstone-projects/87-end-to-end-safety-gate/docs/en.md, the frontmatter defines the lesson as a capstone project while the body content explains the safety gate concept and learning objectives.

code/ Directory

The code/ subdirectory contains the minimal, self-contained implementation and test suite. Files follow the naming convention main.<lang> (e.g., main.py, main.js) and include a header comment citing the corresponding lesson documentation.

A tests/ subdirectory accompanies the implementation to validate correctness. According to the AGENTS.md specification, all code must run directly without external configuration—executing python3 main.py from within the directory must terminate cleanly. The capstone example at phases/19-capstone-projects/87-end-to-end-safety-gate/code/main.py demonstrates this pattern with a runnable safety gate demonstration.

outputs/ Directory

The outputs/ subdirectory stores the lesson's reusable artifact—categorized as a skill, prompt, agent, or MCP server—formatted as Markdown or JSON. These artifacts serve as importable references for downstream lessons, enabling the curriculum to build upon previous work incrementally.

For instance, phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/skill-end-to-end-safety-gate.md publishes the safety gate skill in a standardized format that subsequent lessons can import and extend.

The Learn → Build → Reference Cycle

The three directories collectively enforce a pedagogical workflow that progresses from theory to practice to reusable asset:

1. Learn – Students read docs/en.md to understand concepts and objectives.
2. Build – Students implement or run the code/ to see concepts in action.
3. Reference – The system publishes outputs/ artifacts that other lessons import, creating a dependency chain of reusable AI components.

This cycle ensures that every lesson produces tangible, referenceable assets rather than disposable exercises.

Programmatically Discovering Lessons

Because the structure is strictly enforced, you can enumerate all lessons programmatically by checking for the mandatory docs/en.md file:

from pathlib import Path

root = Path("phases")
for lesson_path in root.rglob("*/*"):
    if (lesson_path / "docs" / "en.md").exists():
        print(f"Lesson: {lesson_path}")
        print(f"  • Docs   : {lesson_path / 'docs' / 'en.md'}")
        print(f"  • Code   : {list((lesson_path / 'code').glob('main.*'))}")
        print(f"  • Outputs: {list((lesson_path / 'outputs').glob('*'))}")

This pattern enables automated CI pipelines to validate that every lesson contains its required components and that all code executes successfully.

Executing and Importing Lesson Components

To run a lesson's demonstration locally, navigate to its code/ directory and execute the main file:

cd phases/19-capstone-projects/87-end-to-end-safety-gate/code
python3 main.py   # Executes the safety‑gate demo and writes outputs/gate_trace.json

Downstream lessons can import artifacts from previous lessons by reading the Markdown or JSON files from the outputs/ directory:

from pathlib import Path

skill_path = Path(__file__).parents[2] / "87-end-to-end-safety-gate" / "outputs" / "skill-end-to-end-safety-gate.md"
skill_md = skill_path.read_text()

# `skill_md` can now be used as documentation or parsed for configuration data.

Summary

• Standardized Paths: Every lesson follows phases/<phase-slug>/<lesson-slug>/ with mandatory docs/, code/, and outputs/ subdirectories.
• Self-Documenting: The docs/en.md file combines human-readable explanations with YAML frontmatter for machine parsing.
• Runnable Code: The code/ directory contains executable implementations and tests that run without external dependencies.
• Reusable Artifacts: The outputs/ directory publishes skills, prompts, agents, or MCP servers that downstream lessons can import.
• Contract-Driven: The AGENTS.md file formally defines this structure, enabling automated testing and site generation across the entire rohitg00/ai-engineering-from-scratch curriculum.

Frequently Asked Questions

What file defines the metadata for each lesson?

The docs/en.md file contains YAML frontmatter that specifies the lesson type, programming language, prerequisites, and estimated duration. This metadata enables automated tooling to categorize and filter lessons without parsing unstructured text.

Can lesson code be executed independently of the curriculum platform?

Yes. According to the repository contract defined in AGENTS.md, code in the code/ directory must be self-contained and runnable directly. Executing python3 main.py from within the lesson's code/ directory performs the demonstration and exits cleanly without requiring external configuration.

What types of artifacts are stored in the outputs/ directory?

The outputs/ directory contains reusable AI components formatted as Markdown or JSON, specifically categorized as skills, prompts, agents, or MCP servers. These artifacts function as importable libraries that subsequent lessons in the curriculum can reference and extend.

How does the curriculum enforce consistency across hundreds of lessons?

The repository relies on a strict directory contract documented in AGENTS.md. Automated scripts and CI pipelines validate that every lesson directory contains the required docs/, code/, and outputs/ subdirectories with properly formatted content, preventing structural drift as the curriculum scales.

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