Kiro IDE Training Guide

Spec-Driven Development mit KI

Was ist Kiro?

Kiro ist eine KI-gestützte, agentische IDE von AWS für Spec-Driven Development. Sie kombiniert natürliche Sprache mit strukturierter Softwareentwicklung — vom Prototyp bis zur Produktion. Basierend auf Code OSS (VS Code-kompatibel).

📝 Spec-Driven Development

Strukturierte Spezifikationen: Requirements → Design → Tasks.

⚡ Vibe Mode

Konversationelles Coding für schnelle Prototypen.

🔌 Agent Hooks

Event-gesteuerte Automatisierungen im Hintergrund.

🎯 Steering & Skills

Persistentes Projektwissen und wiederverwendbare Workflows.

🚀 Powers

Dynamisch ladbare Tool-Bundles mit MCP und Best Practices.

🔗 MCP Server

Model Context Protocol für externe Tools und Wissensquellen.

Session-Typen & Modi

Vibe Sessions: Konversationelles Q&A, exploratives Coding, schnelle Prototypen.

Spec Sessions: Strukturiert: Requirements → Design → Tasks. Für produktionsreife Features.

Autopilot: Kiro arbeitet autonom. Änderungen jederzeit einsehbar und rückgängig machbar.

Supervised: Kiro pausiert nach jeder Änderung zur Genehmigung.

Specs (Spezifikationen)

Specs transformieren eine Idee in einen detaillierten Implementierungsplan. Drei Dateien bilden die Grundlage.

Drei-Phasen-Workflow

  1. requirements.md — User Stories mit Akzeptanzkriterien (EARS-Notation)
  2. design.md — Technische Architektur, Sequenzdiagramme, Interfaces
  3. tasks.md — Diskrete, nachverfolgbare Tasks mit Abhängigkeiten

Spec-Typen

Feature Spec

Für neue Features. Varianten: Requirements-First, Design-First, Quick Plan.

Bugfix Spec

Systematische Fehlerbehebung. Nutzt bugfix.md (statt requirements.md) für die Bug-Analyse, dann design.md und tasks.md.

Beispiel

Prompt: "Add a review system for products" — Kiro generiert:

  • User Stories (Anzeigen, Erstellen, Filtern, Bewerten)
  • EARS-Akzeptanzkriterien mit Edge Cases
  • Design mit TypeScript Interfaces und Mermaid-Diagrammen
  • Sequenzierte Tasks inkl. Unit-Tests und Accessibility

Parallele Task-Ausführung

"Run all Tasks" analysiert Abhängigkeiten und führt unabhängige Tasks in Wellen parallel aus (Wave 1 → Wave 2 → Wave N).

.kiro/specs/feature-name/
├── requirements.md
├── design.md
└── tasks.md

Agent Hooks

Hooks sind "Wenn-Dann"-Regeln: Ein Workspace-Event löst eine KI-Aktion aus.

Trigger-Typen

Trigger werden in der JSON-Konfiguration in PascalCase angegeben. Verfügbarkeit variiert zwischen IDE, CLI und Web.

TriggerBeschreibungVerfügbar
PromptSubmitChat-Nachricht gesendet (kann blockieren)IDE, CLI
StopAgent hat Antwort abgeschlossenIDE, CLI
SessionStartNeue Session gestartetIDE
PreToolUseVor Tool-Ausführung (kann blockieren)IDE, CLI
PostToolUseNach Tool-AusführungIDE, CLI
PostFileCreateAgent erstellt DateiIDE
PostFileSaveAgent speichert DateiIDE
PostFileDeleteAgent löscht DateiIDE
PreTaskExecutionVor Spec-Task (kann blockieren)IDE
PostTaskExecutionNach Spec-TaskIDE
agentSpawnSub-Agent gestartetCLI

Wichtig: Die File-Trigger reagieren nur auf Änderungen durch den Agenten, nicht auf manuelle Editor-Bearbeitungen.

Aktionen

  • agent — Prompt in die Konversation injizieren (Feld prompt). Verbraucht Credits.
  • command — Shell-Befehl im Projekt-Root (Feld command). Event-Daten via STDIN, Exit-Code steuert Verhalten (0 = OK, 2 = blockieren). Verbraucht keine Credits.

Weitere Felder

  • matcher — Regex. Bei Tool-Events gegen Tool-Namen, bei File-Events gegen Pfad
  • Tool-Kategorien: read, write, shell, web, spec, *
  • Präfixe: @mcp, @powers, @builtin
  • timeout (Command-Actions, Default 60s), enabled, confirm (nur Stop-Trigger)

Beispiel: Lint on Save

// .kiro/hooks/lint-on-save.json
{
  "version": "v1",
  "hooks": [{
    "name": "Lint on Save",
    "trigger": "PostFileSave",
    "matcher": "\\.(ts|tsx)$",
    "action": { "type": "command", "command": "npm run lint" }
  }]
}

Beispiel: Test-Update per Agent

{
  "version": "v1",
  "hooks": [{
    "name": "TypeScript Test Updater",
    "trigger": "PostFileSave",
    "matcher": "src/.*\\.ts$",
    "action": {
      "type": "agent",
      "prompt": "Analysiere die Änderungen und aktualisiere die zugehörige Testdatei."
    }
  }]
}

Speicherort: .kiro/hooks/<name>.json (Schema-Version v1) — teilbar via Git mit dem gesamten Team.

Agent Steering

Steering gibt Kiro persistentes Wissen über den Workspace durch Markdown-Dateien. Konventionen müssen nicht in jedem Chat wiederholt werden.

Scopes

ScopePfadBeschreibung
Workspace.kiro/steering/Nur dieses Projekt
Global~/.kiro/steering/Alle Workspaces
Team~/.kiro/steering/Via MDM/Group Policy verteilt

Inclusion-Modi

always

---
inclusion: always
---

Immer geladen. Für Kern-Standards.

fileMatch

---
inclusion: fileMatch
fileMatchPattern: "**/*.tsx"
---

Nur bei passenden Dateien.

manual

---
inclusion: manual
---

Via #name oder /slash-command.

auto

---
inclusion: auto
name: api-design
description: REST API patterns
---

Automatisch bei passendem Request.

Foundation Files (auto-generiert)

  • product.md — Produktzweck, Zielgruppe, Features
  • tech.md — Frameworks, Libraries, Constraints
  • structure.md — Dateiorganisation, Naming, Architektur

Beispiel: API-Standards

---
inclusion: fileMatch
fileMatchPattern: ["**/api/**/*.ts", "**/routes/**/*.ts"]
---

# REST API Standards
- Use kebab-case: /user-profiles
- Use plural nouns: /users
- Error format: { "error": { "code": "...", "message": "..." } }
- All endpoints require Bearer token

Kiro unterstützt auch AGENTS.md (offener Standard) — immer inkludiert, im Workspace-Root oder ~/.kiro/steering/.

Hinweis: In der CLI werden Inclusion-Modi nicht unterstützt — dort werden alle Steering-Dateien automatisch geladen. Custom Agents laden Steering nicht automatisch; es muss im resources-Feld angegeben werden.

Agent Skills

Skills sind portable Instruktionspakete nach dem offenen Agent Skills Standard. Sie bündeln Anweisungen, Skripte und Templates.

Progressive Disclosure

  1. Discovery: Nur Name + Beschreibung geladen
  2. Activation: Bei passender Anfrage: volle Anweisungen
  3. Execution: Skripte/Referenzen bei Bedarf nachgeladen

Struktur & Beispiel

my-skill/
├── SKILL.md           # Pflicht
├── scripts/           # Optional
├── references/        # Optional
└── assets/            # Optional
---
name: pr-review
description: Review pull requests for code quality and security.
---

## Review Process
1. Check for security vulnerabilities
2. Verify error handling
3. Confirm test coverage
4. Review naming and structure

Scopes & Aktivierung

ScopePfad
Workspace.kiro/skills/
Global~/.kiro/skills/
  • Automatisch: Kiro erkennt passende Anfragen
  • Manuell: /skill-name als Slash-Command
  • Import: Von GitHub-URL oder lokalem Ordner

Powers

Powers geben dem KI-Agent sofortigen Zugang zu spezialisiertem Wissen. Sie bündeln MCP-Tools, Workflows und Best Practices — dynamisch geladen per Keyword-Matching.

Wie Powers funktionieren

  1. Kiro liest die Aufgabenbeschreibung
  2. Evaluiert installierte Powers anhand von Keywords
  3. Lädt nur relevante Powers in den Kontext
  4. Deaktiviert automatisch bei Themenwechsel

Inhalt & Struktur

Powers folgen der offenen Agent-Plugins-Spezifikation. Ältere Powers im POWER.md-Format funktionieren weiterhin.

my-power/
├── plugin.json     # Pflicht-Manifest (Keywords zur Aktivierung)
├── skills/         # Agent Skills
│   └── setup/SKILL.md
├── mcp.json        # MCP-Server-Config (optional)
└── dev.kiro/       # Kiro-Erweiterungen wie Steering (optional)

Installation

  • One-Click-Install aus dem Marketplace (kiro.dev/powers)
  • Direkt von GitHub-URLs
  • Verfügbar: IDE, CLI (ab v3), Web. Erstellen: nur IDE und CLI v3

Verfügbare Partner-Powers

Datadog, Dynatrace, Figma, Neon, Netlify, Postman, Supabase, Stripe, Strands SDK und AWS Aurora.

Die Agent-Plugins-Spezifikation wird von Maintainern bei Amazon, Cursor, Microsoft, OpenAI und Vercel getragen.

Vergleich: Skills vs. Powers vs. Steering

EigenschaftSkillsPowersSteering
ZweckWiederverwendbare WorkflowsTool-Integrationen + WissenProjekt-Konventionen
FormatSKILL.md + scripts/plugin.json + skills/ + mcp.jsonMarkdown-Dateien
AktivierungAuto oder /slashDynamisch per Keywordalways / fileMatch / manual / auto
MCP-ToolsNeinJa (dynamisch)Nein
PortabilitätOffener StandardKiro-spezifischKiro-spezifisch
Ideal fürTeam-WorkflowsExterne ServicesPersistente Regeln

Faustregel: MCP-Integration? → Power. Portable Workflows? → Skill. Persistente Regeln? → Steering.

💡 Pro-Tipps vom Kiro-Team

Offizielle Best Practices aus der Kiro-Dokumentation und AWS-Blogs für maximale Produktivität.

Specs: Effektiv arbeiten

  • Vibe → Spec: Im Chat einfach Generate spec sagen — Kiro übernimmt den bisherigen Kontext
  • #spec referenzieren: #spec:feature-name im Chat nutzen um eine Spec als Kontext einzubinden
  • Mehrere kleine Specs: Pro Feature eine eigene Spec statt einer riesigen für die ganze Codebase
  • Sync Files: In tasks.md klicken wenn Aufgaben bereits erledigt sind — Kiro markiert sie automatisch
  • Quick Plan für bekannte Features (schnell, ohne Approval-Gates). Standard-Specs für unbekanntes Terrain.
  • Analyze Requirements: Nach Auto-Generierung nutzen — findet Widersprüche, Mehrdeutigkeiten und Lücken
  • Import aus JIRA/Confluence: Datei ins Repo kopieren, dann #datei.md Generate a spec from it

Steering: Maximale Wirkung

  • 1 Thema pro Datei: api-standards.md, testing-patterns.md — nicht alles in eine Datei
  • fileMatch statt always: Spart Kontext-Platz. Nur laden wenn relevant.
  • Konkrete Beispiele: Code-Snippets und Before/After-Vergleiche statt vager Beschreibungen
  • Foundation Files generieren: Kiro Panel → Steering → "Generate Steering Docs" für product.md, tech.md, structure.md
  • Erkläre das Warum: Nicht nur "Use kebab-case" sondern auch warum (Konsistenz mit API-Gateway)
  • File-Referenzen: #[[file:api/openapi.yaml]] um live Workspace-Dateien zu verlinken

Hooks: Sicher automatisieren

  • Exclusion-Patterns: Immer generierte Dateien ausschließen: !**/*.test.ts, !**/node_modules/**
  • Per Git teilen: Hooks in .kiro/hooks/ committen — das ganze Team profitiert sofort
  • userTriggered für Riskantes: Security-Scans, Deployments, DB-Migrationen manuell auslösen
  • Deskriptive Prompts: Je mehr Kontext im Hook-Prompt, desto besser das Ergebnis
  • Einzeln testen: Hooks nacheinander aktivieren, nicht alle auf einmal

Modelle: Credits sparen

  • Auto für den Alltag: Kiros Model-Router, bestes Preis-Leistungs-Verhältnis (1.0x Baseline)
  • Opus für Schweres: Multi-File-Architektur, lange Sessions, komplexe Bugs (2.2x Credits)
  • Qwen3 Coder Next: Nur 0.05x Credits! Ideal für einfache Tasks und lange Coding-Sessions
  • Haiku für Speed: Schnelles Modell, 0.4x Credits, gut für schnelle Iterationen
  • Credit-Verbrauch tracken: Account Settings → Usage Dashboard regelmäßig prüfen

Allgemeine Workflow-Tipps

  • Häufig committen: Vor und nach Agent-Aktionen — einfaches Rollback bei Fehlern
  • Supervised Mode: Für Security-Code, Prod-Config, Infrastruktur-Änderungen
  • Neuer Chat bei neuem Thema: Frischer Kontext = bessere Ergebnisse
  • Kontext-Provider nutzen: #File, #Folder, #Problems, #Terminal, #Git Diff
  • Bilder nutzen: Architektur-Diagramme, Whiteboard-Fotos, Screenshots per Drag&Drop in den Chat
  • MCP für aktuelle Doku: AWS Docs MCP statt veraltetes Modell-Wissen
  • Powers statt rohe MCP: Powers laden Tools dynamisch — spart 40%+ Kontext-Tokens

MCP Server (Model Context Protocol)

MCP ermöglicht Kiro die Kommunikation mit externen Servern für spezialisierte Tools, Prompts und Ressourcen.

Konfiguration

EbenePfad
Benutzer (Global)~/.kiro/settings/mcp.json
Workspace.kiro/settings/mcp.json

Beispiel

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "disabled": false,
      "autoApprove": []
    },
    "supabase-local": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_ANON_KEY": "${SUPABASE_ANON_KEY}"
      }
    }
  }
}

Beliebte MCP-Server

ServerFunktion
AWS DocumentationAWS-Docs durchsuchen/lesen
AWS MCP ServerAuthentifizierter AWS-Zugriff
SupabaseDB-Operationen, RLS
StripePayment-Integration
MemoryPersistenter Speicher
SonarQubeCode-Qualität

MCP allein lädt alle Tools beim Start (hoher Token-Verbrauch). MCP in einem Power lädt Tools dynamisch — effizienter.

Kiro als IDE

Basierend auf Code OSS. VS Code-Einstellungen und Open VSX-Extensions funktionieren.

Ein einheitlicher Agent Harness, angesprochen über mehrere Surfaces:

💻 IDE (Desktop)

Mac, Windows, Linux. Läuft lokal.

⌨️ CLI

Terminal, headless, CI/CD, Custom Agents.

🌐 Web

app.kiro.dev. Cloud-Sandbox, liefert Änderungen als Pull Requests.

📱 Mobile

iOS (Preview via TestFlight). Greift Cloud-Sessions auf.

Kiro Crew: Orchestrierung von Agent-Teams. Zusätzlich lassen sich ACP-kompatible Editoren (JetBrains, Zed) via Agent Client Protocol anbinden.

Kiro Panel

  • Specs — Erstellen und Verwalten
  • Agent Hooks — Erstellen, aktivieren, deaktivieren
  • Steering & Skills — Verwalten
  • MCP Servers — Status und Konfiguration
  • Powers — Installierte Powers

Kontext im Chat

  • #File / #Folder — Datei/Ordner referenzieren
  • #Problems — Aktuelle Fehler/Warnungen
  • #Terminal — Terminal-Output
  • #Git Diff — Aktuelle Änderungen
  • Bilder, PDFs, DOCX per Drag&Drop

Projektstruktur

my-project/
├── .kiro/
│   ├── settings/mcp.json
│   ├── steering/
│   │   ├── product.md
│   │   ├── tech.md
│   │   └── structure.md
│   ├── hooks/
│   │   └── test-sync.json
│   ├── skills/
│   │   └── pr-review/SKILL.md
│   └── specs/
│       └── feature-reviews/
│           ├── requirements.md
│           ├── design.md
│           └── tasks.md
└── src/

⚠️ Bekannte Probleme & Limitierungen

Kiro ist leistungsfähig, hat aber Grenzen. Hier die häufigsten Probleme aus der Community und offizielle Troubleshooting-Hinweise.

Steering: Warum es manchmal nicht funktioniert

Häufige Ursachen:

  • Context-Window-Limit: Bei langen Konversationen fällt Steering aus dem Kontext. Der Agent "vergisst" Regeln.
  • Zu viele always-Dateien: Konkurrieren um Kontext-Platz und verdrängen sich gegenseitig.
  • Widersprüchliche Anweisungen: Global vs. Workspace — Workspace gewinnt, aber der Agent kann verwirrt werden.
  • Vage Formulierungen: "Schreibe guten Code" ist zu unspezifisch. Konkrete Regeln nötig.
  • fileMatch-Pattern falsch: Glob passt nicht zur Datei → Steering wird nie geladen.
  • Frontmatter-Fehler: Fehlende --- oder YAML-Syntaxfehler = Datei ignoriert.

Workarounds:

  • Steering-Dateien kurz halten (1 Thema pro Datei)
  • fileMatch statt always wo möglich
  • Konkrete Code-Beispiele einbauen
  • Bei langen Sessions: neuen Chat starten
  • Frontmatter mit YAML-Validator prüfen

Rate Limiting & Usage Limits

Problem: "Too many requests" oder "Please return tomorrow to continue building" Meldungen.

  • Einheitlicher Credit-Pool: Vibe und Spec ziehen aus demselben Pool
  • Auto (empfohlen): Kiros Model-Router, 1.0x Baseline
  • Günstig: Qwen3 Coder Next (0.05x), MiniMax M2.1 (0.15x), DeepSeek 3.2 & MiniMax M2.5 (0.25x), Haiku 4.5 (0.4x)
  • Premium: Claude Opus (4.5 bis 5, jeweils 2.2x), Claude Sonnet (4.0 bis 5, 1.3x)
  • Weitere: GPT-5.6 (Luna 0.1x / Terra 1.0x / Sol 2.4x), GLM-5 (0.5x)
  • Multiplikatoren relativ zu Auto. Modell-Katalog ändert sich häufig — aktuelle Werte in der Kiro-Doku prüfen.

Workaround: Credits-Verbrauch im Account-Dashboard tracken. Einfache Fragen im Vibe-Mode stellen (günstiger). Specs für komplexe Features reservieren.

Shell-Integration & Terminal

Problem: Kiro bleibt bei "Working..." hängen, sieht Terminal-Output nicht, oder zeigt seltsame Zeichen.

  • Shell-Customizations (Oh My Posh, Powerlevel10k) interferieren
  • Shell-Integration nicht korrekt installiert
  • Fish-Shell braucht manuellen Patch

Workarounds:

  • Command Palette → "Kiro: Enable Shell Integration"
  • Powerlevel10k: POWERLEVEL9K_TERM_SHELL_INTEGRATION=true in .p10k.zsh
  • Shell-Themes in Kiro deaktivieren (TERM_PROGRAM Check)
  • Manuelle Integration in ~/.zshrc oder ~/.bashrc

Prompt Injection & Sicherheit

AWS Security Bulletin (AWS-2025-019): Prompt-Injection-Schwachstellen in Kiro und Q Developer Plugins. Unsichtbare Steuerzeichen in Dateien können Befehle verschleiern, die ohne Bestätigung ausgeführt werden.

  • Betrifft: Offene Chat-Sessions + Zugriff auf bösartige Dateien
  • Befehle wie find, grep, echo können ohne HITL-Bestätigung laufen

Workaround: Kiro immer aktuell halten (Patches verfügbar). Supervised Mode bei unbekannten Repositories. Keine Dateien aus unvertrauenswürdigen Quellen öffnen.

Plattform-spezifische Probleme

  • macOS: "Kiro is damaged" Meldung → sudo xattr -d com.apple.quarantine /Applications/Kiro.app
  • Windows: "Updates disabled" wenn als Admin installiert → Admin-Checkbox in Properties deaktivieren
  • Windows OneDrive: Desktop-Pfad-Konflikte → Symbolic Link erstellen
  • WSL: Remote SSH und WSL-Verbindungen teilweise instabil
  • PowerShell: Script-Ausführung blockiert → Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Context-Window & Kontext-Verlust

  • Kontext wird automatisch komprimiert bei Limit → Details gehen verloren
  • Große Dateien werden nur teilweise gelesen
  • Frühere Anweisungen können "vergessen" werden

Workaround: Komplexe Aufgaben aufteilen, Specs nutzen, relevante Dateien mit #File referenzieren, neuen Chat für neue Aufgaben.

Datei-Schreibprobleme

  • Sehr große Dateien (>500 Zeilen) werden in Teilen geschrieben (write + append)
  • Windows-Pfade können Probleme verursachen
  • Im Editor erscheinen mehrere "Editing"-Einträge für dieselbe Datei

Workaround: Große Dateien aufteilen, bei Fehlern löschen und neu generieren, Supervised Mode nutzen.

Hooks: Unerwartetes Verhalten

  • Endlosschleifen: Hook ändert Datei → triggert anderen Hook → Endlosschleife
  • Zu breite Patterns: **/* fängt auch generierte Dateien ab

Workaround: Exclusion-Patterns (!**/*.test.ts), Hooks einzeln testen, userTriggered für riskante Aktionen.

MCP-Server: Verbindungsprobleme

  • uvx oder npx nicht installiert oder nicht im PATH
  • Fehlende/ungültige Umgebungsvariablen (API-Keys)
  • JSON-Syntaxfehler in mcp.json
  • GitHub MCP: Rate-Limiting bei zu vielen API-Calls
  • Server-Timeout bei langsamer Verbindung

Workaround: Logs prüfen (Output → "Kiro - MCP Logs"). Server manuell reconnecten. mcp.json validieren. uvx --version testen.

Allgemeine Agent-Limitierungen

  • Halluzinationen: Agent kann Code-Patterns erfinden. Immer Output prüfen.
  • Veraltetes Wissen: Ohne MCP kennt der Agent evtl. nicht die neueste API.
  • Nicht-Determinismus: Gleicher Prompt kann unterschiedliche Ergebnisse liefern.
  • Extensions: Nur Open VSX, nicht VS Code Marketplace.
  • IAM Identity Center: Sessions laufen nach 8h ab, erneute Authentifizierung nötig.

Best Practices:

  • Supervised Mode für kritische Änderungen
  • Specs für komplexe Features statt langer Chats
  • Häufige Git-Commits für einfaches Rollback
  • Agent-Output immer reviewen (besonders Security)
  • MCP-Server für aktuelle Dokumentation nutzen
  • Kiro regelmäßig updaten (Security-Patches)

Quellen: