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

> Understand the purpose of AGENTS.md in ai-engineering-from-scratch. This file details the curriculum's philosophy, dependencies, and automation rules for contributors and AI agents.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: internals
- Published: 2026-08-30

---

**The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) front-matter, plus companion files like [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json). For certification tracks, the manual specifies [`program.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and [`scripts/audit_certifications.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_certifications.py) utilities verify that lessons meet structural requirements, contain valid JSON schemas, and pass all unit tests.

```bash

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), contributors remain responsible for manually updating [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) lesson links and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) status rows to reflect current progress.

## Contributor Onboarding Workflow

[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```bash

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), [`program.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/program.json)), and mandatory sections like Learning Objectives and Interactive Labs.
- **Automation scripts** ([`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), [`scripts/audit_certifications.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)) will flag the violation during validation, and the CI `audit` job will block the pull request. [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md).

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

According to [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.