minions-ai-agents/src/knowledge/standards/documentation_standards.md

📚 Padrões de Documentação (O Protocolo "Bibliotecário")

Público: Arthur Mendes (Docs Gen) & Sherlock Holmes. Objetivo: Se não está escrito, não existe.

[!CRITICAL] O Mandato Arthur: "Uma funcionalidade sem documentação é apenas um bug que ainda não aconteceu. Escreva para o humano que está cansado, com raiva e consertando isso às 3 da manhã."

1. 📂 A Estrutura "Dewey Decimal"

A pasta docs/ é sagrada. Adira a esta estrutura:

• docs/manual_desenvolvimento/: Como construir/contribuir.
• docs/api/: Specs OpenAPI e Guias de Referência.
• docs/ops/: Runbooks, Guias de Deploy e incident_reports/.
• docs/architecture/: As decisões de dossier_arquitetura.md (ADRs).

2. 📝 Estilo de Escrita (Claro & Conciso)

• Língua: Português (PT-BR) para Docs Internos. Inglês para Comentários de Código.
• Tom: Profissional, Direto, Sem Enrolação.
• Formato: GitHub Flavored Markdown (GFM).

A Regra "TL;DR"

Todo documento maior que 50 linhas DEVE ter um ## Resumo (TL;DR) no topo.

3. 🤖 Auto-Geração vs. Escrito à Mão

• Auto-Gerado:
  • Referências de API (Swagger/OpenAPI).
  • Documentação de Template Zabbix (usando generate_template_docs.py).
• Escrito à Mão:
  • Decisões "Por que" (ADRs).
  • Post-Mortems.
  • Tutoriais ("Como adicionar um novo Agente").

4. 💀 Post-Mortems (A Caixa Preta)

Quando um incidente ocorre ("Sev1"), um Post-Mortem é OBRIGATÓRIO. Template:

1. Linha do Tempo: O que aconteceu e quando? (UTC).
2. Causa Raiz: O "Porquê" técnico. (5 Porquês).
3. Resolução: Como foi corrigido?
4. Prevenção: IDs de Jira/Tarefa para correções permanentes.

5. 🔍 O Checklist de Auditoria do Bibliotecário

Antes de fazer merge de um PR:

• Readme: Atualizei o README.md principal se mudei passos de setup?
• Novo Arquivo: Se adicionei src/novo_modulo.py, existe um docs/manual_desenvolvimento/novo_modulo.md?
• Links: Todos os links relativos [Tipo Assim](./arquivo.md) estão funcionando?