Quick Answer
Manual code review matters, and I'm not here to talk you out of it. But your reviewers can't catch bugs they've never heard of. A good reviewer reads the code and checks the logic. What they probably don't have is Stripe's entire documentation sitting in their head. They don't necessarily know Stripe wants an idempotency key on every mutation, or that webhook signature verification isn't optional. api-doctor knows the docs cold. People don't, and that's fine, because that's not what people are for.
The limits of human code review
Code review is genuinely great at catching logic errors, security holes, performance problems, and messy style. Where it struggles is API provider requirements: idempotency keys, signature verification, silent failure modes, deprecated endpoints. Not because reviewers aren't sharp, but because nobody memorizes provider documentation. Stripe alone runs past 200 pages. Auth0 is bigger. You can't hold that in your head, and you shouldn't have to.
A real scenario: the bug that slips through
Your AI writes a charge function. Your reviewer runs down the list. Right function? Yes. Correct parameter types? Yes. Error handling? Yes. Matches the house style? Yes. Approved. Shipped.
Then production happens. The network times out, the retry fires, and a customer gets charged twice. The post-mortem lands on a familiar note: "turns out section 5.3.2 of Stripe's docs says idempotency keys are required for safe retries." The reviewer didn't know. The docs are long. The AI forgot. Everybody did their job, and the bug shipped anyway.
Why api-doctor is different
api-doctor isn't trying to review your logic. It checks deterministic rules pulled straight from provider documentation:
✗ stripe-missing-idempotency-key
src/payments.ts:5
Missing idempotency_key. Retried requests will charge customers twice.
That rule is specific, deterministic, grounded in the actual docs, and it fires every single time. No mood, no fatigue, no skimming.
What each one catches
| Check | Manual Review | api-doctor | |---|---|---| | Logic errors | Good | No | | Performance | Good | No | | Code style | Good | No | | API requirements | Hard | Good | | Provider failure modes | Hard | Good | | Deprecated endpoints | Hard | Good | | Deterministic | Varies | Always |
Where api-doctor catches what humans miss
Long documentation. Stripe has 47 webhook event types. Your code handles three. Did your reviewer really check the other 44? api-doctor walks every path.
Subtle semantics. Does deleteUser() also revoke active sessions? The docs say it should. Your AI code doesn't, and a reviewer might not know it's even a requirement. api-doctor has a rule for exactly that.
Provider changes. Stripe deprecates an endpoint. Your code still calls the old one. A human isn't likely to catch that the day it happens. api-doctor's rules get updated when the provider's docs do.
The workflow
Before api-doctor, it looks like this: the agent writes code, a human reviews it (fingers crossed), you merge, you deploy.
With api-doctor, you add one step: the agent writes code, api-doctor scans it and flags the provider violations, then a human reviews for logic and design, and you merge and deploy.
Humans handle logic and design. api-doctor handles provider requirements. They're better together, not in competition.
Frequently asked questions
Q: Should I replace code review with api-doctor? No, and please don't. Let api-doctor catch the provider-specific bugs, then let a human review the logic and design.
Q: Will api-doctor catch every bug? No. It catches deterministic violations of provider rules. Logic errors and semantic issues are still on you — that split is the whole story of AST rules vs LLM prompts.
Q: What if I disagree with a rule?
Turn it off in api-doctor.config.json. Just read why the rule exists in the provider's docs first, because usually there's a good reason.
Q: How often do the rules update? Whenever providers change their documentation or ship new requirements.