Coding agents#
Since 0.10.0.
A coding agent writes data-access code fast, and an N+1 query passes every
test that only checks results. pytest-queryguard fails those tests, for
SQLAlchemy 2 and for the Django ORM; the files
on this page tell an agent (Claude Code, Cursor, Codex, Copilot and other
tools that read AGENTS.md) to run them, read the findings as data, apply the
suggested loader option (joinedload/selectinload, or
select_related/prefetch_related in Django) and run the tests again to
check the fix. They are short on purpose: the agent learns the loop, the tool
does the measuring.
For agents that look things up, the documentation site has
llms.txt, a
summary, and
llms-full.txt,
every page in one Markdown file (see llmstxt.org).
For an agent that speaks MCP, the MCP server gives the same loop
as tools: run_tests and the static check, lint.
Claude Code plugin#
The repository is a Claude Code plugin marketplace with one plugin, which
installs the skill below from the main branch; the skill works with any
1.x release of the package. In a terminal:
claude plugin install pytest-queryguard --marketplace MaciejZiel/pytest-queryguard
or, inside Claude Code,
/plugin install pytest-queryguard --marketplace MaciejZiel/pytest-queryguard.
Claude Code before 2.1.275 needs two steps:
claude plugin marketplace add MaciejZiel/pytest-queryguard
claude plugin install pytest-queryguard@pytest-queryguard
Add --scope project to the install to record it in the project's
.claude/settings.json, for everyone who works on it. Claude Code then loads
the skill when the task matches its description, or on
/pytest-queryguard:pytest-queryguard. claude plugin update
pytest-queryguard@pytest-queryguard gets the skill as it is on main now
(the plugin has no version number of its own, so each commit is a new
version).
The plugin does not start the MCP server: that one has to run with the interpreter of your project, so add it per project as its page says.
A skill (Claude Code and other agents that read SKILL.md)#
The repository has a skill,
skills/pytest-queryguard/SKILL.md.
Without the plugin, copy it into your project, where Claude Code finds
project skills (Codex and other agents that read SKILL.md files have
their own skills directory):
mkdir -p .claude/skills/pytest-queryguard
curl -fsSL -o .claude/skills/pytest-queryguard/SKILL.md \
https://raw.githubusercontent.com/MaciejZiel/pytest-queryguard/main/skills/pytest-queryguard/SKILL.md
(~/.claude/skills/pytest-queryguard/ makes it available in every
project.) Its description makes the agent load it when the user mentions
N+1 queries, "too many queries", a lazy load in a loop, assertNumQueries
or a query count test, or an alternative to nplusone or django-zeal; after
changing code that loads ORM objects; and when a test fails with
queryguard: N+1 detected. It tells the agent to:
- check that the plugin is installed in the project's environment;
- run the tests of the changed code with
--queryguard-jsonand--queryguard-write-patch; - read the findings from the JSON file (
kind,label,file,line,messagewith itsfix:line) and apply the loader option on the query that loaded the parents, or the patch withgit apply; - run the same tests again, and not to silence findings unless asked.
AGENTS.md#
Paste this into the AGENTS.md (or CLAUDE.md) of your project, and change
the paths:
## N+1 queries (pytest-queryguard)
pytest-queryguard fails any test whose application code runs an N+1 query
(N+1s in test code itself are only counted at the end of the run).
After changing code that queries or loops over ORM objects:
1. Run the tests that cover it:
`python -m pytest tests/test_orders.py --queryguard-json=.queryguard.json --queryguard-write-patch=.queryguard.patch -q`
2. Read `.queryguard.json`: `tests[<node id>].findings[]` has `kind`,
`label`, `file`, `line`, `count` and `message`. The `message` names the
query that loaded the parents (`parents loaded at`) and the fix (`fix:`).
3. Fix at that query, not in the loop: `joinedload(...)` for a many-to-one,
`selectinload(...)` for a collection (Django: `select_related(...)`,
`prefetch_related(...)`); for `repeated-statement`, one query
with `IN (...)`. If `.queryguard.patch` is not empty, `git apply` it from
pytest's rootdir.
4. Re-run the same command; done when the findings are gone and tests pass.
Do not add `ignore()`, `queryguard_ignore` markers or baseline entries to
make a test pass unless asked. Without a database,
`python -m pytest_queryguard.lint --models app.models app/` is a quick
static check; the tests are the proof.
A Cursor rule#
Save as .cursor/rules/pytest-queryguard.mdc; Cursor attaches it when the
agent edits a file the globs match:
---
description: Find and fix N+1 queries with pytest-queryguard after changing SQLAlchemy or Django ORM data access
globs: app/**/*.py,tests/**/*.py
alwaysApply: false
---
After changing code that queries or loops over SQLAlchemy or Django objects, run the
tests that cover it with
`python -m pytest <tests> --queryguard-json=.queryguard.json --queryguard-write-patch=.queryguard.patch -q`.
Read the findings in `.queryguard.json` (`tests[...].findings[]`: `kind`,
`label`, `file`, `line`, `message`). Put the loader option on the query
named by `parents loaded at` in `message` (`joinedload` for many-to-one,
`selectinload` for collections; Django: `select_related`,
`prefetch_related`), or `git apply .queryguard.patch`. Re-run
the same command until the findings are gone. Never silence a finding with
`ignore()`, a marker or a baseline entry unless asked.
Why the JSON file#
The terminal report is written for people and its wording changes between
releases (see Stability); the
--queryguard-json file has documented keys
and a format number. message inside it is the report's text, for the
fix: and parents loaded at lines, which an agent reads as hints. The
patch is written only
when the line of the parent query is certain.