Guia OpenCode Agents: 7 verificações para Subagents e AGENTS.md

Resposta curta: use AGENTS.md para regras do repositório e OpenCode agents quando precisar de um especialista com prompt, modelo, ferramentas e limites próprios.

AGENTS.md guarda regras duráveis do repositório: comandos de teste, estilo, pastas geradas e avisos. O agent define o comportamento de um papel específico.

Misturar as duas camadas cria instruções duplicadas e difíceis de corrigir.

Um subagent ajuda quando separa uma preocupação real: analisar pasta grande, revisar diff arriscado ou pesquisar uma API.

Defina contrato de saída com arquivos, plano de patch ou lista de riscos.

O modelo deve seguir o risco. Revisão, arquitetura e migração exigem mais raciocínio; resumo e notas podem ser mais leves.

Limite ferramentas e caminhos para reduzir mudanças acidentais.

Configuração compartilhada deve ser revisável no Git, mas segredos ficam em variáveis de ambiente ou fluxo do provedor.

Use nomes estáveis como reviewer ou docs-editor.

Comece com inspeção sem escrita. Verifique escopo, tom e formato.

Depois permita uma pequena edição e revise o diff.

1. Nomear papelUse reviewer, planner ou docs-editor.
2. Definir saídaExplique retorno e proibições.
3. Escolher modeloAlinhe raciocínio e custo ao risco.
4. Limitar ferramentasComece pelo mínimo.
5. Validar sem escritaPeça inspeção ou revisão.
6. Revisar diffAmplie só após mudança limpa.
7. Registrar regraDocumente quando usar o agent.

Agents demais confundem o roteamento. Comece por um papel que resolva tarefa repetida.

Não duplique regras entre AGENTS.md e agent.

MCP, hooks e skills aumentam valor e risco.

Valide uma camada por vez: prompt, ferramenta e escrita.

Antes de compartilhar o agent com a equipe, registre uma tarefa bem-sucedida: objetivo, arquivos lidos, comandos executados, resultado e diff revisado. Essa evidência torna o papel verificável e ajuda a perceber regressões quando o prompt muda.

Defina também uma regra de parada. Se faltar contexto, o agent deve pedir o arquivo ou comando certo em vez de adivinhar. Se encontrar segredos, produção ou permissões amplas de escrita, deve parar e listar riscos. Isso protege o repositório sem atrapalhar tarefas normais.

Em equipes pequenas, comece com no máximo dois papéis: reviewer e docs-editor. O reviewer protege mudanças de código; o docs-editor mantém README, guias e notas de migração. Só adicione research agent ou migration-checker quando o uso se repetir.

Depois da primeira semana, faça uma revisão curta. Veja quais tarefas realmente usaram o agent, quais prompts precisaram de ajuste, se alguma ferramenta ficou ampla demais e se a saída ainda segue o contrato. Remova papéis sem uso em vez de manter configuração acumulada.

Exclua também um agent quando ele passar semanas sem uma tarefa clara. Uma lista menor aumenta a chance de o desenvolvedor escolher o papel certo e revisar o resultado com atenção.

Use nomes que deixem o trabalho claro. reviewer, docs-editor, release-checker ou migration-planner ajudam a entender logs, prompts e comentários de revisão. Nomes criativos podem parecer bons no início, mas dificultam auditoria quando a equipe precisa explicar por que um agent foi chamado.

Aumente permissões por etapas. Um agent de leitura pode analisar uma pasta grande e entregar achados; um agent com escrita precisa de diretórios permitidos, comando de verificação e formato de saída que liste arquivos alterados, testes executados e premissas não confirmadas.

Revise a configuração quando o projeto trocar framework, comando de build ou provedor de modelo. Uma regra segura pode ficar antiga depois de uma migração. Registre a data do último teste válido e remova papéis que não correspondem mais ao fluxo real.

{
  "agents": {
    "reviewer": {
      "model": "provider/reasoning-model",
      "description": "Review diffs and return concrete findings only",
      "tools": ["read", "grep"]
    },
    "docs-editor": {
      "model": "provider/fast-model",
      "description": "Update documentation after source changes",
      "tools": ["read", "edit"]
    }
  }
}

Configuração compartilhada deve ser revisável no Git, mas segredos ficam em variáveis de ambiente ou fluxo do provedor.