publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

agente documentação

Browse source
This commit is contained in:
Luiz Silva 2026-08-12 15:26:26 -03:00
parent b92dc7b06e
commit 5f11352ab7
11 changed files with 239 additions and 158 deletions
Download patch file Download diff file Expand all files Collapse all files

10
rules/ddd-documentacao-primeiro.md
View file

@ -14,14 +14,14 @@ updatedAt: "2026-08-12"
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.
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 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-*`.
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.
@ -38,10 +38,10 @@ Esta regra pode ser ignorada apenas para alterações triviais que não impactam
## 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.
- 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 e o agente já cria a função ou arquivo `.ts` sem antes registrar a regra em `DOCUMENTACAO/regras-negocio/` para validação.
- 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