Esse formato foi revolucionário, mas tem um limite evidente: ele mantém a IA do lado de fora da operação.

O OpenCode aponta para outra direção. Ele não trata a IA apenas como uma caixa de perguntas e respostas. Ele coloca o agente dentro do ambiente onde o trabalho técnico acontece: o terminal, o editor, o repositório, os arquivos, os comandos, as permissões e as ferramentas externas.

A diferença parece pequena, mas é estrutural.

Quando a IA conversa, ela ajuda. Quando ela opera com contexto, ferramentas e governança, ela começa a virar infraestrutura de trabalho.

O que é o OpenCode​

O OpenCode é um agente de programação open source desenhado para funcionar no terminal, no IDE e também em uma aplicação desktop. Em vez de ser apenas um assistente que responde perguntas sobre código, ele pode explorar uma base, propor mudanças, editar arquivos, rodar comandos e trabalhar com modelos diferentes.

A documentação oficial informa que o OpenCode usa o AI SDK e o Models.dev para suportar mais de 75 provedores de LLM, além de modelos locais. Isso significa que o agente não está preso a um único fornecedor de IA.

Essa característica muda a forma de avaliar a ferramenta. O valor principal do OpenCode não está apenas em “qual modelo ele usa”, mas em como ele organiza o ambiente de execução ao redor do modelo:

- contexto do projeto;
- ferramentas disponíveis;
- permissões de escrita e execução;
- agentes com papéis diferentes;
- skills reutilizáveis;
- provedores intercambiáveis;
- governança do fluxo agentivo.

Em outras palavras: o OpenCode é menos um “chat para programadores” e mais uma camada operacional para agentes de código.

O problema dos chats de IA no trabalho técnico​

O chat é excelente para raciocinar, explicar, resumir e gerar alternativas. Mas ele é fraco quando o trabalho exige continuidade operacional.

Em programação, isso aparece rapidamente. O desenvolvedor precisa explicar o contexto, colar arquivos, copiar respostas, aplicar patches, rodar testes, voltar com logs, pedir ajustes e repetir o ciclo. O gargalo deixa de ser a inteligência do modelo e passa a ser a fricção entre o modelo e o ambiente real.

O mesmo problema existe fora da programação.

Em engenharia, construção civil, automação de processos e gestão técnica, boa parte do trabalho não é apenas “responder uma pergunta”. É abrir documentos, interpretar padrões, consultar histórico, criar chamados, atualizar tarefas, gerar registros, comparar versões, aplicar procedimentos e deixar rastreabilidade.

A pergunta relevante passa a ser:

> Como tirar a IA da janela de conversa e colocá-la dentro do fluxo real de trabalho, sem perder controle?

O OpenCode é interessante justamente porque mostra uma resposta prática para essa pergunta.

O agente como operador de ambiente​

Um agente útil precisa de mais do que um bom modelo. Ele precisa de ambiente.

No caso do OpenCode, esse ambiente inclui o repositório, o terminal, os arquivos, os comandos e a configuração do projeto. Isso permite que o agente aja com base no estado real do trabalho, não apenas em uma descrição parcial enviada pelo usuário.

Esse é um salto importante.

Um assistente convencional pode dizer:

> “Você provavelmente precisa alterar esta função.”

Um agente operacional pode dizer:

> “Eu encontrei a função, verifiquei onde ela é chamada, propus um plano, editei os arquivos, rodei os testes e mostrei o diff.”

Essa diferença é o núcleo da nova geração de ferramentas de IA. O ganho não vem apenas de respostas melhores. Vem da redução do atrito entre intenção, execução e verificação.

Agentes com papéis diferentes​

Um dos pontos mais importantes do OpenCode é a separação entre agentes com funções e permissões distintas.

A documentação do OpenCode trabalha com agentes como `build`, `plan`, `general` e `explore`. A ideia é simples e poderosa: nem todo agente deve poder fazer tudo.

Um agente de planejamento pode analisar a base e propor caminhos sem modificar arquivos. Um agente de construção pode editar, executar comandos e implementar mudanças. Subagentes podem explorar partes específicas do problema.

Essa separação importa porque autonomia sem governança é risco.

Em qualquer operação técnica séria, o problema não é apenas “a IA consegue fazer?”. A pergunta correta é:

- ela pode fazer isso agora?
- com quais permissões?
- em qual escopo?
- deixando qual registro?
- com qual possibilidade de revisão?
- usando quais dados?

Esse modelo é diretamente transferível para outras áreas.

Em uma operação de construção civil, por exemplo, poderíamos ter agentes com papéis diferentes:

- um agente que lê reuniões e identifica tarefas;
- um agente que transforma decisões em chamados;
- um agente que consulta documentos técnicos;
- um agente que atualiza cronogramas;
- um agente que revisa integrações;
- um agente que apenas planeja, sem executar alterações.

O princípio é o mesmo: agentes não devem ser “superusuários genéricos”. Eles devem operar com papéis, limites e procedimentos.

Skills: conhecimento operacional reutilizável​

Outro ponto essencial é o suporte a skills.

No OpenCode, skills são definidas por arquivos `SKILL.md`. Elas funcionam como instruções reutilizáveis que o agente pode carregar conforme a tarefa.

Esse detalhe é mais importante do que parece.

Na prática, uma skill transforma conhecimento tácito em procedimento executável pelo agente. Em vez de explicar toda vez como revisar uma API, como criar um changelog, como abrir um chamado ou como testar uma integração, a equipe documenta o procedimento uma vez e o agente passa a ter acesso a esse padrão.

Isso aproxima agentes de IA de algo que empresas já conhecem bem: procedimentos operacionais.

A diferença é que, agora, esses procedimentos não são apenas lidos por pessoas. Eles também podem orientar sistemas que executam trabalho.

Para empresas de engenharia, construção e tecnologia aplicada, esse é um ponto decisivo. O valor não está só em “usar IA”. Está em transformar padrões internos em instruções operáveis por agentes.

Modelos gratuitos: o laboratório real dos agentes de código​

Um dos aspectos mais interessantes do OpenCode é que ele não depende de um único modelo.

A documentação oficial de modelos afirma que o OpenCode suporta mais de 75 provedores e modelos locais. Além disso, existe o OpenCode Zen, uma camada opcional com uma lista curada de modelos testados pela equipe do OpenCode.

Na versão atual da documentação do Zen, os modelos listados como gratuitos por tempo limitado são:

Essa lista é relevante porque mostra uma mudança importante: o futuro dos agentes não depende necessariamente de escolher um único modelo vencedor. Ele depende de orquestrar modelos diferentes para tarefas diferentes.

Nem toda tarefa precisa de um modelo frontier caro. Em muitos casos, o melhor modelo é aquele que resolve bem o problema, responde rápido, custa pouco e opera dentro do nível de risco aceitável.

Comparando modelos gratuitos com proprietários​

Benchmarks públicos ajudam a entender essa diferença.

O Artificial Analysis mede modelos em critérios como inteligência, velocidade, preço, janela de contexto e desempenho em tarefas agentivas. Nenhum benchmark deve ser lido como verdade absoluta, mas eles ajudam a comparar ordens de grandeza.

Alguns dados atuais são especialmente úteis para pensar o OpenCode:

A leitura mais interessante não é “gratuitos vencem proprietários” ou “proprietários continuam melhores”. Essa dicotomia é pobre.

A leitura correta é outra:

> Modelos gratuitos ou de baixo custo já são bons o bastante para ocupar uma parte grande da camada operacional do trabalho agentivo.

Eles podem ser suficientes para:

- explorar uma base de código;
- explicar arquivos;
- gerar scripts auxiliares;
- sugerir refatorações;
- escrever documentação;
- fazer triagem de erros;
- operar tarefas repetitivas;
- atuar como subagentes especializados.

Já modelos proprietários de fronteira continuam fazendo sentido para decisões mais críticas, raciocínio mais difícil, tarefas longas, ambiguidades relevantes ou contextos em que a taxa de erro precisa ser menor.

O ponto é que uma arquitetura madura de agentes não precisa escolher apenas um dos caminhos. Ela pode combinar.

O que cada modelo gratuito sugere na prática​

Qwen3.6 Plus Free​

O Qwen3.6 Plus aparece no Artificial Analysis com índice 50, contexto de 1M tokens e suporte a texto, imagem e vídeo como entrada. No OpenCode Zen, sua variante Free aparece como gratuita por tempo limitado.

Isso o torna um candidato forte para tarefas mais complexas, especialmente quando o contexto é grande. A ressalva prática é que ele aparece como mais lento e muito verboso. Para um agente de terminal, isso pode ser bom em planejamento, mas ruim quando a tarefa pede ciclos rápidos.

Uso recomendado:

- planejamento de mudanças grandes;
- leitura de contexto extenso;
- comparação de alternativas técnicas;
- revisão de arquitetura;
- análise de documentação longa.

MiniMax M2.5 Free​

O MiniMax M2.5 aparece no Artificial Analysis com índice 42, velocidade de 92,3 tokens/s, contexto de 205k tokens e licença MIT. A documentação do OpenCode Zen lista a variante MiniMax M2.5 Free como gratuita por tempo limitado.

O perfil é muito interessante para uso operacional: não é o maior índice da lista, mas combina bom desempenho, boa velocidade e preço de referência baixo.

Uso recomendado:

- exploração de base de código;
- refatorações controladas;
- geração de scripts;
- documentação;
- tarefas de rotina com boa relação entre qualidade e velocidade.

Nemotron 3 Super Free​

O Nemotron 3 Super aparece no Artificial Analysis com índice 36, velocidade de 172,8 tokens/s e contexto de 1M tokens. A variante Free aparece no OpenCode Zen como gratuita por tempo limitado.

O ponto forte é claro: velocidade e contexto. Isso pode ser muito útil quando o agente precisa ler muito material, resumir, classificar, navegar em logs ou operar tarefas menos ambíguas.

Uso recomendado:

- leitura de arquivos grandes;
- triagem de logs;
- sumarização operacional;
- classificação de tarefas;
- exploração ampla antes de passar para um modelo mais forte.

Big Pickle​

O Big Pickle é descrito na documentação do OpenCode Zen como um modelo stealth gratuito por tempo limitado. Isso significa que ele pode ser útil para teste e experimentação, mas não oferece a mesma transparência pública de um modelo com página clara de benchmark, especificações e comparativos.

Uso recomendado:

- testes não sensíveis;
- experimentação;
- tarefas descartáveis;
- avaliação interna antes de adoção.

Gratuito não significa sem custo​

Existe uma armadilha comum na adoção de modelos gratuitos: confundir preço zero com risco zero.

A própria documentação do OpenCode Zen informa que os modelos gratuitos estão disponíveis por tempo limitado e que, durante esse período, dados podem ser usados para melhoria do modelo em alguns casos. A seção de privacidade também diferencia a política geral dos provedores e as exceções aplicáveis aos modelos gratuitos.

Isso exige uma regra prática clara:

> Modelo gratuito é excelente para experimentação, código aberto, automações não sensíveis e tarefas de baixo risco. Para código proprietário, contratos, dados de cliente, chaves, logs internos e decisões críticas, use modelos com política adequada de retenção e privacidade — ou modelos locais.

Essa discussão é central para qualquer empresa que queira usar agentes de IA de forma profissional.

O problema não é usar modelos gratuitos. O problema é usá-los sem classificação de dados, sem governança e sem distinção entre ambiente de teste e ambiente sensível.

O que isso ensina além da programação​

Embora o OpenCode seja uma ferramenta para programação, sua importância vai além do código.

Ele mostra um desenho de arquitetura que pode ser aplicado a vários workflows técnicos:

1. o agente precisa conhecer o ambiente;
2. precisa ter ferramentas;
3. precisa operar com permissões;
4. precisa seguir procedimentos;
5. precisa deixar rastros;
6. precisa alternar entre modelos conforme tarefa, custo e risco.

Esse modelo serve para pensar agentes em construção civil, engenharia, gestão de obras, suporte técnico, automação documental e operação de sistemas.

Imagine um fluxo de reuniões em uma empresa de engenharia. Hoje, uma pessoa escuta a reunião, extrai decisões, identifica tarefas, cria chamados, atribui responsáveis, registra prazos e atualiza sistemas.

Um agente operacional poderia apoiar esse fluxo se tivesse:

- acesso às transcrições;
- skill para classificar demandas;
- permissão para criar itens no sistema correto;
- regra para diferenciar bug, melhoria, tarefa e projeto;
- limite para não executar ações sensíveis sem revisão;
- histórico de decisões anteriores;
- integração com documentos, quadros e cronogramas.

Essa é a mesma lógica que o OpenCode aplica ao repositório de código.

O terminal, nesse sentido, é apenas um exemplo poderoso de ambiente operacional. O conceito maior é o agente atuando dentro do sistema onde o trabalho acontece.

OpenCode dentro do VS Code: além do terminal​

Um cuidado importante neste artigo é não reduzir o OpenCode ao terminal. A própria documentação oficial descreve o OpenCode como disponível em três superfícies: interface de terminal, aplicação desktop e extensão para IDE. Isso muda a percepção da ferramenta.

No VS Code, Cursor e outros editores compatíveis, o OpenCode pode ser usado como uma extensão integrada ao fluxo do desenvolvedor. A documentação oficial explica que basta rodar `opencode` no terminal integrado para começar; a extensão pode ser instalada automaticamente nesse processo ou manualmente pelo marketplace.

Na prática, isso cria uma experiência híbrida: o agente continua usando a força operacional do terminal, mas passa a conversar com o contexto visual do editor. O desenvolvedor não precisa abandonar os arquivos abertos, a seleção atual, os atalhos do IDE ou a navegação do projeto.

O que muda no uso diário​

A extensão oficial do OpenCode para VS Code adiciona alguns pontos importantes ao fluxo:

- lançamento rápido com `Cmd+Esc` no macOS ou `Ctrl+Esc` no Windows/Linux;
- criação de nova sessão com `Cmd+Shift+Esc` ou `Ctrl+Shift+Esc`;
- compartilhamento automático da seleção ou aba atual com o OpenCode;
- atalhos para referência de arquivos, como `@File#L37-42`;
- uso do terminal dividido para manter agente e código lado a lado.

Esse conjunto de recursos resolve um problema comum em agentes de código: o atrito de contexto. Em vez de copiar manualmente trechos de arquivo para uma conversa, o desenvolvedor pode referenciar o arquivo certo, a linha certa e a seleção certa a partir do próprio ambiente de trabalho.

Isso reforça a tese central do artigo: o valor do OpenCode não está apenas no modelo usado, mas na forma como ele aproxima agente, contexto e execução.

OpenChamber: uma camada visual para o ecossistema OpenCode​

Também vale citar o OpenChamber, um projeto complementar que se apresenta como uma interface desktop e web para o agente OpenCode. O projeto propõe uma experiência mais visual para revisar diffs, gerenciar agentes, acompanhar servidores de desenvolvimento e manter uma visão mais ampla enquanto a IA trabalha.

O ponto interessante do OpenChamber é que ele amplia a discussão além da oposição “terminal versus IDE”. Ele mostra que o ecossistema em volta do OpenCode está indo para múltiplas interfaces: terminal para operação direta, VS Code para o fluxo de edição, desktop/web para acompanhamento visual e até continuidade em outros dispositivos.

Para o artigo, essa seção é importante porque evita uma leitura limitada: OpenCode não é apenas uma TUI para quem gosta de terminal. Ele é uma base agentiva que pode aparecer em vários pontos do fluxo de desenvolvimento.

O terminal continua sendo a metáfora mais forte, mas o VS Code torna a adoção mais natural para equipes que já trabalham em IDEs. E ferramentas como OpenChamber sinalizam uma direção ainda mais ampla: agentes de código operando com múltiplas interfaces, do terminal à tela visual de revisão.

​

O terminal como metáfora​

O terminal sempre foi uma interface de poder. Ele concentra comandos, arquivos, automações, logs e operações críticas. Colocar um agente ali é simbólico: a IA deixa de ser uma janela separada e passa a habitar a camada de execução.

Mas isso também explica por que agentes precisam de disciplina.

Um erro em uma resposta de chat pode ser irritante. Um erro em um agente com permissão de escrita pode alterar arquivos, apagar dados, executar comandos indevidos ou criar registros incorretos.

Por isso, a evolução dos agentes deve vir acompanhada de práticas como:

- modo de planejamento antes da execução;
- permissões por tipo de ação;
- revisão de diff;
- isolamento de ambiente;
- classificação de dados;
- logs de decisão;
- limites para comandos destrutivos;
- separação entre agente leitor, planejador e executor.

Produtividade sem governança é dívida operacional.

O papel dos modelos locais​

Outro ponto relevante é o suporte a modelos locais.

Modelos locais não são sempre melhores, mais rápidos ou mais inteligentes. Mas eles resolvem uma dimensão importante: controle.

Para certas empresas, especialmente quando há dados confidenciais, contratos, informações de clientes ou propriedade intelectual, a possibilidade de executar modelos em ambiente controlado pode ser decisiva.

Em uma arquitetura madura, modelos locais podem ser usados para:

- triagem de documentos sensíveis;
- tarefas repetitivas de baixo risco;
- classificação interna;
- geração preliminar;
- apoio offline;
- ambientes em que privacidade pesa mais que performance máxima.

Já modelos externos podem ser reservados para tarefas em que a qualidade do raciocínio ou a capacidade agentiva justifique o envio de dados previamente classificados como permitidos.

A decisão deixa de ser ideológica e passa a ser arquitetural.

A nova pergunta: qual agente, com qual modelo, para qual tarefa?​

A discussão sobre IA ainda costuma girar em torno de rankings: qual modelo é melhor, qual responde mais rápido, qual tem o maior benchmark.

Esses rankings importam, mas são insuficientes.

Quando falamos de agentes, a pergunta correta é composta:

> Qual agente, com qual permissão, usando qual modelo, sobre qual contexto, para executar qual tarefa, com qual nível de revisão?

Essa pergunta é muito mais próxima da realidade empresarial.

Um agente que apenas lê documentos pode usar uma configuração. Um agente que altera código precisa de outra. Um agente que cria chamados em um sistema de gestão precisa de regras específicas. Um agente que opera dados sensíveis precisa de restrições mais fortes.

O OpenCode é interessante porque torna essa discussão concreta. Ele mostra que a camada de agente não é apenas uma interface bonita em cima de um LLM. Ela é uma composição entre modelo, ferramenta, contexto, permissão e procedimento.

Riscos e limites​

Apesar do potencial, é importante não romantizar.

Agentes de código ainda erram. Eles podem interpretar mal uma base, criar soluções excessivamente complexas, quebrar testes, ignorar efeitos colaterais ou se perder em tarefas longas.

Modelos gratuitos podem mudar, sair do ar, alterar condições de uso ou deixar de ser gratuitos. Benchmarks podem não refletir um caso de uso específico. E a documentação de provedores muda com frequência.

Além disso, existe uma questão cultural: equipes precisam aprender a delegar trabalho para agentes.

Delegar para IA não é escrever um prompt genérico e esperar mágica. É definir escopo, contexto, critérios de aceite, limites, permissões e forma de revisão.

A maturidade no uso de agentes será menos parecida com “usar um chatbot” e mais parecida com “gerenciar uma equipe operacional automatizada”.

O que empresas podem aprender com o OpenCode​

Mesmo para quem não programa, o OpenCode deixa algumas lições práticas.

A primeira é que agentes devem trabalhar dentro dos sistemas reais, não apenas responder fora deles.

A segunda é que procedimentos importam. Skills, instruções, padrões e permissões são parte da infraestrutura.

A terceira é que modelos são componentes substituíveis. O diferencial está na orquestração.

A quarta é que governança precisa nascer junto com produtividade. Não depois.

A quinta é que o ganho real vem da redução de atrito entre decisão e execução.

Essas lições são especialmente relevantes para setores como construção civil e engenharia, onde a operação é fragmentada entre reuniões, documentos, cronogramas, planilhas, sistemas de gestão, chamados e comunicação informal.

Nesses ambientes, o maior valor da IA pode não estar em “responder melhor”. Pode estar em transformar informação dispersa em ação registrada, rastreável e padronizada.

Conclusão​

O OpenCode é uma ferramenta de programação, mas também é um sinal de uma mudança maior.

A IA está saindo da interface de conversa e entrando nos ambientes operacionais. Ela começa a lidar com arquivos, comandos, ferramentas, permissões, modelos e procedimentos. Isso muda a natureza do trabalho.

O futuro dos agentes não será definido apenas pelo modelo mais inteligente. Será definido pela capacidade de combinar modelos, contexto, ferramentas e governança em fluxos reais.

O OpenCode mostra esse futuro em um lugar onde ele fica muito visível: o terminal de um desenvolvedor.

Mas a lógica vale muito além do terminal.

Toda empresa que depende de conhecimento técnico, processos repetíveis e sistemas fragmentados deve prestar atenção. Porque a próxima vantagem competitiva talvez não esteja em ter acesso à IA, mas em saber transformá-la em agente operacional — com contexto, permissão, procedimento e responsabilidade.

No fim, a pergunta não é se a IA consegue conversar sobre trabalho.

A pergunta é se ela consegue trabalhar dentro do fluxo certo, do jeito certo, com o controle certo.

É aí que a discussão começa a ficar realmente interessante.

Referências​

- Documentação oficial do OpenCode sobre modelos: https://opencode.ai/docs/models/
- Documentação oficial do OpenCode Zen: https://opencode.ai/docs/zen/
- Artificial Analysis — Qwen3.6 Plus: https://artificialanalysis.ai/models/qwen3-6-plus
- Artificial Analysis — MiniMax M2.5: https://artificialanalysis.ai/models/minimax-m2-5
- Artificial Analysis — NVIDIA Nemotron 3 Super: https://artificialanalysis.ai/models/nvidia-nemotron-3-super-120b-a12b
- Artificial Analysis — GLM-5 Reasoning: https://artificialanalysis.ai/models/glm-5
- Artificial Analysis — Gemini 3.1 Pro Preview: https://artificialanalysis.ai/models/gemini-3-1-pro-preview
- Artificial Analysis — GPT-5.3 Codex: https://artificialanalysis.ai/models/gpt-5-3-codex
- Artificial Analysis — Claude Opus 4.6: https://artificialanalysis.ai/models/claude-opus-4-6
- Documentação oficial do OpenCode sobre IDE: https://opencode.ai/docs/ide/
- OpenCode — Visual Studio Marketplace: https://marketplace.visualstudio.com/items?itemName=sst-dev.opencode
- OpenChamber — repositório oficial: https://github.com/openchamber/openchamber

⚙️ O ambiente de referência é sempre Windows.

Como instalar cada um — direto ao ponto e o porquê de cada passo

1. Python​

• Download: python.org/downloads → versão 3.10 ou superior
• Por quê: linguagem base para automações, scripts e uso de bibliotecas como ifcopenshell
• Durante a instalação, marque ✅ "Add Python to PATH" — isso permite rodar python direto no terminal

2. Node.js​

• Download: nodejs.org → versão LTS (mais estável)
• Por quê: necessário para rodar ferramentas modernas de desenvolvimento, incluindo o Gemini CLI
• Instale e verifique com node -v e npm -v no terminal

3. Gemini CLI​

• Com Node.js instalado, rode no terminal:

npm install -g @google/gemini-cli

• Por quê: permite usar a IA Gemini direto pelo terminal, integrado ao seu fluxo de trabalho
• Autentique com sua conta Google: gemini auth login

4. Biblioteca ifcopenshell (Python)​

• Com Python instalado, rode:

pip install ifcopenshell

• Por quê: permite ler, criar e manipular arquivos IFC (formato aberto BIM) via script Python
• Verifique a instalação: python -c "import ifcopenshell; print(ifcopenshell.version)"

5. Google Apps Script + Google Planilhas​

• Acesso: abra uma planilha no Google Sheets → menu Extensões → Apps Script
• Por quê: permite automatizar tarefas dentro do ecossistema Google (enviar e-mails, preencher planilhas, criar relatórios) sem instalar nada
• Não requer instalação local — roda 100% no navegador

6. Google Antigravity IDE​

• Download: antigravity.google → disponível para Windows (preview gratuito)
• Por quê: IDE de nova geração do Google, focada em agentes de IA. É um fork do VS Code, então a interface já é familiar. Permite orquestrar múltiplos agentes de IA trabalhando em paralelo no seu código
• Instale como qualquer programa Windows (.exe), abra e faça login com sua conta Google
• Modelos disponíveis gratuitamente: Gemini 3.1 Pro e Claude Sonnet
• Diferencial: em vez de um chat na barra lateral, você gerencia agentes autônomos que executam tarefas completas — você age como arquiteto, eles executam

Básico de terminal no Windows (CMD / PowerShell)

Por quê usar o terminal? A maioria das instalações e comandos desta aula são feitos pelo terminal.

Como abrir:

• Pressione Windows + R, digite powershell e Enter
• Ou pesquise PowerShell no menu Iniciar → clique com botão direito → Executar como administrador (necessário para instalações)

Comandos essenciais:

Dicas importantes:

• Após instalar qualquer programa, feche e reabra o terminal — ele não atualiza automaticamente
• Quando aparecer erro, leia a última linha: geralmente diz exatamente o problema
• Para colar no terminal Windows: clique com o botão direito do mouse

Troubleshootings comuns

Python​

• python não reconhecido no terminal → reinstale marcando "Add Python to PATH" ou adicione manualmente nas variáveis de ambiente do sistema
• pip não encontrado → use python -m pip install ... em vez de só pip
• Versões conflitantes → use python3 e pip3 se houver Python 2 e 3 instalados

Node.js / npm​

• Erro de permissão no npm → no Windows, abra o terminal como Administrador
• node não reconhecido → reinicie o terminal após a instalação
• Versão antiga → desinstale e baixe a LTS mais recente do site oficial

Gemini CLI​

• Erro de autenticação → rode gemini auth login novamente e certifique-se de usar a conta Google correta
• Comando não encontrado após instalar → feche e reabra o terminal

ifcopenshell​

• Erro ao importar → verifique se instalou no Python correto (python -m pip install ifcopenshell)
• Versão incompatível com Python → use Python 3.10 ou 3.11 para maior compatibilidade

Google Apps Script​

• Script não salvo → use Ctrl+S ou clique no ícone de disquete antes de rodar
• Erro de autorização → na primeira execução, o Google pede permissão; clique em "Permitir" após revisar os escopos
• Cota excedida → o Apps Script tem limites diários gratuitos; espaçe as execuções ou use conta Google Workspace

Google Antigravity​

• Erro de login → tente fechar e reabrir; se persistir, aguarde alguns minutos (pode ser instabilidade do servidor Google)
• "You need to set up a workspace" → abra uma pasta local pelo menu File → Open Folder antes de usar o agente
• Extensões do VS Code não aparecem → por ser um fork, a maioria das extensões é compatível; instale normalmente pela aba Extensions

Terminal Windows (geral)​

• Comando não reconhecido após instalar → feche e reabra o terminal
• Acesso negado / Permission denied → execute o PowerShell como Administrador
• Erro ao colar comando → use botão direito do mouse para colar no CMD/PowerShell

Para engenheiros e arquitetos: é como ter todas as revisões de um projeto (Rev A, Rev B, Rev C...) organizadas automaticamente, sem precisar renomear arquivos.

Instalação

• Download: git-scm.com/download/win
• Instale com as opções padrão — não precisa mudar nada
• Verifique: abra o PowerShell e rode git --version

Conceitos fundamentais (sem enrolação)

Fluxo básico do dia a dia

Você faz alterações nos arquivos
         ↓
git add . (marca os arquivos para salvar)
         ↓
git commit -m "descrição do que foi feito"
         ↓
git push (envia para o GitHub, opcional)

Comandos essenciais no terminal

Configuração inicial (faça uma vez só)​

git config --global user.name "Seu Nome"
git config --global user.email "seu@email.com"

Iniciar um projeto novo com Git​

# Dentro da pasta do projeto:
git init

Salvar o progresso (commit)​

# Ver o que mudou
git status

# Marcar todos os arquivos modificados
git add .

# Salvar com descrição
git commit -m "adiciona script de leitura IFC"

Ver o histórico​

git log --oneline

Voltar para uma versão anterior (sem apagar nada)​

# Copie o código do commit que quer ver (ex: a3f5c12)
git checkout a3f5c12

# Para voltar ao estado atual:
git checkout main

Trabalhar com GitHub​

# Conectar seu projeto local a um repositório do GitHub
git remote add origin https://github.com/seu-usuario/seu-repositorio.git

# Enviar pela primeira vez
git push -u origin main

# Enviar depois (mais simples)
git push

# Baixar atualizações
git pull

Usando Git pelo Antigravity IDE e VS Code (sem digitar comandos)

Tanto o Antigravity quanto o VS Code têm uma interface visual para o Git — você não precisa digitar nada no terminal.

Como acessar​

• Clique no ícone de ramificação na barra lateral esquerda (parece três bolinhas conectadas)
• Ou use o atalho: Ctrl + Shift + G

Fazer um commit pela interface​

1. Faça alterações em qualquer arquivo
2. Abra o painel do Git (Ctrl + Shift + G)
3. Você verá os arquivos modificados listados em "Changes"
4. Clique no + ao lado de cada arquivo (ou no + geral para marcar todos) → eles vão para "Staged Changes"
5. Digite uma mensagem descrevendo o que foi feito
6. Clique em ✔ Commit

Enviar para o GitHub (push) pela interface​

• Após o commit, clique em "Sync Changes" ou no botão ↑ Push
• Se aparecer uma janela pedindo login no GitHub, faça login com sua conta

Ver o histórico visualmente​

• Instale a extensão GitLens (disponível para VS Code e Antigravity)
• Ela adiciona visualização completa do histórico, quem alterou cada linha e quando

Exemplos de uso no dia a dia do trabalho

Exemplo 1 — Salvando o progresso de um script​

Você acabou de fazer o script leitura_ifc.py funcionar. Hora de salvar:

git add leitura_ifc.py
git commit -m "script leitura_ifc funcionando para arquivos até 500 elementos"

Agora se você estragar tudo tentando melhorar, é só voltar a este ponto.

Exemplo 2 — Testando uma mudança arriscada sem medo​

Você quer tentar uma abordagem diferente mas tem medo de quebrar o que já funciona:

# Cria uma branch nova para testar
git checkout -b testar-nova-abordagem

# Faz as alterações e commits normalmente...

# Se funcionar: volta para main e junta
git checkout main
git merge testar-nova-abordagem

# Se não funcionar: abandona a branch e volta para main
git checkout main
# O código principal não foi tocado

Exemplo 3 — Compartilhando um script com a equipe​

Você criou um script útil e quer que seu colega use também:

1. Crie um repositório no github.com
2. No terminal da pasta do projeto:

git remote add origin https://github.com/seu-usuario/scripts-bim.git
git push -u origin main

1. Envie o link para seu colega — ele roda:

git clone https://github.com/seu-usuario/scripts-bim.git

Exemplo 4 — Pedindo ao agente para fazer commits por você​

No Antigravity ou Gemini CLI, você pode pedir:

Faça um commit com uma mensagem descritiva para as alterações que fizemos hoje no script leitura_ifc.py

Ou no fluxo de execução:

Após cada etapa concluída, faça um commit automático com uma mensagem descritiva do que foi feito

Boas mensagens de commit

Uma boa mensagem de commit descreve o que foi feito e por quê (quando não é óbvio).

Gemini CLI

• Acesso: login com sua conta Google — sem precisar pagar nada
• Cota: alta, renovada diariamente
• Dica prática: se a cota acabar no meio do dia, basta fazer login com outra conta Google e continuar
• Modelos disponíveis: somente modelos Google

Google Antigravity IDE

• Plano gratuito: cota alta para uso geral
• Modelos Google (Gemini): cota renovada semanalmente
• Modelos Claude (Anthropic): cotas bem menores e renovação semanal
• Plano pago: disponível para quem precisar de cotas maiores

Capacidade dos modelos

⚡ Gemini 3.1 Flash Lite​

• Modelo ultra rápido e leve do Google
• Cota maior que todos os outros modelos
• Perfeito para perguntas rápidas, chat e tarefas simples
• Use quando: você quiser economizar cota dos modelos maiores ou precisar de uma resposta instantânea para algo direto

🔵 Gemini 3.1 Pro​

• Modelo avançado e inteligente do Google
• Não é o mais rápido, mas é muito capaz
• Ideal para tarefas complexas e grandes: analisar arquivos IFC extensos, gerar scripts completos, raciocínio longo
• Bom com uso de ferramentas (ler arquivos, executar comandos, navegar pastas)
• Use quando: a tarefa for difícil e você tiver paciência para esperar

⚡ Gemini 3.1 Flash​

• Modelo avançado e rápido do Google
• Versão mais leve e ágil — resolve a maioria das situações do dia a dia
• Cota maior do que o Pro: dura mais ao longo do dia
• Use quando: a tarefa for simples ou moderada e você quiser resposta rápida
• Recomendado como modelo padrão para começar

🟠 Claude Sonnet 4.6​

• Modelo da Anthropic (empresa concorrente do Google)
• Desempenho comparável ao Gemini 3.1 Pro
• Inteligente e muito bom com ferramentas e raciocínio estruturado
• Cota menor no plano gratuito — use com moderação
• Use quando: o Gemini Pro não estiver resolvendo bem e você ainda tiver cota Claude disponível

🔴 Claude Opus 4.6​

• Considerado atualmente o modelo mais inteligente do mundo
• Mais lento que os outros
• Desempenho excepcional em tarefas muito difíceis, ambíguas ou críticas
• Cota muito pequena no plano gratuito — use só quando realmente necessário
• Use quando: nenhum outro modelo estiver conseguindo resolver, ou a tarefa for de alta importância e complexidade

Qual modelo usar? Guia rápido

Para engenheiros e arquitetos: é como montar a estrutura de pastas de um projeto BIM antes de começar a modelar.

Por que fazer scaffolding antes de codar?

• O agente vai entender melhor o que você quer fazer
• Você não perde arquivos importantes em pastas erradas
• Facilita pedir ajuda para o agente depois (ele sabe onde está cada coisa)
• Projetos organizados são mais fáceis de continuar semanas depois

Estrutura mínima recomendada

Para um projeto Python simples de automação (ex: leitura de IFC, geração de planilhas):

meu-projeto/
├── gemini.md                  ← instruções para o agente
├── main.py                    ← arquivo principal (ponto de entrada)
├── requirements.txt           ← lista de bibliotecas usadas
├── .gitignore                 ← arquivos que o Git deve ignorar
├── README.md                  ← explicação do projeto
├── exemplos/                  ← arquivos de entrada para testes (ex: .ifc, .xlsx)
├── artifacts/                 ← outputs gerados pelos scripts
├── plans/                     ← planos de tarefas aprovados
├── regras/
│   └── regras-de-negocio.md   ← regras do projeto
└── .gemini/
    └── commands/              ← seus slash commands (.toml)

Como criar manualmente (passo a passo no Windows)

1. Crie uma pasta para o projeto onde quiser (ex: Documentos\projetos\meu-projeto)
2. Abra o PowerShell dentro dessa pasta:
   • Segure Shift e clique com botão direito na pasta → Abrir janela do PowerShell aqui
3. Cole os comandos abaixo para criar toda a estrutura de uma vez:

# Cria todas as pastas
mkdir exemplos, artifacts, plans, regras, .gemini\commands

# Cria os arquivos vazios
New-Item main.py, requirements.txt, README.md, gemini.md, .gitignore -ItemType File
New-Item regras\regras-de-negocio.md -ItemType File

1. Abra o Antigravity IDE → File → Open Folder → selecione a pasta do projeto

Como pedir ao agente para fazer o scaffolding

Você pode pedir ao Gemini CLI ou ao Antigravity para criar a estrutura por você. Basta descrever o projeto:

Crie o scaffolding inicial para um projeto Python com as seguintes características:
- Objetivo: ler arquivos IFC e exportar uma planilha Excel com os elementos e propriedades
- Bibliotecas: ifcopenshell, openpyxl
- Sistema: Windows
- Inclua: gemini.md com instruções básicas, requirements.txt preenchido, README.md com descrição do projeto, .gitignore para Python, e a estrutura de pastas: exemplos/, artifacts/, plans/, regras/
- Não escreva o código ainda, apenas monte a estrutura

O que vai dentro de cada arquivo

requirements.txt​

Lista as bibliotecas que o projeto usa. Uma por linha:

ifcopenshell
openpyxl
pandas

Para instalar tudo de uma vez:

pip install -r requirements.txt

.gitignore​

Arquivos que o Git não deve salvar. Para Python, use este conteúdo mínimo:

# Ambientes virtuais
venv/
.venv/

# Cache do Python
__pycache__/
*.pyc

# Arquivos de configuração local
.env
*.env

# Arquivos grandes de exemplo (opcional)
*.ifc

README.md​

Explicação simples do projeto. Modelo mínimo:

# Nome do Projeto

O que este projeto faz em 1 frase.

## Como usar

1. Instale as dependências: `pip install -r requirements.txt`
2. Coloque seu arquivo `.ifc` na pasta `exemplos/`
3. Rode: `python main.py`
4. O resultado aparece na pasta `artifacts/`

## Tecnologias
- Python 3.10+
- ifcopenshell
- openpyxl

Ambientes virtuais (opcional mas recomendado)

Um ambiente virtual isola as bibliotecas do projeto para não conflitar com outros projetos no mesmo computador.

# Criar ambiente virtual (rode uma vez na pasta do projeto)
python -m venv venv

# Ativar o ambiente (rode toda vez que abrir o terminal)
venv\Scripts\activate

# Você verá (venv) no início da linha quando estiver ativo
# Agora instale as dependências normalmente:
pip install -r requirements.txt

/investigar-bug

O que faz: analisa um erro ou comportamento inesperado, localiza a causa raiz e proposta de correção — sem alterar nada até você aprovar.

Investigar bug​

name = "investigar-bug"
description = "Investiga um bug ou erro: loca causa raiz e propõe correção sem alterar código"
prompt = """
Você é um detetive de código. Sua missão é investigar o problema descrito pelo usuário sem alterar nenhum arquivo.

Passos obrigatórios:
1. Leia os arquivos relevantes para entender o contexto
2. Reproduza mentalmente o fluxo que causa o erro
3. Identifique a causa raiz (não apenas o sintoma)
4. Liste todas as linhas/funções envolvidas no problema
5. Proponha UMA correção clara e simples
6. Salve o relatório em artifacts/bug-report-YYYYMMDD.md
7. Pergunte ao usuário: "Posso aplicar a correção?"

NUNCA altere código antes da aprovação.

Problema relatado: args
"""

<!-- Antigravity: salve como investigar-bug.md nos Workflows -->
# Workflow: investigar-bug

Investigue o problema descrito sem alterar nenhum arquivo.

## Passos obrigatórios
1. Leia os arquivos relevantes para entender o contexto
2. Reproduza mentalmente o fluxo que causa o erro
3. Identifique a causa raiz, não apenas o sintoma
4. Liste linhas, arquivos e funções envolvidos
5. Proponha uma correção clara e simples
6. Salve o relatório em `artifacts/bug-report-YYYYMMDD.md`
7. Pergunte ao usuário: "Posso aplicar a correção?"

Não altere código antes da aprovação.

Exemplo de uso​

/investigar-bug o script leitura_ifc.py trava quando o arquivo IFC tem mais de 500 elementos

/planejar

O que faz: transforma uma ideia ou pedido em um plano estruturado com passos, riscos e estimativa — salvo em /plans para aprovação antes de qualquer execução.

Planejar​

# .gemini/commands/planejar.toml
name = "planejar"
description = "Cria um plano estruturado para uma tarefa e salva em /plans para aprovação"
prompt = """
Crie um plano detalhado para a tarefa descrita. Não execute nada — apenas planeje.

Estrutura do plano:
1. **Objetivo:** o que será entregue
2. **Arquivos que serão criados ou modificados** (liste todos)
3. **Passos em ordem** (numere cada um)
4. **Dependências** (o que precisa estar pronto antes)
5. **Riscos identificados** (o que pode dar errado)
6. **Estimativa** (simples/médio/complexo e por quê)

Salve o plano em plans/plano-YYYYMMDD-[nome-curto].md
Apresente o plano ao usuário e pergunte: "Este plano está correto? Posso prosseguir?"

Tarefa: args
"""

<!-- Antigravity: salve como planejar.md nos Workflows -->
# Workflow: planejar

Crie um plano detalhado para a tarefa descrita. Não execute nada, apenas planeje.

## Estrutura do plano
1. Objetivo do que será entregue
2. Arquivos que serão criados ou modificados
3. Passos em ordem
4. Dependências
5. Riscos identificados
6. Estimativa: simples, médio ou complexo, com justificativa

Salve o plano em `plans/plano-YYYYMMDD-[nome-curto].md`.
Apresente o plano ao usuário e pergunte: "Este plano está correto? Posso prosseguir?"

Exemplo de uso​

/planejar criar um script Python que lê um arquivo IFC e exporta uma planilha com todos os elementos e suas propriedades

/executar

O que faz: executa uma tarefa já aprovada (idealmente a partir de um plano existente em /plans), reportando cada passo concluído.

Executar​

# .gemini/commands/executar.toml
name = "executar"
description = "Executa uma tarefa aprovada, passo a passo, com reporte de progresso"
prompt = """
Execute a tarefa descrita. Se existir um arquivo de plano em plans/ relacionado a essa tarefa, leia-o primeiro.

Regras de execução:
- Execute um passo de cada vez
- Após cada passo, informe: "✅ Passo X concluído: [o que foi feito]"
- Se algo inesperado acontecer, PARE e informe o usuário antes de continuar
- Não modifique arquivos fora do escopo da tarefa
- Ao terminar, salve um resumo em artifacts/execucao-YYYYMMDD.md com o que foi feito

Tarefa: args
"""

<!-- Antigravity: salve como executar.md nos Workflows -->
# Workflow: executar

Execute a tarefa descrita. Leia o plano em `plans/` se existir.

## Regras
- Execute um passo de cada vez
- Reporte: "✅ Passo X concluído: [o que foi feito]"
- Se algo inesperado acontecer, PARE e avise
- Não modifique arquivos fora do escopo
- Ao terminar, salve resumo em `artifacts/execucao-YYYYMMDD.md`

Exemplo de uso​

/executar criar o script de exportação IFC conforme plano aprovado

Output esperado: arquivos criados conforme o plano + artifacts/execucao-20260324.md com resumo do que foi feito.

/testar

O que faz: executa testes em um script ou função existente com um arquivo de exemplo real, mostra o resultado e indica se passou ou falhou.

Testar​

# .gemini/commands/testar.toml
name = "testar"
description = "Testa um script ou função com dados reais e reporta o resultado"
prompt = """
Execute um teste funcional no arquivo ou função indicada.

Passos:
1. Leia o código do arquivo indicado
2. Identifique o que ele deveria fazer
3. Rode o script com um arquivo de entrada de exemplo (se disponível na pasta)
4. Capture o output ou erro
5. Compare com o resultado esperado
6. Classifique: ✅ PASSOU ou ❌ FALHOU
7. Se falhou: descreva o problema e sugira a correção
8. Salve o resultado em artifacts/teste-YYYYMMDD.md

Arquivo/função a testar: args
"""

<!-- Antigravity: salve como testar.md nos Workflows -->
# Workflow: testar

Execute um teste funcional no arquivo indicado.

## Passos
1. Leia o código do arquivo
2. Identifique o que ele deveria fazer
3. Rode com arquivo de exemplo disponível
4. Capture output ou erro
5. Classifique: ✅ PASSOU ou ❌ FALHOU
6. Se falhou: descreva o problema e sugira correção
7. Salve em `artifacts/teste-YYYYMMDD.md`

Exemplo de uso​

/testar leitura_ifc.py usando o arquivo modelo.ifc que está na pasta /exemplos

Output esperado: artifacts/teste-20260324.md com resultado ✅ PASSOU ou ❌ FALHOU, output capturado e sugestão de correção se necessário.

/criar-testes

O que faz: lê um script existente e gera automaticamente um arquivo de testes unitários cobrindo os casos principais — sem modificar o script original.

Criar testes​

# .gemini/commands/criar-testes.toml
name = "criar-testes"
description = "Gera arquivo de testes unitários para um script existente"
prompt = """
Analise o arquivo indicado e crie testes unitários para ele.

Passos:
1. Leia o código do arquivo
2. Identifique todas as funções/comportamentos que podem ser testados
3. Para cada função, crie testes para:
   - Caso normal (entrada válida esperada)
   - Caso de borda (entrada vazia, zero, lista vazia, etc.)
   - Caso de erro (entrada inválida ou arquivo inexistente)
4. Use a biblioteca `pytest` para Python
5. Adicione comentários em português explicando o que cada teste verifica
6. Salve o arquivo como artifacts/test_[nome-original].py
7. Informe quantos testes foram criados e quais casos foram cobertos

Arquivo a testar: args
"""

<!-- Antigravity: salve como criar-testes.md nos Workflows -->
# Workflow: criar-testes

Gere testes unitários para o arquivo indicado. Não modifique o arquivo original.

## Passos
1. Leia o código
2. Identifique funções/comportamentos testáveis
3. Para cada função, crie testes: caso normal, borda e erro
4. Use `pytest` para Python
5. Comentários em português explicando cada teste
6. Salve como `artifacts/test_[nome-original].py`
7. Informe quantos testes e quais casos foram cobertos

Exemplo de uso​

/criar-testes leitura_ifc.py

Output esperado: artifacts/test_leitura_ifc.py com testes completos prontos para rodar com pytest.

/documentar

O que faz: lê um script e gera documentação clara em português explicando o que ele faz, como usar e quais são os parâmetros.

Documentar​

# .gemini/commands/documentar.toml
name = "documentar"
description = "Gera documentação em português para um script existente"
prompt = """
Leia o arquivo indicado e crie uma documentação completa em português.

Estrutura da documentação:
1. **O que este script faz** (1 parágrafo simples, sem jargão)
2. **Como usar** (comando exato para rodar)
3. **Parâmetros e entradas** (o que precisa fornecer)
4. **O que o script gera** (output esperado)
5. **Exemplo prático completo**
6. **Erros comuns e como resolver**

Salve como artifacts/docs-[nome-do-arquivo].md
Escreva como se fosse explicar para alguém que nunca programou.

Arquivo: args
"""

<!-- Antigravity: salve como documentar.md nos Workflows -->
# Workflow: documentar

Crie documentação em português para o arquivo indicado.

## Estrutura
1. O que este script faz (linguagem simples)
2. Como usar (comando exato)
3. Parâmetros e entradas
4. O que gera (output esperado)
5. Exemplo prático completo
6. Erros comuns e como resolver

Salve como `artifacts/docs-[nome].md`
Escreva para quem nunca programou.

Exemplo de uso​

/documentar exportar_planilha.py

Output esperado: artifacts/docs-exportar_planilha.md com documentação completa pronta para compartilhar com a equipe.

/revisar-codigo

O que faz: revisa um script e aponta problemas de qualidade, segurança e boas práticas — sem alterar nada, apenas sugere melhorias.

Revisar código​

# .gemini/commands/revisar-codigo.toml
name = "revisar-codigo"
description = "Revisa um script e aponta problemas de qualidade e segurança sem alterar nada"
prompt = """
Faça uma revisão de código no arquivo indicado. Não altere nenhum arquivo.

Verifique e aponte problemas em:
1. **Clareza:** o código é fácil de entender? Variáveis têm nomes claros?
2. **Segurança:** há senhas, tokens ou dados sensíveis expostos no código?
3. **Erros silenciosos:** há trechos que podem falhar sem avisar o usuário?
4. **Eficiência:** há algo que pode ser simplificado sem perder funcionalidade?
5. **Boas práticas:** o código segue o padrão da linguagem?

Formato do resultado:
- ✅ O que está bom
- ⚠️ O que precisa de atenção (com linha do arquivo)
- ❌ O que deve ser corrigido (com sugestão)

Salve o relatório em artifacts/revisao-[nome].md
Pergunte ao usuário se quer aplicar as correções sugeridas.

Arquivo: args
"""

<!-- Antigravity: salve como revisar-codigo.md nos Workflows -->
# Workflow: revisar-codigo

Revise o arquivo indicado. Não altere nada.

## Verifique
1. Clareza: nomes de variáveis, legibilidade
2. Segurança: senhas ou tokens expostos
3. Erros silenciosos: falhas sem aviso
4. Eficiência: simplificações possíveis
5. Boas práticas da linguagem

## Formato
- ✅ O que está bom
- ⚠️ Atenção (com linha)
- ❌ Deve corrigir (com sugestão)

Salve em `artifacts/revisao-[nome].md`
Pergunte se quer aplicar as correções.

Exemplo de uso​

/revisar-codigo leitura_ifc.py

Output esperado: artifacts/revisao-leitura_ifc.md com itens classificados em ✅ bom / ⚠️ atenção / ❌ corrigir.

Estrutura de pastas recomendada

meu-projeto/
├── gemini.md                    ← instruções gerais do agente
├── .gemini/
│   └── commands/                ← workflows do Gemini CLI (.toml)
├── plans/                       ← planos gerados pelo /planejar
├── regras/
│   └── regras-de-negocio.md     ← regras do projeto
├── artifacts/                   ← outputs gerados pelos workflows
└── (código do projeto)

1. Objetivo deste material​

Este material resume, de forma simples e prática, o que são:

• Codex app, da OpenAI;
• Claude Code, da Anthropic.

A ideia aqui não é aprofundar tudo, mas explicar:

• o que cada ferramenta faz;
• como elas funcionam no dia a dia;
• quando cada uma faz mais sentido;
• quais modelos aparecem nas documentações oficiais;
• onde consultar as fontes oficiais.

O foco continua sendo o mesmo público do projeto: iniciantes, em ambiente Windows, usando IA como apoio para produtividade, automação, scripts, revisão e organização de projetos.

2. Antes de tudo: o que essas ferramentas são?​

As duas ferramentas pertencem à categoria de agentes de codificação.

Na prática, isso significa que elas não servem apenas para “responder perguntas sobre código” como um chat comum. Elas podem trabalhar de forma mais ativa dentro de um projeto, por exemplo:

• ler arquivos da pasta do projeto;
• sugerir alterações;
• editar arquivos;
• executar comandos no terminal;
• explicar código existente;
• ajudar a testar, revisar e organizar tarefas.

Em outras palavras:

• um chat comum normalmente conversa sobre o código;
• um agente de código consegue agir no ambiente de desenvolvimento, dentro de permissões e regras.

3. O que é o Codex app da OpenAI?​

O Codex app é a experiência de desktop da OpenAI para trabalhar com o Codex em vários fluxos de desenvolvimento. A documentação oficial descreve o app como uma experiência focada para trabalhar com threads em paralelo, com suporte a worktrees, automações e funcionalidades de Git.

De forma simples, pense assim:

• o Codex é o agente de codificação da OpenAI;
• o Codex app é uma interface para organizar esse trabalho de forma mais visual e operacional.

O que ele faz na prática​

Segundo a documentação oficial, o Codex pode ajudar a:

• escrever código;
• entender bases de código desconhecidas;
• revisar código;
• propor correções;
• trabalhar com múltiplas tarefas em paralelo.

A OpenAI também descreve o Codex app como um “command center” para trabalho com agentes de programação.

O que isso significa para o usuário iniciante​

Para quem está começando, o Codex app pode ser entendido como:

• um lugar para conversar com agentes de codificação;
• organizar tarefas por projeto;
• revisar alterações antes de aplicar;
• combinar contexto de projeto + execução de tarefas + Git.

Observação importante sobre Windows​

A OpenAI anunciou o Codex app inicialmente para macOS e depois informou que ele passou a estar disponível também para Windows. Isso é relevante para o contexto do seu projeto, porque o ambiente de referência é Windows.

4. O que é o Claude Code da Anthropic?​

O Claude Code é a ferramenta agentic de codificação da Anthropic. A documentação oficial explica que ele ajuda a:

• construir funcionalidades;
• corrigir bugs;
• automatizar tarefas de desenvolvimento;
• compreender a base de código;
• atuar em arquivos e ferramentas do ambiente.

A própria Anthropic descreve o Claude Code como uma ferramenta que pode:

• ler a base de código;
• editar arquivos;
• executar comandos;
• integrar-se ao terminal, IDE, app desktop e navegador.

O que ele faz na prática​

Em uso diário, o Claude Code pode ser usado para:

• pedir explicações sobre um projeto existente;
• solicitar criação de scripts;
• revisar erros;
• refatorar trechos;
• executar tarefas repetitivas;
• gerar plano de implementação antes de mudar código.

Observação importante sobre Windows​

A documentação oficial informa compatibilidade com:

• Windows 10 1809+ ou Windows Server 2019+;
• PowerShell ou CMD;
• e, no Windows, a Anthropic informa que Git for Windows é necessário.

Para o seu público, isso é importante porque mostra que não é uma ferramenta pensada apenas para macOS ou Linux.

5. A ideia central: como essas ferramentas funcionam?​

Embora OpenAI e Anthropic usem terminologias próprias, o funcionamento geral é parecido.

Fluxo básico​

1. Você escolhe uma pasta ou projeto​

A ferramenta passa a trabalhar olhando para aquele contexto.

2. Você dá uma instrução​

Exemplos:

• “explique este projeto”;
• “crie um script para renomear arquivos”;
• “revise este erro”;
• “monte um plano antes de alterar”.

3. O agente lê contexto​

Ele pode analisar arquivos, estrutura de pastas, comandos, dependências e histórico local.

4. O agente propõe ou executa ações​

Dependendo do fluxo e das permissões, ele pode:

• sugerir mudanças;
• editar arquivos;
• executar comandos;
• abrir uma revisão;
• pedir aprovação para ações mais sensíveis.

5. Você revisa​

Esse ponto é essencial. Mesmo com agentes bons, o uso correto continua sendo:

• revisar alterações;
• validar resultado;
• testar;
• versionar com Git quando necessário.

6. Codex app e Claude Code não são “mágica”​

Um erro comum de iniciante é imaginar que essas ferramentas “programam sozinhas”. Na prática, elas funcionam melhor quando existe:

• pasta organizada;
• instrução clara;
• objetivo pequeno por etapa;
• validação humana;
• controle de versão.

Por isso, o melhor uso continua sendo o mesmo princípio já presente no restante do projeto:

• planejar;
• executar em etapas;
• testar;
• revisar;
• documentar.

7. Onde o Codex app se encaixa melhor?​

O Codex app tende a fazer mais sentido quando você quer:

• trabalhar com várias frentes em paralelo;
• organizar tarefas por thread;
• usar uma experiência mais centralizada;
• combinar app + Git + worktrees + tarefas em nuvem/local;
• manter um fluxo mais operacional e visual.

Exemplos de uso​

• revisar um projeto React;
• criar uma automação em Python;
• abrir tarefas separadas para corrigir bugs diferentes;
• analisar uma base de código antiga;
• produzir mudanças com revisão antes de aceitar.

8. Onde o Claude Code se encaixa melhor?​

O Claude Code tende a fazer muito sentido quando você quer:

• uma experiência fortemente ligada ao terminal e à IDE;
• trabalhar com leitura e edição da base de código;
• automatizar tarefas de desenvolvimento;
• criar um fluxo com regras do projeto usando arquivos como CLAUDE.md;
• usar o mesmo ecossistema também de forma programável com o Claude Agent SDK.

Exemplos de uso​

• pedir para explicar uma base de código existente;
• gerar scripts utilitários;
• investigar bug com contexto do repositório;
• revisar e refatorar arquivos;
• usar o agente como apoio constante no terminal.

9. Comparação direta​

Codex app (OpenAI)​

Pense no Codex app como:

• uma central para trabalho com o agente de código da OpenAI;
• foco em threads, paralelismo, worktrees, automações e Git;
• boa opção para fluxo mais visual e de coordenação.

Claude Code (Anthropic)​

Pense no Claude Code como:

• um agente de codificação muito ligado ao terminal e ao editor;
• forte em leitura de base de código, edição, execução de comandos e automação;
• boa opção para fluxo contínuo de desenvolvimento assistido.

Em comum​

Os dois ajudam a:

• entender projeto;
• editar código;
• automatizar tarefas;
• acelerar revisão e implementação;
• trabalhar melhor quando o projeto está organizado.

10. Modelos citados nas fontes oficiais​

Esta parte é importante porque muita gente confunde ferramenta com modelo.

A ferramenta é a interface e o fluxo de trabalho. O modelo é o mecanismo de IA usado por trás.

10.1. Modelos citados oficialmente no ecossistema Codex​

Nas fontes oficiais da OpenAI consultadas, aparecem estes nomes relevantes:

• gpt-5.4: recomendado pela OpenAI para a maioria das tarefas no Codex;
• gpt-5.4-mini: opção mais rápida e econômica para tarefas mais leves;
• gpt-5.3-codex-spark: citado em research preview para iteração de código muito rápida em alguns contextos;
• GPT-5-Codex: modelo otimizado para tarefas agentic de codificação;
• GPT-5.3-Codex: modelo descrito pela OpenAI como muito capaz para tarefas de codificação agentic.

Como interpretar isso de forma simples​

• se a tarefa é mais geral e forte, a documentação sugere começar com gpt-5.4;
• se a tarefa é mais leve, gpt-5.4-mini pode fazer mais sentido;
• quando a documentação fala em GPT-5-Codex ou GPT-5.3-Codex, está falando de variantes otimizadas para fluxos de codificação agentic.

10.2. Modelos citados oficialmente no ecossistema Claude Code​

Na documentação oficial consultada da Anthropic, aparecem:

• aliases de modelo no Claude Code como sonnet, opus e haiku;
• nas páginas gerais da Anthropic, a geração mais recente mencionada inclui Claude Opus 4.6 e Claude Sonnet 4.6.

Como interpretar isso de forma simples​

• Opus costuma representar a linha mais forte para tarefas complexas;
• Sonnet costuma equilibrar qualidade e velocidade;
• Haiku tende a ser a linha mais leve e rápida;
• no Claude Code, a documentação explica que aliases podem apontar para a versão mais recente habilitada no ambiente.

11. Qual dos dois escolher?​

Para um iniciante, a resposta mais honesta é:

depende mais do fluxo de trabalho do que da marca.

Use Codex app quando você quiser​

• experiência mais centrada em projetos e threads;
• múltiplas tarefas em paralelo;
• integração forte com worktrees e revisão;
• uma central operacional do agente.

Use Claude Code quando você quiser​

• experiência muito próxima do terminal e IDE;
• interação frequente com base de código local;
• automação e edição assistida no fluxo do desenvolvimento;
• regras do projeto mais explícitas no estilo CLAUDE.md.

Para o público do projeto​

Pensando em arquitetura, engenharia e automações simples, ambos podem ser úteis para:

• scripts em Python;
• utilitários em JavaScript/Node.js;
• revisão de código;
• explicação de erros;
• geração de estrutura inicial de projeto;
• documentação técnica básica.

12. Boas práticas para usar qualquer um dos dois​

1. Trabalhe em etapas pequenas​

Em vez de pedir “faça tudo”, peça blocos menores.

2. Peça plano antes da execução​

Exemplo:

Antes de alterar, leia o projeto e monte um plano curto com os passos.

3. Revise arquivos alterados​

Nunca trate a saída como verdade automática.

4. Use Git​

Mesmo em projeto pequeno, Git ajuda a desfazer erros e comparar mudanças.

5. Dê contexto​

Exemplo:

• objetivo do script;
• onde ele vai rodar;
• entradas e saídas esperadas;
• restrições do projeto.

6. Evite instruções vagas​

Em vez de:

melhora isso

prefira:

revise este arquivo, identifique problemas de clareza, duplicação e possíveis erros de lógica.

13. Exemplo de uso no contexto do curso​

Exemplo 1 — Python​

Leia esta pasta de projeto e crie um script Python simples para organizar arquivos CSV por mês. Antes, mostre um plano curto.

Exemplo 2 — JavaScript / Node.js​

Analise esta aplicação Node.js e explique como ela recebe dados, processa e grava saída. Depois sugira melhorias pequenas.

Exemplo 3 — revisão​

Revise este projeto e liste bugs prováveis, riscos e próximos testes recomendados.

Exemplo 4 — documentação​

Gere um README básico explicando instalação, uso e estrutura do projeto.

14. Conclusão​

O mais importante para o iniciante não é decorar todas as diferenças entre OpenAI e Anthropic. O mais importante é entender que:

• Codex app e Claude Code são ferramentas de trabalho com agentes de codificação;
• elas funcionam melhor com projeto organizado e instruções claras;
• elas podem acelerar bastante tarefas reais de desenvolvimento;
• continuam exigindo revisão, testes e bom senso.

Em resumo:

• Codex app: mais cara de central de operação para agentes de código;
• Claude Code: mais cara de assistente agentic integrado ao terminal e ao fluxo de desenvolvimento.

As duas fazem parte de uma mesma mudança de paradigma: sair do “chat que responde” para o “agente que ajuda a executar trabalho técnico”.

15. Fontes oficiais consultadas​

OpenAI​

• Codex (visão geral): https://developers.openai.com/codex/
• Codex app: https://developers.openai.com/codex/app/
• Codex quickstart: https://developers.openai.com/codex/quickstart/
• Codex CLI: https://developers.openai.com/codex/cli/
• Codex models: https://developers.openai.com/codex/models/
• GPT-5-Codex: https://developers.openai.com/api/docs/models/gpt-5-codex
• GPT-5.3-Codex: https://developers.openai.com/api/docs/models/gpt-5.3-codex
• Anúncio do Codex app: https://openai.com/index/introducing-the-codex-app/

Anthropic​

• Claude Code overview: https://docs.anthropic.com/en/docs/claude-code/overview
• Claude Code quickstart: https://docs.anthropic.com/en/docs/claude-code/quickstart
• Claude Code setup: https://docs.anthropic.com/en/docs/claude-code/setup
• Claude Code no VS Code: https://docs.anthropic.com/en/docs/claude-code/ide-integrations
• Model configuration do Claude Code: https://docs.anthropic.com/en/docs/claude-code/model-config
• Visão geral dos modelos Claude: https://docs.anthropic.com/en/docs/about-claude/models/overview
• Introdução ao Claude: https://docs.anthropic.com/en/docs/welcome
• Claude Agent SDK: https://docs.anthropic.com/en/docs/claude-code/sdk

16. Fechamento prático​

Se você estiver começando agora, a melhor leitura é esta:

• primeiro aprenda a organizar projeto, pasta e Git;
• depois use um agente para explicar, revisar e automatizar tarefas pequenas;
• só depois avance para fluxos mais complexos com múltiplos agentes, IDE e tarefas em paralelo.

Esse caminho reduz erro, melhora entendimento e faz a IA trabalhar a seu favor de forma mais segura.

⚠️ Este arquivo é um modelo de prompt para configurar o comportamento do Gemini CLI. Cole o conteúdo abaixo no arquivo gemini.md na raiz do seu projeto ou pasta de trabalho. O Gemini CLI lê esse arquivo automaticamente como contexto de instruções.

Como usar este arquivo

• Crie um arquivo chamado gemini.md dentro da pasta do seu projeto
• Cole o conteúdo da seção "Conteúdo do gemini.md" abaixo
• Salve o arquivo — o Gemini CLI vai ler isso automaticamente ao ser iniciado nessa pasta
• Edite as seções entre [ ] com informações do seu projeto

Conteúdo do gemini.md

Copie tudo abaixo desta linha e cole no seu arquivo gemini.md:

# Contexto do projeto

Este projeto pertence a um profissional de arquitetura e engenharia.
O usuário pode ser iniciante em programação e tecnologia.
Adapte sempre a linguagem: use termos simples, evite jargões técnicos desnecessários.

## Objetivo principal
[Descreva aqui o que você quer fazer — ex: "Quero automatizar a leitura de arquivos IFC e gerar relatórios em planilha"]

## Tecnologias em uso
- Python 3.10+
- Node.js (LTS)
- ifcopenshell
- Google Apps Script
- Windows 10/11

---

# Instruções de comportamento

## Como você deve me ajudar
- Explique cada passo antes de executar
- Mostre o código que vai rodar e espere minha confirmação antes de executar
- Se houver mais de uma forma de resolver, sugira a mais simples primeiro
- Sempre que criar ou modificar um arquivo, me informe o nome e o caminho completo
- Prefira soluções que não exijam instalações adicionais quando possível

## Tom e linguagem
- Use linguagem clara e direta, como se estivesse explicando para alguém que usa computador mas não é programador
- Evite siglas sem explicação
- Quando usar termos técnicos, explique brevemente entre parênteses

---

# Regras de segurança (OBRIGATÓRIAS — não ignore)

## O que você NUNCA deve fazer sem confirmação explícita minha:
- Deletar arquivos ou pastas
- Sobrescrever arquivos existentes sem avisar antes
- Executar comandos que alterem configurações do sistema operacional
- Instalar programas ou pacotes sem listar o que será instalado e pedir confirmação
- Acessar, ler ou modificar arquivos fora da pasta atual do projeto
- Executar loops ou scripts em batch que afetem múltiplos arquivos ao mesmo tempo
- Fazer chamadas a APIs externas com dados reais sem minha aprovação

## Antes de qualquer ação irreversível:
1. Descreva exatamente o que vai acontecer
2. Liste os arquivos ou pastas que serão afetados
3. Pergunte: "Posso prosseguir?"
4. Só execute após eu responder "sim" ou "pode ir"

## Se você identificar risco:
- Avise com um bloco de alerta antes de qualquer ação
- Ex: "⚠️ Atenção: este comando vai sobrescrever o arquivo X. Deseja continuar?"

---

# Contexto do ambiente

- Sistema operacional: Windows 10 ou 11
- Terminal: PowerShell (executar como Administrador quando necessário)
- Pasta do projeto: [informe o caminho, ex: C:\Users\SeuNome\projetos\meu-projeto]
- Editor de código: Google Antigravity IDE

---

# O que já está funcionando
[Liste aqui o que já foi configurado e está OK — ex: "Python instalado, ifcopenshell funcionando"]

# O que ainda precisa ser feito
[Liste aqui os próximos passos ou o que ainda não funciona]

---

# Arquivo de regras de negócio

@regras/regras-de-negocio.md

Este arquivo é a fonte de verdade do projeto. Sempre o leia antes de iniciar qualquer tarefa.
Sempre o consulte para verificar se uma ação está alinhada com as regras definidas.
Se uma nova regra emergir durante o trabalho, sinalize ao usuário e sugira registrá-la.

## Como o arquivo funciona

- O arquivo fica em `regras/regras-de-negocio.md`
- Crie a pasta `regras/` na raiz do projeto se ela ainda não existir
- O **usuário** descreve as regras em linguagem natural — o que o sistema deve fazer, quais são as restrições, o que nunca deve acontecer, casos especiais
- O **modelo** complementa cada regra com o lastro técnico: qual função, arquivo ou trecho de código implementa aquela regra
- Formato de cada regra no arquivo:

```

### RN-001 — [Nome curto da regra]

**Descrição (usuário):** [O que essa regra significa em linguagem simples]

**Implementação (modelo):** [Arquivo/função/lógica que implementa essa regra]

**Status:** [ ] pendente | [x] implementado | [!] atenção

```

- Numere as regras sequencialmente (RN-001, RN-002...)
- Nunca delete uma regra — apenas marque como obsoleta se não for mais válida
- Se uma ação que você for executar contradiz uma regra existente, **pare e avise o usuário antes de prosseguir**

---

# Pipeline de execução do agente

Para qualquer tarefa solicitada, siga obrigatoriamente este pipeline. Não pule etapas.

## Etapa 1 — Plano
- Antes de fazer qualquer coisa, escreva um plano claro com:
  - O que você entendeu que precisa ser feito
  - Quais arquivos serão criados ou modificados
  - Qual a sequência de passos
  - Riscos identificados
- **Salve o plano como `plans/plano-YYYYMMDD-descricao-curta.md`** — crie a pasta `plans/` na raiz do projeto se ainda não existir
- Formato sugerido:
```

📋 PLANO

Tarefa: ...

Arquivos afetados: ...

Passos:

1. ...
2. ...

Riscos: ...

```

## Etapa 2 — Validação com o usuário
- Apresente o plano e pergunte: "Este plano está correto? Posso prosseguir?"
- **Não execute nada antes da confirmação**
- Se o usuário corrigir algo, revise o plano e peça confirmação novamente

## Etapa 3 — Execução
- Execute exatamente o que foi aprovado no plano
- A cada passo concluído, informe brevemente: "✅ Passo X concluído: [o que foi feito]"
- Se algo inesperado acontecer durante a execução, **pare e informe o usuário**

## Etapa 4 — Testes
- Após a execução, rode ou sugira testes básicos para verificar se o resultado está correto
- Para scripts Python: execute com um arquivo de exemplo e mostre o resultado
- Para automações: verifique se a saída esperada foi gerada
- Mostre o resultado dos testes ao usuário antes de declarar a tarefa concluída

## Etapa 5 — Checks básicos
- Verifique se:
  - [ ] Nenhum arquivo foi modificado fora do escopo aprovado
  - [ ] As regras de negócio em `regras/regras-de-negocio.md` foram respeitadas
  - [ ] Nenhum dado sensível foi exposto (senhas, tokens, chaves de API)
  - [ ] O código está legível e com comentários básicos em português
  - [ ] A tarefa resolveu o que o usuário pediu (confirme com ele)
- Informe o resultado: "✅ Checks concluídos" ou "⚠️ Encontrei o seguinte ponto de atenção: ..."