The rate limiter is a good example to walk through, because it's exactly where specs earn their keep. One requirement worth adding to that requirements.md: who is exempt, and how the limiter knows.
We found this the hard way this week (I build Mythex, an AI app builder). Our API's per-IP limit counted our own internal services like single users. One sat behind a few shared Cloudflare IPs, another behind one container IP, and on production they started getting 429s on the requests that serve published sites. Nothing in the code was wrong. The spec just never said "internal callers carrying the service token aren't users".
That's the general case for spec-driven work: the bugs that survive are usually missing sentences, not wrong code.
Mythex
AI app builder — chat to build, preview, and publish
That is the ultimate spec-driven lesson one can get. It’s wild how often the bugs that survive aren’t logic errors, but missing sentences. I actually ran into a similar issue with auth scopes the agent built the perfect middleware, for one of my client when i went into detailed review of their code end; but the spec didn’t account for read-only service accounts. It’s a reminder that the Spec isn’t a set it and forget it document; it’s a living contract that needs to be stress-tested against real-world traffic patterns, not just happy paths.
Read-only service accounts are a great example, because they're exactly the caller nobody pictures while writing the happy path. One habit that helps: give every spec a short "who calls this" table (signed-in users, admins, service accounts, scheduled jobs, webhooks) and have the agent fill in the expected behaviour for each row before it writes code. Most of the missing sentences show up as blank rows.
The rate limiter is a good example to walk through, because it's exactly where specs earn their keep. One requirement worth adding to that requirements.md: who is exempt, and how the limiter knows.
We found this the hard way this week (I build Mythex, an AI app builder). Our API's per-IP limit counted our own internal services like single users. One sat behind a few shared Cloudflare IPs, another behind one container IP, and on production they started getting 429s on the requests that serve published sites. Nothing in the code was wrong. The spec just never said "internal callers carrying the service token aren't users".
That's the general case for spec-driven work: the bugs that survive are usually missing sentences, not wrong code.