Amazon Kiro IDE: The Complete Guide to Spec-Driven AI Development (2026)

Amazon launched Kiro IDE in July 2025 and the developer community noticed immediately. Not because it comes from Amazon. Because it does something no other AI coding IDE has done at the same level: it gives the AI a structured understanding of what you’re building before you write a single line of code.

This guide covers everything you need to know about Kiro IDE in 2026 — how steering files work, what specs actually generate, how hooks automate your workflow, and how it stacks up against Cursor and Claude Code. We include real .kiro/steering/ file examples you can copy today.

What Is Kiro IDE?

Kiro is Amazon’s AI-native coding IDE, currently available as a free public preview at kiro.dev. It is built on VS Code (Code OSS), which means your existing VS Code settings, themes, and extensions carry over without reconfiguration.

A few things worth knowing before you dive in:

It replaces Amazon Q Developer. AWS end-of-lifed Amazon Q Developer in favor of Kiro. If you used Q Developer, Kiro is the successor — and a significant upgrade in approach.

It is free during preview. Pricing for post-preview is not yet announced.

The source is on GitHub. The project lives at github.com/kirodotdev/Kiro.

The core philosophy Kiro introduces is spec-driven development: before the AI writes code, it helps you define what you’re actually building — user stories, data models, API contracts. This shifts the AI from reactive assistant to collaborative planner.

The Three Pillars: Specs, Steering, and Hooks

Kiro’s architecture rests on three concepts that work together:

• Specs — structured feature planning that generates requirements, designs, and interfaces before code
• Steering files — persistent context files that tell the AI how to behave in your project
• Hooks — event-driven automations that trigger when files change

Each pillar solves a different problem. Specs prevent misalignment on what to build. Steering files prevent the AI from forgetting your project conventions. Hooks prevent repetitive manual follow-ups after code changes.

Steering Files: The CLAUDE.md Equivalent

If you use Claude Code, you know CLAUDE.md — a markdown file that tells Claude how to work in your project. Kiro’s equivalent is the steering file.

File Location and Structure

Steering files live in one of two places:

• .kiro/steering/ — workspace-scoped, committed to version control, shared with your team
• ~/.kiro/steering/ — global scope, applies to all projects on your machine

Each steering file is a Markdown file with optional YAML frontmatter. The frontmatter controls when Kiro injects the file into the AI’s context.

Inclusion Modes

Kiro supports four inclusion modes, set via the inclusion key in frontmatter:

always (default) — File content is injected into every AI interaction in the workspace. Use this for your core conventions: coding standards, testing requirements, architectural decisions.

fileMatch — File is only included when the user or AI is working on files matching a glob pattern. Use this for domain-specific rules that only apply to certain parts of the codebase.

manual — File is only included when explicitly referenced with #filename in a prompt. Use this for reference documentation or migration guides you want available on demand.

auto — Kiro decides whether the file is relevant based on the current task. Useful for specialized guidelines that apply to some tasks but not others.

Working Steering File Examples

Here is a complete steering file for general coding standards:

---
inclusion: always
---

# Project Standards

## Stack
- TypeScript strict mode everywhere
- React 18 with functional components
- Tailwind CSS for styling (no CSS modules)
- Vitest for testing (not Jest)

## File Conventions
- Components in `src/components/[ComponentName]/index.tsx`
- Co-locate tests: `src/components/[ComponentName]/index.test.tsx`
- Types in `src/types/` — no inline type declarations for shared types

## Code Rules
- No `any` types. Use `unknown` and narrow.
- Prefer named exports over default exports
- All async functions must handle errors explicitly — no unhandled promise rejections
- Do not import from `../../../` — use `@/` path aliases

## Before Committing
Run `npm run typecheck && npm run test` before suggesting any commit.

Here is a fileMatch steering file for API routes only:

---
inclusion: fileMatch
fileMatch: ["src/api/**/*.ts", "src/handlers/**/*.ts"]
---

# API Handler Standards

## Validation
- All request bodies validated with Zod schemas
- Schemas live in `src/api/schemas/` — never inline

## Error Responses
Use the `ApiError` class from `src/lib/errors.ts` for all error responses.
Never return raw error messages to the client.

## Logging
Log all 5xx errors with full request context using `logger.error()`.

And a manual steering file for migration guidelines:

---
inclusion: manual
---

# Database Migration Guidelines

## Rules
- Never modify existing migration files
- Always create a new migration file for schema changes
- Run `npm run db:migrate:dry` before applying any migration
- Migrations in `src/db/migrations/` are numbered sequentially: `0001_`, `0002_`, etc.

To reference a manual file in a prompt, type #migration-guidelines (matching the filename without .md).

Workspace vs Global Scope

Workspace steering files (.kiro/steering/) belong in your repository. They define project-specific conventions and are shared with every developer who opens the project in Kiro.

Global steering files (~/.kiro/steering/) apply across all your projects. Use these for personal preferences — your preferred comment style, language habits, or your personal AGENTS.md template. They do not override workspace rules.

AGENTS.md Compatibility

Kiro natively reads AGENTS.md files. If you already maintain an AGENTS.md in your repository root (the cross-tool open standard for AI agent instructions), Kiro treats it as an always-included steering file automatically.

You do not need to convert or duplicate your AGENTS.md into a Kiro-specific format. Place it in your workspace root or inside .kiro/steering/ — both locations work.

This matters for teams using multiple AI coding tools. A single AGENTS.md at the repository root gives instructions to Claude Code, Codex, GitHub Copilot (supporting AGENTS.md), and Kiro. One file, four tools.

If you want to browse community-contributed steering file templates and AGENTS.md examples, you can find them in our gallery.

Specs: AI-Driven Feature Planning

Specs are Kiro’s most distinctive feature. When you start a new feature, instead of jumping straight to code, you describe what you want to build in natural language. Kiro then generates:

• User stories in EARS (Easy Approach to Requirements Syntax) notation
• Technical design documents with architecture decisions
• Data flow diagrams in Mermaid format
• TypeScript interfaces for your data models
• Database schemas derived from the design

The spec lives in .kiro/specs/[feature-name]/ and acts as a shared artifact between you and the AI for the entire feature development cycle.

The key insight: when you later ask Kiro to implement the feature, it reads the spec. The AI knows what success looks like before writing a line of code. This eliminates the most common failure mode of AI coding tools — confidently building the wrong thing.

Spec-driven development pairs naturally with steering files. The steering file tells Kiro how to build (conventions, stack, standards). The spec tells it what to build (requirements, design, interfaces). Together, they close the gap between what you intended and what gets implemented.

Hooks: Automate Your Workflow

Hooks are event-driven automations triggered by file system events: save, create, or delete. They let you attach AI-powered follow-up actions to your normal development flow.

A few practical hook configurations:

Auto-update tests when a component changes:

Trigger: file saved matching src/components/**/*.tsx
Action: Update the corresponding test file to reflect any changed props or behavior

Regenerate API docs when a route changes:

Trigger: file saved matching src/api/**/*.ts
Action: Update src/docs/api/ to reflect any changed endpoints or schemas

Lint check on save:

Trigger: any TypeScript file saved
Action: Run ESLint on the saved file and suggest fixes for any errors

Hooks run within Kiro’s agentic environment, so they can read other files, check existing tests, and propose contextual changes — not just run shell commands.

MCP Integration in Kiro

Kiro supports the Model Context Protocol (MCP) natively. You can connect MCP servers directly from Kiro’s settings, giving the AI access to external tools: database clients, API documentation, vector search, internal knowledge bases.

MCP configuration in Kiro follows the same JSON format used by Claude Code and other MCP-compatible tools:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost/mydb"
      }
    }
  }
}

Custom subagents extend this further. Kiro lets you define domain-specific agents — a security review agent, an API contract validator, a performance profiler — each with their own system prompt and tool access.

Kiro vs Cursor vs Claude Code: Quick Comparison

The most meaningful difference is not feature parity — it is philosophy. Cursor optimizes for fast iteration on existing code. Claude Code optimizes for terminal-based autonomous tasks. Kiro optimizes for the spec-to-implementation cycle: plan first, then build with full shared context.

Getting Started in 5 Minutes

1. Download Kiro from kiro.dev and sign in with your AWS account
2. Open your project — your existing VS Code settings and extensions load automatically
3. Create .kiro/steering/project.md with your core conventions (copy the example above as a starting point)
4. Start a new chat and describe a feature you want to build. When Kiro offers to create a spec, accept it
5. Review the generated user stories and design, adjust what does not fit, then ask Kiro to implement

The steering file you create in step 3 immediately improves every subsequent interaction. The AI now knows your stack, your naming conventions, and your testing approach before you type anything.

Frequently Asked Questions

What is the difference between Kiro steering files and CLAUDE.md?

Steering files and CLAUDE.md solve the same core problem: giving an AI coding tool persistent, project-specific context. The main differences are scope and activation control. Kiro steering files support four inclusion modes (always, fileMatch, manual, auto), letting you serve different rules to the AI depending on what is being worked on. CLAUDE.md is a single always-active file (though it supports @import for modular organization). Both formats are Markdown. If you want file-pattern-aware rule activation, steering files have a cleaner built-in system.

Does Kiro work with existing VS Code extensions?

Yes. Kiro is built on Code OSS (the open-source base of VS Code), so the vast majority of VS Code extensions work directly. Your theme, keybindings, and language extensions carry over without reconfiguration.

Can I use Kiro and Claude Code on the same project?

Yes, and they share context through AGENTS.md. Place an AGENTS.md in your project root with your universal conventions. Kiro reads it natively. Claude Code reads it natively. Both tools get the same baseline instructions. Use Kiro’s steering files for Kiro-specific configuration (spec preferences, hook definitions) on top of the shared AGENTS.md.

Are specs required in Kiro?

No. Kiro works as a standard AI coding IDE without ever using specs. You can write steering files and use the chat interface exactly like you would in Cursor. Specs are an optional layer for teams that want structured feature planning built into their AI workflow. Many developers use Kiro day-to-day without specs and only reach for them when starting a substantial new feature.

Is Kiro production-ready in 2026?

Kiro is in public preview as of July 2025 and has been in active use for approximately a year. The core features — steering files, MCP integration, the chat interface — are stable for daily development use. Specs and hooks are mature enough for serious projects. The main caveat is that pricing is not yet finalized for the post-preview period.