publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
.agent/DOCUMENTACAO
History
Exact
Luiz Silva 2e6db7dda6 chore(agent): padronizar salvamento obrigatorio de evidencias de testes em .evidencias
2026-10-30 11:02:09 -03:00
..
templates chore(agent): padronizar salvamento obrigatorio de evidencias de testes em .evidencias 2026-10-30 11:02:09 -03:00
INDICE chore(agent): remover permissoes de commit da IA no projeto e wiki (apenas sugerir texto) e manter push automatico exclusivo no .agent 2026-10-14 17:53:33 -03:00
INDICE.md chore(agent): remover permissoes de commit da IA no projeto e wiki (apenas sugerir texto) e manter push automatico exclusivo no .agent 2026-10-14 17:53:33 -03:00
README chore(agent): remover permissoes de commit da IA no projeto e wiki (apenas sugerir texto) e manter push automatico exclusivo no .agent 2026-10-14 17:53:33 -03:00
README.md chore(agent): remover permissoes de commit da IA no projeto e wiki (apenas sugerir texto) e manter push automatico exclusivo no .agent 2026-10-14 17:53:33 -03:00

README.md

type name description updatedAt
structural README Manifesto e matriz canônica dos 6 pilares do Documentation-Driven Development (DDD) 2026-10-14

Documentation-Driven Development (DDD)

Manifesto

No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, módulo, tela, API, decisão técnica) deve ser implementado sem documentação prévia no local adequado. A documentação é a especificação viva e o contrato formal do sistema.

Princípios Fundamentais

  1. Doc First — Nenhum artefato novo sem documentação prévia.
  2. Doc como Contrato — A documentação é a especificação; o código a implementa.
  3. Código Satisfaz Doc — Se o código diverge da documentação, o código está incorreto.
  4. Sincronia Obrigatória — Mudança no código \rightarrow atualização da doc; mudança na doc \rightarrow atualização no código.
  5. Localização Canônica — Cada nível de documentação tem seu destino formal exclusivo.
  6. Leitura Antes de Escrita — Antes de alterar ou criar, ler o que já existe.

A Matriz Canônica dos 6 Pilares

Pilar Escopo / Destino Formato Público Conteúdo Obrigatório
1. Código-Fonte .ts, .vue, .js JSDoc + comentários inline Desenvolvedores / IA Comentários claros e coerentes quanto à aplicação prática e contexto de negócio.
2. Ajuda na Tela (UI) *-front/.../{componente}.ajuda.md Markdown co-localizado Usuários da UI Para modalX.vue, o arquivo DEVE ser modalX.ajuda.md. Explica objetivo, botões, campos e instruções de uso.
3. Wiki do Usuário <modulo-wiki>/<modulo-id>/ Markdown (VitePress) Usuários / Clientes Aplicação VitePress voltada ao acesso dos usuários. Manuais operacionais, tutoriais de uso, conceitos de negócio e fluxos da aplicação. Arquivos e mídias pesadas no MinIO Paiol.
4. Wiki de Desenvolvimento <modulo-wiki>/dev/<modulo-id>/ Markdown (VitePress) Desenvolvedores / Arquitetos Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica, modelos de banco, regras de negócio ({modulo}.regras-negocio.md), filas BullMQ, CRONs e ADRs.
5. Integração de IA Rota Backend /llm.md Markdown dinâmico Agentes de IA / LLMs Catálogo vivo de schemas Zod, enums canônicos e contratos de API para consumo por LLMs.
6. Memória das Ações da IA e Identidade <base_projeto>/memorias-ia/ YAML / Markdown Agentes de IA / Auditoria Arquivo mandatório modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso, modulo-wiki), índice central historico-acoes.md (Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte) e arquivos dedicados de sessão sessao-AAAA-MM-DD-slug.md.

ℹ️ Arquitetura VitePress (<modulo-wiki>, padrão: ../wiki) e Identidade do Projeto:

  • <modulo-wiki> é uma aplicação VitePress cujo caminho é definido em memorias-ia/modulo.yml (fallback padrão: ../wiki/).
  • <modulo-wiki>/<modulo-id>/ representa a documentação de acesso dos usuários e operadores (onde <modulo-id> provém de memorias-ia/modulo.yml).
  • <modulo-wiki>/dev/<modulo-id>/ representa a documentação de acesso interno pela equipe de desenvolvimento e arquitetura.
  • O arquivo <base_projeto>/memorias-ia/modulo.yml é obrigatório em todos os projetos.
  • Mídias e Arquivos no MinIO Paiol: Imagens, manuais em PDF, gravações em vídeo e anexos pesados NUNCA devem ser commitados no Git da Wiki; devem ser enviados ao MinIO Paiol via ./.agent/scripts/upload-paiol-wiki.sh e referenciados via URLs https://paiol.idz.one/wiki/....

Hub Central de Templates (DOCUMENTACAO/templates/)

Todos os modelos canônicos para instanciar a documentação nos projetos residem em DOCUMENTACAO/templates/:

Pilar / Categoria Destino Canônico no Projeto Template Canônico
Identidade do Módulo (Pilar 6) <base_projeto>/memorias-ia/modulo.yml modulo.yml.template
Índice de Ações da IA (Pilar 6) <base_projeto>/memorias-ia/historico-acoes.md historico-acoes.md.template
Registro de Sessão da IA (Pilar 6) <base_projeto>/memorias-ia/sessao-AAAA-MM-DD-slug.md sessao-memoria.md.template
Domínio do Módulo (Pilar 3 e 4) <modulo-wiki>/<modulo-id>/index.md modulo-dominio.md.template
Regras de Negócio (Pilar 4) <modulo-wiki>/dev/<modulo-id>/<servico>.regras-negocio.md regra-negocio.md.template
Decisões Arquiteturais - ADR (Pilar 4) <modulo-wiki>/dev/<modulo-id>/adrs/ adr.md.template
Ajuda na Tela / UI (Pilar 2) *-front/src/.../{componente}.ajuda.md ajuda-tela.md.template
Contratos de API (Pilar 5 e 4) Rota /llm.md ou <modulo-wiki>/dev/<modulo-id>/contratos/ contrato-api.md.template
Fluxos e Telas (Pilar 3 e 4) <modulo-wiki>/<modulo-id>/fluxos/ fluxo-usuario.md.template

Workflow DDD

  1. Receber Demanda: Identificar os pilares impactados.
  2. Documentar Prévia: Criar/atualizar a documentação no destino apropriado usando templates padronizados.
  3. Validar com Operador: Apresentar a documentação preliminar para alinhamento e aprovação.
  4. Implementar: Codificar de acordo com a documentação aprovada.
  5. Validar: Testar e analisar para assegurar que o código satisfaz a documentação em 100%.
  6. Sincronizar & Registrar Memória: Sincronizar ajustes finais e registrar a sessão em <base_projeto>/memorias-ia/.

Referências

  • Rule: rules/ddd-documentacao-primeiro.md
  • Rule: rules/identidade-modulo.md
  • Rule: rules/jsdoc-padrao.md
  • Rule: rules/regras-negocio-md.md
  • Skill: skills/adicionar-ajuda/SKILL.md
  • Skill: skills/documentar-dominio-modulo/SKILL.md
  • Skill: skills/documentar-decisao-tecnica/SKILL.md
  • Skill: skills/diagnosticar-lacunas-documentacao/SKILL.md
  • Skill: skills/aprimora-ia/SKILL.md