# Validation Commands to Run Before Pushing Changes in AI Engineering From Scratch > Ensure code quality in AI engineering by running validation commands before pushing. Automate checks for lesson structure, test coverage, and README counts. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: best-practices - Published: 2026-06-17 --- **Run `python3 scripts/audit_lessons.py` to validate lesson structure and test coverage, followed by `python3 scripts/check_readme_counts.py --fix` to synchronize the README lesson counts before every push.** Before committing changes to the **AI Engineering From Scratch** curriculum, contributors must execute specific validation commands that ensure structural integrity and documentation consistency. These pre-push checks, defined in the repository's [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), enforce the same standards as the CI pipeline and prevent common errors like mismatched lesson counts or missing required files from reaching the main branch. ## Essential Pre-Push Validation Commands The repository requires two core validation steps that mirror the `audit` and `readme-counts-sync` CI jobs. Running these locally catches discrepancies before submission. ### Run the Curriculum Audit The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script performs a comprehensive walkthrough of every lesson under the `phases/` directory. It validates that each lesson contains required files, verifies front-matter consistency, and executes unit test suites to ensure code quality. Specifically, the audit verifies: - **[`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** exists with valid YAML front-matter matching the implementation language - **`code/main.*`** runs without errors and exits with status 0 - **`code/tests/`** contains a minimum of 5 unit tests that all pass - **[`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)** and other metadata files are present and properly formatted Execute the full curriculum audit from the repository root: ```bash python3 scripts/audit_lessons.py ``` ### Synchronize README Lesson Counts The [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py) script parses the generated curriculum catalog and reconciles the lesson table in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md). This ensures the displayed statistics accurately reflect the true state of the repository. Check for count discrepancies: ```bash python3 scripts/check_readme_counts.py ``` Automatically fix any drift detected in the README: ```bash python3 scripts/check_readme_counts.py --fix ``` ## Complete Pre-Push Validation Workflow For comprehensive validation before pushing changes, execute these commands in sequence: ```bash # 1. Verify lesson structures and run all test suites python3 scripts/audit_lessons.py # 2. Check README synchronization (dry run) python3 scripts/check_readme_counts.py # 3. Auto-fix README if counts are outdated python3 scripts/check_readme_counts.py --fix ``` This workflow guarantees that your changes will pass the continuous integration checks and maintain curriculum consistency across all phases. ## Lesson-Level Validation for Targeted Changes When modifying a specific lesson, run targeted validation within that lesson's directory rather than the full curriculum audit. Navigate to the lesson's code directory and verify both execution and test coverage: ```bash # Example: Validating a specific lesson edit cd phases/05-phase-nn/12-some-lesson/code # Verify the implementation executes successfully python3 main.py # Run the lesson's unit test suite with verbose output python3 -m unittest discover tests -v ``` Successful validation requires [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) to exit with status 0 and all unit tests to pass. ## What the Validation Scripts Verify Understanding the specific checks helps interpret validation failures. The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script enforces structural requirements across these critical paths: - **`phases/*/*/docs/en.md`** – Documentation files containing front-matter that must align with the lesson's programming language - **`phases/*/*/code/main.*`** – Primary implementation files that must execute without runtime errors - **`phases/*/*/code/tests/`** – Directories containing `unittest` frameworks with comprehensive coverage - **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** – The top-level catalog kept synchronized by [`check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/check_readme_counts.py) These validations ensure that the curriculum remains structurally sound, fully tested, and accurately documented for learners. ## Summary - **Run `python3 scripts/audit_lessons.py`** before every push to validate lesson structure, required files, and test suites across all phases in the `phases/` directory. - **Execute `python3 scripts/check_readme_counts.py`** to verify README accuracy, applying the `--fix` flag to automatically update lesson counts when drift is detected. - **Validate individual lessons locally** by running [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) and `python3 -m unittest discover tests -v` within the specific lesson's `code/` directory when making targeted changes. - These commands align with the CI jobs defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and prevent structural errors from breaking the main branch build. ## Frequently Asked Questions ### What happens if I skip the validation commands before pushing? The CI pipeline will fail during the `audit` or `readme-counts-sync` jobs if you bypass local validation. Common failures include mismatched lesson counts in the README, missing required files like [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) or [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), or unit test failures in specific lessons. Running these commands locally catches issues before they trigger CI failures. ### How do I fix README count discrepancies automatically? Use the `--fix` flag with the README check script: `python3 scripts/check_readme_counts.py --fix`. This updates the lesson table in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) to reflect the current state of the `phases/` directory, eliminating manual count updates and reducing documentation errors. ### Can I validate just one lesson instead of the entire curriculum? Yes. Navigate to the specific lesson's code directory (for example, `phases/03-phase-example/07-new-lesson/code`) and run `python3 main.py` followed by `python3 -m unittest discover tests -v`. This targeted approach validates execution and test coverage without running the full curriculum audit, saving time during iterative development. ### What files must every lesson include to pass the audit? According to [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), each lesson directory must contain: [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with valid front-matter, `code/main.*` (the implementation file), a `code/tests/` directory with at least 5 unit tests, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json). The audit validates both file existence and content integrity, ensuring consistent curriculum quality across all phases.