Como programar com um amigo de IA sem perder o juízo: configurando o OpenCode com /add e /help

O problema: muitas ferramentas, nada de memória

Vladimir Bandov, desenvolvedor backend da Domclick, negou por muito tempo a necessidade de usar agentes. Quando finalmente testou o OpenCode Desktop, se deparou com uma realidade dura: uma infinidade de Skills, MCP, Permissions e várias configurações ao mesmo tempo. O agente ficava dando passos desnecessários, inventando e executando coisas que não faziam parte da tarefa.

A primeira meia hora de configuração correu bem, mas logo ficou claro: era preciso memorizar qual skill servia para quê e explicar a lógica ao agente toda vez — primeiro o plano, depois os acessos, as configurações, os comandos no terminal. Depois de algumas noites livres, o autor encontrou uma abordagem mais prática. Ela consome mais tokens, mas funciona como deveria: o agente como ajudante, não como um desenvolvedor completo que precisa de vigilância.

O esquema: quatro arquivos e uma referência

A solução se baseia em uma estrutura minimalista dentro de ~/.config/opencode/: um arquivo de ajuda, o HELP.md, e duas pastas com skills e comandos.

Estrutura:

• HELP.md — um registro único que os dois comandos leem em vez de fazer uma varredura cara
• skills/environment-manager/SKILL.md — a skill principal para adicionar novos recursos
• skills/opencode-help/SKILL.md — uma skill auxiliar
• commands/add.md — o comando de adicionar
• commands/help.md — o comando de ajuda

/add: diga o que você quer, não o nome de um pacote

O comando /add passa o pedido do usuário para a skill environment-manager. A ordem de execução é fixa e rígida.

Etapas de execução: 1. Verificação: a tarefa já pode ser resolvida com skills, commands ou MCP já instalados? 2. Tabela comparativa de opções com colunas: Opção, Tipo, O que eu ganho, Acessos/segredos, Riscos, Sobrecarga de contexto/tokens, Recomendação 3. Escolha explícita de uma opção com justificativa 4. Texto completo dos arquivos e um diff unificado, caminhos exatos, lista de arquivos afetados 5. Atualização do HELP.md: data da preparação e skills, commands, MCP e permissions afetados 6. Nada é gravado sem confirmação explícita do usuário

Proibições: nenhuma alteração sem confirmação; não modificar o opencode.jsonc, não instalar pacotes, não conectar MCP, não criar OAuth/PAT, não ler segredos, tokens, .env, chaves SSH, service.json.

Dentro do environment-manager existem limites rígidos: usar as skills já existentes (general-engineering, technical-research, prompt-engineering, token-efficient-workflow, project-learning) apenas para sua finalidade. Avaliar MCP e plugins de terceiros com base em: mantenedor, fonte oficial, tokens exigidos, permissões, localidade/rede, manutenção ativa, risco de supply-chain, sobrecarga de contexto/tokens, compatibilidade com o OpenCode V2.

As permissões padrão são do tipo ask. O acesso de escrita a GitHub, bancos de dados, e-mail, armazenamento, Sentry, Jira, Docker e nuvem só é liberado após um pedido explícito separado.

/help: ler o que já está pronto em vez de auditar

A primeira versão do /help escaneava skills, commands e permissions a cada execução — lento e caro. A segunda versão simplesmente lê o HELP.md.

O comando responde em três etapas: primeiro usa a seção relevante do HELP.md; se não for suficiente, busca a resposta em fontes seguras e somente leitura e na documentação oficial do OpenCode; indica explicitamente que o HELP.md é um registro preparado, não uma garantia em tempo real. Se o registro e os fatos não coincidirem, mostra a divergência e sugere atualizar o HELP.md por meio do /add.

Como funciona na prática

Usuário: "/add quero integração com o GitHub." O environment-manager verifica o que já existe, propõe uma tabela de opções (skill vs. MCP vs. plugin), escolhe explicitamente a melhor, mostra o texto completo dos novos arquivos e o diff, atualiza o HELP.md e espera a confirmação. Nada muda automaticamente.

Usuário: "/help o que eu tenho?" O comando lê o HELP.md e exibe a lista de skills, commands, MCP e permissions conectados. Ele avisa que a informação vem do registro, não do estado em tempo real.

Resultado: Vladimir Bandov evitou o erro principal — não tentou memorizar a configuração sozinho, nem a delegou ciegamente ao agente. O agente propõe um plano, mostra o diff e espera a confirmação. Dois comandos, um registro, regras simples. Mais tokens, mas muito menos sofrimento.