52 lines
3.8 KiB
Markdown
52 lines
3.8 KiB
Markdown
---
|
|
type: rule
|
|
name: ddd-documentacao-primeiro
|
|
description: Regra global que exige a documentação de novos artefatos antes da implementação (Documentation-Driven Development).
|
|
scope: global
|
|
trigger: always_on
|
|
priority: alta
|
|
updatedAt: "2026-08-12"
|
|
---
|
|
|
|
# Regra: Documentação Obrigatória Antes da Implementação
|
|
|
|
## Contexto
|
|
Implementar sem documentar leva ao acúmulo de conhecimento implícito, código inconsistente e perda do conhecimento institucional. Para garantir que as decisões de design, regras de negócio e fluxos estejam claros antes de qualquer código ser escrito, adotamos o Documentation-Driven Development (DDD). A documentação atua como o contrato formal do que será construído.
|
|
|
|
## Regra
|
|
Antes de implementar qualquer novo artefato (regra, skill, workflow, funcionalidade, endpoint de API, decisão técnica) ou realizar alterações substanciais em artefatos existentes, o agente **DEVE OBRIGATORIAMENTE** criar ou atualizar a documentação na pasta `DOCUMENTACAO/funcionalidades/<funcionalidade>/` utilizando o template apropriado de `DOCUMENTACAO/_templates/`.
|
|
|
|
## Protocolo DDD
|
|
|
|
Para toda nova demanda ou funcionalidade, siga rigorosamente os passos abaixo:
|
|
|
|
1. **Identificar Funcionalidade**: Analisar a demanda e determinar a qual funcionalidade ela pertence (avaliacoes, empresas, formularios, contratos-comerciais, relatorios, importador, ajuda-suporte, validade). Para decisões transversais, usar `DOCUMENTACAO/_transversais/`.
|
|
2. **Consultar Template**: Consultar o respectivo template em `DOCUMENTACAO/_templates/_template-*`.
|
|
3. **Criar/Atualizar Documentação**: Redigir a documentação na categoria adequada usando a estrutura do template. Se a funcionalidade altera algo existente, a documentação prévia deve ser atualizada.
|
|
4. **Apresentar ao Operador**: Validar a documentação redigida com o operador (usuário humano) antes de iniciar qualquer código.
|
|
5. **Implementar**: Escrever o código de forma que ele satisfaça e implemente *exatamente* o que foi estabelecido na documentação aprovada.
|
|
6. **Validar**: Testar ou analisar o código para assegurar que ele respeita a especificação em 100%.
|
|
7. **Sincronizar**: Se durante a implementação descobrir-se que ajustes na abordagem são necessários, a documentação deve ser atualizada em sincronia com o código.
|
|
|
|
## Exceções
|
|
Esta regra pode ser ignorada apenas para alterações triviais que não impactam regras de negócio, fluxos ou arquitetura, tais como:
|
|
- Correção de erros de digitação (typos) em arquivos e variáveis.
|
|
- Formatação de código ou linting.
|
|
- Ajustes simples de imports.
|
|
- Continuação de trabalho (ex: a doc já foi feita em um prompt/sessão anterior para esta mesma task).
|
|
|
|
## Exemplos
|
|
|
|
✅ **Correto**:
|
|
- O operador pede um novo endpoint de avaliações. O agente cria/atualiza `DOCUMENTACAO/funcionalidades/avaliacoes/contratos.md` detalhando a API usando o template `_templates/_template-contrato`. Após aprovação, cria o código na API.
|
|
|
|
❌ **Incorreto**:
|
|
- O operador pede uma nova regra de negócio complexa para empresas e o agente já cria a função ou arquivo `.ts` sem antes registrar a regra em `DOCUMENTACAO/funcionalidades/empresas/regras-negocio.md` para validação.
|
|
- O agente toma uma decisão técnica grande (ex: trocar a biblioteca de state management) e apenas implementa no código sem gerar um ADR.
|
|
|
|
## Impacto
|
|
O código não é mais a fonte da verdade para o funcionamento esperado, mas sim a *implementação* da verdade registrada na documentação. Isso garante rastreabilidade, reduz dependência de memória implícita de sessões passadas e facilita a manutenção por humanos e outras instâncias do agente.
|
|
|
|
## Referências
|
|
- `DOCUMENTACAO/README` (Manifesto DDD)
|
|
- Skills relacionadas: `documentar-decisao-tecnica`, `documentar-dominio-modulo`, `documentar-regras-negocio`
|