From 02f765022009b441234b3db2953e9a34e55b568e Mon Sep 17 00:00:00 2001
From: Connor1996 <zbk602423539@gmail.com>
Date: Sun, 8 Feb 2026 12:22:07 -0800
Subject: [PATCH] add AGENTS.md

Signed-off-by: Connor1996 <zbk602423539@gmail.com>
---
 AGENTS.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9b575e2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,81 @@
+# AGENTS.md
+
+## Scope
+
+- This file applies to the entire repository.
+- Use this as the default test-running policy for coding agents.
+
+## Objective
+
+- Run and verify tests in a way that matches the book workflow (`book/src/*.md`).
+- Prefer `pdm` entrypoints defined in `pyproject.toml`.
+
+## Environment Requirements
+
+- macOS on Apple Silicon is expected by the project.
+- Install dependencies first:
+
+```bash
+pdm install -v
+pdm run check-installation
+```
+
+- Optional baseline check from the setup chapter (reference solution, Week 1):
+
+```bash
+pdm run test-refsol -- -- -k week_1
+```
+
+## Agent Test Workflow
+
+1. Start with the smallest relevant scope (`--week` + `--day`).
+2. Use pytest filters via `-- -k ...` to isolate failing tasks.
+3. Run broader suites only after targeted tests pass.
+4. If extension code changed, rebuild extensions before testing.
+
+## Canonical Commands
+
+Run all tests:
+
+```bash
+pdm run test
+```
+
+Run a specific chapter/day:
+
+```bash
+pdm run test --week <WEEK> --day <DAY>
+```
+
+Run with pytest filters:
+
+```bash
+pdm run test --week 1 --day 3 -- -k task_2
+pdm run test --week 2 --day 2 -- -k cpu
+pdm run test --week 2 --day 2 -- -k gpu
+```
+
+Run reference-solution tests:
+
+```bash
+pdm run test-refsol
+pdm run test-refsol --week 2 --day 2 -- -k cpu
+```
+
+## Extension Rebuild Rule
+
+Rebuild before tests if these changed:
+
+- `src/extensions/src/*`
+
+Commands:
+
+```bash
+pdm run build-ext
+```
+
+## Guardrails
+
+- Use `--` before pytest args (`-k`, `-q`, `--collect-only`, etc.).
+- `pdm run test --week X --day Y` auto-copies `tests_refsol/test_week_X_day_Y.py` into `tests/`.
+- Model-dependent tests (0.5B/1.5B/7B) skip when models are not downloaded locally.