opencode-go-agents/README.md

Arquitetura de Agentes — OpenCode

Implementação do padrão Planner-Executor em 3 níveis (low/mid/high) para qualquer linguagem de programação.

Estrutura de arquivos

seu-projeto/
├── opencode.json                        ← configuração principal
└── .opencode/
    └── agents/
        ├── router.md                    ← classifica complexidade
        ├── low-planner.md               ← analisa AST imediata
        ├── low-executor.md              ← emite micro-diff
        ├── mid-planner.md               ← decompõe em task list
        ├── mid-executor.md              ← código idiomático
        ├── high-planner.md              ← ADR + portão de aprovação
        └── high-executor.md             ← Clean Arch + perf

Instalação

1. Copie opencode.json para a raiz do seu projeto
2. Copie a pasta .opencode/ para o mesmo nível

cp opencode.json /caminho/do/seu-projeto/
cp -r .opencode /caminho/do/seu-projeto/

Agentes

Agentes primários (built-in + customizados)

Agente	Modo	Modelo	Descrição
build	primary	opencode-go/qwen3.6-plus	Orquestrador principal. Invoca @router e delega para planners/executors
plan	primary	opencode-go/qwen3.6-plus	Análise somente-leitura. Usa @explore e @scout para navegar código

Subagentes customizados (deste repositório)

Todos os subagentes abaixo possuem "hidden": true no opencode.json. Isso significa que eles não aparecem na lista de agentes disponíveis (menu Tab) e só podem ser invocados explicitamente via @nome-do-agente pelo agente build durante o fluxo de orquestração. O usuário final interage apenas com @build ou @plan.

Agente	Modelo	Hidden	Função
router	opencode-go/deepseek-v4-flash	✅	Classifica complexidade (low/mid/high) e detecta linguagem
low-planner	opencode-go/deepseek-v4-flash	✅	Análise de AST pontual, plano micro-cirúrgico
low-executor	opencode-go/deepseek-v4-flash	✅	Geração de micro-diff, custo mínimo
mid-planner	opencode-go/deepseek-v4-pro	✅	Raciocínio estruturado para task list
mid-executor	opencode-go/qwen3.6-plus	✅	Código idiomático para qualquer linguagem
high-planner	opencode-go/qwen3.7-max	✅	Análise arquitetural profunda, ADR, cross-file
high-executor	opencode-go/qwen3.7-max	✅	Clean Arch, DDD, performance, migrações críticas

Subagentes built-in do OpenCode

O OpenCode inclui estes agentes — não é necessário configurá-los:

Agente	Modo	Visível no @	Descrição
general	subagent	✅	Propósito geral, executa tarefas multi-etapa em paralelo
explore	subagent	✅	Navegação rápida pelo codebase, somente-leitura
scout	subagent	❌	Pesquisa em documentação externa e dependências (pode não aparecer no autocomplete dependendo da versão)
compaction	primary	❌	Sistema interno — compacta contexto longo. Não selecionável.
title	primary	❌	Sistema interno — gera títulos de sessão. Não selecionável.
summary	primary	❌	Sistema interno — cria resumos de sessão. Não selecionável.

Alternativas para High: opencode-go/kimi-k2.6 e opencode-go/minimax-m3 são substitutos válidos para o opencode-go/qwen3.7-max caso você queira rotacionar ou comparar outputs arquiteturais.

Fluxo de uso

O usuário interage apenas com @build ou @plan. Todos os demais agentes são hidden e trabalham nos bastidores:

Você → @build → @router → classifica
                → @low-planner  → @low-executor   (correções, lints)
                → @mid-planner  → @mid-executor   (features, testes)
                → @high-planner → APROVAÇÃO → @high-executor  (arquitetura)

Ou apenas análise:
Você → @plan → @explore / @scout (somente leitura)

Comandos úteis

Ação	Como usar
Alternar agente primário	Tab ou atalho configurado (build ↔ plan)
Invocar subagente hidden	Não aparece no menu — é invocado automaticamente pelo @build
Invocar subagente built-in visível	@explore, @general (visíveis no @ autocomplete)
Navegar sessões pai/filho	<Leader>+Right / <Leader>+Left

Exemplos de uso

Correção rápida (LOW):

@build corrija o erro de sintaxe na linha 42 do arquivo auth.py

Implementação de feature (MID):

@build implemente um endpoint de login com validação de JWT

Refatoração arquitetural (HIGH):

@build refatore o módulo de pagamentos para usar Clean Architecture

Análise sem alterações:

@plan analise a complexidade ciclomática do módulo de relatórios

Explorar código:

@explore encontre todos os handlers de eventos assíncronos

Consultar documentação externa (se disponível):

@scout como o Redis implementa pub/sub internamente?

Níveis de complexidade

LOW — Escopo ultra-focado

• Correção de sintaxe explícita
• Geração de docstring
• Renomeação de variável
• Lint fix pontual
• Regex simples

Output: Micro-diff (apenas caracteres alterados)

MID — Desenvolvimento diário

• Implementação de método/função nova
• Criação de rotas de API
• Escrita de testes
• Correção de bugs de lógica
• Refatoração com padrões (Factory, Strategy, Repository)

Output: Unified diff + testes nativos da stack

HIGH — Arquitetura e infraestrutura

• Diagnóstico de falhas distribuídas
• Refatoração cross-service
• Otimização de queries SQL
• Investigação de memory leaks
• Design de contratos entre serviços
• Migrações críticas sem table lock
• Configuração de observabilidade (OpenTelemetry)

Output: ADR + plano aprovado antes de gerar código

Economia de tokens

• Low: Apenas os caracteres alterados (micro-diff)
• Mid: Unified diff — nunca repete código inalterado
• High: Plano textual aprovado antes de gerar código massivo

Permissões configuradas

Agente	Write	Edit	Bash	Hidden
build	✅	✅	✅	❌
plan	❌	❌	❌	❌
router	❌	❌	❌	✅
low-planner	❌	❌	❌	✅
low-executor	✅	✅	❌	✅
mid-planner	❌	❌	❌	✅
mid-executor	✅	✅	✅	✅
high-planner	❌	❌	🔒 (apenas leitura)	✅
high-executor	✅	✅	✅	✅

plan tem permission.edit: deny e permission.bash: deny explícitos no opencode.json.

O high-planner tem bash restrito a comandos de leitura (grep, find, ls, cat, wc, head, tail, git log, git diff, git blame) para análise sem risco de alterações acidentais.

Suporte a linguagens

Este framework é agnóstico de linguagem. Os agentes detectam automaticamente a linguagem do código e aplicam:

• Convenções de nomenclatura nativas (camelCase, snake_case, PascalCase, etc.)
• Padrões idiomáticos da linguagem
• Ferramentas de teste nativas da stack
• Logging e observabilidade seguindo o padrão do ecossistema

Exemplos de linguagens suportadas: Java, Python, TypeScript, JavaScript, Go, Rust, C#, Ruby, Kotlin, Swift, PHP, Scala, Elixir, e qualquer outra linguagem suportada pelo modelo.

Customização

Alterar modelos

Edite opencode.json e substitua o campo model de cada agente:

{
  "agent": {
    "build": {
      "model": "opencode-go/qwen3.7-max"
    }
  }
}

Adicionar novos agentes

Crie um arquivo .md em .opencode/agents/ e adicione a configuração em opencode.json:

{
  "agent": {
    "security-reviewer": {
      "description": "Revisa código para vulnerabilidades de segurança",
      "mode": "subagent",
      "model": "opencode-go/qwen3.6-plus",
      "prompt": "{file:.opencode/agents/security-reviewer.md}",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

Licença

MIT