{"owner":"rohitg00","repo":"ai-engineering-from-scratch","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# AGENTS.md\n\nOperating manual for contributors and AI agents touching this repo. Read it before opening a PR.\n\nThe repo is a curriculum, not a SaaS app. The lessons are the product. Every rule below keeps 435 lessons coherent over time.\n\n---\n\n## Philosophy\n\n435 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.\n\n---\n\n## Repo layout\n\n```\nphases/\n  NN-phase-slug/\n    NN-lesson-slug/\n      docs/en.md              # lesson explainer\n      code/                   # implementation + tests\n      quiz.json               # 6 questions\n      outputs/                # reusable artifact (skill / prompt / agent / MCP server)\nREADME.md                     # public face; lesson counts auto-synced\nROADMAP.md                    # phase/lesson status\nglossary/terms.md             # canonical term definitions\nsite/\n  build.js                    # parses README + ROADMAP + glossary -> data.js\n  data.js                     # generated; rebuilt by CI on main push\ncertifications/claude/\n  program.json                # program metadata, source policy, official links\n  tracks/*.json               # exam blueprint, ordered route, study plans\n  lessons/NN-slug/            # shared certification lesson contract\n  assessments/<exam-code>/    # original diagnostics and full mocks\nscripts/                      # automation\n.github/workflows/\n  curriculum.yml              # invariant + auto-sync workflow\n```\n\n---\n\n## Hard rules\n\n1. **One commit per lesson directory.** Never batch multiple lessons into one commit. A 10-lesson PR has 10 commits.\n2. **Conventional commit subjects** ≤72 chars: `feat(phase-NN/MM): <slug>`. Body explains why, not what.\n3. **Mermaid or SVG only** for diagrams. No ASCII / Unicode box-drawing.\n4. **Every fenced code block needs a language tag.** Use `text`, `json`, `python`, `typescript`, `rust`, `julia`, `bash`, `console`, `mermaid`, `yaml` as appropriate.\n5. **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.\n6. **Dependency allowlist** (see `Dependencies` below). Stdlib-first.\n7. **Never commit generated files**: `catalog.json` is gitignored, `site/data.js` is rebuilt by CI, `package-lock.json` is never tracked.\n\n---\n\n## Dependencies\n\n| Language   | Allowed                                                                  |\n|------------|--------------------------------------------------------------------------|\n| Python     | `numpy`, `torch`, `h5py`, `zstandard`, `safetensors`, stdlib              |\n| TypeScript | `hono`, `zod`, `ws` (only when WebSockets needed), `@hono/node-server`, Node 20+ stdlib |\n| Rust       | stdlib only (single-file `rustc --edition 2021`)                          |\n| Julia      | `Random`, `Statistics`, `LinearAlgebra`, `Printf` (Julia stdlib)          |\n\nIf a finding suggests a banned dep, skip it with the reason \"stays stdlib-first for educational clarity.\"\n\n---\n\n## Lesson contract\n\n### docs/en.md frontmatter\n\n```markdown\n# <Title>\n\n> <One-line hook>\n\n**Type:** <Learn | Build | Reference>\n**Languages:** <comma-list matching the main.* files in code/>\n**Prerequisites:** <comma-list of upstream lessons, or \"None\">\n**Time:** ~<estimate in minutes>\n\n## Learning Objectives\n- <4-6 bullet points starting with a verb>\n```\n\nThe `**Languages:**` field must match the languages with a `main.*` file in `code/`.\n\n### quiz.json schema\n\n```json\n{\n  \"lesson\": \"<dir-slug>\",\n  \"title\": \"<Lesson Title>\",\n  \"questions\": [\n    {\"stage\": \"pre\",   \"question\": \"...\", \"options\": [\"a\",\"b\",\"c\",\"d\"], \"correct\": 0, \"explanation\": \"\"},\n    {\"stage\": \"check\", \"question\": \"...\", \"options\": [\"a\",\"b\",\"c\",\"d\"], \"correct\": 1, \"explanation\": \"\"},\n    {\"stage\": \"check\", \"question\": \"...\", \"options\": [\"a\",\"b\",\"c\",\"d\"], \"correct\": 2, \"explanation\": \"\"},\n    {\"stage\": \"check\", \"question\": \"...\", \"options\": [\"a\",\"b\",\"c\",\"d\"], \"correct\": 1, \"explanation\": \"\"},\n    {\"stage\": \"post\",  \"question\": \"...\", \"options\": [\"a\",\"b\",\"c\",\"d\"], \"correct\": 3, \"explanation\": \"\"},\n    {\"stage\": \"post\",  \"question\": \"...\", \"options\": [\"a\",\"b\",\"c\",\"d\"], \"correct\": 0, \"explanation\": \"\"}\n  ]\n}\n```\n\nExactly 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.\n\n### Claude certification contract\n\nCertification lessons under `certifications/claude/lessons/` follow the same\ndocumentation, quiz, diagram, dependency, and one-commit-per-lesson rules as\nphase lessons. Every certification lesson needs a runnable main file and at\nleast five deterministic tests. Tracks reference stable lesson paths so one\nlesson can serve several credentials without duplication. Conceptual lessons\nstill need practical work: use a scenario runner, policy scorer, artifact\nvalidator, approval simulator, threat-model checker, or evidence grader instead\nof artificial provider API code. A track may also reference an existing\n`phases/` lesson as an optional deep dive.\n\nFull-parity certification lessons use the same explain, manipulate, build,\nship, and verify loop as the strongest phase lessons. Every certification\nlesson must include the exact sections `Interactive Lab`, `Practice Lab`,\n`Shipped Artifact`, `Verify It`, and `Capstone Connection`; embed a registered\n`figure` mechanism; ship at least one file under `outputs/`; and provide a\nrunnable scenario, simulator, scorer, or artifact validator with tests. Code in\na conceptual lesson must exercise the lesson's judgment. Do not add a fake API\nintegration merely to satisfy the runnable surface. Governance lessons can use\nmock incidents, policy scorers, threat-model checks, ADR validation, approval\nworkflows, or evidence-bundle graders.\n\n`program.json` owns the independent-course disclaimer, verification date, and\nofficial links. `prerequisites.json` owns the machine-readable certification\nlesson dependency graph. Every required track route must contain those internal\nprerequisites before the lesson that consumes them. Each file in `tracks/` owns\none public exam blueprint, its exact domain weights, ordered lesson route,\nassessment declarations, and study plans.\nExam facts must come from the current official guide. Product and model details\nmust be dated and checked against current official documentation.\n\nDiagnostics and mocks use a separate assessment schema because they support\nmultiple-response questions:\n\n```json\n{\n  \"id\": \"claude-ccar-f-diagnostic\",\n  \"version\": 1,\n  \"track\": \"claude-ccar-f\",\n  \"kind\": \"diagnostic\",\n  \"title\": \"Architect Foundations Diagnostic\",\n  \"timeLimitMinutes\": 30,\n  \"questions\": [\n    {\n      \"id\": \"ccar-f-agent-001\",\n      \"domain\": \"agentic-architecture-orchestration\",\n      \"objective\": \"choose-an-orchestration-pattern\",\n      \"type\": \"single\",\n      \"prompt\": \"A self-contained original scenario...\",\n      \"options\": [\"a\", \"b\", \"c\", \"d\"],\n      \"correct\": [1],\n      \"explanation\": \"Why the decision fits and the alternatives do not.\",\n      \"references\": [\"certifications/claude/lessons/16-multi-agent-orchestration-and-delegation\"]\n    }\n  ]\n}\n```\n\n`correct` is always an array. A `single` item has exactly one index; a\n`multiple` item has at least two. Questions must be original, map to a public\nobjective, include a substantive explanation, and never reproduce or attempt\nto reconstruct confidential exam content. Practice percentages are raw scores,\nnot Anthropic scaled scores, and the curriculum never guarantees a pass.\nPublic certification pages and lesson context must also state that this is an\nindependent community curriculum that is not affiliated with, endorsed by,\nsponsored by, or authorized by Anthropic.\n\n### AI-native certification learner mode\n\nWhen a user asks to choose, start, resume, study, practice, or assess a Claude\ncertification, read and follow `skills/claude-certification/SKILL.md` before\nteaching. This applies to Codex and any other harness that reads `AGENTS.md`;\nClaude Code also discovers the matching wrapper under `.claude/skills/`.\n\nTreat the repository as an interactive tutor in learner mode. Read the selected\ntrack manifest, teach one route lesson at a time, run its real scenario and\ntests, require a learner-owned artifact under `learning-artifacts/`, grade the\nstored quiz or assessment, and preserve progress in\n`CLAUDE-CERTIFICATION.md`. Do not modify checked-in reference artifacts as\nlearner work. The certification curriculum is delivered through GitHub and the\nwebsite and is intentionally outside the book-generation pipeline.\nIt remains English-only and is intentionally outside the machine-translation\npipeline as well.\n\n### code/\n\n- Runs end-to-end and exits 0 on the canonical command for the language.\n- Self-terminating demo. No infinite stdin loops, no hangs on missing API keys.\n- 4-6 line header comment citing the lesson's `docs/en.md` path and any spec or RFC sources.\n\n### code/tests/\n\n- 5+ unit tests minimum.\n- Runs via the language's stdlib runner (`python3 -m unittest discover`, `npx tsx --test`, Rust/Julia inline).\n\n---\n\n## Per-PR validation\n\nRun locally before pushing:\n\n```bash\npython3 scripts/audit_lessons.py\npython3 scripts/audit_certifications.py\npython3 scripts/check_readme_counts.py        # advisory — CI fixes on merge\n\n# For each lesson touched:\ncd phases/NN-phase/MM-lesson/code\npython3 main.py && python3 -m unittest discover tests -v   # or the lang equivalent\n```\n\nCI gates (`.github/workflows/curriculum.yml`):\n\n| Job                              | Trigger      | Behavior                                              |\n|----------------------------------|--------------|-------------------------------------------------------|\n| `audit`                          | push + PR    | Runs `audit_lessons.py`. Blocking.                    |\n| `readme-counts-sync` (main only) | push to main | Rebuilds catalog + auto-fixes README counts.         |\n| `site-rebuild` (main only)       | push to main | Re-runs `node site/build.js`, commits `site/data.js`. |\n| `readme-counts-drift`            | PR           | Advisory only — main self-heals on merge.             |\n\n---\n\n## Automation contract\n\n**CI handles automatically — do not touch in your PR:**\n\n| Surface              | Bot                            | When                |\n|----------------------|--------------------------------|---------------------|\n| `catalog.json`       | rebuilt on demand (gitignored) | every CI job        |\n| `README.md` counts   | `readme-counts-sync`           | on push to main     |\n| `site/data.js`       | `site-rebuild`                 | on push to main     |\n\n**You handle:**\n\n| Surface                       | When                                                             |\n|-------------------------------|------------------------------------------------------------------|\n| `README.md` lesson-link rows  | when adding a new lesson — link `[Title](phases/NN-phase/MM-lesson/)` |\n| `ROADMAP.md` status           | when marking a lesson complete or WIP                            |\n| `glossary/terms.md`           | when introducing a term used by more than one lesson             |\n\n**Common bug**: if `grep -c 'tree/main/phases/NN-' site/data.js` is 0 after merge, the Phase NN README rows are plain text and missing the `[Title](phases/NN-...)` markdown link. `site/build.js` derives the URL from that link.\n\n---\n\n## Conflict resolution\n\n```bash\ngit fetch origin main\ngit merge --no-edit origin/main\n\n# Catalog conflict (legacy branches only — catalog.json is gitignored now):\ngit rm catalog.json\ngit commit --no-edit\n\n# README count conflict:\ngit checkout --theirs README.md\npython3 scripts/build_catalog.py\npython3 scripts/check_readme_counts.py --fix\ngit add README.md && git commit --no-edit\n\n# site/data.js conflict:\ngit checkout --theirs site/data.js\nnode site/build.js\ngit add site/data.js && git commit --no-edit\n\ngit push origin <your-branch>\n```\n\nAvoid `git push --force` to a branch with open review comments. Force-push detaches them.\n\n---\n\n## New-lesson onboarding\n\n```bash\nmkdir -p phases/NN-phase-slug/MM-new-lesson/{docs,code/tests,outputs}\n\n# 1. Write docs/en.md with the frontmatter above.\n# 2. Write code/main.<lang> with the 4-6 line header.\n# 3. Write code/tests/test_main.* with 5+ tests.\n# 4. Write quiz.json with the schema above.\n# 5. (Optional) Add outputs/skill-<slug>.md if the lesson ships a skill.\n\n# 6. Add to README.md:\n#    | MM | [Lesson Title](phases/NN-phase-slug/MM-new-lesson/) | Type | Lang |\n\n# 7. Update ROADMAP.md status row.\n\n# 8. Validate locally.\n\n# 9. Atomic commit:\ngit add phases/NN-phase-slug/MM-new-lesson README.md ROADMAP.md\ngit commit -m \"feat(phase-NN/MM): add <slug>\"\ngit push -u origin <your-branch>\ngh pr create --title \"feat(phase-NN/MM): add <slug>\" --body \"<5-line summary>\"\n```\n\n`site/data.js` regenerates on merge — leave it for CI.\n\n---\n\nLast reviewed: 2026-05-27.\n"}}