Padrão Oficial de SDD (Spec-Driven Development)

A especificação vem antes do código. Todo projeto da AEX mantém a pasta .specs/ para contratos de entrega por feature — especialmente quando humanos e IA trabalham juntos.

Propósito

SDD (Spec-Driven Development) garante que cada feature tenha um contrato claro antes da implementação:

• Delimita escopo e critérios de aceite.
• Evita que a IA invente comportamento fora do pedido.
• Facilita code review: o PR implementa o que está na spec?

Não substitui os onze documentos obrigatórios em docs/ (ver DOCUMENTATION_STANDARD). Eles descrevem o produto de forma permanente; .specs/ descreve esta entrega.

Onde cada coisa mora

A tarefa no ClickUp rastreia quem e quando; a spec em .specs/ define o quê e como validar.

Estrutura

.specs/
├── README.md                 # Como usar SDD neste repositório
└── <feature-kebab>/
    ├── SPEC.md               # O quê: escopo, critérios de aceite, fora de escopo
    ├── PLAN.md               # Como: arquivos, ordem, riscos
    └── TASKS.md              # Checklist de implementação

Nomenclatura

• Pasta da feature: kebab-case (ex.: backend-nestjs, secretaria-ia).
• Arquivos fixos: SPEC.md, PLAN.md, TASKS.md (UPPER_SNAKE_CASE).
• Um assunto por pasta — não agrupe features distintas na mesma spec.

Fluxo

1. Spec — criar .specs/<feature>/SPEC.md a partir do template. Referenciar RFs do PRD; detalhar só o escopo desta entrega.
2. Aprovação — humano revisa e aprova a spec antes de codar.
3. Plano — preencher PLAN.md e TASKS.md (pode ser feito pela IA, sempre amarrado à spec).
4. Implementação — branch feature/..., código em passos pequenos, commits Conventional.
5. Verificação — PR atende todos os critérios de aceite da SPEC.md?
6. Documentação — atualizar docs/ afetados (API.md, DATABASE.md, etc.) no mesmo PR.

Quando usar

Fronteira com docs/

• Não copie o PRD inteiro para cada SPEC.md. Referencie (ex.: "Implementa RF-03 do PRD").
• Não duplique arquitetura permanente — aponte para docs/ARCHITECTURE.md e detalhe só o que muda nesta entrega.
• Atualize docs/ quando a spec introduzir comportamento que vira contrato permanente (endpoint novo → API.md; tabela nova → DATABASE.md).

Templates

Modelos em templates/specs/:

• README.md — guia da pasta no projeto
• SPEC_TEMPLATE.md
• PLAN_TEMPLATE.md
• TASKS_TEMPLATE.md

Prompt de nova feature: templates/prompts/NEW_FEATURE.md.

Regras (resumo)

1. Todo projeto de aplicação mantém .specs/README.md na raiz (pasta pronta; features nascem sob demanda).
2. Spec aprovada antes de implementar features não triviais.
3. Três arquivos por feature: SPEC.md, PLAN.md, TASKS.md.
4. PR verificado contra a spec; documentação permanente atualizada no mesmo PR.
5. Specs versionadas no Git — histórico de decisões de entrega fica no repositório.