If your AI coding sessions feel like vibe-coding without a plan, the Kiro AI IDE takes a deliberately different approach. Instead of generating code from a one-line prompt, Kiro forces you through a structured spec workflow first: requirements written in EARS notation, then a technical design, then discrete tasks. This tutorial walks through installing the Kiro AI IDE, writing your first spec, and using agent hooks and MCP servers in production-style work. By the end, you will know exactly when spec-driven development pays off and when it slows you down.
What Is the Kiro AI IDE?
Kiro is an agentic IDE from AWS, built on a VS Code-compatible base and powered by Claude Sonnet 4.5 (with an Auto mode that routes between frontier models). Unlike pure chat-based assistants, Kiro structures every feature as a spec: a folder containing requirements.md, design.md, and tasks.md. The AI does not jump straight to code. Instead, it negotiates the plan with you first, then executes tasks one by one against the agreed plan.
This positioning matters. Tools like Cursor and Claude Code can produce excellent results on small, well-scoped prompts. However, they can also drift on multi-day features because there is no shared artifact tracking what was decided, why, and what is left to build. Kiro tries to solve that problem by making the spec the source of truth.
EARS Notation: The Mental Model You Need First
EARS stands for Easy Approach to Requirements Syntax. Originally developed at Rolls-Royce, the notation gives you a small set of templates that turn fuzzy user stories into testable, machine-readable acceptance criteria. Kiro generates EARS-formatted requirements automatically, but you will write and edit them often, so the patterns are worth memorizing.
There are five core patterns:
| Pattern | Template | Use When |
|---|---|---|
| Ubiquitous | THE SYSTEM SHALL [response] | The behavior is always true |
| Event-driven | WHEN [trigger] THE SYSTEM SHALL [response] | A specific event causes the behavior |
| State-driven | WHILE [state] THE SYSTEM SHALL [response] | Behavior holds during a state |
| Optional feature | WHERE [feature included] THE SYSTEM SHALL [response] | Feature flags or build variants |
| Unwanted behavior | IF [bad condition] THEN THE SYSTEM SHALL [response] | Error handling and edge cases |
A concrete example for a password reset feature looks like this:
THE SYSTEM SHALL store passwords using Argon2id with a minimum work factor of 3.
WHEN a user submits a valid email on the reset form THE SYSTEM SHALL send a one-time
reset link valid for 30 minutes.
WHILE a reset link is unused and unexpired THE SYSTEM SHALL allow exactly one password
change before the link is invalidated.
WHERE rate limiting is enabled THE SYSTEM SHALL block more than 5 reset requests per
email per hour.
IF a user submits an expired reset link THEN THE SYSTEM SHALL display "This link has
expired" and offer to send a new one.
Notice what is missing: no vague words like “user-friendly”, “appropriate”, or “fast”. Every line is concrete enough to write a test against. As a result, downstream tasks generated by Kiro are also concrete, not aspirational.
Installing Kiro and Signing In
Kiro is currently distributed as a desktop installer for macOS, Windows, and Linux. Download the build for your OS from kiro.dev, then sign in. You have two account options: AWS Builder ID (free, fastest path for individuals) or AWS IAM Identity Center (for teams already on AWS SSO).
Expected first-run output looks like this:
# After install, launch Kiro and open a project folder
$ kiro .
# First-time auth prompts the browser:
# Visit https://oidc.kiro.dev/device?user_code=ABCD-EFGH
# Confirm in browser to complete sign-in
Once authenticated, open the Kiro panel on the left sidebar. You will see four sections that map directly to the spec workflow: Specs, Steering, Agent Hooks, and MCP. Pin the panel — you will use it constantly.
If you have a .gitignore already, add .kiro/cache/ and .kiro/sessions/ to it. The .kiro/specs/ and .kiro/steering/ folders, by contrast, should be committed; they are part of your project’s documented intent and survive across teammates.
Step 1: Generate Steering Docs
Before writing a spec, give Kiro project context. Click Generate Steering Docs in the Kiro panel. The agent inspects your repo and produces three files in .kiro/steering/:
product.md— what the product does and who uses ittech.md— the stack, frameworks, and key dependenciesstructure.md— folder layout and architectural conventions
Review each file. Steering is read on every prompt, so an inaccuracy here propagates into every future spec. For instance, if tech.md says “uses Express” but you actually run Fastify, all generated code will use the wrong middleware patterns. Spend five minutes correcting these files; it pays back across every subsequent feature.
You can add custom steering files too. A common pattern is .kiro/steering/style.md describing naming conventions, error-handling style, and import order. For backend projects, a .kiro/steering/api.md with your standard response envelope ({data, error, meta}) prevents Kiro from inventing a new response shape per endpoint.
Step 2: Create Your First Spec (Requirements Phase)
Now create a spec. Click the + in the Specs section and describe the feature in plain language:
Add an invite-by-email flow for our SaaS app. An admin can invite a teammate by email; the invitee gets a signed link that expires in 7 days; on signup, they join the inviter’s workspace.
Kiro generates .kiro/specs/team-invites/requirements.md. The output uses EARS notation grouped by user story:
## Story: Admin invites teammate
THE SYSTEM SHALL restrict invite creation to users with the `admin` role.
WHEN an admin submits an invite form with a valid email THE SYSTEM SHALL
create an invite record and send an email containing a signed link.
IF the email already belongs to a workspace member THEN THE SYSTEM SHALL
return "User already in workspace" without creating an invite.
## Story: Invitee accepts invite
WHILE an invite is unaccepted and within 7 days of creation THE SYSTEM
SHALL allow the invitee to complete signup and join the workspace.
IF the invite link is expired or already used THEN THE SYSTEM SHALL
display "This invite is no longer valid" and offer to request a new one.
This is the moment to slow down. Read every requirement. The trade-offs you negotiate here cost five minutes; the same trade-offs argued during code review cost an afternoon. For example, if you want invites to also extend an existing user’s workspace membership rather than rejecting them, edit the IF statement now. Click Approve Requirements only when the doc reflects the real intent.
Step 3: Review the Design Phase
After approval, Kiro generates design.md. This file is more free-form: data models, sequence diagrams (in mermaid), API endpoints, and key decisions. A typical design block looks like this:
## Data Model
invites (
id uuid pk,
workspace_id uuid fk,
email citext not null,
token_hash bytea not null,
expires_at timestamptz not null,
accepted_at timestamptz null,
invited_by uuid fk users(id)
)
Index: (workspace_id, email) where accepted_at is null
-- prevents duplicate active invites
Why this matters: the agent committed to hashing the invite token rather than storing it raw. That is a security decision worth catching. Likewise, the partial unique index encodes a real-world constraint — you can re-invite someone after their previous invite expires or is accepted, but not while one is pending. If Kiro proposes a design that contradicts your steering docs or your team’s practices, edit it before approving. Skipping this review is the single most common mistake new Kiro users make.
Step 4: Execute the Tasks Phase
Once design is approved, Kiro generates tasks.md — a numbered, checkbox-style list of discrete units of work:
## Tasks
- [ ] 1. Create `invites` migration (postgres) with partial unique index
- [ ] 2. Add `Invite` Prisma model and regenerate client
- [ ] 3. Implement `POST /api/invites` (admin role required)
- [ ] 4. Implement `GET /api/invites/:token` (validate + accept)
- [ ] 5. Add invite email template (Resend, signed link)
- [ ] 6. Add Vitest unit tests for token generation and expiry
- [ ] 7. Add Playwright e2e: admin invites + invitee accepts flow
Click any task to execute it. Kiro spawns an agent session scoped to that task only. The agent reads the spec, the steering files, and any task-relevant code, then proposes a diff. You approve, edit, or reject the diff exactly like a pull request review.
The narrow scope is the point. A general “build the invites feature” prompt is too broad — agents drift, hallucinate APIs, and produce 1,500-line diffs that are unreadable. Task-by-task execution keeps each diff in the 50–250 line range, which is the sweet spot for human review.
If you have used Claude Code’s terminal workflow, the mental model is similar: treat the AI as a senior engineer who needs a tight, well-scoped issue rather than a vague mandate.
Agent Hooks: Automating Side Tasks
Agent hooks are Kiro’s answer to repetitive, mechanical work that does not deserve a full spec. Click + in the Agent Hooks section and create one with three fields:
- Trigger: file save, file create, file delete, or manual
- Pattern: a glob like
src/**/*.ts - Instructions: natural-language directive
A useful starter hook updates tests when source files change:
name: Update tests on save
trigger: onSave
pattern: src/**/*.ts
instructions: |
When this file is saved, check whether the corresponding *.test.ts
file still covers all exported functions. If not, add or update
tests. Do not modify the source file itself.
Other hooks that earn their keep in real codebases:
- Regenerate OpenAPI types when route handlers change
- Update
CHANGELOG.mdwhen a new migration is added toprisma/migrations/ - Run a security review pass on any file under
src/auth/before commit
The trade-off is cost and noise. Hooks consume credits on every fire and occasionally produce diffs you do not want. Start with one or two hooks, watch them for a week, and only add more after you have a feel for the false-positive rate.
Adding MCP Servers
The Model Context Protocol lets Kiro talk to external tools — databases, issue trackers, browsers, your own internal APIs. Open the MCP section in the Kiro panel and toggle servers on, or paste a JSON config:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres",
"postgresql://localhost/myapp"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
}
}
}
Why this matters: with the Postgres MCP enabled, you can ask Kiro “what’s the actual schema of the users table?” during the design phase, and it queries your dev database directly instead of guessing. As a result, the generated design.md reflects reality rather than the agent’s mental model of what your schema “probably” looks like.
For a deeper walkthrough of MCP itself, see our guide on Claude Code MCP servers — the protocol is the same; only the host changes.
When to Use the Kiro AI IDE
- You are building a multi-day feature where requirements and design need to be reviewed by a teammate or product manager
- Your team values traceability — the ability to answer “why did we build it this way?” six months later
- You work in a regulated environment (healthcare, fintech, gov) where formal acceptance criteria are part of the audit trail
- You frequently lose context between sessions and want a durable artifact (the spec) that survives across days
- You are onboarding to a codebase and want generated steering docs to summarize what is there
When NOT to Use the Kiro AI IDE
- The change is a one-line bug fix or a CSS tweak; the spec ceremony costs more than the fix
- You are exploring or prototyping and do not yet know what you want to build
- Your team has zero appetite for reviewing a requirements doc; the workflow only pays off if specs get read
- You work in a domain Kiro’s models do not handle well (highly proprietary embedded systems, niche legal-tech DSLs)
- You need a free option — Kiro is credit-metered, and heavy use is not cheap
Common Mistakes With the Kiro AI IDE
- Approving requirements without reading them. The whole workflow assumes the spec reflects intent. Skim-approving means downstream code is technically correct against requirements you never actually agreed to.
- Letting steering docs go stale. When
tech.mdsays “Express” but you migrated to Fastify three months ago, every new spec inherits the wrong assumptions. Treat steering files like code: review them when stacks change. - One giant spec for an entire epic. Kiro works best with specs scoped to one feature, not one quarter. Break large initiatives into multiple specs that link to each other.
- Over-hooking. Adding ten agent hooks before you understand which ones actually help leads to noise, surprise diffs, and wasted credits. Add one, observe, then expand.
- Treating EARS as bureaucracy. EARS exists because vague requirements produce vague code. If a generated requirement reads “the system shall be user-friendly”, rewrite it. The fix is almost always replacing one fuzzy adjective with a measurable condition.
Real-World Scenario: A Mid-Sized SaaS Team
Consider a small SaaS team — three backend engineers and one product manager — building a billing-overhaul feature that touches Stripe, internal credit ledgers, and a customer-facing billing page. Without a spec workflow, kickoff typically means a 90-minute meeting, a hallway-conversation summary in Slack, and three engineers building slightly divergent mental models of the same feature.
With Kiro, the same kickoff produces a requirements.md reviewed by all four people in one sitting. EARS-style conditions force the team to surface decisions that would otherwise leak out as bugs: what happens when a webhook arrives twice, what happens when a credit balance goes negative, what happens when Stripe is unreachable for 30 minutes. The PM signs off on the requirements doc; engineers hand off tasks without losing context.
The trade-off is upfront time. The first spec on a new project typically takes longer than just starting to code, because the team is also editing the steering docs and learning each other’s preferences. By the third spec, the per-feature overhead drops noticeably — most of what slowed down the first spec was project context that is now captured durably.
Conclusion
The Kiro AI IDE bets that structure beats speed for any feature large enough to deserve a code review. Spec-driven development with EARS notation forces the trade-offs out of your head and into a file your whole team can read, edit, and reference later. For one-line tweaks it is overkill; for any feature you would put in a sprint, it earns its keep.
To go deeper on the broader AI tooling landscape, compare the Kiro approach against terminal-first agents in our Cursor vs Claude Code comparison, or explore an open-source alternative in our OpenCode setup guide. For a different IDE-based agent, our Windsurf editor and Cascade agent walkthrough covers a similar shape with a very different agent loop. If you want a wider view of where each tool fits, our roundup of AI tools for coding productivity is the right next read.
