I Almost Shipped Something Broken — Here's What Fixed That

I run a gateway service behind a pool of API keys - rotating them, handling rate limits, retrying when things fail. Standard infra stuff. Recently I built a stats endpoint on top of it to track call success rates, failure reasons, and latency per model.

It worked. It ran. The output looked clean.

That was the problem.

Looking done isn't the same as being done

AI coding agents are great at producing code that looks finished — it compiles, it runs, the happy path works. What they're not automatically great at is the stuff a senior engineer checks before merging: edge cases, failure classification correctness, whether your metrics could silently produce wrong numbers under load.

I'd shipped a few things trusting exactly that "looks done" signal. No structured review, no second pass — just "it ran, ship it."

What I tried

I came across Agent Skills — an open-source pack by Addy Osmani that drops a set of slash commands into your coding agent (Claude Code, Cursor, Codex, and others): /spec, /plan, /build, /test, /review, /ship, among others. Each one encodes a step senior engineers actually take — writing a spec before code, reviewing on a five-axis rubric, checking for security gaps before merging.

Install is one line:

bash

npx skills add addyosmani/agent-skills

I pointed /review at code I'd already shipped — my stats endpoint and the failure-classification logic behind it. Not a toy example. Real code, already in use.

What it caught

The review didn't rewrite anything. It flagged specific things — file, line, why it mattered, and how severe it was. Some I already half-suspected. A couple I hadn't thought about at all.

That's the actual value: not "AI writes better code," but "AI can be made to check its own work the way a person would, instead of stopping the moment something runs."

The takeaway

AI-written code passing on the first try isn't proof it's correct — it's just proof it didn't immediately break. The gap between those two things is exactly where bugs live long enough to reach production.

Adding a review step doesn't slow you down much. It's one extra command. What it buys you is catching the stuff that "it ran fine" quietly hides.

If you're running any real infrastructure behind AI-generated code — even code you wrote yourself with AI assistance — it's worth running an actual review pass before you trust it in production. Not because the code is bad. Because "looks done" was never the bar.