ai-engineering-from-scratch/CONTRIBUTING.md

Contributing to AI Engineering from Scratch

Thank you for wanting to make AI education better for everyone.

Ways to Contribute

1. Add a New Lesson

Each lesson lives in phases/XX-phase-name/NN-lesson-name/ with this structure:

NN-lesson-name/
├── code/           At least one runnable implementation
├── notebook/       Jupyter notebook for experimentation (optional)
├── docs/
│   └── en.md       Lesson documentation (required)
└── outputs/        Prompts, skills, or agents this lesson produces (if applicable)

Lesson doc format (en.md):

# Lesson Title

> One-line motto — the core idea in one sentence.

## The Problem

Why does this matter? What can't you do without this?

## The Concept

Explain with diagrams, visuals, and intuition. Code comes later.

## Build It

Step-by-step implementation from scratch.

## Use It

Now use a real framework or library to do the same thing.

## Ship It

The prompt, skill, agent, or tool this lesson produces.

## Exercises

1. Exercise one
2. Exercise two
3. Challenge exercise

2. Add a Translation

Create a new file in any lesson's docs/ folder:

docs/
├── en.md    (English — always required)
├── zh.md    (Chinese)
├── ja.md    (Japanese)
├── es.md    (Spanish)
├── hi.md    (Hindi)
└── ...

Keep the same structure as the English version. Translate content, not code.

3. Add an Output

If a lesson should produce a reusable prompt, skill, agent, or MCP server:

1. Create it in the lesson's outputs/ folder
2. Add a reference in the top-level outputs/ index

Prompt format:

---
name: prompt-name
description: What this prompt does
phase: 14
lesson: 01
---

[System prompt or template here]

Skill format:

---
name: skill-name
description: What this skill teaches
version: 1.0.0
phase: 14
lesson: 01
tags: [agents, loops]
---

[Skill content here]

4. Fix Bugs or Improve Existing Lessons

• Fix code that doesn't run
• Improve explanations
• Add better diagrams
• Update outdated information

5. Add Exercises or Projects

More exercises and projects are always welcome, especially ones that connect multiple phases.

Guidelines

• Code must run. Every code file should execute without errors with the listed dependencies.
• No comments in code. Code should be self-explanatory. Use the docs for explanation.
• Best language for the job. Don't force Python where TypeScript or Rust is the better choice.
• Build from scratch first. Always implement the concept from first principles before showing the framework version.
• Keep it practical. Theory serves practice, not the other way around.
• No AI slop. Write like a human. Be direct. Cut filler.

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b add-lesson-phase3-gradient-descent)
3. Make your changes
4. Ensure all code runs
5. Submit a pull request with a clear description

Code of Conduct

See CODE_OF_CONDUCT.md. Be kind, be helpful, be constructive.