Kiro: how to review code when an AI IDE builds from structured specs

2026-04-29 · 5 min read · ZenCode

Kiro is Amazon’s AI IDE built around a spec-first development model. Instead of prompting the AI with a natural-language request and reviewing what comes back, you start by creating a structured specification — a machine-readable document describing requirements, data models, and API contracts. Kiro reads the spec and generates the implementation: file structure, data layer, handlers, tests, and wiring. The AI doesn’t interpret a vague instruction; it executes against a defined artifact.

The code quality Kiro produces is comparable to what you’d get from Amazon Q Developer or GitHub Copilot Agent Mode on an equivalent task. What changes is the starting point. Because Kiro’s input is a structured spec and not a free-form prompt, the relationship between intent and output is more explicit — and that explicitness creates its own set of review traps. Three of them recur consistently.

The three Kiro review traps

1. Spec-compliance substitution

When code is generated from a spec, the spec becomes the implicit review standard. Reviewers open the diff, verify that the data model matches the spec, check that the API endpoints match the spec, confirm that the error codes match the spec — and then approve. The review has been completed in the sense that nothing contradicts the written requirements. But the question “is this code correct?” has been silently replaced by “does this code match the spec?”

These are not the same question. A spec can be internally consistent and completely wrong. It can omit a class of concurrent requests that will cause a race condition. It can describe an authentication flow that is spec-compliant and exploitable. It can specify a data model that normalizes correctly and performs badly at the query patterns your application actually runs. Kiro will faithfully implement what the spec says. It will not tell you what the spec forgot.

The fix is to hold two separate review passes mentally distinct. The first pass checks spec compliance: did the AI implement what was asked? The second pass checks correctness independent of the spec: is this implementation correct even if the spec had never existed? The second pass is the one that gets dropped when spec-compliance substitution takes hold, and it is the only one that catches the gaps the spec did not anticipate.

2. Hook-driven automation confidence

Kiro includes a hooks system: configurable automations that run on file save, on spec update, or on other events. A typical Kiro project runs the linter on save, runs the relevant tests on spec update, and runs a build check before the diff is surfaced to you. By the time you see Kiro’s output, it has already passed a validation pipeline that you configured.

Passing hooks creates a feeling analogous to passing tests in a CI pipeline — the code feels pre-cleared. The difference is that CI tests are usually written to probe actual behavior, while Kiro hooks are often configured during project setup to run fast and never revisited. Linting checks style, not correctness. The test suite that runs in the hook was written before the spec existed and may not cover the new surface area at all. A build that compiles is a weaker signal than it looks when the new code paths added by the spec have no dedicated tests yet.

The practical consequence is that “all hooks passed” is shown prominently in Kiro’s UI, and reviewers register it as a positive signal without asking what the hooks actually checked. Before trusting the hook result, it is worth opening the hook configuration and asking: what would a hook NOT catch in the code the spec just generated? The answer is almost always “the new behavior the spec introduced.”

3. AWS-first vendor capture

Kiro is an AWS product and its agent is trained on AWS documentation, AWS SDKs, and patterns from AWS reference architectures. When Kiro generates code from a spec that describes, say, “store user sessions” or “send notifications asynchronously,” it reaches naturally for DynamoDB, SQS, SNS, and Lambda. The implementations it produces are syntactically correct, idiomatic for AWS, and consistent with AWS best practices — which is exactly what makes vendor capture easy to miss.

The problem is not that AWS services are wrong choices. The problem is that the spec did not specify AWS. It specified behavior. Kiro resolved that behavior to AWS primitives silently, and reviewers fluent in AWS will read the DynamoDB calls, recognize the pattern, and approve without noticing that a Redis cluster or a standard Postgres table with a TTL index would have served the same requirement with fewer moving parts and no vendor dependency.

This is a subtler trap than the first two because the code is correct. It runs. It scales. It passes the hooks. The issue only surfaces when the team later wants to move the service, when AWS pricing changes at a tier the spec’s projected load will hit, or when a new engineer joins who is not AWS-fluent and now has to maintain an architecture that is more complex than the requirement warranted. Reviewing for vendor capture means asking, for each AWS-specific choice Kiro made: did the spec require this service, or did Kiro choose it because it was the most available option?

What Kiro’s spec model does well

The three traps above are real, but they are not arguments against Kiro’s approach. Spec-first development has a genuine advantage over prompt-driven generation: the spec creates an artifact that can be versioned, reviewed independently of the code, and used to audit the implementation later. A natural-language prompt disappears the moment the code is accepted; a spec persists in the repository alongside the code it generated.

That persistence changes the review dynamic over time. When a bug surfaces three months after Kiro generated the implementation, the spec is still there. You can read what the requirement said, compare it to what the code does, and determine whether the bug is in the spec, in the implementation, or in both. This kind of traceability is rare in prompt-driven tools and is one of the things Kiro’s model gets genuinely right.

The challenge is that the same artifact that creates traceability also creates spec-compliance substitution. The spec is useful because it is the ground truth. It becomes a trap when it substitutes for independent correctness review. Holding both properties simultaneously — the spec as a useful artifact and the spec as an incomplete description of what the code should actually do — is the core skill of reviewing code that Kiro generated.

Kiro occupies the same category as Google Jules and Devin: tools that run an extended agentic loop and return a completed artifact rather than an incremental suggestion. The review pattern is similar — treat the output as contractor work you did not watch, not as a suggestion you accepted — but Kiro adds the spec layer, which changes where the highest-leverage review questions live. For Kiro, those questions are: what did the spec not say, what did the hooks not check, and which architectural choices reflect AWS availability rather than requirement necessity?