Comparando Ambientes de Desenvolvimento Orientado a Especificações (SDD): SpecKit vs Kiro

Introdução

Este artigo compara duas abordagens representativas para implementar o "Desenvolvimento Orientado a Especificações (SDD)", uma metodologia que ganhou atenção significativa recentemente.

• VSCode + GitHub Copilot + SpecKit: Adicionando um toolkit SDD ao editor existente
• Kiro IDE: Um IDE all-in-one com recursos SDD integrados

O Que é Desenvolvimento Orientado a Especificações (SDD)?

No desenvolvimento tradicional, o código é central e as especificações são complementares. O SDD inverte isso tratando as especificações como entregáveis executáveis.

Principais Benefícios do SDD

• Clarificação e documentação de requisitos
• Instruções precisas para agentes de IA
• Redução de desalinhamento entre equipes
• Suporte a processos de melhoria iterativa

Ambiente 1: VSCode + GitHub Copilot + SpecKit

Visão Geral

O SpecKit é um toolkit open-source para implementar SDD em ambientes de desenvolvimento existentes. Fornecido pelo GitHub, permite interação com agentes de IA por meio de slash commands.

Configuração

# Instalar o Specify CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Inicializar um novo projeto
specify init my-project --ai copilot

# Ou em um projeto existente
specify init . --ai copilot

Fluxo de Desenvolvimento

1. Estabelecer a Constituição do Projeto

/speckit.constitution Create principles focused on code quality, 
testing standards, user experience consistency, and performance requirements

Este comando gera .specify/memory/constitution.md, definindo as diretrizes de todo o projeto.

2. Criar Especificações

/speckit.specify Build an application that can help me organize my photos 
in separate photo albums. Albums are grouped by date and can be re-organized 
by dragging and dropping on the main page.

Arquivos gerados:

• .specify/specs/001-feature-name/spec.md: Requisitos e user stories da funcionalidade

3. Criar Plano de Implementação Técnica

/speckit.plan The application uses Vite with minimal number of libraries. 
Use vanilla HTML, CSS, and JavaScript as much as possible.

Arquivos gerados:

• plan.md: Arquitetura técnica
• data-model.md: Definição do modelo de dados
• contracts/api-spec.json: Especificações da API
• research.md: Documentação de pesquisa técnica

4. Decomposição de Tarefas

/speckit.tasks

Arquivos gerados:

• tasks.md: Lista de tarefas de implementação (com marcadores de dependências e execução paralela)

5. Executar Implementação

/speckit.implement

A implementação prossegue sequencialmente com base na lista de tarefas.

Detalhes dos Arquivos de Prompt do SpecKit

O SpecKit gera múltiplos arquivos de prompt no diretório .github/prompts/.

speckit.constitution.prompt.md

Propósito: Definir princípios fundamentais e diretrizes de desenvolvimento para o projeto

Estrutura:

---
description: Create or update project governing principles
---

# Project Constitution

Create a comprehensive constitution document that includes:

1. **Code Quality Standards**
   - Naming conventions
   - Documentation requirements
   - Code review processes

2. **Testing Standards**
   - Unit test coverage requirements
   - Integration test strategies
   - Test documentation

3. **Architecture Principles**
   - Design patterns to follow
   - Technology stack constraints
   - Performance requirements

4. **User Experience Guidelines**
   - Accessibility standards
   - Responsive design requirements
   - Internationalization considerations

Funcionalidades:

• Agentes de IA referenciam este documento em todas as fases subsequentes
• Impõe melhores práticas específicas do projeto
• Garante consistência entre equipes

speckit.specify.prompt.md

Propósito: Estruturar requisitos de funcionalidades no formato de user story

Estrutura:

---
description: Define requirements and user stories
---

# Specification Template

## User Stories

**As a** [user type]
**I want** [goal]
**So that** [benefit]

### Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Functional Requirements

### FR-001: [Requirement Name]
**Priority**: High/Medium/Low
**Description**: Detailed requirement description
**Dependencies**: [Other requirements]

Processo de Geração:

1. Analisar a descrição em linguagem natural do usuário
2. Converter para user stories
3. Clarificar critérios de aceitação
4. Atribuir IDs de requisitos funcionais

speckit.plan.prompt.md

Propósito: Detalhar planos de implementação técnica

Estrutura:

---
description: Create technical implementation plans
---

# Implementation Plan

## Technology Stack
- Frontend: [Framework/Library]
- Backend: [Framework]
- Database: [Type]
- Deployment: [Platform]

## Architecture Overview
[Diagramas de arquitetura do sistema, diagramas de componentes]

## Data Model
[Diagramas de entidade-relacionamento, definições de tabelas]

## API Specifications
[Definições de endpoints, formatos de requisição/resposta]

## Implementation Phases
1. Phase 1: [Core features]
2. Phase 2: [Advanced features]

## Technical Considerations
- Security requirements
- Performance optimization
- Scalability concerns

Funcionalidades:

• Adere aos princípios de constitution.md
• Resolve tecnicamente os requisitos de spec.md
• Compara múltiplas escolhas de tecnologia

speckit.tasks.prompt.md

Propósito: Decompor em tarefas concretas e implementáveis

Estrutura:

---
description: Generate actionable task lists
---

# Task Breakdown

## User Story: [Story ID]

### Task 1: [Task Name]
**File**: `src/components/Feature.tsx`
**Type**: Implementation
**Dependencies**: None
**Parallel**: [P] (if parallelizable)
**Description**: Detailed task description
**Acceptance**: How to verify completion

### Task 2: [Task Name]
**File**: `tests/Feature.test.tsx`
**Type**: Testing
**Dependencies**: Task 1

Regras de Geração:

• Gerenciar dependências explicitamente
• Especificar caminhos de arquivos concretamente
• Considerar a ordem do Test-Driven Development (TDD)
• Marcar tarefas que podem ser executadas em paralelo

speckit.implement.prompt.md

Propósito: Executar a implementação com base na lista de tarefas

Fluxo de Execução:

---
description: Execute implementation plan
---

# Implementation Execution

1. **Validate Prerequisites**
   - Constitution exists
   - Spec is complete
   - Plan is approved
   - Tasks are defined

2. **Parse Tasks**
   - Read tasks.md
   - Build dependency graph
   - Identify parallel tasks

3. **Execute Tasks**
   For each task in order:
   - Create/modify specified files
   - Run tests (if TDD)
   - Validate against acceptance criteria
   - Update task status

4. **Progress Reporting**
   - Mark tasks as In Progress/Done
   - Report errors with context
   - Suggest next steps

speckit.clarify.prompt.md

Propósito: Clarificar partes ambíguas da especificação por meio de perguntas

Estrutura:

---
description: Clarify underspecified areas
---

# Clarification Questions

## Coverage Analysis
[Identificar áreas não cobertas na especificação]

## Sequential Questions
1. **Question**: [Specific question]
   **Context**: [Why this is important]
   **Options**: [Possible answers]

[Answers are added to Clarifications section when recorded]

Funcionalidades:

• Recomendado executar antes da criação do Plan
• Elicitar respostas por meio de perguntas estruturadas
• As respostas são integradas na especificação

Exemplo de Documentos Gerados

Em um projeto real, a estrutura de diretórios fica assim:

my-project/
├── .specify/
│   ├── memory/
│   │   └── constitution.md          # Princípios do projeto
│   ├── specs/
│   │   └── 001-photo-albums/
│   │       ├── spec.md               # Especificações de funcionalidades
│   │       ├── plan.md               # Plano de implementação
│   │       ├── tasks.md              # Lista de tarefas
│   │       ├── data-model.md         # Modelo de dados
│   │       ├── contracts/
│   │       │   └── api-spec.json    # Especificações da API
│   │       └── research.md           # Pesquisa técnica
│   ├── scripts/
│   │   ├── create-new-feature.sh
│   │   └── setup-plan.sh
│   └── templates/
│       ├── spec-template.md
│       ├── plan-template.md
│       └── tasks-template.md
├── .github/
│   └── prompts/
│       ├── speckit.constitution.prompt.md
│       ├── speckit.specify.prompt.md
│       ├── speckit.plan.prompt.md
│       ├── speckit.tasks.prompt.md
│       ├── speckit.implement.prompt.md
│       ├── speckit.clarify.prompt.md
│       └── speckit.analyze.prompt.md
└── src/
    └── [Arquivos de implementação]

Vantagens

✅ Open Source: Gratuito para uso sob licença MIT
✅ Flexibilidade: Suporta múltiplos agentes de IA (Claude, Gemini, Copilot, etc.)
✅ Adoção Gradual: Pode adotar incrementalmente começando pelos recursos necessários

Desvantagens

❌ Configuração Manual: A configuração inicial requer múltiplas etapas
❌ Complexidade de Integração: Necessário combinar múltiplas ferramentas
❌ Experiência de UI: Centrado em linha de comando com feedback visual limitado
❌ Curva de Aprendizado: Necessário entender o papel e a ordem de cada comando

Ambiente 2: Kiro IDE

Visão Geral

O Kiro é um IDE Agentic com suporte desde protótipo até produção, com recursos SDD nativamente integrados.

Configuração

1. Baixe o IDE em kiro.dev
2. Instale e inicie
3. Pode importar automaticamente configurações e plugins do VS Code

Fluxo de Desenvolvimento

1. Gerar Steering Docs

Selecione "Generate Steering Docs" no painel Kiro para gerar o seguinte em .kiro/steering/:

• Informações sobre a stack tecnológica do projeto
• Convenções de codificação
• Diretrizes de fluxo de trabalho

2. Três Fases da Criação de Spec

Fase de Requisitos

Descreva user stories e critérios de aceitação no formato EARS (Easy Approach to Requirements Syntax):

WHEN [condition/event]
THE SYSTEM SHALL [expected behavior]

Arquivo gerado: .kiro/specs/feature-name/requirements.md

Fase de Design

Documente arquitetura técnica e diagramas de sequência:

Arquivo gerado: .kiro/specs/feature-name/design.md

Fase de Tarefas

Plano detalhado para tarefas de implementação:

Arquivo gerado: .kiro/specs/feature-name/tasks.md

3. Automação com Hooks

Automação orientada a eventos que executa tarefas automaticamente em resposta a mudanças de arquivos:

Exemplo: "Ao salvar um componente React, gerar automaticamente arquivos de teste"

{
  "hooks": [
    {
      "trigger": "onFileSave",
      "pattern": "**/*.tsx",
      "action": "generateTests"
    }
  ]
}

Estrutura de Documentos do Kiro

my-project/
├── .kiro/
│   ├── steering/
│   │   ├── tech-stack.md
│   │   ├── coding-standards.md
│   │   └── workflows.md
│   └── specs/
│       └── photo-albums/
│           ├── requirements.md    # Requisitos no formato EARS
│           ├── design.md          # Design de arquitetura
│           └── tasks.md           # Tarefas de implementação
└── src/
    └── [Arquivos de implementação]

Vantagens

✅ Experiência Integrada: Todos os recursos nativamente integrados no IDE
✅ UI Visual: Gerenciamento visual das listas de spec e status de tarefas
✅ Automação: Execução de tarefas em background com Hooks

Desvantagens

❌ IDE Dedicado Necessário: Necessário migrar dos editores existentes
❌ Vendor Lock-in: Dependência dos recursos específicos do Kiro

Tabela de Comparação Detalhada

Comparação de Documentos Gerados

Constitution/Steering

SpecKit:

• .specify/memory/constitution.md: Arquivo único
• Descreve princípios gerais do projeto
• Referenciado por todos os comandos

Kiro:

• .kiro/steering/: Múltiplos arquivos
• Separa stack tecnológica, convenções de codificação, fluxos de trabalho
• Auto-gerado + customizável

Especificação

SpecKit:

# spec.md

## User Stories
As a user, I want to...

## Functional Requirements
FR-001: Feature description

## Review Checklist
- [ ] Requirements are clear
- [ ] Acceptance criteria defined

Kiro:

# requirements.md (EARS format)

WHEN user clicks upload button
THE SYSTEM SHALL display file selection dialog

WHEN file size exceeds 10MB
THE SYSTEM SHALL display error message

Plano de Implementação

SpecKit:

# plan.md

## Architecture
- Frontend: React
- Backend: Node.js

## Implementation Details
[Guia detalhado de implementação]

# data-model.md
[Esquema do banco de dados]

# contracts/api-spec.json
{Especificação OpenAPI}

Kiro:

# design.md

## Component Architecture
[Diagrama de arquitetura do sistema]

## Sequence Diagrams
[Diagramas de fluxo]

## Technical Considerations
[Performance, segurança, etc.]

Tarefas

SpecKit:

# tasks.md

## User Story: US-001

### Task 1: Setup database schema
File: src/db/schema.sql
Dependencies: None
[P] Parallel: Yes

### Task 2: Create API endpoint
File: src/api/upload.ts
Dependencies: Task 1

Kiro:

# tasks.md

## Phase 1: Core Implementation

- [ ] Task 1: Database setup
  Status: Not Started
  Assignee: [Auto]
  
- [ ] Task 2: API development
  Status: Not Started
  Dependencies: Task 1

Diretrizes de Uso

Quando Escolher SpecKit

1. Quer manter o ambiente VSCode existente

   • Use plugins e configurações extensos existentes
   • Evite custos de migração de editor

2. Toda a equipe é nova no SDD

   • Aprenda gradualmente com abordagem baseada em comandos
   • Fácil de compartilhar documentos via Git

3. Quer experimentar múltiplos agentes de IA

   • Alterne entre Claude, Gemini, Copilot, etc.
   • Evite vendor lock-in

4. Prioridade open source

   • Desenvolvimento orientado pela comunidade
   • Liberdade para customizar

Quando Escolher o Kiro

1. Maximizar produtividade

   • Trabalhe rapidamente com UI integrada
   • Automatize tarefas repetitivas com Hooks

2. Foco visual

   • Gerencie specs e tarefas visualmente
   • Acompanhe progresso no dashboard

3. Necessite de automação avançada

   • Fluxos de trabalho orientados a eventos
   • Integração com serviços externos via MCP

4. Novos projetos

   • Sem vínculos com o ambiente existente
   • Experimente a mais recente experiência SDD

Uso Avançado com Arquivos de Prompt do SpecKit

Criando Prompts Customizados

Os arquivos de prompt do SpecKit podem ser livremente customizados:

---
description: Custom quality checklist generator
---

# /speckit.custom-checklist

Generate a quality checklist for:

1. **Security Review**
   - Authentication check
   - Authorization verification
   - Input validation

2. **Performance Review**
   - Database query optimization
   - Caching strategy
   - Load testing results

[Output format: Markdown checklist in spec directory]

Gerenciando Múltiplas Specs

# Funcionalidade 1
specify init . --ai copilot
/speckit.specify Build user authentication system

# Funcionalidade 2 (em nova branch)
git checkout -b feature/002-payment
/speckit.specify Integrate payment gateway

Exemplos de Fluxo de Trabalho Prático

Desenvolvimento em Equipe com SpecKit

graph TD
    A[Gerente de Produto] -->|Definir requisitos| B["speckit.specify"]
    B --> C["Gerar spec.md"]
    C --> D[Tech Lead]
    D -->|Seleção de tecnologia| E["speckit.plan"]
    E --> F["Gerar plan.md, data-model.md"]
    F --> G[Desenvolvedor]
    G -->|Revisar tarefas| H["speckit.tasks"]
    H --> I["Gerar tasks.md"]
    I --> J["speckit.implement"]
    J --> K["Gerar código"]
    K --> L[Pull Request]
    L --> M[Code Review]
    M -->|Aprovar| N[Merge]

Fluxo de desenvolvimento em equipe com SpecKit: Comandos diferentes para papéis diferentes, compartilhando documentos via Git

Desenvolvimento Solo com Kiro

graph TD
    A[Ideia] --> B[Spec Chat]
    B --> C[Gerar Requisitos]
    C --> D[Gerar Design]
    D --> E[Gerar Tarefas]
    E --> F[Código com referência #spec]
    F --> G[Salvar arquivo]
    G --> H[Acionar Hooks]
    H --> I[Auto-gerar testes]
    I --> J[Executar em background]

Fluxo de desenvolvimento solo com Kiro IDE: Ciclo de desenvolvimento eficiente com UI integrada e automação via Hooks

Conclusão

O SpecKit é ideal para equipes que querem adotar o SDD aproveitando os ambientes de desenvolvimento existentes. É open source, altamente flexível e permite adoção gradual.

O Kiro é adequado para desenvolvedores que buscam a mais recente experiência de Agentic IDE. Com UI integrada, recursos de automação e feedback visual, maximiza a produtividade.

Ambos os ambientes visam romper com o tradicional "vibe coding" e realizar um processo de desenvolvimento sistemático centrado em especificações. Escolha com base na natureza do seu projeto, composição da equipe e ambiente de desenvolvimento existente.

• Experimente o SpecKit: Repositório GitHub
• Experimente o Kiro: Site Oficial