Pular para conteúdo

name: specify description: 'Convert a natural-language feature description into SDD spec (user stories, FRs, success criteria). Triggers: "specify", "criar spec", "nova feature", "feature spec". Skip for refining an existing spec (clarify).' argument-hint: "[descricao da feature em linguagem natural]" allowed-tools: - Read - Write - Edit - Glob - Grep - Bash

Skill: Especificar Feature (SDD)

Transforme uma descricao em linguagem natural em uma feature spec completa seguindo o formato Spec-Driven Development. Foco no QUE e POR QUE — nunca no COMO implementar.

Pre-requisitos

Opcional mas recomendado: - /briefing — contextualiza a feature dentro do projeto - /constitution — principios ajudam a calibrar escopo e padroes de qualidade

Sem esses, a skill funciona mas pode precisar de mais [NEEDS CLARIFICATION].

Proximos passos

  1. /clarify — resolver ambiguidades da spec (se houver [NEEDS CLARIFICATION])
  2. /plan — gerar plano tecnico de implementacao
  3. /checklist — validar qualidade dos requisitos antes de implementar

Argumentos

$ARGUMENTS

Leitura de artefatos foundational (briefing + constitution)

Antes de ler docs/01-briefing-discovery/briefing.md ou docs/constitution.md direto do disco, verifique se ha cache valido populado pelo agente-00c ou feature-00c. Aditivo — se nao houver cache, leia direto do disco conforme comportamento padrao (FR-CACHE-014).

  1. Detectar agente ativo: variavel AGENTE_00C_STATE_DIR setada, OU <projeto-alvo>/.claude/agente-00c-state/state.json existente, OU <projeto-alvo>/.claude/feature-00c-state/<short>/state.json.

  2. Se ativo, tente consumir o resumo via Bash: 

    ~/.claude/skills/agente-00c-runtime/scripts/state-cache.sh get-resumo \
  --state-dir "$SD" --artifact briefing

  3. Exit 0 + stdout nao-vazio: use o resumo como conteudo.
  4. Exit 1: cache miss (campo ausente, estrategia=passthrough, drift detectado) — caia em leitura direta.
  5. Exit 2: erro fatal (state.json corrompido) — aborte com diagnostico do stderr.

Mesmo protocolo para --artifact constitution.

  1. Apos consumo (hit ou miss), registre metrica via: 

    ~/.claude/skills/agente-00c-runtime/scripts/state-cache.sh metrics-bump \
  --state-dir "$SD" --tipo <hit|miss-drift|miss-disabled> \
  [--chars-economizados N]
    onde N = source_chars - resumo_chars quando hit, ou 0 caso contrario.

  2. Standalone (sem state.json): leia direto do disco. Comportamento identico a versao pre-cache.

Spec: docs/specs/_archived/agente-00c-artifact-cache/spec.md FR-CACHE-008.

FLUXO DE EXECUCAO

0. TRIAGEM         Classificar pedido e confirmar relevancia do SDD
     |
1. ANALISE         Parsear descricao e extrair conceitos
     |
2. ESTRUTURA       Criar diretorio e gerar short name
     |
3. ESPECIFICACAO   Preencher template com conteudo concreto
     |
4. VALIDACAO       Checar qualidade contra criterios internos
     |
5. CLARIFICACAO    Resolver ambiguidades criticas com o usuario
     |
6. SALVAMENTO      Salvar e reportar proximos passos

ETAPA 0: TRIAGEM (OBRIGATORIA ANTES DE PROSSEGUIR)

Antes de gerar qualquer artefato, classifique o pedido e valide com o usuario se o fluxo SDD completo faz sentido para o escopo. O fluxo SDD (spec → clarify → plan → tasks) tem custo real e nem todo pedido justifica esse overhead.

0.1 Classificar o pedido

Analise $ARGUMENTS e classifique em uma das categorias:

  • Feature nova: comportamento/capacidade que o sistema nao tem hoje, com multiplos atores, fluxos ou regras de negocio → SDD completo se paga.
  • Ajuste/extensao pontual: mudanca pequena em feature existente, uma regra nova, um campo a mais → SDD provavelmente e overkill.
  • Bugfix: correcao de comportamento incorreto → NAO usar specify, sugerir a skill bugfix.
  • Refactor/tarefa tecnica: mudanca interna sem impacto funcional observavel → NAO usar specify, sugerir execucao direta ou execute-task.

0.2 Avaliar relevancia do SDD

Considere sinais de que o SDD completo vale o custo: - Feature tem 2+ user stories independentes? - Envolve multiplos atores ou papeis? - Tem regras de negocio ou edge cases nao triviais? - Precisa alinhar stakeholders antes de implementar? - Vai gerar backlog de tarefas para mais de uma sessao de trabalho?

Se a maioria e "nao", provavelmente o pedido pode ser resolvido inline ou com um UC/ADR pontual, sem passar pelo pipeline SDD.

0.3 Apresentar a analise e deixar o usuario decidir

Antes de criar diretorio ou arquivos, apresentar ao usuario:

## Triagem do pedido

**Classificacao**: [Feature nova | Ajuste pontual | Bugfix | Refactor]

**Analise de relevancia SDD**:
- [Justificar por que vale ou nao vale gerar spec completa]
- [Citar sinais especificos do pedido]

**Opcoes**:

1. **Executar direto** — resolver o pedido sem gerar artefatos SDD
   (recomendado se: escopo pequeno, bugfix, refactor, ajuste inline)
2. **Criar feature SDD completa** — gerar spec + seguir pipeline
   (recomendado se: feature com stories multiplas, stakeholders, backlog)
3. **Alternativa sugerida**: [ex: criar UC classico, ADR, rodar bugfix]

Qual caminho prefere?

NUNCA prosseguir para ETAPA 1 sem confirmacao explicita do usuario. Se o usuario escolher opcao 1 ou 3, encerrar a skill e executar o caminho escolhido (ou delegar para skill apropriada).

ETAPA 1: ANALISE

1.1 Parsear Descricao

Extraia do input ($ARGUMENTS): - Atores: Quem usa a feature (usuarios, admins, sistemas) - Acoes: O que a feature permite fazer - Dados: Que entidades/informacoes estao envolvidas - Restricoes: Limites, regras, condicoes

1.2 Ler Contexto do Projeto

SEMPRE LER (se existirem):
-- README.md
-- CLAUDE.md
-- docs/constitution.md (para alinhar com principios)
-- docs/specs/ (para verificar IDs existentes e evitar duplicatas)

ETAPA 2: ESTRUTURA

2.1 Gerar Short Name

Crie um nome curto (2-4 palavras, kebab-case) que capture a essencia da feature: - Formato acao-substantivo quando possivel - Preservar termos tecnicos e siglas - Exemplos: - "Quero adicionar autenticacao de usuario" → user-auth - "Implementar integracao OAuth2 para a API" → oauth2-api-integration - "Criar dashboard de analytics" → analytics-dashboard

2.2 Criar Diretorio

Criar docs/specs/{short-name}/ (ou caminho sugerido pelo usuario).

ETAPA 3: ESPECIFICACAO

3.1 Template da Feature Spec

Ler o template em templates/feature-spec.md (mesmo diretorio desta skill) e preencher com conteudo concreto derivado da descricao. Estrutura:

  • User Scenarios & Testing — stories priorizadas (P1..Pn) + edge cases
  • Requirements — functional requirements e key entities
  • Success Criteria — measurable outcomes, technology-agnostic

Para ver exemplos de spec bem escrita vs mal escrita: - examples/spec-good.md — ilustra stories independentes, success criteria mensuraveis, zero detalhes de implementacao - examples/spec-bad.md — catalogo de anti-patterns (jargao tecnico em SC, stories acopladas, adjetivos vagos, excesso de [NEEDS CLARIFICATION])

3.2 Regras de Preenchimento

User Stories: - Priorizadas como jornadas de usuario ordenadas por importancia - Cada story deve ser INDEPENDENTEMENTE TESTAVEL - Se implementar apenas UMA story, ainda deve haver um MVP viavel - Adicionar quantas stories forem necessarias (P1, P2, P3, P4...)

Functional Requirements: - Cada requisito deve ser testavel - Foco no QUE o sistema faz, nao COMO implementar - Usar defaults razoaveis para detalhes nao especificados: - Retencao de dados: praticas padrao da industria - Performance: expectativas padrao para web/mobile - Tratamento de erros: mensagens user-friendly com fallbacks - Autenticacao: session-based ou OAuth2 para web apps - Para ambiguidades criticas, marcar com [NEEDS CLARIFICATION: pergunta especifica] - MAXIMO 3 marcadores [NEEDS CLARIFICATION] no total - Prioridade de clarificacao: escopo > seguranca > UX > detalhes tecnicos

Decisoes de Infraestrutura Auditaveis (obrigatorio para features com runtime de longo prazo):

Features que envolvem schedulers, sessoes persistentes, refresh de tokens externos ou rotacao de chaves DEVEM declarar essas politicas como FRs explicitos no spec — NAO como divida descoberta na execucao. Razao: a execucao-fonte do agente-00c teve scheduling (sug-016), encryption key rotation (sug-011) e refresh policy (sug-015) descobertos na onda-007 como pendencias urgentes; deveriam ter sido FRs desde o spec.

Checklist minimo (cada item vira FR explicito quando aplicavel):

Tipo de decisao FR explicito sugerido Quando aplicar
Politica de scheduling FR-NN-INFRA-SCHED: autoSchedule = 'cron' \| 'wakeup' \| 'manual' \| 'auto' (default <X>) Feature dispara trabalho periodico ou agendado
Politica de key rotation FR-NN-INFRA-KEY: SESSION_ENCRYPTION_KEY suporta versionamento (v1:<base64>, v2:<base64>) — rotacao sem downtime Feature criptografa dados persistentes
Refresh policy (token externo) FR-NN-INFRA-REFRESH: refresh on-demand + job periodico a cada Xmin; gap window aceitavel: Y min Feature consome IdP, OAuth, ou recurso com TTL
Mutex multi-pod FR-NN-INFRA-LOCK: serializacao cross-pod via <pg_try_advisory_xact_lock\|redis lock\|SELECT FOR UPDATE> Deploy multi-replica + estado compartilhado
Backup / restore FR-NN-INFRA-BACKUP: snapshot cron Xh, retencao Yd, restore tested via RB-NNN Feature persiste dados criticos
Idempotencia FR-NN-INFRA-IDEMP: <chave de idempotencia, TTL, scope> Feature aceita request retry

Se a feature NAO toca nenhum desses, anotar explicitamente uma linha > Decisoes de infraestrutura: N/A (feature stateless, sem scheduling). NAO deixar implicito — N/A explicito > silencio.

Success Criteria: - DEVEM ser mensuráveis (tempo, porcentagem, contagem, taxa) - DEVEM ser technology-agnostic (sem frameworks, linguagens, databases) - DEVEM ser user-focused (perspectiva do usuario/negocio) - DEVEM ser verificaveis sem conhecer detalhes de implementacao

Exemplos de Success Criteria BEM escritos: - "Usuarios completam checkout em menos de 3 minutos" - "Sistema suporta 10.000 usuarios concorrentes" - "95% das buscas retornam resultados em menos de 1 segundo"

Exemplos de Success Criteria MAL escritos (implementation-focused): - "API response time under 200ms" (muito tecnico) - "Database handles 1000 TPS" (detalhe de implementacao) - "React components render efficiently" (framework-specific)

ETAPA 4: VALIDACAO

4.1 Checklist de Qualidade Interna

Valide a spec contra estes criterios:

  • Nenhum detalhe de implementacao (linguagens, frameworks, APIs)
  • Focado no valor para o usuario e necessidades do negocio
  • Escrito para stakeholders nao-tecnicos
  • Todas as secoes obrigatorias preenchidas
  • Requisitos sao testaveis e nao-ambiguos
  • Success criteria sao mensuráveis
  • Success criteria sao technology-agnostic
  • Acceptance scenarios definidos para todas as stories
  • Edge cases identificados
  • Escopo claramente delimitado

4.2 Auto-Correcao

Se itens falham na validacao: 1. Listar itens que falharam e problemas especificos 2. Atualizar a spec para corrigir cada problema 3. Re-validar (max 3 iteracoes) 4. Se ainda falhando apos 3 iteracoes: documentar problemas restantes e avisar usuario

ETAPA 5: CLARIFICACAO

5.1 Resolver [NEEDS CLARIFICATION]

Se existem marcadores [NEEDS CLARIFICATION] na spec:

  1. Extrair todos os marcadores
  2. Se mais de 3: manter apenas os 3 mais criticos e fazer guesses informados para o resto
  3. Para cada marcador, apresentar ao usuario:
## Questao [N]: [Topico]

**Contexto**: [Citar secao relevante da spec]

**O que precisamos saber**: [Pergunta especifica]

**Respostas Sugeridas**:

| Opcao | Resposta | Implicacoes |
|-------|----------|-------------|
| A     | [Primeira opcao] | [O que significa para a feature] |
| B     | [Segunda opcao] | [O que significa para a feature] |
| C     | [Terceira opcao] | [O que significa para a feature] |

**Sua escolha**: _[Aguardar resposta]_
  1. Apos respostas: atualizar spec substituindo marcadores pelas respostas

ETAPA 6: SALVAMENTO

6.1 Salvar Spec

Salvar em docs/specs/{short-name}/spec.md.

6.2 Reportar

## Spec Criada

**Feature**: {short-name}
**Arquivo**: docs/specs/{short-name}/spec.md
**Status**: Draft
**User Stories**: {N} stories (P1-P{N})
**Requisitos**: {N} functional requirements
**Clarificacoes pendentes**: {N}

### Proximos Passos

1. `/clarify` — Refinar ambiguidades na spec (se houver NEEDS CLARIFICATION)
2. `/plan` — Gerar plano tecnico de implementacao

DIRETRIZES RAPIDAS

  • Foco no QUE usuarios precisam e POR QUE
  • Evitar COMO implementar (sem tech stack, APIs, estrutura de codigo)
  • Escrito para stakeholders de negocio, nao desenvolvedores
  • Quando secao nao se aplica: remover inteiramente (nao deixar como "N/A")
  • Pensar como tester: todo requisito vago deve falhar no checklist de qualidade

Gotchas

ZERO detalhes de implementacao na spec

Sem linguagens, frameworks, APIs, estrutura de codigo, nomes de bibliotecas, classes. A spec responde QUE e POR QUE — o COMO vai para /plan. Se aparece "em React" ou "com PostgreSQL" na spec, esta errado.

Success Criteria devem ser technology-agnostic E mensuraveis

Correto: "Usuario completa checkout em <3 minutos", "95% das buscas retornam <1s", "Sistema suporta 10k usuarios concorrentes". Errado: "API responde <200ms" (tecnico), "Database aguenta 1000 TPS" (implementacao), "Componentes React renderizam rapido" (framework).

Maximo 3 [NEEDS CLARIFICATION] — priorizar escopo > seguranca > UX > tech

Mais de 3 marcadores indica que a spec deveria voltar ao usuario antes de escrever. Priorize o que impacta corretude e use defaults informados para o resto.

Cada user story deve ser INDEPENDENTEMENTE TESTAVEL

Se implementar apenas P1 nao ha MVP viavel, as stories estao acopladas demais. Cada story precisa ter valor isolado para o usuario.

Nao deixar secoes vazias com "N/A"

Se a feature nao envolve entidades de dados, remover a secao "Key Entities" inteira — nao deixar header com "N/A" abaixo. Secoes vazias sao ruido para o /plan e /create-tasks downstream.

Defaults razoaveis ao inves de [NEEDS CLARIFICATION] para tudo

Retencao de dados, tratamento de erros padrao, autenticacao web-padrao — se nao critico, use o default da industria e documente a suposicao. Marcar tudo como pendente trava o fluxo.