560 lines
18 KiB
Markdown
560 lines
18 KiB
Markdown
## Spec
|
|
|
|
**"Dar estrutura antes de escrever código"** - Totalmente em conformidade com o spec-driven development de Kiro
|
|
|
|
Diferente das ferramentas tradicionais de geração de código, realiza o desenvolvimento orientado por especificações de Kiro focado em dar estrutura ao caos do desenvolvimento. A partir de uma entrada mínima de requisitos, expande gradualmente desde especificações detalhadas de nível de product manager até design implementável, garantindo qualidade consistente do **protótipo ao ambiente de produção**.
|
|
|
|
### Como usar
|
|
|
|
```bash
|
|
# Solicitar Spec Mode ao Claude (entrada mínima de requisitos)
|
|
"Crie spec de [descrição da funcionalidade]"
|
|
|
|
# Expansão gradual estilo Kiro:
|
|
# 1. Requisitos simples → Geração automática de user stories detalhadas
|
|
# 2. Descrição estruturada de requisitos usando notação EARS
|
|
# 3. Refinamento de especificações através de diálogo gradual
|
|
# 4. Geração de 3 arquivos independentes:
|
|
# - requirements.md: Definição de requisitos usando notação EARS
|
|
# - design.md: Design incluindo diagramas Mermaid e interfaces TypeScript
|
|
# - tasks.md: Plano de implementação com aplicação automática de boas práticas
|
|
```
|
|
|
|
### Efeitos Comprovados (Resultados do Kiro)
|
|
|
|
**Aplicativo de compartilhamento seguro de arquivos em 2 dias**
|
|
|
|
```bash
|
|
"Crie spec de sistema de compartilhamento de arquivos (com suporte a criptografia)"
|
|
→ Aplicativo de compartilhamento de arquivos criptografados de nível de produção concluído em 2 dias
|
|
→ Aplicação automática de boas práticas de segurança
|
|
→ Sem necessidade de prompts adicionais
|
|
```
|
|
|
|
**Desenvolvimento de jogo em uma noite (iniciante)**
|
|
|
|
```bash
|
|
"Crie spec de jogo de quebra-cabeça 2D"
|
|
→ Desenvolvedor de código aberto sem experiência em desenvolvimento de jogos
|
|
→ Criação de jogo concluída em uma noite
|
|
→ Kiro cuidou da lógica de implementação, desenvolvedor se concentrou na criatividade
|
|
```
|
|
|
|
**Protótipo→Produção em um fim de semana**
|
|
|
|
```bash
|
|
"Crie spec de sistema de gerenciamento de produtos para site de e-commerce"
|
|
→ Do conceito ao protótipo funcional em um fim de semana
|
|
→ Qualidade consistente do protótipo ao ambiente de produção
|
|
→ Abordagem estruturada através de spec-driven development
|
|
```
|
|
|
|
### Exemplos Básicos
|
|
|
|
```bash
|
|
# Criação de spec para nova funcionalidade (entrada mínima)
|
|
"Sistema de avaliação de produtos
|
|
- Funcionalidade de avaliação por estrelas
|
|
- Postagem de comentários
|
|
- Upload de imagens"
|
|
|
|
# Criação de spec para funcionalidade de sistema
|
|
"Autenticação de usuário
|
|
- Suporte OAuth
|
|
- Autenticação multifator"
|
|
|
|
# Criação de spec para funcionalidade de API
|
|
"API de sistema de pagamento
|
|
- Integração Stripe
|
|
- Foco em segurança"
|
|
```
|
|
|
|
### Integração com Claude
|
|
|
|
```bash
|
|
# Spec de funcionalidade complexa
|
|
"Crie spec de funcionalidade de chat. Inclua WebSocket, notificações em tempo real e gerenciamento de histórico"
|
|
|
|
# Spec de funcionalidade com integração de banco de dados
|
|
"Crie spec de funcionalidade de gerenciamento de estoque para site de e-commerce. Inclua adição de produtos, atualização de estoque e funcionalidade de alertas"
|
|
|
|
# Spec de funcionalidade de frontend
|
|
"Crie spec de dashboard React. Inclua exibição de gráficos, filtros e funcionalidade de exportação"
|
|
|
|
# Spec de funcionalidade de backend
|
|
"Crie spec de API RESTful. Inclua autenticação, validação e registro de logs"
|
|
```
|
|
|
|
### Características do Spec Mode
|
|
|
|
**Fluxo de Trabalho de Diálogo Gradual**
|
|
|
|
- Reprodução completa do diálogo gradual que é o valor original do Kiro
|
|
- Refinamento colaborativo de especificações com o usuário em cada fase
|
|
- Geração de arquivos após processo de esclarecimento de dúvidas, discussão de opções e aprovação
|
|
|
|
**Expansão Interativa em 3 Estágios**
|
|
|
|
- **Phase 1**: Requirements Discovery → Discussão → Aprovação → Geração de `requirements.md`
|
|
- **Phase 2**: Design Exploration → Discussão → Aprovação → Geração de `design.md`
|
|
- **Phase 3**: Implementation Planning → Discussão → Aprovação → Geração de `tasks.md`
|
|
|
|
**Especificação Dinâmica**
|
|
|
|
- Resolução de ambiguidades nos requisitos através de diálogo
|
|
- Apresentação e discussão de opções técnicas
|
|
- Explicação de trade-offs e confirmação de decisões
|
|
|
|
### Exemplos Detalhados
|
|
|
|
```bash
|
|
# Funcionalidade complexa de sistema
|
|
"Crie spec de sistema de pagamento online. Inclua integração Stripe, segurança e tratamento de erros"
|
|
|
|
# Funcionalidade de frontend
|
|
"Crie spec de componente React. Inclua gerenciamento de estado, design de propriedades e testes"
|
|
|
|
# Funcionalidade de backend
|
|
"Crie spec de API GraphQL. Inclua design de schema, resolvers e autenticação"
|
|
|
|
# Funcionalidade DevOps
|
|
"Crie spec de pipeline CI/CD. Inclua automação de testes, deployment e monitoramento"
|
|
```
|
|
|
|
### Fluxo de Trabalho de Diálogo Gradual (Phase by Phase)
|
|
|
|
#### Phase 1: Requirements Discovery & Discussion
|
|
|
|
**1. Expansão automática a partir de entrada mínima (estilo Kiro)**
|
|
|
|
```text
|
|
Usuário: "Sistema de gerenciamento de usuários
|
|
- Funcionalidade de login
|
|
- Edição de perfil
|
|
- Permissões de administrador"
|
|
|
|
Claude: "Vou gerar user stories detalhadas a partir dos requisitos.
|
|
Esta compreensão está correta?
|
|
|
|
User Stories geradas automaticamente:
|
|
- Funcionalidade de registro e autenticação de usuários (suporte OAuth)
|
|
- Funcionalidade de gerenciamento de perfil (avatar, configurações)
|
|
- Funcionalidade de gerenciamento de permissões (RBAC)
|
|
- Funcionalidade de reset de senha
|
|
- Log de auditoria de segurança
|
|
|
|
Complementei os detalhes não explicitados. Há outras funcionalidades necessárias?"
|
|
```
|
|
|
|
**2. Descrição estruturada de requisitos usando notação EARS**
|
|
|
|
```text
|
|
Claude: "Vou estruturar os requisitos com a notação EARS do Kiro:
|
|
|
|
Definição de requisitos pela notação EARS:
|
|
|
|
WHEN o usuário tenta fazer login
|
|
GIVEN que inseriu email e senha corretos
|
|
THEN o sistema confirma a autenticação
|
|
AND redireciona para o dashboard em caso de sucesso
|
|
|
|
WHILE o usuário está na tela de edição de perfil
|
|
THE SYSTEM SHALL executar validação em tempo real
|
|
AND exibir preview das mudanças
|
|
|
|
WHERE funcionalidades que requerem permissões de administrador
|
|
IS há tentativa de acesso
|
|
THE SYSTEM SHALL verificar o nível de permissão
|
|
AND negar acesso se insuficiente"
|
|
```
|
|
|
|
**3. Complementação automática de casos extremos e requisitos de segurança**
|
|
|
|
```text
|
|
Claude: "Baseado nas boas práticas do Kiro, também considerei os seguintes casos:
|
|
|
|
Requisitos de segurança (complementação automática):
|
|
- Proteção contra ataques de força bruta
|
|
- Gerenciamento de sessão e timeout
|
|
- Proteção CSRF e contramedidas XSS
|
|
- Requisitos de força da senha
|
|
|
|
Casos extremos (detecção automática):
|
|
- Limitação de login simultâneo
|
|
- Funcionalidade de bloqueio de conta
|
|
- Garantia de integridade durante migração de dados
|
|
- Balanceamento de carga para grandes volumes de requisições
|
|
|
|
Estes requisitos são adequados?"
|
|
```
|
|
|
|
**5. Conclusão e aprovação da Phase 1**
|
|
|
|
```text
|
|
Claude: "Requirements Phase foi concluída.
|
|
Posso gerar requirements.md?"
|
|
→ "Próximo passo" → Geração de requirements.md
|
|
```
|
|
|
|
#### Phase 2: Design Exploration & Discussion
|
|
|
|
**1. Análise de codebase + Proposta automática de design (estilo Kiro)**
|
|
|
|
```text
|
|
Claude: "Vou analisar a codebase existente e propor a arquitetura ideal:
|
|
|
|
Resultado da análise da codebase:
|
|
- Autenticação: JWT + Express.js (v4.18.x)
|
|
- Banco de dados: PostgreSQL (v14+)
|
|
- Frontend: React + TypeScript (v18+)
|
|
- Padrões existentes: Repository pattern, separação de camada Service
|
|
|
|
Arquitetura recomendada pelo Kiro:
|
|
- Conformidade com Clean Architecture
|
|
- Elementos de Domain-Driven Design
|
|
- Aplicação parcial do padrão CQRS
|
|
- Boas práticas de segurança automatizadas
|
|
|
|
Proceder com este design?"
|
|
```
|
|
|
|
**2. Design visual com diagramas Mermaid**
|
|
|
|
```text
|
|
Claude: "Gerei automaticamente o design de sistema com diagrama Mermaid:
|
|
|
|
Diagrama de arquitetura gerado automaticamente:
|
|
|
|
graph TB
|
|
Client[React Client] --> API[Express API Gateway]
|
|
API --> Auth[Auth Service]
|
|
API --> User[User Service]
|
|
API --> Profile[Profile Service]
|
|
|
|
Auth --> AuthDB[(Auth Database)]
|
|
User --> UserDB[(User Database)]
|
|
Profile --> ProfileDB[(Profile Database)]
|
|
|
|
Auth --> JWT[JWT Service]
|
|
Auth --> OAuth[OAuth Provider]
|
|
|
|
Também gerar diagrama de fluxo de dados?"
|
|
```
|
|
|
|
**3. Geração automática de interfaces TypeScript**
|
|
|
|
```text
|
|
Claude: "Vou gerar automaticamente interfaces TypeScript baseadas no design:
|
|
|
|
Interfaces TypeScript geradas automaticamente:
|
|
|
|
// Domain entities
|
|
interface User {
|
|
readonly id: UserId;
|
|
readonly email: Email;
|
|
readonly profile: UserProfile;
|
|
readonly auth: AuthSettings;
|
|
readonly permissions: Permission[];
|
|
readonly createdAt: Date;
|
|
readonly updatedAt: Date;
|
|
}
|
|
|
|
interface UserProfile {
|
|
readonly displayName: string;
|
|
readonly avatar: AvatarUrl;
|
|
readonly preferences: UserPreferences;
|
|
}
|
|
|
|
interface AuthSettings {
|
|
readonly passwordHash: PasswordHash;
|
|
readonly mfaEnabled: boolean;
|
|
readonly lastLoginAt: Date;
|
|
readonly failedAttempts: number;
|
|
}
|
|
|
|
// Use cases
|
|
interface UserRepository {
|
|
findById(id: UserId): Promise<User | null>;
|
|
findByEmail(email: Email): Promise<User | null>;
|
|
save(user: User): Promise<void>;
|
|
}
|
|
|
|
interface AuthenticationService {
|
|
authenticate(credentials: LoginCredentials): Promise<AuthResult>;
|
|
refreshToken(token: RefreshToken): Promise<AccessToken>;
|
|
}
|
|
|
|
Proceder com este design de interface?"
|
|
```
|
|
|
|
**4. Conclusão e aprovação da Phase 2**
|
|
|
|
```text
|
|
|
|
Claude: "Design Phase foi concluída.
|
|
Posso gerar design.md?"
|
|
→ "Próximo passo" → Geração de design.md
|
|
|
|
```
|
|
|
|
#### Phase 3: Implementation Planning & Discussion
|
|
|
|
**1. Aplicação automática de boas práticas (estilo Kiro)**
|
|
|
|
```text
|
|
|
|
Claude: "Gerei plano de implementação com aplicação automática das boas práticas do Kiro:
|
|
|
|
Estratégia de implementação gerada automaticamente:
|
|
|
|
1. Desenvolvimento Security-First
|
|
- Incorporação automática de contramedidas OWASP Top 10
|
|
- Implementação automática de criptografia e hashing
|
|
- Geração automática de testes de segurança
|
|
|
|
2. Aplicação forçada de Clean Architecture
|
|
- Implementação automática de separação de camadas
|
|
- Aplicação automática de inversão de dependência
|
|
- Aplicação forçada de design testável
|
|
|
|
3. Otimização de performance
|
|
- Implementação automática de estratégia de cache
|
|
- Otimização de banco de dados
|
|
- Utilização de processamento assíncrono
|
|
|
|
Proceder com esta abordagem?"
|
|
|
|
```
|
|
|
|
**2. Configuração automática de pontos de verificação de qualidade**
|
|
|
|
```text
|
|
|
|
Claude: "Configurei automaticamente pontos de verificação de qualidade para cada etapa de implementação:
|
|
|
|
Processo automático de garantia de qualidade:
|
|
|
|
Phase 3a: Implementação de Backend
|
|
|
|
- [ ] Scan de segurança (SAST/DAST)
|
|
- [ ] Teste de especificação de API (conformidade OpenAPI)
|
|
- [ ] Teste de performance (carga e resposta)
|
|
- [ ] Scan de vulnerabilidades (dependências e CVE)
|
|
|
|
Phase 3b: Implementação de Frontend
|
|
|
|
- [ ] Teste de acessibilidade (WCAG 2.1 AA)
|
|
- [ ] Teste de compatibilidade de navegadores
|
|
- [ ] Verificação de design responsivo
|
|
- [ ] Confirmação de cabeçalhos de segurança
|
|
|
|
Phase 3c: Integração e Deploy
|
|
|
|
- [ ] Suite de testes E2E
|
|
- [ ] Configuração de pipeline CI/CD
|
|
- [ ] Configuração de monitoramento e logs
|
|
- [ ] Auditoria de segurança do ambiente de produção
|
|
|
|
Tudo será executado automaticamente. Há padrões de qualidade adicionais?"
|
|
|
|
```
|
|
|
|
**3. Análise automática de dependências e mitigação de riscos**
|
|
|
|
```text
|
|
|
|
Claude: "Analisei automaticamente a ordem de implementação e estratégias de mitigação de riscos:
|
|
|
|
Ordem de implementação otimizada:
|
|
|
|
Semana 1: Infraestrutura e base de segurança
|
|
|
|
- Design e criação de schema de banco de dados
|
|
- Base de autenticação (JWT + gerenciamento de sessão)
|
|
- Implementação de middleware de segurança
|
|
- Endpoints básicos de API
|
|
|
|
Semana 2: Implementação de funcionalidades core
|
|
|
|
- Funcionalidade de gerenciamento de usuários
|
|
- Funcionalidade de gerenciamento de perfil
|
|
- Sistema de gerenciamento de permissões
|
|
- Validação e tratamento de erros
|
|
|
|
Semana 3: Funcionalidades avançadas e otimização
|
|
|
|
- Implementação de autenticação multifator
|
|
- Funcionalidade de log de auditoria
|
|
- Otimização de performance
|
|
- Integração com frontend
|
|
|
|
Estratégias de mitigação de riscos detectadas automaticamente:
|
|
|
|
- Autenticação multifator: Introdução gradual (SMS→Autenticação por app)
|
|
- Gerenciamento de sessão: Configuração de cluster Redis
|
|
- Acesso em massa: Rate limiting + Utilização de CDN
|
|
- Integridade de dados: Reforço do gerenciamento de transações
|
|
|
|
Há problemas com este plano?"
|
|
|
|
```
|
|
|
|
**4. Conclusão e aprovação da Phase 3**
|
|
|
|
```text
|
|
|
|
Claude: "Implementation Planning Phase foi concluída.
|
|
Posso gerar tasks.md?"
|
|
→ "Próximo passo" → Geração de tasks.md
|
|
|
|
```
|
|
|
|
### Funcionalidades Específicas do Kiro
|
|
|
|
**Notação EARS (Easy Approach to Requirements Syntax)**
|
|
|
|
```text
|
|
# Padrões padrão de notação EARS do Kiro
|
|
|
|
WHEN [situação / trigger]
|
|
GIVEN [precondição]
|
|
THEN [comportamento do sistema]
|
|
AND [comportamento adicional]
|
|
|
|
WHILE [estado / processo]
|
|
THE SYSTEM SHALL [comportamento obrigatório]
|
|
AND [comportamento relacionado]
|
|
|
|
WHERE [funcionalidade / componente]
|
|
IS [condição / estado]
|
|
THE SYSTEM SHALL [comportamento correspondente]
|
|
```
|
|
|
|
**Funcionalidades de geração automática**
|
|
|
|
- **Diagramas Mermaid**: Geração automática de diagramas de arquitetura e fluxo de dados
|
|
- **Interfaces TypeScript**: Criação automática de definições de tipos baseadas no design
|
|
- **Boas práticas**: Incorporação automática de contramedidas de segurança e performance
|
|
- **Pontos de verificação de qualidade**: Configuração automática de padrões de qualidade por etapas
|
|
|
|
**Integração hooks**
|
|
|
|
- Verificação automática de qualidade ao salvar arquivos
|
|
- Aplicação automática de padrões de código
|
|
- Execução automática de scan de segurança
|
|
- Verificação automática de contramedidas OWASP Top 10
|
|
|
|
**Garantia de qualidade protótipo→produção**
|
|
|
|
- Design consistente através de abordagem estruturada
|
|
- Aplicação forçada de desenvolvimento Security-First
|
|
- Aplicação automática de arquitetura escalável
|
|
- Incorporação de gerenciamento contínuo de qualidade
|
|
|
|
### Observações
|
|
|
|
**Escopo de aplicação**
|
|
|
|
- Spec Mode é otimizado para implementação de funcionalidades
|
|
- Para correções simples ou mudanças em pequena escala, use formato de implementação normal
|
|
- Recomendado para desenvolvimento de novas funcionalidades ou modificações complexas
|
|
|
|
**Garantia de qualidade**
|
|
|
|
- Clarificação de critérios de conclusão para cada etapa
|
|
- Revisão de design antes da implementação
|
|
- Padrões de qualidade abrangentes incluindo testes e acessibilidade
|
|
|
|
**Cuidados na execução**
|
|
|
|
- Resolver ambiguidades nos requisitos antes de avançar para a etapa de design
|
|
- Gerar tarefas de implementação após conclusão do design
|
|
- Valorizar processo de aprovação em cada etapa
|
|
|
|
### Frases de Ativação e Controle
|
|
|
|
#### Controle de fluxo de trabalho gradual
|
|
|
|
**Triggers de início**
|
|
|
|
- "Crie spec de [nome da funcionalidade]"
|
|
- "Quero desenvolver [nome da funcionalidade] orientado por spec"
|
|
- "Projete [nome da funcionalidade] a partir de especificações"
|
|
|
|
**Controle de progressão de fases**
|
|
|
|
- **"Próximo passo"**: Conclui a fase atual e gera arquivo, avança para próxima fase
|
|
- **"Modifique"**: Ajusta e melhora conteúdo dentro da fase atual
|
|
- **"Refaça"**: Recomeça a fase atual do início
|
|
- **"Explique detalhadamente"**: Apresenta explicações mais detalhadas ou opções
|
|
- **"Pule"**: Pula a fase atual e vai para a próxima (não recomendado)
|
|
|
|
**Timing de geração de arquivos**
|
|
|
|
```text
|
|
Conclusão Phase 1 → "Próximo passo" → Geração de requirements.md
|
|
Conclusão Phase 2 → "Próximo passo" → Geração de design.md
|
|
Conclusão Phase 3 → "Próximo passo" → Geração de tasks.md
|
|
```
|
|
|
|
### Exemplo de Execução (Fluxo Gradual)
|
|
|
|
```bash
|
|
# Exemplo de uso
|
|
Usuário: "Crie spec de sistema de gerenciamento de usuários"
|
|
|
|
# Phase 1: Requirements Discovery
|
|
Claude: [Início de confirmação e discussão de requisitos]
|
|
Usuário: [Resposta, discussão, modificação]
|
|
Claude: "Requirements Phase foi concluída. Posso avançar?"
|
|
Usuário: "Próximo passo"
|
|
→ Geração de requirements.md
|
|
|
|
# Phase 2: Design Exploration
|
|
Claude: [Início de proposta e discussão de design]
|
|
Usuário: [Discussão de escolhas técnicas / arquitetura]
|
|
Claude: "Design Phase foi concluída. Posso avançar?"
|
|
Usuário: "Próximo passo"
|
|
→ Geração de design.md
|
|
|
|
# Phase 3: Implementation Planning
|
|
Claude: [Início de discussão de plano de implementação]
|
|
Usuário: [Discussão de prioridades, riscos, esforço]
|
|
Claude: "Implementation Phase foi concluída. Posso avançar?"
|
|
Usuário: "Próximo passo"
|
|
→ Geração de tasks.md
|
|
|
|
# Conclusão
|
|
Claude: "Preparação para spec-driven development concluída. Pode iniciar a implementação."
|
|
```
|
|
|
|
### Diferenças com /plan
|
|
|
|
| Característica | /plan | /spec |
|
|
| ----------------------- | -------------------------------- | ------------------------------------------------------------------------- |
|
|
| Objetivo | Plano geral de implementação | Desenvolvimento orientado por especificação funcional |
|
|
| Formato de saída | Documento de plano único | 3 arquivos independentes (requirements.md, design.md, tasks.md) |
|
|
| Definição de requisitos | Organização básica de requisitos | Critérios de aceitação detalhados usando notação EARS |
|
|
| Design | Foco em seleção técnica | Baseado em análise de codebase |
|
|
| Implementação | Decomposição geral de tarefas | Sequência considerando dependências |
|
|
| Garantia de qualidade | Estratégia básica de testes | Requisitos abrangentes de qualidade (testes, acessibilidade, performance) |
|
|
| Sincronização | Plano estático | Atualização dinâmica de spec |
|
|
|
|
### Casos de Uso Recomendados
|
|
|
|
**Uso recomendado de spec**
|
|
|
|
- Desenvolvimento de novas funcionalidades
|
|
- Modificações complexas de funcionalidades
|
|
- Design de API
|
|
- Design de banco de dados
|
|
- Implementação de UI/UX
|
|
|
|
**Uso recomendado de plan**
|
|
|
|
- Design de sistema geral
|
|
- Construção de infraestrutura
|
|
- Refatoração
|
|
- Seleção técnica
|
|
- Mudanças de arquitetura
|