Última revisão: setembro de 2026
Você instalou o OpenCode, abriu o terminal e agora está olhando para a interface sem saber exatamente o que fazer?
Este guia foi feito para esse momento.
Aqui, você vai aprender como usar o OpenCode na prática, começando por uma tarefa simples e avançando até o ponto em que consegue pedir ao agente para analisar um projeto, encontrar problemas, modificar arquivos, executar comandos, testar alterações e revisar o resultado.
A ideia não é apresentar uma lista enorme de comandos. Vamos aprender trabalhando.
Neste tutorial, você vai aprender a: abrir um projeto no OpenCode, preparar o ambiente, fazer perguntas sobre o código, referenciar arquivos, planejar alterações, modificar arquivos, revisar o trabalho do agente, executar testes, desfazer alterações e escrever pedidos mais eficientes.
O que você precisa antes de começar
Para acompanhar este tutorial, você deve ter:
- o OpenCode instalado;
- um projeto para trabalhar;
- um modelo/provedor configurado;
- acesso ao terminal;
- de preferência, Git configurado no projeto.
Se você ainda não instalou o OpenCode no Windows, recomendamos começar pelo nosso tutorial:
[Como instalar o OpenCode no Windows: guia passo a passo]
O OpenCode é executado a partir do diretório do projeto. Ao iniciar opencode, ele abre sua interface de terminal interativa, conhecida como TUI. Também é possível iniciar o OpenCode indicando diretamente o caminho do projeto.
OpenCode não é apenas um chatbot
Essa é uma das ideias mais importantes deste tutorial.
Quando você conversa com um chatbot tradicional, o fluxo costuma ser:
Você faz uma pergunta
↓
A IA responde
Com um agente de programação, o processo pode ser muito mais amplo:
Você define um objetivo
↓
O agente analisa o projeto
↓
Consulta arquivos
↓
Utiliza ferramentas
↓
Modifica arquivos
↓
Executa comandos
↓
Analisa os resultados
↓
Você revisa o trabalho
O OpenCode possui ferramentas que permitem ao modelo interagir com o projeto, incluindo leitura e edição de arquivos e execução de comandos de shell. Essas ações são controladas pelo sistema de permissões do OpenCode.
Isso muda completamente a maneira como você deve trabalhar.
Você não precisa apenas perguntar:
“Como faço isso?”
Também pode dizer:
“Analise meu projeto, identifique onde isso deve ser implementado e proponha uma solução.”
E, posteriormente:
“Implemente a solução que você propôs.”
O projeto que vamos usar como exemplo
Para tornar o tutorial realmente prático, imagine que temos um pequeno projeto chamado TaskFlow.
Ele possui:
taskflow/
├── src/
├── public/
├── package.json
├── README.md
└── ...
Não importa se o seu projeto é diferente.
Pode ser:
- um site;
- uma aplicação;
- um projeto em JavaScript;
- Python;
- TypeScript;
- outra linguagem;
- ou até um projeto de estudo.
O objetivo aqui é aprender a maneira de trabalhar com o agente, e não uma linguagem específica.
Regra de ouro: aumente a complexidade aos poucos
Se você nunca utilizou um agente de programação, não comece dizendo:
“Construa um aplicativo completo.”
Comece pequeno.
Uma boa progressão é:
PERGUNTAR
↓
ENTENDER
↓
ANALISAR
↓
PLANEJAR
↓
ALTERAR
↓
TESTAR
↓
REVISAR
Essa abordagem reduz a chance de você perder o controle sobre o que está acontecendo no projeto.
💡 Dica do NextTechAI
Quanto maior o risco da tarefa, menor deve ser o salto que você pede ao agente.
1. Abra o OpenCode dentro do seu projeto
Primeiro, abra o terminal.
Entre no diretório do projeto.
Por exemplo:
cd /caminho/do/seu/projeto
Depois execute:
opencode
O OpenCode será iniciado utilizando o diretório atual como contexto de trabalho. A documentação oficial também permite iniciar o programa passando diretamente o caminho do projeto.
No Windows usando WSL, por exemplo, seu projeto pode estar em um caminho semelhante a:
cd /mnt/c/Users/SeuNome/Documents/taskflow
Depois:
opencode
✅ Checkpoint
Neste momento, você deve estar dentro do OpenCode com o cursor pronto para receber uma solicitação.
2. Prepare o projeto com /init
Se este é um projeto novo para o OpenCode, uma das primeiras coisas que você pode fazer é executar:
/init
O comando orienta o OpenCode a analisar o projeto e criar ou atualizar um arquivo chamado:
AGENTS.md
Esse arquivo serve para registrar informações e instruções relevantes para o agente trabalhar naquele projeto. A documentação oficial recomenda inclusive manter o AGENTS.md no Git.
Por que isso é importante?
Imagine que seu projeto tenha regras específicas:
- estrutura de pastas;
- padrões de código;
- comandos para testes;
- convenções de nomenclatura;
- tecnologias utilizadas;
- regras que devem ser respeitadas.
O AGENTS.md pode ajudar o OpenCode a entender esse contexto.
O que fazer?
Digite:
/init
Aguarde o processo terminar.
Depois, você pode perguntar:
Explique o que você identificou neste projeto e quais são as principais regras que encontrou.
🧪 Teste na prática
Depois do /init, faça uma pergunta simples:
Faça um resumo da estrutura deste projeto e explique a função das principais pastas e arquivos.
O objetivo não é modificar nada.
Queremos primeiro entender se o agente compreendeu o projeto.
3. Faça sua primeira pergunta ao OpenCode
Agora vamos começar a utilizar o agente como assistente de programação.
Uma boa primeira pergunta é:
Analise este projeto e explique como ele está organizado. Não altere nenhum arquivo.
Observe a diferença.
Não estamos pedindo:
“Conserte tudo.”
Estamos pedindo:
“Entenda primeiro.”
Essa é uma excelente forma de começar.
4. Use @ para trabalhar com arquivos específicos
Uma das funções extremamente úteis do OpenCode é a possibilidade de referenciar arquivos utilizando @.
Por exemplo:
@src/App.tsx
Ao utilizar @, o OpenCode pode pesquisar arquivos no diretório atual e adicionar o arquivo referenciado ao contexto da conversa.
Você pode fazer uma pergunta como:
Explique como este componente funciona: @src/App.tsx
Ou:
Analise @src/App.tsx e @src/components/Header.tsx. Explique como esses dois arquivos se relacionam.
Isso é muito melhor do que simplesmente dizer:
“Olhe meu código.”
Você está direcionando o agente para aquilo que realmente importa.
5. Aprenda a diferença entre perguntar e pedir uma alteração
Compare:
Pergunta
O que esta função faz?
Análise
Encontre possíveis problemas nesta função.
Planejamento
Identifique o problema e proponha uma solução. Não altere os arquivos ainda.
Implementação
Implemente a solução proposta e explique quais arquivos foram modificados.
Esses quatro pedidos parecem semelhantes, mas representam níveis diferentes de intervenção.
6. Antes de modificar o projeto, use Git
Se o projeto utiliza Git, este é um bom momento para verificar seu estado.
No terminal:
git status
Você pode também conferir as alterações:
git diff
Antes de uma alteração importante, ter um ponto de retorno é uma prática recomendável.
Por exemplo:
git add .
git commit -m "Estado inicial antes da alteração"
Você não é obrigado a usar Git para trabalhar com o OpenCode.
Mas, quando um agente pode modificar vários arquivos, o controle de versão se torna especialmente útil.
7. Sua primeira alteração
Agora vamos fazer algo simples.
Imagine que o TaskFlow tenha um formulário de criação de tarefas.
Em vez de dizer:
Melhore o formulário.
Experimente:
Analise o formulário de criação de tarefas. Quero impedir que o usuário envie o formulário sem preencher o título. Primeiro explique como você faria essa alteração e quais arquivos precisariam ser modificados. Não faça alterações ainda.
Agora o agente deve analisar o projeto e apresentar uma proposta.
Por que fazer isso?
Porque você mantém uma etapa de revisão antes da execução.
Se a proposta fizer sentido, então diga:
Implemente essa solução. Modifique apenas os arquivos necessários e explique o que foi alterado.
8. Antes e depois: um fluxo real de trabalho
Imagine que o código original permita:
Título: [ ]
[ Criar tarefa ]
Sem qualquer validação.
Você pede:
Impedir o envio quando o título estiver vazio.
O fluxo ideal é:
ANTES
↓
Análise
↓
Plano
↓
Aprovação
↓
Alteração
↓
Teste
↓
DEPOIS
O resultado pode ser algo como:
Título: [ ]
Informe o título da tarefa.
[ Criar tarefa ]
O mais importante não é a alteração visual.
É aprender o processo.
9. Entenda as permissões do OpenCode
Como o OpenCode possui ferramentas capazes de realizar ações no projeto, você precisa entender o sistema de permissões.
O OpenCode pode configurar ações para:
allow— permitir automaticamente;ask— solicitar aprovação;deny— bloquear.
Entre as ferramentas controláveis estão leitura, edição, execução de comandos, busca e outras operações.
Isso significa que, dependendo da configuração, uma ação pode exigir sua aprovação antes de ser executada.
O que você deve fazer?
Não aprove automaticamente qualquer operação apenas porque o OpenCode sugeriu.
Leia:
- qual ferramenta será utilizada;
- qual arquivo será alterado;
- qual comando será executado;
- qual objetivo aquela ação possui.
⚠️ Atenção
Um agente de programação pode ser muito útil, mas você continua responsável por revisar as ações realizadas no seu projeto.
10. Revise o que o OpenCode fez
Depois de uma alteração, não passe imediatamente para a próxima tarefa.
Pergunte:
Explique exatamente quais arquivos você modificou e por quê.
Depois:
Revise suas próprias alterações e procure possíveis problemas ou efeitos colaterais.
Você também pode utilizar o Git:
git diff
Assim você consegue visualizar as alterações realizadas.
Esse hábito é importante porque o objetivo não é simplesmente fazer a IA escrever código.
É trabalhar em conjunto com ela.
11. Execute testes e comandos
Depois de uma alteração, peça ao OpenCode para verificar o resultado.
Por exemplo:
Execute os testes relacionados a essa alteração e me informe se algum falhar.
O OpenCode possui uma ferramenta bash que permite ao agente executar comandos de shell quando essa ação está autorizada pelas permissões.
Dependendo do projeto, isso pode significar executar comandos como:
npm test
ou:
npm run build
ou:
pytest
O comando correto depende da tecnologia utilizada pelo projeto.
Um bom pedido
Identifique primeiro qual comando este projeto utiliza para executar os testes. Depois execute os testes relacionados à alteração que acabamos de fazer.
Esse pedido é melhor do que presumir um comando.
12. E se o OpenCode errar?
Ele pode errar.
Pode:
- interpretar incorretamente o requisito;
- modificar o arquivo errado;
- alterar mais arquivos do que o necessário;
- introduzir um novo problema;
- escolher uma solução inadequada;
- interpretar incorretamente o resultado de um teste.
Isso faz parte da utilização de sistemas de IA.
Quando isso acontecer, não precisa simplesmente começar tudo novamente.
Você pode explicar o problema:
A alteração não resolveu o problema. O formulário ainda permite o envio quando o título está vazio. Analise novamente o comportamento e explique por que sua solução anterior não funcionou.
Depois:
Corrija o problema sem modificar outras partes do formulário.
Quanto mais específico for o feedback, mais fácil será orientar a próxima tentativa.
13. Como desfazer uma alteração
O OpenCode possui o comando:
/undo
Ele pode desfazer a última mensagem da conversa e também reverter as alterações de arquivos associadas àquela operação.
O sistema utiliza Git para gerenciar essas alterações, portanto o projeto precisa ser um repositório Git para que esse mecanismo de reversão funcione como documentado.
Também existe:
/redo
para refazer uma operação desfeita.
A documentação atual explica que /redo só fica disponível após um /undo e que as alterações de arquivos também podem ser restauradas.
💡 Dica do NextTechAI
Não trate
/undocomo substituto de backup ou Git. Use controle de versão como parte normal do seu fluxo de desenvolvimento.
14. A regra dos pedidos progressivos
Um dos melhores hábitos que você pode desenvolver é dividir tarefas grandes.
Imagine que você queira adicionar um sistema de login.
Em vez de:
Crie um sistema de login completo.
Comece:
Etapa 1
Analise o projeto e identifique como o sistema de autenticação poderia ser integrado.
Etapa 2
Apresente uma proposta de arquitetura. Não altere arquivos.
Etapa 3
Implemente apenas a estrutura inicial aprovada.
Etapa 4
Execute os testes.
Etapa 5
Revise a implementação procurando problemas de segurança ou inconsistências.
Etapa 6
Corrija os problemas encontrados.
Esse processo proporciona muito mais controle.
15. Como escrever bons pedidos para o OpenCode
Não existe uma fórmula única para escrever prompts perfeitos.
Mas pedidos geralmente ficam melhores quando informam:
contexto + objetivo + restrições + resultado esperado
Veja:
Pedido fraco
Melhore meu site.
Pedido melhor
Analise a página inicial e identifique problemas de responsividade.
Pedido ainda melhor
Analise a página inicial, especialmente em telas de 360px, 768px e desktop. Identifique problemas de responsividade e explique uma possível solução. Não altere os arquivos ainda.
Pedido para implementação
Implemente a solução aprovada para os problemas de responsividade. Modifique apenas os arquivos necessários e, ao terminar, explique cada alteração realizada.
Perceba que o último pedido deixa muito menos espaço para interpretação.
16. Use contexto quando ele realmente importa
Imagine que você esteja trabalhando neste arquivo:
src/components/LoginForm.tsx
Em vez de:
Corrija o login.
Você pode escrever:
Analise @src/components/LoginForm.tsx e identifique por que o formulário permite o envio quando o campo de e-mail está vazio. Não altere o código ainda.
O @ ajuda a indicar explicitamente o arquivo relevante.
17. Não peça para a IA fazer tudo de uma vez
Um erro comum de iniciantes é transformar uma tarefa de 10 etapas em uma única mensagem.
Por exemplo:
Crie o sistema de login, banco de dados, painel administrativo, recuperação de senha, autenticação social, testes e documentação.
Esse tipo de tarefa pode envolver muitas decisões.
Uma abordagem mais controlada é:
Arquitetura
↓
Implementação
↓
Testes
↓
Correções
↓
Documentação
Assim você consegue acompanhar o processo.
18. O que são os agentes do OpenCode?
O OpenCode também possui diferentes agentes e subagentes para tarefas específicas.
A documentação apresenta, entre outros conceitos, agentes primários e subagentes. As permissões também podem ser configuradas por agente.
Para um iniciante, porém, não é necessário dominar esse assunto agora.
Neste primeiro tutorial, concentre-se no fluxo básico:
Você
↓
OpenCode
↓
Projeto
↓
Ferramentas
↓
Resultado
Agentes, subagentes e configurações avançadas merecem um tutorial próprio.
19. Comandos essenciais para começar
Você não precisa decorar todos os comandos do OpenCode.
Alguns dos mais úteis neste primeiro contato são:
| Comando | Função |
|---|---|
/help | Exibe ajuda |
/init | Cria ou atualiza AGENTS.md |
/connect | Configura um provedor |
/models | Lista modelos disponíveis |
/new | Inicia uma nova sessão |
/sessions | Lista e alterna entre sessões |
/undo | Desfaz uma operação |
/redo | Refaz uma operação desfeita |
/exit | Sai do OpenCode |
Esses comandos fazem parte da interface atual documentada do OpenCode.
Há muitos outros recursos, mas não precisamos transformar este tutorial em uma cópia da documentação.
Próximo artigo relacionado:
Comandos do OpenCode: guia completo
20. Um recurso útil: executar comandos com !
Na interface TUI, o OpenCode permite iniciar uma mensagem com ! para executar um comando de shell e adicionar a saída à conversa.
Por exemplo:
!git status
ou:
!ls -la
Esse mecanismo é diferente de simplesmente conversar com o agente: você está solicitando diretamente a execução de um comando no ambiente do projeto.
Use esse recurso com atenção, especialmente para comandos que modificam arquivos ou executam operações destrutivas.
21. Segurança: o que você não deve colocar no projeto sem pensar
Antes de permitir que um agente trabalhe em um projeto real, tenha cuidado com informações sensíveis.
Evite expor desnecessariamente:
- senhas;
- tokens;
- chaves privadas;
- chaves de API;
- credenciais;
- dados pessoais;
- arquivos confidenciais.
Também é importante saber qual provedor e modelo você está utilizando e entender como seus dados são tratados por esse serviço.
O OpenCode permite controlar ferramentas por meio de permissões, incluindo leitura, edição, shell e acesso à web, entre outras.
22. Erros comuns de quem está começando
“Vou pedir para ele construir tudo”
Pode funcionar em alguns casos, mas dificulta a revisão.
Prefira dividir.
“Vou aceitar todas as alterações”
Não faça isso automaticamente.
Leia o que está sendo alterado.
“Se a IA escreveu, está correto”
Não necessariamente.
Código gerado por IA precisa ser testado e revisado.
“Não preciso de Git”
Você pode utilizar o OpenCode sem Git, mas trabalhar com controle de versão oferece uma camada importante de segurança e rastreabilidade.
“Quanto maior meu prompt, melhor”
Também não.
Um pedido longo e confuso pode ser pior do que uma instrução curta, objetiva e contextualizada.
23. O fluxo de trabalho que recomendamos
Depois de utilizar o OpenCode algumas vezes, você pode transformar o processo em um hábito:
1. DEFINA O OBJETIVO
↓
2. ANALISE O PROJETO
↓
3. PEÇA UMA PROPOSTA
↓
4. REVISE
↓
5. AUTORIZE A IMPLEMENTAÇÃO
↓
6. EXECUTE TESTES
↓
7. REVISE AS ALTERAÇÕES
↓
8. FAÇA COMMIT
Esse é um fluxo muito mais seguro do que simplesmente:
“Faça meu projeto.”
24. Seu primeiro exercício com o OpenCode
Agora você pode fazer um exercício completo.
Abra um projeto pequeno e execute esta sequência.
Passo 1 — Entender
Peça:
Analise a estrutura deste projeto e explique as principais pastas e arquivos. Não altere nada.
Passo 2 — Encontrar uma melhoria
Depois:
Identifique uma pequena melhoria que possa ser implementada sem alterar a arquitetura do projeto.
Passo 3 — Planejar
Explique como você implementaria essa melhoria e quais arquivos precisariam ser modificados. Não altere nada ainda.
Passo 4 — Implementar
Depois de revisar:
Implemente a solução proposta. Modifique apenas os arquivos necessários.
Passo 5 — Testar
Execute os testes ou verificações apropriadas para essa alteração.
Passo 6 — Revisar
Finalmente:
Revise as alterações que você acabou de fazer. Procure possíveis erros, regressões ou efeitos colaterais e informe o que encontrou.
Parabéns: você acabou de reproduzir um pequeno ciclo real de desenvolvimento assistido por IA.
25. O que você deve aprender depois
Depois de dominar esse fluxo básico, o próximo passo é entender melhor o ecossistema ao redor do OpenCode.
Nossa trilha recomendada é:
🟢 Você está aqui
Como usar o OpenCode na prática
↓
🟢 Próximo passo
OpenCode é gratuito? Entenda como funciona
↓
🟢 Depois
Como usar modelos gratuitos de IA no OpenCode
↓
🔵 Depois
O que é um LLM? Entenda os modelos de linguagem
↓
🔵 Depois
Como rodar uma IA localmente no seu PC com Ollama
↓
🔵 Depois
OpenCode + Ollama: como usar IA local para programar
E, posteriormente, podemos criar conteúdos específicos sobre:
- comandos avançados;
- agentes e subagentes;
- permissões;
- MCP;
- comandos personalizados;
- automação;
- configuração avançada.
Perguntas frequentes sobre como usar o OpenCode
Preciso saber programar para usar o OpenCode?
Não necessariamente.
Você pode utilizar o OpenCode para aprender programação, entender projetos e pedir explicações sobre código.
Entretanto, quanto maior a complexidade do projeto, mais importante se torna compreender programação suficiente para avaliar as respostas e alterações produzidas pela IA.
O OpenCode modifica meus arquivos?
Pode modificar arquivos quando a ferramenta e as permissões utilizadas permitirem essa ação. O OpenCode possui ferramentas integradas para leitura e edição de arquivos, além de execução de comandos.
Por isso, é importante revisar as alterações.
Posso pedir para o OpenCode apenas analisar?
Sim.
Inclusive, essa é uma excelente maneira de começar.
Você pode escrever:
Analise este projeto e explique o problema. Não altere nenhum arquivo.
Posso indicar um arquivo específico?
Sim.
Use @ para localizar e referenciar arquivos dentro do projeto.
Por exemplo:
@src/App.tsx
O arquivo referenciado pode ser incluído no contexto da conversa.
O que acontece se o OpenCode fizer uma alteração errada?
Você pode investigar o problema, pedir uma correção ou utilizar /undo para reverter a operação dentro das condições suportadas pelo sistema. O mecanismo de /undo utiliza Git para controlar as alterações.
Preciso usar Git?
Não é uma exigência absoluta para utilizar o OpenCode.
Porém, Git é altamente útil para acompanhar alterações e criar pontos de retorno.
Além disso, recursos como /undo e /redo dependem do mecanismo de controle de alterações baseado em Git.
Preciso conhecer todos os comandos do OpenCode?
Não.
Para começar, concentre-se em poucos comandos e aprenda o fluxo de trabalho.
Com o tempo, você poderá explorar os recursos avançados.
Conclusão
Aprender a usar o OpenCode não significa decorar uma lista de comandos.
O mais importante é aprender como trabalhar com um agente de programação.
Você começa explicando o objetivo.
Depois permite que o agente analise o projeto.
Em seguida, pede uma proposta, revisa a solução, autoriza a implementação, executa testes e verifica o resultado.
O fluxo passa a ser:
OBJETIVO
↓
ANÁLISE
↓
PLANO
↓
IMPLEMENTAÇÃO
↓
TESTE
↓
REVISÃO
Essa mudança de mentalidade é provavelmente mais importante do que qualquer comando individual.
O OpenCode pode acelerar várias etapas do desenvolvimento, mas isso não elimina a necessidade de compreender o que está acontecendo no projeto.
Use a IA para aumentar sua capacidade de desenvolver — não para abrir mão do controle sobre o código.
Leia também
- O que é OpenCode? Guia completo para iniciantes
- Como instalar o OpenCode no Windows: guia passo a passo
- OpenCode é gratuito? Entenda como funciona
- Como usar modelos gratuitos de IA no OpenCode
- OpenCode vs Claude Code: qual a diferença?
Última revisão: setembro de 2026
Conteúdo editorial do NextTechAI. As informações técnicas sobre comandos e recursos do OpenCode devem ser conferidas na documentação oficial caso o software receba alterações futuras.