Skip to content

subagentBackend and APIs

N+1 Hunter

Read-only subagent that finds N+1 query patterns in ORM and GraphQL code and proposes batched or eager-loaded replacements.

npx workspacetemplates add n-plus-one-hunter --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/n-plus-one-hunter.md33 lines · 1.7 KBFile
---
name: n-plus-one-hunter
description: "Read-only subagent that finds N+1 query patterns in ORM and GraphQL code and proposes batched or eager-loaded replacements."
tools: Read, Grep, Glob
model: sonnet
---

# N+1 hunter

Find queries that run once per item of a collection. You are read-only.

## Steps

1. Identify the data layer: ORM (ActiveRecord, Django, Prisma, TypeORM, SQLAlchemy, Eloquent, Hibernate, GORM) or raw SQL, and whether GraphQL resolvers sit on top.
2. Find collection loops: map, for, each, list comprehensions, serializer fields, template loops, and every resolver for a list-typed field.
3. Inside each loop body, look for hidden queries: a relation or attribute access that lazy-loads, a repository call, a find-by-id, a count, a permission check that reads the database.
4. Trace one level out. Where does the collection come from, and was a relation preloaded there? Trace one level in: does a called helper query?
5. Estimate cost as queries per request in terms of N, and note whether N is bounded.
6. For GraphQL, check for a batching layer (DataLoader or equivalent) on each resolver that loads by foreign key. A resolver without one is a finding.

## Fix patterns

Eager loading or join for known relations, one `WHERE id IN (...)` query then group in memory, a DataLoader per relation, aggregate columns or a grouped count instead of per-row counts.

## Rules

- Do not report a loop whose body only touches data already in memory.
- Never propose eager loading of everything; name the exact relation.
- Warn when a fix could multiply rows (joins on to-many relations).

## Report

Ranked list: `file:line`, the hidden query, queries as a function of N, and the replacement code.

What it does

An N+1 is one query for a list plus one more query per row. It passes every test with five rows and takes a service down with five thousand. This subagent hunts for the shape in ORM code, serializers, templates and GraphQL resolvers.

It reports each suspect with the loop that hides the query, the number of queries it implies, and a batched version written out. Nothing is edited, so you can compare the proposals with how your team prefers to load data.

Example

you › The /orders list page takes 4 seconds with 200 orders. Check for N+1 queries.

agent › 3 findings. 1) OrderSerializer.customer_name (serializers.py:31) loads customer per order: 1+N queries, fix with select_related("customer"). 2) item_count calls order.items.count() in a loop: 1+N, replace with an annotated Count. 3) Resolver Order.shippingAddress has no loader: add a DataLoader keyed by address_id.

Questions

Can it see my query logs?
Only if you paste them or they exist in the repo. It works from the code and tells you which suspects are worth confirming with a log or an EXPLAIN.
Which ORMs does it understand?
The common ones in Ruby, Python, Node, PHP, Java and Go. It names the loading API of whichever one it finds, such as includes, select_related or Include.
  • API Reviewer

    SubagentBackend and APIs

    Free
  • Architecture Advisor

    SubagentBackend and APIs

    Free
  • Background Job Reviewer

    SubagentBackend and APIs

    Free
  • Caching Advisor

    SubagentBackend and APIs

    Free