stribus/pygerengastos / .agents/skills/reversa-spec-sdd
reversa-spec-sdd
VerifiedAgente final do time Code New Project Agents do Reversa. Decompõe um PRD em componentes lógicos e gera specs SDD (Spec-Driven Development) por componente, com score automático de qualidade. Use quando o usuário digitar "/reversa-spec-sdd", "reversa-spec-sdd" ou quando invocado pelo orquestrador `/reversa-new`. Lê `_reversa_sdd/prd.md` e produz `_reversa_sdd/sdd/<componente>.md`. Ao concluir, faz handoff para `/reversa-forward`. Também pode ser usado avulso para avaliar uma spec existente (modo de avaliação) ou para gerar spec única a partir de qualquer entrada que o usuário forneça. Entrega: arquivos `.md` no formato SDD com score de qualidade (0 a 100) e análise de gaps.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.7 KB |
| assets/spec_examples.md | markdown | 7.0 KB |
| references/evaluation_rubric.md | markdown | 4.3 KB |
| references/sdd_guide.md | markdown | 5.1 KB |
| references/spec_template.md | markdown | 6.8 KB |
| scripts/spec_scorer.py | script | 17.3 KB |
references/sdd_guide.md
View on GitHub# Guia de Metodologia — Spec-Driven Development
## O que é SDD?
Spec-Driven Development é a prática de escrever uma especificação detalhada de comportamento **antes** de escrever qualquer código. A spec responde ao **quê** o sistema deve fazer — não ao **como** implementar.
Não confundir com:
- **TDD** (Test-Driven Development): escreve testes antes do código — complementar ao SDD
- **DDD** (Domain-Driven Design): padrão arquitetural — independente do SDD
- **BDD** (Behavior-Driven Development): foco em comportamentos com Gherkin — um subconjunto de SDD
---
## Princípios Fundamentais
### 1. Behavior, not Implementation
A spec descreve o comportamento observável, não a implementação interna.
❌ Ruim: "O sistema deve usar Redis para cache das sessões"
✅ Bom: "O sistema deve manter a sessão do usuário ativa por 30 dias em dispositivos onde ele marcou 'lembrar de mim'"
A implementação (Redis, JWT, banco de dados) é uma decisão técnica de quem implementa — não da spec.
### 2. Ambiguidade = Bug Futuro
Toda ambiguidade na spec se torna um bug, uma reunião de alinhamento ou uma discussão em PR no futuro. Torne ambiguidades explícitas com `⚠️ ABERTO:` — é melhor um item aberto visível do que uma suposição silenciosa.
### 3. Non-Goals são tão importantes quanto Goals
"O que não vamos fazer" previne scope creep, alinha expectativas e acelera decisões. Uma feature sem non-goals tende a crescer indefinidamente.
### 4. A Spec é um Contrato Vivo
A spec muda conforme o entendimento evolui — e isso é saudável. O que importa é que as mudanças sejam registradas (Decision Log) e que todos os stakeholders estejam alinhados com a versão atual.
### 5. LLM-Readiness
Uma boa spec moderna deve ser legível por LLMs que vão ajudar a implementar. Isso significa:
- Requisitos numerados (IDs rastreáveis)
- Comportamentos explícitos, não implícitos
- Edge cases documentados (LLMs não adivinham casos extremos)
- Contexto de negócio incluído (o "porquê" ajuda a tomar boas decisões de implementação)
---
## O Ciclo SDD
```
Ideia/Problema
↓
Entrevista ←──────────────────────┐
↓ │
Rascunho da Spec │
↓ │
Avaliação (Score) │
↓ │
Score < 80? ──── Sim ──── Identificar gaps
↓ Não
Spec Aprovada
↓
Implementação
↓
Spec vs. Código (validação final)
```
---
## Quando Escrever a Spec
| Tamanho da feature | Recomendação |
|-------------------|--------------|
| Fix de bug | Não precisa de spec |
| Melhoria pequena (< 1 dia dev) | Spec mínima: goals + requisitos principais |
| Feature nova (1–5 dias) | Spec completa, mas concisa |
| Feature complexa (> 5 dias) | Spec completa + revisão por 2+ pessoas |
| Sistema novo | Spec de arquitetura + specs por feature |
---
## Prioridades de Requisitos (MoSCoW)
| Prioridade | Significado | Decisão se não couber no prazo |
|-----------|-------------|-------------------------------|
| **Must** | Obrigatório — sem isso não lança | Bloqueia o lançamento |
| **Should** | Importante — mas há workaround | Adia para próxima versão |
| **Could** | Nice-to-have | Descarta se necessário |
| **Won't** | Conscientemente fora do escopo | Documenta como Non-Goal |
---
## Antipadrões Comuns
### "Spec like a PRD de grande empresa"
Specs de 50 páginas que ninguém lê. Prefira specs concisas que cobrem o essencial com clareza.
### "Spec como lista de tarefas técnicas"
"Criar tabela users, adicionar endpoint POST /auth, integrar com OAuth..." — isso é um plano de implementação, não uma spec. A spec fala em comportamento.
### "Spec verbal / em Slack"
Decisões tomadas em conversa sem registro se perdem e geram conflitos. Toda spec deve existir como documento escrito.
### "Spec que nunca muda"
Specs congeladas que não refletem a realidade do que foi implementado. A spec deve ser atualizada quando a implementação divergir intencionalmente.
### "Open Questions silenciosas"
Assumir respostas para perguntas não respondidas. Sempre use `⚠️ ABERTO:` e resolva antes de implementar.
---
## Vocabulário do SDD
| Termo | Definição |
|-------|-----------|
| **Spec** | Documento que descreve o comportamento esperado de uma feature |
| **RF** | Requisito Funcional — o que o sistema deve fazer |
| **RNF** | Requisito Não-Funcional — como o sistema deve se comportar (performance, segurança...) |
| **Goal** | Objetivo que a feature deve atingir |
| **Non-Goal** | O que está explicitamente fora do escopo |
| **Edge Case** | Caso limite ou não-óbvio que o sistema deve tratar corretamente |
| **Happy Path** | O fluxo principal e mais comum de uso |
| **Critério de Aceite** | Condição verificável que define quando um requisito está implementado |
| **Open Question** | Dúvida não resolvida que pode impactar o design |
| **Decision Log** | Registro de decisões importantes e o porquê foram tomadas |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |