docs: record the Python-first testing preference in AGENTS.md

New coverage should land as a doctest example or a pytest case. Agents have
been adding Rust tests that CI never executes: no workflow invokes
`cargo test`, and `cargo clippy --all-targets` only compiles the test code.
Write down that constraint, along with the reason a `cargo test` job is not a
trivial addition, so the tradeoff does not have to be rediscovered.

Also point at the FFI example suites, which are easy to overlook when judging
whether behavior is reachable from Python.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: timsaucer

AGENTS.md

@@ -62,6 +62,40 @@ pre-commit run --all-files
 
 Fix any failures before committing.
 
+## Test Coverage
+
+Always prefer Python coverage — a doctest example in a docstring, or a pytest
+case. The user-facing Python surface is the first line of defense and the
+primary focus, so behavior should be pinned where users actually meet it.
+
+**CI does not run Rust tests.** No workflow invokes `cargo test`; the only
+Rust checks are `cargo fmt --check` and
+`cargo clippy --no-deps --all-targets`. `--all-targets` compiles
+`#[cfg(test)]` code, so a Rust test cannot rot into a non-compiling state, but
+it is never executed and a behavioral regression will not fail the build. A
+Rust test added today is dead weight.
+
+Adding a `cargo test` job is not a one-line change: `crates/core/Cargo.toml`
+enables `pyo3/extension-module` unconditionally, so the test binary fails to
+link against `Py_*` symbols on Linux. The feature would have to be gated first.
+
+Write a Rust test only when the behavior is genuinely unreachable from Python,
+and wire up CI in the same change so it actually runs. Before concluding it is
+unreachable, check the suites that already exist:
+
+- `python/tests/` — the main suite. Run `pytest python/`, **not**
+  `pytest python/tests/`: `--doctest-modules` is on by default and the
+  narrower path skips the doctests in `python/datafusion/`.
+- `examples/datafusion-ffi-example/python/tests/` and
+  `examples/datafusion-ffi-query-planner-example/python/tests/` — integration
+  coverage across a real FFI boundary, for anything involving extension
+  codecs, table providers, query planners, or capsule export. These need the
+  example crates built (`maturin build`, then install the wheel).
+- `examples/tpch/` — end-to-end query coverage.
+
+Prefer asserting observable behavior over internal accessors. A test that
+checks a getter can pass while the path a user actually takes is broken.
+
 ## Python Function Docstrings
 
 Every Python function must include a docstring with usage examples.