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 defand mustawaitnon-blocking clients. Never call a blocking library insideasync 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 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 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__.pyfiles 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
defvsasync defby your I/O, not by reflex. FastAPI runs a plaindefhandler in a threadpool, so a sync handler over a sync driver (SQLModel/SQLAlchemySession) is correct — not a bug to “fix” by addingasync. The inverse is the bug: never make a blocking call insideasync def. Go async only when the whole call chain awaits a non-blocking client, and offload CPU-bound work withrun_in_threadpool.
The path findings are now regression tests using the real template paths. The async wording has no test; it’s prose.