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

Developers should run the repository’s built-in validation scripts—audit_lessons.py, check_readme_counts.py, and 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, 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:

python3 scripts/audit_lessons.py

To audit a specific phase only:

python3 scripts/audit_lessons.py --phase 14

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

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 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:

python3 scripts/check_readme_counts.py

Validate Internal Cross-References

Broken cross-lesson links disrupt the learning experience. The 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:

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:

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 from the README metadata. Developers can preview this process locally to catch rendering issues early:

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 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 to verify lesson structure, front-matter, and file naming conventions.
• Execute scripts/check_readme_counts.py to synchronize README statistics with actual lesson counts.
• Validate links using 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}