03. Workflows e boas práticas¶

🎯 Objetivo¶

Combinar agentes, comandos e worktrees em workflows confiáveis e adotar práticas que mantêm qualidade e custo sob controle.

🔀 Trabalho isolado com worktrees¶

Deixe o agente trabalhar em uma worktree para isolar mudanças arriscadas. Configure o destino:

{
  "worktree": { "directory": "../worktrees" }
}

O agente pode criar/mover/remover worktrees pelo namespace opencode (via execute) ou pela API/SDK. Worktrees reduzidas também são úteis em pipelines paralelos.

🤝 Orquestração com subagentes¶

Use o agente plan para planejar antes de o build editar
Delegue exploração/busca ao subagente explore (read-only)
Limite passos do subagente para evitar voltas: steps: 8 no agente
Controle quais subagentes um agente pode lançar com a permissão subagent

📋 Instruções versionadas (`AGENTS.md`)¶

AGENTS.md

# Convenções do projeto
- Responda em português; commits em Conventional Commits
- Rode `npm test` antes de considerar uma tarefa concluída
- Nunca commitar segredos; use {env:...} na configuração

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"]
}

🧹 Contexto e custo sob controle¶

{
  "compaction": { "auto": true },
  "tool_output": { "max_lines": 2000, "max_bytes": 51200 },
  "snapshots": false
}

Veja detalhes em Otimização e Operação.

🔐 Higiene de git e segurança¶

Commits pequenos por tarefa facilitam revisar o que o agente fez
Revise sempre os diffs antes de git push
Force aprovação: { "action": "shell", "resource": "git push *", "effect": "ask" }
Para restrições que não podem ser reabilitadas por um repo, use policies

🔍 Diagnóstico¶

opencode debug config          # config efetiva
opencode debug paths db        # onde ficam dados/credenciais
opencode service status        # estado do serviço
# logs: ~/.local/share/opencode/log/opencode.log
# verboso: OPENCODE_LOG_LEVEL=DEBUG opencode run "..."

Ao compartilhar logs, remova API keys e dados sensíveis.

❓ Desafio prático¶

Escreva um AGENTS.md real com 5 convenções do seu time
Monte um workflow: plan planeja → build implementa → explore verifica
Isole uma tarefa arriscada numa worktree e revise antes de aplicar
Meça o custo do workflow com opencode stats --cost

📚 Fonte oficial¶

Instructions · Permissions · Compaction · Snapshots

Próximo passo: Módulo 05 — Integração · Voltar ao módulo