🚀 Gemini CLI Context Framework

Este repositório é um template padronizado para transformar o Gemini CLI num agente autônomo de infraestrutura. Ele utiliza uma arquitetura de contexto separada por Identidade (Persona), Regras (Premissas) e Conhecimento Técnico (Skills).

📂 Estrutura do Framework

.  
├── .gemini/  
│   ├── personas/              # Identidades da IA (Ex: Arquiteto Debian, Auditor Cloud)  
│   │   └── Ops_Architect.md   # Persona principal focada em Debian 12 e Docker imutável
│   └── skills/                # Conhecimentos modulares (Ex: terraform, ansible, k8s)  
├── scripts/                   # Automação e entrypoints para execução da CLI
│   └── ask-gemini.sh          # Interface CLI que monta o super-prompt  
├── GEMINI.md                  # Instruções de comportamento e tom de voz  
├── GUIA.md                    # Runbook técnico do laboratório/ambiente  
├── PREMISSAS.md               # Guardrails, regras de segurança e workflow de Git  
├── README.md                  # Documentação do framework  
└── TESTS.md                   # Protocolos de validação de código

🛠️ Como Funciona o Fluxo

O script ask-gemini.sh consolida quatro camadas de informação antes de enviar a pergunta para a IA:

1. Persona: Define o perfil sênior (ex: Debian Ops Architect).
2. Contexto Base: Carrega o GEMINI.md (comportamento) e PREMISSAS.md (segurança).
3. Skills: (Opcional) Adiciona conhecimentos específicos via flag -s.
4. Tarefa: O seu comando ou dúvida técnica.

---

🚀 Como Utilizar

Preparação do Contexto

Ao iniciar um novo projeto de infraestrutura, copie esta estrutura e personalize o GUIA.md e o PREMISSAS.md com as especificidades do novo ambiente.

Execução

Utilize o script ask-gemini.sh para realizar consultas. O script anexa automaticamente os arquivos de contexto ao seu comando:

chmod +x scripts/ask-gemini.sh  
./scripts/ask-gemini.sh "Crie um arquivo de configuração para o servidor Nginx seguindo o padrão do GUIA.md"

Exemplos de Comandos

• Consulta Simples (Usa a Persona padrão):

./scripts/ask-gemini.sh "Crie um docker-compose para um servidor Nginx"

• Consulta com Skills Adicionais:

./scripts/ask-gemini.sh -s terraform,security "Provisione um bucket S3 seguindo as premissas"

• Trocar de Persona:

./scripts/ask-gemini.sh -p Cloud_Architect "Desenhe uma solução multi-region"

---

🧠 Seleção de Skills por Cenário

Para otimizar o consumo de tokens e garantir que o Gemini tenha o foco técnico correto para a tarefa, utilize a flag -s combinando as habilidades necessárias para cada contexto.

Cenário de Uso	Flag Sugerida	Objetivo Técnico
Laboratório Local (Vagrant/Docker)	-s networking,docker	Configuração de serviços de rede (DHCP/DNS) e infraestrutura imutável local.
Provisionamento em Nuvem (AWS/Azure)	-s iac-terraform,documentation	Tradução de arquitetura para IaC, gestão de Remote State e diagramas Mermaid.
Configuração de Servidores (Ansible)	-s ansible-config,identity-ldap	Automação de SO via Roles e integração de usuários com OpenLDAP (LDAPS).
Documentação e Auditoria	-s documentation	Atualização de README.md, GEMINI.md e organização de Commits e Tags.
Full Stack Ops (Ciclo Completo)	-s docker,ansible-config,documentation	Do build da imagem à configuração do host, com registro completo da atividade.

Como combinar múltiplas skills:

Você pode passar múltiplos arquivos separados por vírgula (sem espaços) para o script:

Exemplo: Criar um servidor web no Debian 12 com Docker e documentar a alteração

./scripts/ask-gemini.sh -s docker,documentation "Provisione um container Nginx otimizado e gere o diagrama de arquitetura."  

---

🛡️ Workflow de Desenvolvimento

Conforme definido no PREMISSAS.md, a IA está instruída a:

• Solicitar a criação de uma branch antes de propor alterações em ficheiros.
• Fornecer os comandos git checkout -b e git commit necessários.
• Validar toda a entrega com base nos critérios do TESTS.md.

---

🧩 Configuração dos MCPs (Braços de Execução)

Para que o assistente consiga interagir com o sistema e com os ficheiros do laboratório, é necessário registar os servidores MCP na Gemini CLI. Estes comandos devem ser executados uma única vez no host:

1. Filesystem (Acesso a ficheiros local)

Permite que a IA leia e escreva no diretório do projeto.

gemini mcp add filesystem npx -y @modelcontextprotocol/server-filesystem $(pwd)

2. Sequential Thinking (Raciocínio Lógico)

Melhora a capacidade da IA de resolver problemas complexos de infraestrutura por etapas.

gemini mcp add thinking npx -y @modelcontextprotocol/server-sequential-thinking

3. Docker (Gestão de Containers)

Permite à IA listar, inspeccionar e validar containers e redes Docker no host.

gemini mcp add docker npx -y mcp-server-docker

Nota: Estes comandos registam os MCPs permanentemente na base de dados da sua CLI. Pode verificar os MCPs ativos com:

gemini mcp list

---

🦾 MCPs de Automação e DevOps

1. Git (Gestão de Versão) - Substitua $(pwd) pelo caminho do seu repo se necessário

gemini mcp add git npx -y @modelcontextprotocol/server-git --repository $(pwd)

2. Shell (O "Coringa" para Terraform e Ansible)

ATENÇÃO: Use com cautela, pois dá acesso ao terminal do host.

gemini mcp add shell npx -y mcp-server-shell

3. Fetch (Busca de Documentação Técnica online)

gemini mcp add fetch npx -y @modelcontextprotocol/server-fetch

---

🎬 Fluxo de Trabalho em Ação (Exemplo Prático)

Para entender como a Persona, as Skills e os MCPs colaboram, imagine o seguinte cenário: você precisa iniciar um novo serviço de DNS.

Prompt do Usuário:

"Crie uma nova branch chamada infra-dns, gere o ficheiro main.tf para um servidor DNS no Debian 12 e execute o terraform plan para validarmos."

⚙️ O que acontece nos bastidores:

• Raciocínio (Persona + Thinking MCP): O Ops Architect analisa o pedido e utiliza o Sequential Thinking para planejar as etapas: (1) Git, (2) Filesystem, (3) Shell.

• Preparação (Git MCP): O assistente executa o comando de criação de branch automaticamente, respeitando a regra de workflow definida em PREMISSAS.md.

• Escrita (Filesystem MCP + Skill Terraform): Com base na sua Skill de Terraform, a IA escreve o código main.tf seguindo os padrões de modularidade e Remote State.

• Validação (Shell MCP): O assistente executa o terraform plan no seu terminal e analisa a saída para garantir que não existam erros de sintaxe ou conflitos de recursos.

• Entrega: Você recebe o código pronto, com a branch criada e a validação técnica concluída.

---

🛠️ Troubleshooting

Caso encontre comportamentos inesperados ao utilizar o framework, verifique os pontos abaixo:

1. Erro de Permissão no MCP Filesystem

Sintoma: A IA alega que não consegue ler os ficheiros PREMISSAS.md ou GUIA.md.

Solução: Certifique-se de que registou o MCP apontando para o diretório atual ($(pwd)). Se mudou a pasta do projeto de lugar, é necessário remover e adicionar o MCP novamente para atualizar o caminho no banco de dados da CLI.

2. Docker Socket Não Encontrado

Sintoma: O comando de diagnóstico do Docker falha ou a IA diz que não existem containers ativos.

Solução: Verifique se o seu usuário tem permissão para aceder ao socket do Docker (/var/run/docker.sock). No Debian, pode ser necessário adicionar o seu usuário ao grupo docker:

sudo usermod -aG docker $USER

Lembre-se de reiniciar a sessão após este comando.

3. Falha na Execução do Script ask-gemini.sh

Sintoma: command not found ou permission denied.

Solução: Verifique se o script tem permissão de execução (chmod +x scripts/ask-gemini.sh) e se o binário gemini está presente no seu PATH.

4. Conflito de Contexto (Tokens Excedidos)

Sintoma: Respostas truncadas ou erro de limite de contexto ao usar a flag -u.

Solução: A flag -u lê todos os ficheiros .sh, .tf e .yml. Se o diretório contiver ficheiros muito grandes ou binários acidentais, o limite de tokens pode ser atingido. Utilize o .gitignore para manter a pasta limpa.

5. Erro de Sintaxe nos MCPs

Sintoma: A CLI não reconhece os comandos mcp add.

Solução: Verifique se a sua versão da Gemini CLI está atualizada. Utilize gemini mcp list para validar quais braços estão configurados corretamente.

---

💖 Apoie este Projeto Open Source

Se você gosta dos meus projetos, considere:

• 🏆 Me indicar para o GitHub Stars Indicar Aqui
• ⭐ Dar uma estrela nos repositórios
• 🐛 Reportar bugs ou melhorias
• 🤝 Contribuir com código

---

⚖️ Licença

Distribuído sob a licença Apache 2.0. Esta licença oferece permissão para uso, modificação e distribuição, além de garantir proteção contra disputas de patentes para colaboradores e usuários. Veja o arquivo LICENSE para mais informações.