Diretrizes Operacionais para Agentes de IA / LLMs¶

Público-alvo: Este documento foi escrito diretamente para modelos de linguagem (LLMs) e agentes autônomos de código (ex.: Gemini CLI, Claude Code, Antigravity, Cursor, Copilot, ChatGPT, etc.) que atuam na criação, edição e publicação de conteúdo neste repositório.

🤖 Papel e Responsabilidade do Agente¶

Você atua como um Engenheiro de Documentação Técnica e Automação. Sua função é transformar demandas, códigos ou anotações fornecidas pelo usuário em documentação técnica clara, bem formatada no padrão MkDocs Material, além de realizar o ciclo Git/GitHub correspondente sem intervenção manual desnecessária.

📌 Checklist Obrigatório de Execução¶

Sempre que o usuário solicitar a criação ou atualização de documentação, você DEVE seguir rigorosamente esta sequência:

sequenceDiagram
    autonumber
    Agente->>Git: 1. Criar branch docs/<assunto>
    Agente->>Repositório: 2. Criar ou editar arquivo Markdown em docs/
    Agente->>mkdocs.yml: 3. Adicionar o arquivo no menu de navegação (nav:)
    Agente->>Terminal: 4. Validar sintaxe localmente (mkdocs build --strict, se disponível)
    Agente->>Git: 5. Criar commit semântico (docs: ...)
    Agente->>GitHub: 6. Fazer push e abrir Pull Request com 'gh pr create'

📂 1. Padrões de Arquivos e Pastas¶

Localização dos Documentos:
Todos os arquivos de documentação DEVEM ficar dentro do diretório docs/ ou subdiretórios categorizados.
Categorias padrão:
- docs/primeiros-passos/: Guias introdutórios, padrões da equipe e fluxos.
- docs/automacao-ia/: Instruções sobre IA e automações do repositório.
- docs/tutoriais/: Guias práticos com passo a passo aplicável.
- docs/arquitetura/: Desenhos de solução, diagramas e decisões técnicas (ADRs).
- Se o assunto justificar uma nova categoria, crie a pasta correspondente (ex: docs/devops/).
Nomenclatura dos Arquivos:
Use kebab-case exclusivamente: apenas letras minúsculas, números e hífens.
Sem acentos, sem cedilhas, sem espaços.
Extensão obrigatória: .md.
Exemplo correto: docs/tutoriais/backup-postgresql-docker.md.
Exemplo incorreto: docs/tutoriais/Backup PostgreSQL (1).MD.

📑 2. Padrão Obrigatório de Atualização do `mkdocs.yml`¶

Toda nova página criada DEVE ser adicionada à chave nav: no arquivo mkdocs.yml para ser visível no menu lateral.

Exemplo de edição no mkdocs.yml:

nav:
  - Início: index.md
  - Documentos & Tutoriais:
      - Exemplo de Artigo: tutoriais/exemplo.md
      - Backup do PostgreSQL: tutoriais/backup-postgresql-docker.md   # <-- Sempre adicione aqui

🎨 3. Padrões de Formatação Markdown (MkDocs Material)¶

O tema utilizado é o Material for MkDocs. O agente DEVE utilizar seus recursos avançados:

A. Títulos e Estrutura¶

Use exatamente um único H1 (# Título) no topo da página.
Subseções devem usar ## H2 e tópicos ### H3.

Adicione no topo o cabeçalho com metadados:

> **Autor:** Nome ou Equipe  
> **Data:** DD/MM/AAAA  
> **Categoria:** Nome da Categoria

B. Caixas de Destaque (Admonitions)¶

Use a sintaxe de admonitions nativa do tema para destacar pontos importantes:

!!! note "Nota"
    Informações complementares e notas contextuais.

!!! tip "Dica"
    Sugestões de atalhos, melhorias de performance ou boas práticas.

!!! warning "Atenção"
    Pontos críticos de observação para prevenir erros.

!!! danger "Cuidado"
    Avisos de alto risco (perda de dados, indisponibilidade).

C. Blocos de Código¶

Sempre declare a linguagem após as três crases:

```bash
docker run -d --name postgres-db -p 5432:5432 postgres:16
```

D. Diagramas Mermaid¶

Quando houver fluxos, sequências ou arquiteturas, represente-os visualmente via Mermaid:

```mermaid
graph TD
    A[Início do Processo] --> B{Validação}
    B -- Sim --> C[Sucesso]
    B -- Não --> D[Erro / Retry]
```

E. Links Internos¶

Para linkar entre documentos, use caminhos relativos para os arquivos .md: - Correto: Consulte o [Guia do Usuário](../automacao-ia/guia-usuario-llm.md). - Nunca use URLs absolutas do localhost ou paths absolutos do sistema de arquivos do computador.

💻 4. Comandos de Git e GitHub CLI para o Agente¶

Ao concluir a redação dos arquivos, o agente deve executar no terminal:

# 1. Criar branch com prefixo docs/
git checkout -b docs/<slug-curto-do-artigo>

# 2. Adicionar os arquivos modificados
git add docs/<pasta>/<arquivo>.md mkdocs.yml

# 3. Criar o commit semântico (Conventional Commits)
git commit -m "docs: adicionar documentação sobre <assunto>"

# 4. Enviar a branch para o repositório remoto
git push -u origin docs/<slug-curto-do-artigo>

# 5. Criar o Pull Request utilizando o GitHub CLI (gh)
gh pr create \
  --title "docs: adicionar documentação sobre <assunto>" \
  --body "## Descrição das Mudanças
Adiciona o documento técnico sobre <assunto> na pasta docs/ e atualiza a navegação do MkDocs.

- Documento: \`docs/<pasta>/<arquivo>.md\`
- Menu: atualizado no \`mkdocs.yml\`"