Guia do Usuário: Produção de Documentos com LLMs¶

Este guia orienta os colaboradores sobre como utilizar Modelos de Linguagem (LLMs) e Agentes de IA (como Gemini CLI, Claude Code, Antigravity, Cursor, ChatGPT, etc.) para criar, atualizar e publicar documentos nesta base de conhecimento de forma rápida e padronizada.

🎯 Por que usar LLMs para a Documentação?¶

As LLMs conectadas a ferramentas de terminal e repositório não apenas redigem textos técnicos com clareza, mas também podem executar o ciclo completo de engenharia: 1. Criar a branch de trabalho. 2. Escrever o artigo em Markdown no padrão do MkDocs Material. 3. Inserir o artigo no menu de navegação de mkdocs.yml. 4. Criar o commit semântico. 5. Fazer o push e abrir o Pull Request no GitHub com o comando gh pr create.

[!IMPORTANT] A LLM deve seguir as regras operacionais definidas no documento:
📄 Instruções Operacionais para o Agente / LLM.
Você pode simplesmente passar esse link ou o arquivo AGENTS.md para que o agente saiba exatamente o que fazer.

📥 Pré-requisito Inicial: Baixar o Repositório com o Git¶

Antes de trabalhar com a LLM ou agente autônomo, você deve clonar o repositório do projeto para a sua máquina local:

# 1. Baixar (clonar) o repositório
git clone https://github.com/f4bioss/gestao-conhecimento.git

# Ou se preferir usar SSH:
# git clone git@github.com:f4bioss/gestao-conhecimento.git

# 2. Entrar no diretório do projeto
cd gestao-conhecimento

[!TIP] Caso já tenha baixado o repositório anteriormente, atualize sua branch main antes de solicitar novas tarefas à LLM:
git checkout main && git pull origin main

🪜 Passo a Passo: O Ciclo de Trabalho do Usuário¶

O processo de criação de documentação utilizando IA segue 4 passos simples:

Passo 1: Reunir o Conteúdo Bruto¶

Separe o tema, comandos de terminal executados, rascunhos, atas de reunião ou links que você deseja documentar. Não se preocupe com a formatação estética neste momento.

Passo 2: Acionar a LLM / Agente de IA (Geração Automatizada)¶

É neste passo que a LLM assume o trabalho pesado. Abra o seu assistente de IA (Antigravity, Gemini CLI, Claude Code, Cursor, ChatGPT, etc.) no projeto e envie as instruções: 1. Referencie o arquivo de diretrizes da IA: docs/automacao-ia/instrucoes-para-agente.md (ou AGENTS.md). 2. Utilize um dos Modelos de Prompts Prontos listados na seção abaixo, colando o conteúdo bruto que você reuniu no Passo 1. 3. A LLM irá executar de forma assistida ou autônoma: - Criar uma nova branch Git (docs/<nome-do-artigo>). - Escrever o arquivo Markdown formatado no padrão MkDocs Material (títulos, caixas de destaque, blocos de código e diagramas Mermaid). - Registrar o documento no menu nav: em mkdocs.yml. - Criar o commit semântico (ex: docs: adicionar ...). - Fazer o push para o GitHub e abrir o Pull Request utilizando a CLI gh pr create.

Passo 3: Validar a Entrega via Preview do Firebase¶

Com o Pull Request aberto pela LLM, o GitHub Actions compilará o MkDocs e o bot do Firebase Hosting publicará um link de Preview temporário nos comentários do PR. Abra o link para revisar visualmente a documentação pronta.

Passo 4: Fazer o Merge para Produção¶

Se a revisão visual estiver aprovada, aprove e faça o Merge do Pull Request no GitHub. Em cerca de 1 minuto o site oficial estará atualizado.

💡 Modelos de Prompts Prontos para Copiar e Colar¶

Ao executar o Passo 2, use os modelos de instrução abaixo com a sua LLM ou Agente de IA:

Cenário 1: Criar um Artigo Técnico Completo com Pull Request¶

Por favor, aja conforme as regras descritas em "docs/automacao-ia/instrucoes-para-agente.md".

Preciso criar um novo documento técnico com as seguintes informações:
- Título: [Ex: Guia de Backup do PostgreSQL com Docker]
- Categoria / Subpasta: [Ex: tutoriais / docs/tutoriais/]
- Conteúdo principal: [Cole aqui suas notas, comandos soltos, rascunho ou links de referência]

Tarefas que você deve executar:
1. Crie uma branch com o padrão: docs/backup-postgresql-docker
2. Escreva o documento Markdown usando as caixas de destaque (admonitions), blocos de código com destaque de sintaxe e, se aplicável, um diagrama Mermaid.
3. Adicione o novo documento ao menu de navegação em "mkdocs.yml".
4. Faça o commit semântico (ex: "docs: adicionar guia de backup postgresql").
5. Envie a branch para o GitHub e abra um Pull Request com o comando `gh pr create` contendo um resumo das mudanças.

Cenário 2: Atualizar ou Expandir um Documento Existente¶

Por favor, atualize o documento "docs/caminho/do-arquivo.md" com base nas seguintes notas:
[Inserir os novos passos, mudanças de versão ou avisos]

Lembre-se de:
1. Criar uma nova branch (ex: docs/atualizar-guia-X).
2. Manter a integridade da formatação MkDocs já existente.
3. Fazer o commit semântico e abrir o Pull Request.

Cenário 3: Transformar Anotações Rápidas ou Reunião em Documento¶

Tenho as seguintes anotações brutas de uma reunião técnica:
"""
[Cole aqui o texto desformatado, anotações de chat, atas de reunião, etc.]
"""

Estruture essas anotações no formato padrão da nossa base de conhecimento:
1. Defina um título claro e objetivo.
2. Separe por Contexto, Pré-requisitos, Passo a Passo e Referências.
3. Inclua um diagrama Mermaid explicativo se houver fluxo de processos.
4. Salve na pasta docs/ apropriada e adicione ao menu no "mkdocs.yml".

🔍 Como Validar a Entrega da LLM¶

Depois que o agente abrir o Pull Request: 1. Acesse o Pull Request no GitHub (https://github.com/f4bioss/gestao-conhecimento/pulls). 2. O GitHub Actions compilará o MkDocs e o bot do Firebase Hosting adicionará um comentário com o link de Preview temporário. 3. Clique no link para verificar como o artigo ficou renderizado visualmente (tabelas, blocos de código e diagramas). 4. Se estiver tudo correto, basta clicar em Merge pull request! O site oficial em produção será atualizado automaticamente em cerca de 1 minuto.