# How Developers Can Perform Local Validation Before Pushing Code in the AI Engineering Curriculum

> Learn how developers can perform local validation before pushing code by running built-in scripts and unit tests. Ensure code quality and accuracy before committing.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: best-practices
- Published: 2026-09-11

---

**Developers should run the repository’s built-in validation scripts—[`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py), [`check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/check_readme_counts.py), and [`link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/link_check.py)—along with unit tests, to verify lesson structure, documentation accuracy, and code functionality before opening a pull request.**

The **ai-engineering-from-scratch** curriculum enforces a strict "run-everything-locally-first" policy. Before submitting a pull request, developers must perform local validation before pushing code to ensure lesson integrity and prevent CI failures. This proactive approach catches structural errors, broken links, and failing tests early in the development cycle.

## Run the Lesson Audit Script

The primary gatekeeper is [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), which validates every lesson against the curriculum's structural requirements. This script checks for required files, correct front-matter formatting, and naming conventions, aborting with a non-zero exit code if any rule is violated.

To validate the entire curriculum:

```bash
python3 scripts/audit_lessons.py

```

To audit a specific phase only:

```bash
python3 scripts/audit_lessons.py --phase 14

```

For CI-friendly output parsing, use the JSON flag:

```bash
python3 scripts/audit_lessons.py --json

```

## Verify README Documentation Accuracy

Documentation drift occurs when lesson counts in the master README become desynchronized from the actual repository contents. The [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py) script ensures the README’s lesson-count table accurately reflects the current number of lessons, preventing misleading documentation from reaching production.

Run this check with:

```bash
python3 scripts/check_readme_counts.py

```

## Validate Internal Cross-References

Broken cross-lesson links disrupt the learning experience. The [`scripts/link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/link_check.py) script implements the **L010 rule**, which validates all internal links between lessons. This catches broken references before they trigger failures in the CI pipeline.

Execute the link validator to ensure all cross-references resolve correctly:

```bash
python3 scripts/link_check.py

```

## Execute Unit Tests for Code Lessons

Each lesson ships with a `code/tests/` folder containing language-specific test suites. Developers must run the appropriate test runner to confirm implementations work as expected before submission.

For Python lessons, navigate to the lesson directory and run:

```bash
cd phases/11-llm-engineering/01-prompt-engineering/code
python3 -m unittest discover tests -v

```

## Optional: Preview Site Generation Locally

The CI pipeline regenerates [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) from the README metadata. Developers can preview this process locally to catch rendering issues early:

```bash
node site/build.js

```

This local build step ensures the curriculum site renders correctly before the automated workflow processes it.

## Align with CI Pipeline Checks

The repository's [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) repeats the same validation steps executed locally. By running the lesson audit, README checks, link validation, and unit tests on your machine, you guarantee the pull request will pass automated jobs. Skipping local validation risks immediate CI failure and delays the review process.

## Summary

- **Run [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** to verify lesson structure, front-matter, and file naming conventions.
- **Execute [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py)** to synchronize README statistics with actual lesson counts.
- **Validate links** using [`scripts/link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/link_check.py) to enforce the L010 rule and prevent broken references.
- **Test code implementations** by running unit tests in each lesson's `code/tests/` directory.
- **Mirror CI expectations**—the [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) workflow duplicates these exact checks.

## Frequently Asked Questions

### What is the "run-everything-locally-first" policy?

The "run-everything-locally-first" policy requires developers to execute all validation scripts and tests on their local machine before pushing code or opening pull requests. This ensures structural integrity and code quality before automated CI processes begin.

### How do I validate only a specific phase locally?

Pass the `--phase` argument to the audit script with the phase number. For example, `python3 scripts/audit_lessons.py --phase 14` validates only phase 14, reducing validation time when working on isolated curriculum sections.

### What happens if I skip local validation and push directly?

Skipping local validation risks immediate CI failure. The [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) pipeline enforces the same checks as the local scripts, so unvalidated code will fail automated tests, blocking pull request merge and requiring additional fix commits.

### Which script checks for broken internal links?

The [`scripts/link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/link_check.py) script validates internal links according to the **L010 rule**. It scans all cross-lesson references to ensure every link points to a valid resource, preventing navigation errors in the deployed curriculum.