publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
.agent/rules/ddd-documentacao-primeiro.md
Luiz Silva b92dc7b06e docuemntação
2026-08-12 14:01:38 -03:00

3.5 KiB
Raw Blame History

type name description scope trigger priority updatedAt
rule ddd-documentacao-primeiro Regra global que exige a documentação de novos artefatos antes da implementação (Documentation-Driven Development). global always_on alta 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, módulo, 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/ utilizando o template apropriado da respectiva categoria.

Protocolo DDD

Para toda nova demanda ou funcionalidade, siga rigorosamente os passos abaixo:

  1. Identificar Categoria: Analisar a demanda e determinar em qual(is) categoria(s) de documentação ela se encaixa (arquitetura, módulos, regras-negócio, contratos, fluxos).
  2. Consultar Template: Consultar o respectivo template em DOCUMENTACAO/<categoria>/_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. O agente cria DOCUMENTACAO/contratos/novo-endpoint detalhando a API e os schemas usando o template. Após aprovação, cria o código na API.

❌ Incorreto:

  • O operador pede uma nova regra de negócio complexa e o agente já cria a função ou arquivo .ts sem antes registrar a regra em DOCUMENTACAO/regras-negocio/ 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