IA no terminal: como trabalhar com o OpenCode

A primeira onda de IA para programação ficou conhecida pelo autocomplete: você escrevia o início de uma função e o modelo sugeria o restante. Ferramentas agênticas mudaram essa relação. Agora a IA pode investigar um repositório, formular um plano, editar vários arquivos, executar testes e revisar o próprio resultado.

O OpenCode leva esse fluxo para o terminal, sem amarrar o desenvolvedor a um único modelo ou provedor. Ele é open source e também está disponível como aplicativo desktop e extensão para IDE. Mais importante: trata o modelo como uma parte de um sistema maior, composto por contexto, ferramentas, permissões e verificação.

Um agente de código não é um programador autônomo. É um modelo probabilístico operando ferramentas determinísticas dentro dos limites que você definiu.

Do chat para o ciclo agêntico

Uma conversa comum com uma LLM produz texto. Um agente precisa fechar um ciclo:

objetivo do usuário
      ↓
leitura do contexto
      ↓
decisão do modelo
      ↓
chamada de ferramenta
      ↓
resultado real do ambiente
      ↓
nova decisão, verificação ou resposta

Quando você pede "corrija o build", o OpenCode não precisa adivinhar todo o problema em uma única resposta. Ele pode localizar os arquivos, ler a configuração, executar o build, observar o erro, aplicar uma alteração mínima e executar o build novamente.

Essa capacidade vem de três camadas diferentes:

Modelo: interpreta o objetivo, raciocina e escolhe a próxima ação.
OpenCode: organiza sessões, contexto, agentes, ferramentas e permissões.
Ambiente local: contém o código, Git, compiladores, testes e credenciais.

Confundir essas camadas gera expectativas ruins. Um modelo melhor pode raciocinar melhor, mas não corrige contexto ausente, permissões excessivas ou uma suíte de testes que não representa o comportamento esperado.

Por que usar o OpenCode

O principal diferencial é a combinação de abertura e controle. O OpenCode usa o AI SDK e o catálogo Models.dev para suportar dezenas de provedores, incluindo modelos comerciais, gateways e execução local. A escolha pode considerar qualidade, preço, latência, privacidade ou requisitos da empresa.

Na prática, isso permite:

usar um modelo rápido para explorar o repositório e outro mais capaz para uma refatoração complexa;
trocar de provedor sem trocar toda a interface e o fluxo de trabalho;
manter configurações e agentes específicos dentro do projeto;
executar a IA no mesmo ambiente em que os comandos de desenvolvimento já funcionam;
auditar alterações pelo Git antes de qualquer commit ou deploy.

A interface de terminal também reduz a distância entre sugestão e evidência. O agente pode executar exatamente os comandos que a equipe executaria: testes, lint, compilação, migrações e inspeção de diffs.

Instalação e primeiro projeto

Como este projeto já usa pnpm, a instalação global pode ser feita assim:

pnpm install -g opencode-ai

Depois, abra o OpenCode dentro do repositório:

cd /caminho/do/projeto
opencode

No primeiro uso, conecte um provedor com /connect, escolha um modelo com /models e inicialize o contexto do projeto:

/connect
/models
/init

O comando /init analisa o repositório e cria ou melhora um AGENTS.md. Esse arquivo deve ser revisado e versionado, pois funciona como documentação operacional para as próximas sessões e para toda a equipe.

Contexto é mais importante que um prompt longo

Uma LLM não conhece automaticamente as decisões do projeto. Ela vê as instruções, os arquivos lidos, resultados de ferramentas e mensagens que cabem na janela de contexto. Quanto mais ruído entra, menos atenção sobra para o que é relevante.

Um bom AGENTS.md registra fatos estáveis:

# Convenções do projeto

- Use pnpm 11 e Node.js 22 ou superior.
- Rode `pnpm test`, `pnpm lint` e `pnpm build` antes de concluir.
- Posts ficam em `content/blog` e usam frontmatter YAML.
- Não altere arquivos gerados em `.next`.
- Nunca faça commit ou push sem solicitação explícita.

O objetivo não é transformar o arquivo em um manual completo. Instruções demais competem entre si. Arquitetura, comandos, convenções incomuns e limites de segurança são mais úteis do que regras genéricas como "escreva código limpo".

Durante uma conversa, use @ para referenciar arquivos específicos. Pedir "analise @lib/posts.ts e os testes relacionados" produz um ponto de partida melhor do que "entenda todo o projeto".

Plan e Build são controles diferentes

O OpenCode inclui dois agentes primários. Você alterna entre eles com Tab:

Plan investiga e propõe uma solução sem modificar o repositório. Edições e comandos de shell exigem aprovação por padrão.
Build possui as ferramentas necessárias para implementar e validar uma mudança.

Plan é útil quando o custo de uma direção errada é alto: migrações de banco, mudanças de autenticação, arquitetura distribuída ou alterações que atravessam vários pacotes. O plano cria um ponto de revisão antes da execução.

Para tarefas pequenas e bem especificadas, Build direto reduz cerimônia. A decisão deve considerar risco e ambiguidade, não o número de linhas esperado.

O OpenCode também oferece subagentes especializados:

Explore pesquisa o código rapidamente sem alterar arquivos.
Scout investiga documentação e código de dependências externas.
General executa pesquisas e trabalhos complexos de múltiplas etapas.

Subagentes ajudam a paralelizar investigação e mantêm o agente principal focado. Eles não criam verdade por consenso: toda conclusão importante ainda precisa de evidência no código, na documentação ou na execução dos testes.

Ferramentas transformam intenção em evidência

O OpenCode disponibiliza ferramentas para leitura, busca, edição, patches, shell, LSP, web e delegação. A LLM escolhe uma ferramenta e fornece argumentos; o OpenCode executa a operação e devolve o resultado ao modelo.

Isso torna possível um fluxo verificável:

1. glob encontra os arquivos relevantes
2. grep localiza símbolos e referências
3. read constrói contexto suficiente
4. apply_patch faz uma alteração rastreável
5. bash executa testes e build
6. git diff mostra exatamente o que mudou

O ganho de produtividade não vem de gerar mais código por minuto. Vem de reduzir o tempo entre hipótese e feedback. Uma implementação que não compila deixa de ser uma resposta convincente assim que o agente pode executar o compilador.

Permissões são parte da arquitetura

Ferramentas poderosas ampliam o impacto de um erro. Por isso, o OpenCode permite configurar cada ação como allow, ask ou deny, inclusive com padrões para comandos e caminhos.

Uma configuração conservadora por projeto pode ser:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "glob": "allow",
    "grep": "allow",
    "webfetch": "allow",
    "bash": {
      "*": "ask",
      "pnpm test*": "allow",
      "pnpm lint*": "allow",
      "pnpm build*": "allow",
      "git status*": "allow",
      "git diff*": "allow",
      "git push*": "deny",
      "rm -rf*": "deny"
    }
  }
}

As regras mais específicas ficam depois do curinga porque a última regra compatível vence. O OpenCode já bloqueia leitura de arquivos .env por padrão, mas credenciais também não devem aparecer em prompts, logs, comandos ou arquivos versionados.

--auto aprova automaticamente o que normalmente perguntaria, mas não ignora regras com deny. É útil em ambientes controlados e descartáveis. Em uma máquina com acesso a produção, autonomia sem política explícita é apenas uma forma rápida de ampliar o raio de impacto.

Agentes especializados

Um agente pode ter prompt, modelo e permissões próprios. Por exemplo, um revisor que nunca altera arquivos pode viver em .opencode/agents/review.md:

---
description: Revisa alterações procurando bugs, regressões e riscos
mode: subagent
permission:
  edit: deny
  bash:
    "*": deny
    "git diff*": allow
    "pnpm test*": allow
---

Priorize problemas de comportamento, segurança e testes ausentes.
Cite arquivo e linha para cada finding.

Na sessão, ele pode ser chamado com @review. Separar revisão de implementação reduz o viés de defender a solução que o próprio agente acabou de escrever.

Especialização funciona melhor quando o escopo é objetivo. "Especialista em tudo" é apenas outro agente genérico com um prompt maior.

MCP: conectando a IA ao mundo externo

O Model Context Protocol permite adicionar ferramentas locais ou remotas. Um servidor MCP pode consultar documentação, issues, observabilidade, bancos de dados ou APIs internas. Para o modelo, essas integrações aparecem ao lado das ferramentas nativas.

Exemplo com um servidor remoto de documentação:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  },
  "permission": {
    "context7_*": "allow"
  }
}

MCP não deve virar uma coleção de integrações sempre ligadas. Cada servidor adiciona definições de ferramentas ao contexto, consome tokens e aumenta a superfície de confiança. Habilite somente o necessário para a tarefa e aplique permissões por agente quando uma integração for sensível.

Um fluxo que funciona no dia a dia

1. Comece pelo resultado esperado

Uma boa solicitação descreve comportamento, restrições e validação:

Adicione busca por título e tag na lista de posts.
Preserve o layout atual, suporte teclado e mobile,
e considere concluído somente após testes, lint e build.

Isso é melhor do que prescrever cada função. O agente recebe liberdade de implementação sem perder critérios de aceite.

2. Peça investigação antes de edição

Mesmo em Build, solicite que o agente localize padrões existentes. Reutilizar a arquitetura do projeto costuma ser mais importante do que aplicar a solução mais popular da internet.

3. Trabalhe em incrementos verificáveis

Mudanças pequenas facilitam leitura de diff, rollback e diagnóstico. Se a tarefa envolve banco, API e interface, valide cada fronteira antes de avançar.

4. Exija evidência

"Parece correto" não é uma validação. Peça os comandos executados, resultados e limitações. Teste automatizado, type checker e build reduzem incerteza, embora nenhum deles prove sozinho que o produto está correto.

5. Revise o diff como responsável final

Antes do commit:

git status --short
git diff
pnpm test
pnpm lint
pnpm build

Procure mudanças fora do escopo, dependências desnecessárias, tratamento de erro ausente e testes que apenas repetem a implementação.

Onde a IA ainda falha

OpenCode melhora o ciclo de trabalho, mas não remove limitações dos modelos:

Alucinação: APIs, opções e comportamentos podem ser inventados. Consulte a versão real da documentação e execute o código.
Contexto incompleto: uma decisão local pode violar requisitos que nunca entraram na conversa.
Prompt injection: arquivos, páginas e resultados de ferramentas podem conter instruções maliciosas. Conteúdo lido é dado, não autoridade.
Otimização para o teste: o agente pode fazer a suíte passar sem preservar a intenção do produto.
Mudanças amplas: refatorações grandes parecem coerentes na resposta, mas escondem regressões no diff.
Custo e latência: mais contexto, MCPs e subagentes aumentam consumo. Use o modelo mais simples que executa a tarefa com qualidade suficiente.

Modelos locais reduzem o envio de código a terceiros, mas privacidade não é sinônimo de qualidade ou segurança. Ainda existem permissões de sistema, dependências, logs e ferramentas externas para controlar.

O papel do desenvolvedor muda

Com IA agêntica, digitar código deixa de ser o único centro do trabalho. Ganham importância:

decompor problemas e definir critérios de aceite;
fornecer contexto sem inundar a janela do modelo;
desenhar limites de permissão;
interpretar testes, métricas e comportamento real;
revisar decisões arquiteturais e riscos operacionais.

Isso não diminui a necessidade de conhecimento técnico. O agente acelera tanto boas quanto más decisões. Quem entende o sistema consegue detectar quando uma solução elegante está errada; quem não entende pode apenas aceitar uma resposta bem escrita.

Vale a pena?

O OpenCode é especialmente útil para explorar código desconhecido, implementar mudanças bem especificadas, automatizar tarefas repetitivas, produzir testes e investigar falhas com feedback do ambiente.

Ele deve ser usado com mais cuidado em incidentes de produção, migrações irreversíveis, código regulado e qualquer operação com credenciais ou dados sensíveis. Nesses cenários, Plan, agentes somente leitura e aprovação humana não são burocracia: são controles de engenharia.

A pergunta certa não é "a IA consegue programar sozinha?". A pergunta útil é: como desenhar um processo em que a IA acelera investigação e execução sem remover evidência, revisão e responsabilidade? O OpenCode é uma boa resposta porque torna esse processo configurável, visível e próximo das ferramentas que o desenvolvedor já usa.