Kiro cheatsheet

A one-page reference for Kiro's spec-driven workflow. For the full walkthrough and worked EARS/design/tasks examples, see the complete guide.

📖 Full guide: Kiro →

The core loop

Idea → requirements.md → [review gate]
     → design.md → [review gate]
     → tasks.md → [review gate]
     → implementation

Spec first, code second — the agent never touches implementation files until a task list is approved.

.kiro/ layout

.kiro/
├── specs/<feature>/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
├── steering/{product,tech,structure}.md
├── hooks/*.json
└── settings/mcp.json

EARS acceptance criteria

WHEN <trigger> THE SYSTEM SHALL <response>
IF <precondition> THEN THE SYSTEM SHALL <response>
WHILE <state> THE SYSTEM SHALL <response>

Unambiguous and testable — unlike "handle errors gracefully," every criterion has a concrete trigger and observable response.

Tasks trace to requirements

- [x] 1. Add failed_attempts/locked_until columns
      _Requirements: 3, 4_
- [ ] 2. Implement lockout logic
      _Requirements: 3, 4_

Three-hop trace: requirement → task → commit/PR.

Steering (persistent context)

File	Purpose
product.md	what the product is, who it's for
tech.md	stack, versions, conventions
structure.md	repo layout, naming, boundaries

inclusion: always \| fileMatch \| manual controls when a steering file loads.

Agent hooks

{
  "trigger": { "type": "fileEdited", "pattern": "src/services/**/*.ts" },
  "action": { "type": "agentPrompt", "prompt": "Sync tests for this change." }
}

For deterministic housekeeping (test sync, doc refresh) — not a CI replacement; hooks can be skipped or missed.

MCP integration

{ "mcpServers": { "aws-docs": { "command": "uvx",
  "args": ["aws-documentation-mcp-server@latest"], "autoApprove": [] } } }

Scope autoApprove to read-only tools — never auto-approve write/delete capable ones.

Kiro vs. autocomplete tools

	Cursor/Copilot	Kiro
Intent	chat transcript, ephemeral	checked into git
Review	after code (diff)	before code + per-task
Traceability	none by default	requirement → task → PR

Common mistakes

• Skipping review gates (one uninterrupted pass to code)
• Vague EARS criteria with no concrete trigger/response
• Treating .kiro/specs/ as disposable, deleting after merge
• Letting steering docs drift out of date
• Over-scoping hooks to fire on every keystroke-adjacent save
• Broad MCP autoApprove on write/delete tools

When to skip specs

Small, self-contained changes — a one-line fix, quick prototype — don't need requirements/design overhead. Specs earn their cost on features with real acceptance criteria, multiple reviewers, or compliance needs.