Como usar o OpenCode em um projeto grande sem quebrar o código

Rodar um agente numa pasta vazia é uma coisa

Soltar ele num repositório com anos de histórico, pipeline de CI e cinco pessoas esperando o build passar é outra completamente diferente

O OpenCode é um agente de código open source pra rodar no terminal, com repositório público sob licença MIT e mais de 160.000 estrelas segundo o site oficial

O ponto é que a ferramenta ser boa não te salva de escopo largo

Então aqui a gente vai montar a rotina: contexto escrito, escopo apertado e revisão antes de deixar ele encostar em arquivo de verdade 🙂

O que precisa estar pronto antes de deixar o agente editar o repositório

Antes de qualquer comando, três coisas precisam estar de pé

1. Git limpo, sem exceção

O OpenCode grava snapshots durante a sessão, e eles ajudam bastante

Mas a própria documentação posiciona snapshot como conveniência pra revisar trabalho recente, não como substituto de commit do Git nem de backup

Se liga nisso: mudanças nos metadados do Git não são capturadas pelo snapshot

Ou seja, seu ponto de retorno de verdade continua sendo o commit

2. Arquivo de configuração no lugar

A configuração do projeto vive no opencode.json na raiz, e existe a versão global em ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json"
}

Começa com isso e vai enchendo conforme os passos abaixo

3. Clareza sobre qual pedaço do repositório está em jogo

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

Arquivos fora do diretório ativo ficam de fora do snapshot

Então "abrir o agente na raiz do monorepo e pedir uma refatoração" já começa com a rede de segurança furada

Projeto grande pede recorte, do mesmo jeito que uma boa organização de pastas em equipe pede: você decide onde a coisa mora antes de começar a mexer

Passo a passo para usar o OpenCode em um projeto grande

A ordem importa aqui, beleza? Cada passo fecha uma porta que o passo seguinte poderia arrombar

1. Rode o /init e escreva o contexto do projeto

O /init cria o AGENTS.md na raiz do repositório

Esse arquivo vale pra aquele diretório e pros subdiretórios dele

E tem um detalhe bom: rodar de novo melhora o arquivo existente em vez de substituir, então não tem medo de perder o que você escreveu

O erro comum deste passo: reescrever no AGENTS.md regras que já existem em outros documentos do repositório

Pra isso existe a chave instructions no opencode.json, que aponta arquivos de regras já existentes sem duplicar conteúdo (também dá pra usar no global ~/.config/opencode/opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "docs/padroes-de-codigo.md",
    "CONTRIBUTING.md"
  ]
}

O outro erro é misturar mania pessoal no arquivo do time

"eu gosto de resposta curta", "sempre me explica em português", isso não é regra do projeto

Isso vai pro AGENTS.md global, em ~/.config/opencode/AGENTS.md, que não entra no Git nem cai no colo do time

2. Comece no plan, só troque pro build depois de aprovar

O OpenCode tem o agente plan, somente leitura, que analisa o código e propõe a abordagem sem alterar arquivo nenhum

E tem o build, que é o padrão, com acesso total pra ler, editar e rodar comandos

A troca entre os dois é na tecla Tab, ali mesmo no terminal

É como pedir pro cara novo do time ler o módulo e te contar o plano antes de sair commitando

O erro comum deste passo: abrir direto no build numa base que o agente ainda não leu

Ele vai tentar, e vai chutar a arquitetura que ele acha mais provável, não a que você tem

3. Feche as permissões antes da primeira tarefa

As permissões ficam na chave permission do opencode.json, cobrindo tipos como read, edit, bash e webfetch

Cada uma aceita três valores: allow executa direto, ask pede aprovação e deny bloqueia

O bash aceita padrão com curinga por comando, e esse é o exemplo oficial da documentação:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny"
    }
  }
}

E agora a regra que faz TODA a diferença: na avaliação dos padrões, a última regra que casa é a que vale

Por isso o catch-all * vem primeiro e as específicas vêm depois

Inverteu a ordem, o * come as regras de baixo e você acha que está protegido sem estar

Tome cuidado com isso, é o tipo de coisa que só aparece no dia errado 😛

As permissões podem ser definidas globalmente e também dentro da configuração de um agente específico, o que é ótimo quando você quer um agente mais solto e outro na coleira

4. Ligue o retorno objetivo do LSP

O OpenCode integra servidores LSP e usa os diagnósticos como retorno pro agente, subindo o servidor conforme a extensão do arquivo

Isso muda o jogo em base grande: em vez de o agente achar que ficou bom, ele recebe o erro de volta

A configuração fica na seção lsp, e definir lsp como true habilita os embutidos

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}

Se a sua máquina ou a política da empresa não permite download automático de servidor, dá pra desligar por variável de ambiente:

OPENCODE_DISABLE_LSP_DOWNLOAD=true

O erro comum deste passo: culpar o agente pelo código quebrado quando não está chegando diagnóstico nenhum de volta pra ele

5. Defina o escopo e entenda os subagentes

O OpenCode separa agentes primários de subagentes pelo campo mode, que aceita primary, subagent ou all, configurado no opencode.json ou em arquivo markdown de agente

Subagente também pode ser chamado na mão, mencionando o nome com @ na mensagem:

@nome-do-subagente mapeia os pontos que chamam o serviço de pagamento

E aqui vai o aviso que muita gente pula: o subagente general, de uso geral pra pesquisa e tarefa de múltiplos passos, tem acesso total às ferramentas exceto todo

Tradução: ele TAMBÉM altera arquivo

"Ah, mas é só uma pesquisa", pois é, não é

Outro ponto: a versão v1.18.2 passou a impedir por padrão que subagentes disparem subagentes aninhados, com um limite configurável pela opção subagent_depth

6. Cuide do que sai do repositório

O compartilhamento de sessão é manual por padrão: o link só é gerado quando você roda o comando /share

Só que conversa compartilhada fica acessível publicamente pra quem tiver o link

Em código de cliente ou repositório fechado, isso é conversa séria

Dá pra desligar o recurso por completo, definindo a opção share como "disabled" na configuração

O agente já mexeu no que não devia: o que dá para desfazer e o que não volta

Aconteceu

Você aprovou uma tarefa larga, ou deixou uma permissão em allow, e a sessão encostou onde não era pra encostar

O caminho de volta são os comandos /undo e /redo, que voltam e refazem o histórico da conversa junto com as alterações de arquivo feitas pelo agente

Eles se apoiam nos snapshots, que ficam habilitados por padrão (e são desligáveis pela opção snapshot na configuração)

Agora a parte honesta, que é a que interessa em repositório de verdade

O que o snapshot captura:

• arquivos rastreados pelo Git
• arquivos não rastreados que não estão ignorados, com um limite de tamanho: os não rastreados acima de 2 MiB ficam de fora

O que fica de fora:

• arquivos ignorados pelo Git
• arquivos fora do diretório ativo
• mudanças nos metadados do Git

E tem o aviso mais importante de todos, que está na própria documentação: undo e redo não revertem efeitos colaterais de comandos de shell

Ou seja, mudança em banco de dados, serviço, processo, recurso de rede, estado do Git e saída de build ignorada continuam lá do jeito que ficaram

O arquivo volta, o DROP TABLE não volta

Como prevenir, na prática:

• commit antes de soltar o build, sempre
• deny nos comandos destrutivos e nos que publicam coisa (é pra isso que serve o exemplo do git push * lá em cima)
• diretório ativo estreito, pra rede de segurança cobrir o que você está mexendo

Que tipo de tarefa entregar ao agente em um repositório de verdade

Com as travas montadas, dá pra escolher tarefa que combina com elas

Leitura e mapeamento no agente plan

Perfeito pra "me explica como esse fluxo funciona e onde ele é chamado"

É somente leitura, então o pior cenário é uma explicação errada, não um arquivo destruído

Alteração cirúrgica num diretório só

Como o AGENTS.md vale pro diretório e pros subdiretórios dele, dá pra ter um arquivo de regras específico daquela pasta, com as convenções daquele módulo

Agente aberto ali, escopo ali, snapshot cobrindo ali

Pesquisa de múltiplos passos delegada a subagente

Massa pra rastrear uso de uma função pelo repositório inteiro

Com a ressalva já dita: o general tem acesso total às ferramentas exceto todo, então ele pode editar

Se é pra ser só pesquisa, a permissão de edit precisa estar em ask ou deny

Trabalho com bash em ask enquanto a rotina não está calibrada

É chato nas primeiras horas, eu sei

Mas é assim que você descobre quais comandos ele tenta rodar sozinho, e aí você promove pra allow os que são inofensivos

E o que NÃO entregar: mudança larga e vaga que atravessa o repositório inteiro

"padroniza o tratamento de erro do projeto" é o tipo de pedido que gera um diff que ninguém revisa direito, e diff que ninguém revisa é bug com data marcada

O que aprendi rodando o OpenCode na prática

No vídeo eu mostro o OpenCode conectado a um provedor externo de modelos, e teve umas lições que valem pra qualquer setup

A primeira é boba e derruba muita gente: quando colei a chave de API, qualquer caractere extra junto, inclusive um espaço, invalidava a conexão

Depois de conectar, a checagem que eu faço é perguntar pro modelo qual modelo ele é

A resposta bateu com o que eu tinha escolhido na lista, e só aí eu segui

Parece trivial, mas é a diferença entre debugar o agente e debugar a sua configuração

Aí criei um projeto do zero pelo OpenCode pra ver ele trabalhar: uma calculadora de churrasco em React com Vite

Passei estrutura de pastas, formulário, lógica de cálculo em arquivo separado, tela de resultado, lista de compras, tema escuro e sem back-end

Ele foi mostrando cada passo e no fim entregou o resumo do que fez: regras de cálculo, componentes criados e tema visual

Quando pedi pra ele executar o projeto e me mostrar rodando, bati num limite de uso e não consegui concluir esse passo naquele modelo

E aqui está o aprendizado que mais vale pra projeto grande: o limite chega mais rápido do que parece porque não é só o seu prompt que consome

As idas e voltas entre o agente e o modelo acontecem sozinhas durante a execução da tarefa

Cada leitura de arquivo, cada correção, cada tentativa

Contornei trocando pra outro modelo disponível na mesma conexão, e virou estratégia: ir rotacionando

A outra coisa que testei foi a interface web da plataforma, e a conclusão foi bem clara

Ali o uso é limitado: o modelo não devolve estrutura de pastas nem roda comando no terminal, então eu tinha que copiar o código e colar no PC pra executar

O ganho de verdade naquele formato é a etapa ANTERIOR ao desenvolvimento: planejar a aplicação, escrever um PRD, um documento de requisitos e um arquivo de contexto do projeto bem feito

Testei isso pedindo um jogo tower defense, com estrutura de pastas definida e as regras escritas no prompt, e ele entregou arquivo por arquivo

Olha só como isso fecha com o começo do post: o chat serve pra escrever o contexto, o terminal serve pra executar com trava

O documento que sai dali é exatamente o material que vira o seu AGENTS.md

Veja o OpenCode rodando

No vídeo abaixo eu mostro a conexão do provedor, a checagem do modelo e o projeto sendo criado do zero, incluindo o momento em que o limite de uso aparece e como eu contorno

É o complemento prático da rotina descrita aqui: dá pra ver o ritmo real das idas e voltas do agente antes de você soltar isso num repositório de trabalho

Próximo passo: monte a rotina antes da primeira tarefa grande

Resumindo o que segura o OpenCode em projetos grandes, são três pernas

Contexto: AGENTS.md na raiz gerado pelo /init, o que já existe apontado pela chave instructions do opencode.json, e as suas manias no ~/.config/opencode/AGENTS.md global

Escopo: plan antes de build, troca no Tab só depois de aprovar o plano, e consciência de que subagente como o general também edita arquivo

Revisão: permissões com allow, ask e deny na ordem certa (catch-all primeiro), LSP devolvendo diagnóstico pro agente, e snapshots com /undo sabendo que efeito de comando de shell não volta

Próximo passo concreto, pra fazer hoje: roda o /init no repositório, escreve as três ou quatro regras que mais doem no seu projeto (aquelas que todo mundo do time repete em code review) e testa a primeira tarefa com bash em ask

Uma tarefa pequena, num diretório só, com o Git limpo

Se passar nesse teste, você calibra e vai subindo

Agora bora testar aí, e me conta como foi na sua base…

até o próximo post! 😀