Material didático · Kiro

Desenvolvimento com Spec no Kiro Crew

Tour pelo Spec First e Bugfix Spec (Kiro IDE, CLI e Kiro Web) e pelo papel do Crew — dashboard web no Gateway (localhost:5476 ou AWS) — com Steering, MCP, Skills e Task Runner.

Começar o tour Ver proposta de uso Ver a spike
  • Spec First
  • Bugfix Spec
  • Steering
  • MCP
  • Skills

01 · Contexto

O que é o Kiro Crew

O Kiro Crew é um agente de IA pessoal open-source, persistente e autoaprendente. Ele roda na sua máquina ou em hardware remoto (por exemplo, um servidor na AWS) e oferece três superfícies principais: app desktop, dashboard web e CLI — além de canais como Slack e Discord.

Gateway + chat

O Gateway é o servidor do Crew. Localmente, o dashboard abre em http://localhost:5476. Cada aba de chat é uma sessão com acesso a arquivos, comandos e ferramentas MCP.

Persistente 24/7

Sessões, memória, agendas e checkpoints sobrevivem a reinícios. Você pode deixar o Crew rodando como serviço, em Docker ou em host remoto.

Task Runner

No painel Projects, você descreve o objetivo, opcionalmente refina em uma spec markdown do Task Runner (conceito próprio do Crew) e executa: decompõe passos, testa, retenta falhas e salva progresso.

Duas peças, papéis distintos. O fluxo oficial de Feature Spec / Bugfix Spec (arquivos requirements.md / bugfix.md, design.md, tasks.md) roda no Kiro IDE, no CLI e no Kiro Web (app.kiro.dev). O Crew é o runtime persistente: dashboard no Gateway, agents, Steering/MCP/Skills e o Task Runner (spec markdown + execução longa). A proposta do time une as duas.

02 · Conceito

O que é uma Spec

Uma Spec (especificação) é um artefato estruturado que transforma uma ideia de alto nível em um plano de implementação rastreável — com accountability entre produto e engenharia.

Os três arquivos vivem em .kiro/specs/<nome>/

requirements.md

ou bugfix.md

User stories e critérios de aceite — ou análise do bug (atual / esperado / o que não muda).

design.md

Arquitetura

Arquitetura técnica, diagramas de sequência, modelos de dados, erros e estratégia de testes.

tasks.md

Plano executável

Tarefas discretas e rastreáveis, com dependências. Dá para rodar uma a uma ou todas (waves paralelas).

Notação EARS

Nos requisitos, o Kiro usa o formato EARS — claro, testável e fácil de virar caso de teste: 

WHEN [condição]
THE SYSTEM SHALL [comportamento]

03 · Feature Spec

Fluxo Spec First (Requirements-First)

Comece pelo o quê o sistema deve fazer; só depois gere o como. Ideal quando há user stories claras, arquitetura flexível ou projeto greenfield.

Criar Spec (Feature)

No IDE/CLI/Web, você cria uma Feature Spec e escolhe o fluxo Requirements-First. No Crew, o ângulo paralelo é abrir o Projects / chat, descrever o objetivo e refinar em uma spec antes de rodar.

requirements.md com EARS

O Kiro gera user stories, critérios de aceite, comportamentos em EARS (WHEN … THE SYSTEM SHALL …, casos de borda e tratamento de erro. 

WHEN um usuário envia dados válidos de cadastro
THE SYSTEM SHALL criar uma nova conta

Revisar / iterar (gate)

Você revisa a completude, itera nas stories e confirma só quando o “o quê” está certo. Esse gate evita desenhar arquitetura em cima de requisitos vagos.

design.md

Com requisitos confirmados, nasce o design: arquitetura, diagramas de sequência, modelos de dados, stack, tratamento de erros e estratégia de testes.

Gate de design

Valide se o design cobre os requisitos, se a stack faz sentido e se o plano é sustentável. Só então avance para as tarefas.

tasks.md — waves paralelas

Tarefas discretas, com dependências e marcação opcional/obrigatória. Ao rodar tudo, o Kiro monta um grafo: Wave 1 (sem deps) em paralelo, Wave 2 depois, e assim por diante.

Implementar · Task Runner · PR

Execute tarefas individualmente ou em lote. No Kiro Web, o agente implementa e abre um pull request. No Crew, o Task Runner decompõe, executa, testa, retenta falhas e salva checkpoints.

04 · Bug Fix Spec

Bugfix Spec

Mesmas três fases — análise, design, tasks — com conteúdo feito para corrigir com precisão e evitar regressão.

Feature

Spec First

  • requirements.md — o que construir
  • Design de arquitetura nova
  • Tasks para entregar a feature

Bugfix

Correção cirúrgica

  • bugfix.md — defeito, esperado, anti-regressão
  • Design com root cause
  • Tasks + validação (reproduz, corrige, não regressa)

1. bugfix.md

  • Comportamento atual (defeito) — WHEN … THEN o sistema [errado]
  • Comportamento esperado — WHEN … THEN o sistema SHALL [correto]
  • O que NÃO muda — WHEN … THEN o sistema SHALL CONTINUE TO [existente]

Documentar o que permanece é o coração da anti-regressão.

2. design.md com root cause

O Kiro explora o código, analisa a causa raiz e propõe o fix — com propriedades a testar: o bug existe, o fix funciona, o restante continua.

3. Tasks + validação

As tarefas incluem validação (incluindo property-based tests quando aplicável): reproduzir o bug, confirmar a correção e garantir que nada mais quebrou.

Use Bugfix Spec para bugs complexos, caminhos críticos, compliance ou histórico de regressão. Typo ou one-liner óbvio? Um quick fix no chat costuma bastar.

05 · Contexto persistente

Steering

Steering são arquivos markdown com regras que o agente herda de forma persistente — padrões, libs, commits, PRs e testes — sem você repetir em todo chat.

Pasta: .kiro/steering/ (workspace) · ~/.kiro/steering/ (global)

product.md

Propósito do produto, usuários, features-chave e objetivos de negócio.

tech.md

Frameworks, libs, ferramentas e restrições técnicas preferidas pelo time.

structure.md

Organização de pastas, naming, imports e decisões de arquitetura.

Você também pode criar arquivos custom (ex.: convenções de commit/PR). Em conflito, workspace vence global. No Crew: abra Agent Capabilities → Steering; toda sessão do workspace herda esses arquivos.

06 · Integrações

MCP

O Model Context Protocol liga o Kiro a servidores externos que oferecem tools, prompts e resources — APIs, docs, bancos, ferramentas do time.

No Crew: Integrations (MCP)

No dashboard, em Agent Capabilities → Integrations (MCP), você habilita, adiciona, remove e faz probe dos servidores. Built-ins incluem kirocrew-core e kirocrew-cron.

Exemplo didático

Um MCP do Azure DevOps pode ler User Stories e alimentar o início de um Spec First — trazendo o “o quê” direto do backlog para o Crew. A config de servidores MCP fica associada aos agents / mcpServers.

Tools MCP passam pelo mesmo pipeline de aprovação do Crew (prompt interativo ou Autopilot).

07 · Conhecimento sob demanda

Skills

Skills são arquivos markdown que ensinam workflows e expertise de domínio. Em geral carregam sob demanda (por triggers), mantendo o contexto enxuto. No Crew você gerencia em Agent Capabilities → Skills; lições aprendidas também moldam o comportamento ao longo do tempo.

Steering
Skill
Sempre (contexto persistente da sessão)
Sob demanda (quando o assunto bate nos triggers)
Padrões do projeto / time
Workflows específicos (ex.: prepare-pr)
.kiro/steering/
~/.kiro/crew/skills/ (Crew)

08 · Para o time

Proposta de uso

Um desenho simples para manter o Crew sempre ligado, puxar trabalho do Azure DevOps e entregar PRs alinhados às convenções do time.

Ver a spike Ver fluxo proposto
01

Crew 24/7 na AWS

Servidor na AWS rodando Kiro Crew continuamente (Gateway remoto). Dashboard acessível à equipe; sessões, cron e Task Runner seguem mesmo longe do notebook.

02

Custom agents + MCP ADO

Conjunto de agents (modelo/prompt/tools sob medida) com MCP do Azure DevOps para obter User Stories e alimentar o início do Spec.

03

Skill + Steering compartilhados

Convenções de desenvolvimento, testes, documentos, commits e PRs que todos seguem — Steering sempre ativo; Skills para workflows pontuais.

04

Fluxo resumido

US (ADO via MCP) → Spec First ou Bugfix (Kiro IDE/CLI/Web) → execução no Crew (Task Runner / agents) → PR alinhado às convenções