# My AI rule pack nudged agents toward blocking FastAPI code

ZeroContext ships small rule files, one set per stack, that a coding agent pulls when it's working on a matching file. The agent treats them as instructions. My FastAPI set said:

> Endpoints that do I/O are `async def` and must `await` non-blocking clients. Never call a blocking library inside `async def`; run it in a threadpool or use an async client.

Read carefully, that's not wrong. The second sentence even warns about the bug. The first one sets the default, though, and [the official full-stack FastAPI template](https://github.com/fastapi/full-stack-fastapi-template) uses a synchronous SQLModel `Session`. An agent that takes the rule at its word would see an endpoint doing I/O and make it `async def`, and then `session.exec()` would [block the event loop](https://fastapi.tiangolo.com/async/) for every request.

---

## How it turned up

I tested every rule set against a real repo for its stack: the full-stack FastAPI template, Vercel's AI chatbot, ripgrep. Reading the rules next to real code is what showed it.

The same pass found two smaller ones:

- empty `__init__.py` files were matching the FastAPI routing rules, so a package marker pulled in the whole set
- the React, Next.js and Drizzle sets excluded `*.test.*` but not `*.spec.*` or `__tests__/`, so test files got component and ORM rules

---

## The rewrite

The new rule:

> Choose `def` vs `async def` by your I/O, not by reflex. FastAPI runs a plain `def` handler in a threadpool, so a sync handler over a sync driver (SQLModel/SQLAlchemy `Session`) is correct — not a bug to "fix" by adding `async`. The inverse is the bug: never make a blocking call inside `async def`. Go async only when the whole call chain awaits a non-blocking client, and offload CPU-bound work with `run_in_threadpool`.

The path findings are now regression tests using the real template paths. The async wording has no test; it's prose.
