AGENTS.md · rohitg00/ai-engineering-from-scratch

Sections

1. Philosophy
2. Repo layout
3. Hard rules
4. Dependencies
5. Lesson contract
6. Per-PR validation
7. Automation contract
8. Conflict resolution
9. New-lesson onboarding

First lines (shown under the repo's MIT license)

# AGENTS.md

Operating manual for contributors and AI agents touching this repo. Read it before opening a PR.

The repo is a curriculum, not a SaaS app. The lessons are the product. Every rule below keeps 542 lessons coherent over time.

---

## Philosophy

542 lessons. 20 phases. Every algorithm built from raw math before a single framework gets imported. You write backprop, the tokenizer, the attention mechanism, and the agent loop by hand in Python, TypeScript, Rust, or Julia. Then you run the same operation through the production library so the framework stops being a black box. The "Build It / Use It" split is the spine. Each lesson ships a reusable artifact you can plug into your daily workflow.

---

## Repo layout

```
phases/
  NN-phase-slug/
    NN-lesson-slug/
      docs/en.md              # lesson explainer
      code/                   # implementation + tests
      quiz.json               # 6 questions
      outputs/                # reusable artifact (skill / prompt / agent / MCP server)
README.md                     # public face; lesson counts auto-synced
ROADMAP.md                    # phase/lesson status
glossary/terms.md             # canonical term definitions
site/
  build.js                    # parses README + ROADMAP + glossary -> data.js
  data.js                     # generated; rebuilt by CI on main push
certifications/claude/
  program.json                # program metadata, source policy, official links
  tracks/*.json               # exam blueprint, ordered route, study plans
  lessons/NN-slug/            # shared certification lesson contract
  assessments/<exam-code>/    # original diagnostics and full mocks
manuals/
  AUTHORING.md                # manual contract: shape, figures, capture kit, prose limits
  <id>/manual.json            # pinned subject, palette, parts and sections
  <id>/sections/*.md          # one file per section
  <id>/figures/*.svg          # static figures; figure kit sources in figures/src/
  <id>/capture/               # offline capture kit and the records it wrote
scripts/                      # automation
.github/workflows/
  curriculum.yml              # invariant + auto-sync workflow
```

---

## Hard rules

1. **Size commits by judgment.** Commit count is a judgment call, not one commit per lesson. A small fix gets 1 to 2 commits. A large change gets a few logical commits, each one a step a reviewer can read on its own.
2. **Conventional commit subjects** ≤72 chars: `feat(phase-NN/MM): <slug>`. Body explains why, not what.
3. **Mermaid or SVG only** for diagrams. No ASCII / Unicode box-drawing.
4. **Every fenced code block needs a language tag.** Use `text`, `json`, `python`, `typescript`, `rust`, `julia`, `bash`, `console`, `mermaid`, `yaml` as appropriate.
5. **Original implementations only.** Don't cite external curriculum repos in docs, code comments, or commit text. Cite RFCs, official specs, and academic papers when they are the canonical source.
6. **Dependency allowlist** (see `Dependencies` below). Stdlib-first.
7. **Never commit generated files**: `catalog.json` is gitignored, `site/data.js` is rebuilt by CI, `package-lock.json` is never tracked.
8. **Answer every review bot thread.** CodeRabbit and Devin review each PR. Fix the finding or reply with the reason it does not apply, then resolve the thread.

---

## Dependencies

| Language   | Allowed                                                                  |
|------------|--------------------------------------------------------------------------|
| Python     | `numpy`, `torch`, `h5py`, `zstandard`, `safetensors`, stdlib              |
| TypeScript | `hono`, `zod`, `ws` (only when WebSockets needed), `@hono/node-server`, Node 20+ stdlib |
| Rust       | stdlib only (single-file `rustc --edition 2021`)                          |
| Julia      | `Random`, `Statistics`, `LinearAlgebra`, `Printf` (Julia stdlib)          |

If a finding suggests a banned dep, skip it with the reason "stays stdlib-first for educational clarity."

---

## Lesson contract

### docs/en.md frontmatter

```markdown
# <Title>

> <One-line hook>

**Type:** <Learn | Build | Reference>
**Languages:** <comma-list matching the main.* files in code/>
**Prerequisites:** <comma-list of upstream lessons, or "None">
**Time:** ~<estimate in minutes>

## Learning Objectives
- <4-6 bullet points starting with a verb>
```

The `**Languages:**` field must match the languages with a `main.*` file in `code/`.

### quiz.json schema

```json
{
  "lesson": "<dir-slug>",
  "title": "<Lesson Title>",
  "questions": [
    {"stage": "pre",   "question": "...", "options": ["a","b","c","d"], "correct": 0, "explanation": ""},
    {"stage": "check", "question": "...", "options": ["a","b","c","d"], "correct": 1, "explanation": ""},
    {"stage": "check", "question": "...", "options": ["a","b","c","d"], "correct": 2, "explanation": ""},
    {"stage": "check", "question": "...", "options": ["a","b","c","d"], "correct": 1, "explanation": ""},
    {"stage": "post",  "question": "...", "options": ["a","b","c","d"], "correct": 3, "explanation": ""},
    {"stage": "post",  "question": "...", "options": ["a","b","c","d"], "correct": 0, "explanation": ""}
  ]
}
```

Exactly 6 questions: 1 pre + 3 check + 2 post. `correct` is zero-indexed. The site renderer only understands this shape — legacy `q/choices/answer` schemas crash silently.

Keep the distractors comparable in length to the correct option. When the correct answer is the longest by a wide margin, a reader can guess it without knowing the material. `scripts/check_quiz_bias.py --check` gates this, and `scripts/debias_quizzes.py` spreads the correct option across positions.

### Claude certification contract

Certification lessons under `certifications/claude/lessons/` follow the same
documentation, quiz, diagram, dependency, and commit-size rules as phase
lessons. Every certification lesson needs a runnable main file and at
least five deterministic tests. Tracks reference stable lesson paths so one
lesson can serve several credentials without duplication. Conceptual lessons
still need practical work: use a scenario runner, policy scorer, artifact
validator, approval simulator, threat-model checker, or evidence grader instead
of artificial provider API code. A track may also reference an existing
`phases/` lesson as an optional deep dive.

Full-parity certification lessons use the same explain, manipulate, build,
ship, and verify loop as the strongest phase lessons. Every certification
lesson must include the exact sections `Interactive Lab`, `Practice Lab`,
`Shipped Artifact`, `Verify It`, and `Capstone Connection`; embed a registered
`figure` mechanism; ship at least one file under `outputs/`; and provide a
runnable scenario, simulator, scorer, or artifact validator with tests. Code in
a conceptual lesson must exercise the lesson's judgment. Do not add a fake API
integration merely to satisfy the runnable surface. Governance lessons can use
mock incidents, policy scorers, threat-model checks, ADR validation, approval
workflows, or evidence-bundle graders.

`program.json` owns the independent-course disclaimer, verification date, and
official links. `prerequisites.json` owns the machine-readable certification
lesson dependency graph. Every required track route must contain those internal
prerequisites before the lesson that consumes them. Each file in `tracks/` owns
one public exam blueprint, its exact domain weights, ordered lesson route,
assessment declarations, and study plans.
Exam facts must come from the current official guide. Product and model details
must be dated and checked against current official documentation.

Diagnostics and mocks use a separate assessment schema because they support
multiple-response questions:

```json
{
  "id": "claude-ccar-f-diagnostic",
  "version": 1,
  "track": "claude-ccar-f",
  "kind": "diagnostic",
  "title": "Architect Foundations Diagnostic",
  "timeLimitMinutes": 30,
  "questions": [
    {