What Is the Purpose of the AGENTS.md File in ai-engineering-from-scratch?

The AGENTS.md file serves as the operating manual for contributors and AI agents working with the rohitg00/ai-engineering-from-scratch repository, codifying the curriculum's philosophy, strict dependency rules, lesson contracts, and automation expectations.

This repository is an educational curriculum—not a SaaS product—where every lesson must implement algorithms from first principles before importing any framework. The AGENTS.md file, located in the repository root, ensures that both human contributors and automated agents can navigate, extend, and verify the curriculum reliably while maintaining consistency across all phases and certifications.

Core Purpose and Philosophy

The Operating Manual for Humans and AI Agents

AGENTS.md functions as the single source of truth for anyone interacting with the codebase. It defines hard rules that prevent accidental inclusion of generated files or disallowed libraries, preserving the educational intent. By centralizing conventions, the file enables AI agents to understand repository boundaries without ambiguity.

Curriculum-First Architecture

The manual emphasizes that this is a learning resource, not a production application. Contributors must build algorithms from scratch using only approved dependencies like numpy and torch before leveraging higher-level abstractions. This constraint ensures learners understand foundational concepts rather than simply calling library methods.

Repository Structure and Hard Rules

Directory Hierarchy Conventions

The file specifies exactly where content belongs within the phases/ and certifications/ directories. Each lesson lives in a numbered folder containing:

• docs/en.md - Main lesson content with required front-matter
• code/ - Implementation files
• code/tests/ - Minimum five deterministic tests
• outputs/ - Generated artifacts

Additional top-level directories include site/ for website generation and scripts/ for validation tooling.

Strict Dependency Allow-List

AGENTS.md enforces a one-commit-per-lesson policy and mandates conventional commit messages. It maintains a strict dependency allow-list restricting Python packages to educational essentials like numpy, torch, and standard library modules. This prevents bloated environments and keeps the focus on algorithmic understanding rather than framework-specific syntax.

Lesson and Certification Contracts

Required Front-Matter and Metadata

Every lesson must include specific schemas in docs/en.md front-matter, plus companion files like quiz.json. For certification tracks, the manual specifies program.json and tracks/*.json structures that define learning paths and prerequisites.

Mandatory Lesson Components

The contract requires every lesson to contain:

• Learning Objectives - Clear outcomes stated upfront
• Interactive Lab - Hands-on coding exercises
• Verify It - Self-check comprehension questions
• At least five deterministic tests in code/tests/ to validate implementations

These requirements ensure pedagogical consistency whether the content covers phase lessons or Claude certification modules.

Automation and CI Integration

Local Validation Scripts

Before submitting pull requests, contributors run local audits using scripts defined in AGENTS.md. The scripts/audit_lessons.py and scripts/audit_certifications.py utilities verify that lessons meet structural requirements, contain valid JSON schemas, and pass all unit tests.

# Validate a new lesson locally

cd phases/02-phase/example-lesson/code
python3 main.py && python3 -m unittest discover tests -v

Continuous Integration Jobs

The manual documents CI workflows including audit and site-rebuild jobs. While automation handles website generation via site/build.js, contributors remain responsible for manually updating README.md lesson links and ROADMAP.md status rows to reflect current progress.

Contributor Onboarding Workflow

AGENTS.md provides a step-by-step checklist for adding new content. The workflow ensures atomic commits and proper documentation from folder creation through PR submission:

# Add a new lesson following the onboarding checklist

mkdir -p phases/03-phase/04-new-lesson/{docs,code/tests,outputs}

# …populate files…

git add phases/03-phase/04-new-lesson README.md ROADMAP.md
git commit -m "feat(phase-03/04): add new-lesson"
git push -u origin my-branch

This standardization prevents merge conflicts and maintains the repository's coherent architecture as the curriculum grows.

Summary

• AGENTS.md acts as the master operating manual for the ai-engineering-from-scratch curriculum, governing both human contributors and AI agents.
• The file enforces strict rules including first-principles implementation, dependency allow-lists, and one-commit-per-lesson policies.
• Lesson contracts mandate specific front-matter schemas, metadata files (quiz.json, program.json), and mandatory sections like Learning Objectives and Interactive Labs.
• Automation scripts (scripts/audit_lessons.py, scripts/audit_certifications.py) and CI jobs ensure quality without manual oversight for every check.
• The onboarding checklist provides reproducible steps for extending the curriculum while maintaining consistency across phases/, certifications/, and site/ directories.

Frequently Asked Questions

Does AGENTS.md apply to AI agents only?

No. While the file explicitly addresses AI agents to help automated systems understand repository boundaries, it primarily serves human contributors. The dual audience ensures that both automated tooling and developers follow identical conventions when generating or modifying lesson content.

What happens if I use a dependency not on the allow-list?

The local audit scripts (scripts/audit_lessons.py) will flag the violation during validation, and the CI audit job will block the pull request. AGENTS.md strictly limits Python dependencies to educational essentials like numpy and torch to maintain the curriculum's focus on algorithmic fundamentals.

How does AGENTS.md enforce the one-commit-per-lesson rule?

The file mandates conventional commit messages with specific prefixes (e.g., feat(phase-03/04):) and atomic changes. While the rule is documented in AGENTS.md, enforcement occurs through code review and the audit CI job, which validates that lesson additions correspond to single, focused commits touching only the intended lesson directory and metadata files like README.md and ROADMAP.md.

Where should I place certification-specific content versus regular phase lessons?

According to AGENTS.md, standard curriculum lessons belong in phases/XX-phase/XX-lesson-name/ directories, while Claude certification content lives under certifications/claude-certification/ with specific metadata files including program.json and tracks/*.json. The structure ensures that certification tracks maintain separate schemas while sharing the same core lesson contracts regarding tests and documentation.

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