Deep Dives

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 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__.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.